void vortex_profiles_register gchar *  uri,
VortexOnStartChannel  start,
gpointer  start_user_data,
VortexOnCloseChannel  close,
gpointer  close_user_data,
VortexOnFrameReceived  received,
gpointer  received_user_data
 

Allows to register a new profile inside the Vortex Library.

Register a profile to be used on channel creation. Profiles are used by Vortex channels to know which message to exchange and the channel semantics. To be able to create vortex channels you must register at least one profile.

On vortex session establishment, vortex peer acting as server sends to vortex peer acting as client (or initiator) its registered profiles. This enable both sides to know if they can talk together.

In order to get an idea about profile names to use you can see actual reserved profiles name defined by BEEP RFC. Some on them are:

  • The one time password profile: "http://iana.org/beep/SASL/OTP"
  • The TLS profile: "http://iana.org/beep/TLS"
  • The profile used by Coyote layer at Af-Arch: "http://fact.aspl.es/profiles/coyote_profile"

You must not free the uri argument memory. This function does not make a copy so, if you free uri you will get unexpected behaviors. It's recommended to use static values to avoid problems.

Associated to the profile being registered are the handlers. There are three handlers to be executed during the profile life.

When a remote peer wants to create a channel sends a start channel message. On that event, when an start message is received, the start handler will be executed.

When a remote peer wants to close an already created channel it sends the close channel message. The close handler is executed on that event.

For all frames received, received handler will be executed.

You can get more info about these handlers here. You can also read the following document to know more about profiles.

If you don't provide handlers for start and close, a default handler will be used.

These default handlers always return TRUE, so, on channel creation it will accept always and on channel closing it will accept always.

If you don't provide a received handler, all data received will be acknowledged but dropped.

There are some exception to previous information. First one is that there are two levels of handlers to be executed on events for channels with a profile. The first level is defined by previous ones handlers. But a second level of handlers exists on per-channel basis.

This second level of handlers are executed for the same events before the first level is executed. If a handler for a particular event is not found on second level, then the first handler is executed.

If a handler for a particular event is found on second level, the is executed and first level handler not.

This allows you to have several levels of handlers to be executed in a general way and handlers to be executed for a particular channel.

Another exceptions comes with the start handler. It only allows you to get notified about the channel number requested to be created and the connection where it was received the petition. On most cases it is not needed more information.

However, the start message have several optional attributes and content element that are used by profile definitions to implement things such as TLS. On that case it is need to get notified with all data available. You can check vortex_profiles_register_extended_start function to know more about this issue.

You can check this section to know more about how second level, first level and wait reply method implemented by Vortex Library to receive frames.

You can also check this tutorial about creating new profiles for your application.

Parameters:
uri a profile name to register
start a handler to control channel creation
start_user_data user defined data to be passed in to start handler
close a handler to control channel termination
close_user_data user defined data to be passed in to close handler
received a handler to control incoming frames
received_user_data user defined data to be passed in to received handler