axl_bool vortex_profiles_register ( VortexCtx ctx,
const char *  uri,
VortexOnStartChannel  start,
axlPointer  start_user_data,
VortexOnCloseChannel  close,
axlPointer  close_user_data,
VortexOnFrameReceived  received,
axlPointer  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 allowing the application level to implement the channel semantic. 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 (there are exceptions to this rule since some BEEP peers may hide which profiles are really supported until, for example, proper authentication is negotiated).

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: ""
  • The TLS profile: ""
  • The profile used by Coyote layer at Af-Arch: ""

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 axl_true, so, on channel creation it will accept and on channel closing it will accept.

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 needed 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.

ctxThe context where the operation will be performed.
uriA profile name to register
startA handler to control channel creation
start_user_dataUser defined data to be passed in to start handler
closeA handler to control channel termination
close_user_dataUser defined data to be passed in to close handler
receivedA handler to control incoming frames
received_user_dataUser defined data to be passed in to received handler
The function return axl_true if the profile was properly registered. Otherwise axl_false is returned.

References vortex_hash_lookup(), vortex_hash_replace(), vortex_mutex_create(), vortex_mutex_lock(), and vortex_mutex_unlock().

Referenced by vortex_alive_init(), vortex_sasl_accept_negotiation_full(), vortex_tls_accept_negotiation(), vortex_tunnel_accept_negotiation(), and vortex_xml_rpc_accept_negotiation().