VortexChannel * vortex_channel_new ( VortexConnection connection,
int  channel_num,
const char *  profile,
VortexOnCloseChannel  close,
axlPointer  close_user_data,
VortexOnFrameReceived  received,
axlPointer  received_user_data,
VortexOnChannelCreated  on_channel_created,
axlPointer  user_data 
)

Creates a new channel over the given connection.

Creates a new channel over the session connection with the channel num channel_num specified. If channel num is 0, the next free channel number is used. The new channel will be created under the terms of the profile defined. Both peers must support the given profile, otherwise the channel will not be created.

Because the channel is a MSG/RPY transaction between the client and the server, it will block caller until channel is created.

If you want to avoid getting blocked, you can use on_channel_created handler. If you define this handler, the function will unblock the caller and create the channel on a separated thread. Once the channel is created, caller will be notified through the callback defined by on_channel_created.

There are some events that happens during the channel life. They are close handler and received handler. They are executed when the event they represent happens. A description for each handler is the following:

  • close handler: (see more info on vortex_handlers: VortexOnCloseChannel) This handler is executed when a channel close petition has arrived from remote peer.

    If you signal to close channel through vortex_channel_close, this handler is NOT executed, but it is executed when the given channel receive a remote channel close request. This handler should return axl_true if channel can be closed or axl_false if not.

    This can be convenient if there are more data to be sent and to be able to notify remote peer this is actually happening.

    This handler is optional. You can use NULL and the first level handler for close event will be used. If the first level handler is also not defined, a default handler will be used, which returns always axl_true. This means to agree to close the channel always.

    You can also define user data to be passed into close handler on its execution. This user data is close_user_data.

  • received handler: (see more info on vortex_handlers: VortexOnFrameReceived) This handler is executed when a channel receive a frame.

    As the same as close handler definition, if you provide a NULL value for this handler the first level handler will be executed. If this first level handler is not defined, frame is dropped.

As you can see, there are 2 level of handlers to be executed when events happens on channel life. You can also see vortex_profiles_register documentation. Also check out this section where is explained in more detail how frames are received.

Later, to be able to close and free the channels created you must use vortex_channel_close. DO NOT USE vortex_channel_free to close or free channel resources. This function is actually called by Vortex Library when the channel resources can be deallocated.

On channel creation, it could happen an application do not register the profile that is going to be used for the new channel. This is a problem because if you don't define the close, start or frame received many problems will appear.

By default, if vortex_channel_new detects you didn't register a profile, then the function will do it for you. On this automatic profile registration, vortex library will assign the default close and start handler which always replies axl_true to close and start channels, but frame received handler will still not defined.

As a consequence you must ensure to register a frame received handler at first level using vortex_profiles function or ensure to register a frame received handler for this function.

Again, you may be asking your self why not simply deny channel creation for those petition which didn't define frame received at any level. This is done because there are still more method to retrieve frames from remote peers, bypassing the frame received handlers (for the second and first levels).

This method can be used with vortex_channel_wait_reply which wait for a specific reply. Check out this section to know more about Wait Reply method.

NOTE: in threaded mode, channel creation process can fail, as the same as non-threaded mode, so you can also get a NULL value for both invocation models.

This executing model is slightly different from vortex_connection_new where the value returned must be checked with vortex_connection_is_ok.

You can check the error code returned by the remote peer if the channel creation fails (NULL value returned) by calling to vortex_connection_pop_channel_error.

NOTE2: especially under threaded-moded (activated if on_channel_created is defined) the channel reference can't be used until the channel reference is notified.

During the channel preparation, a reference starts to be available at the connection, and it is possible to get a reference to it (i.e. vortex_connection_get_channel or vortex_connection_get_channel_by_func). This is provided to avoid race conditions with other running threads during its preparation and to allow application level to do some provisioning on the channel (vortex_channel_set_data).

In short, do use the channel reference to send data until it was notified to be completely created.

Parameters
connectionsession where channel will be created.
channel_numthe channel number. Using 0 automatically set the next channel number free.
profilethe profile under the channel will be created.
closehandler to manage channel closing.
close_user_datauser data to be passed in to close handler.
receivedhandler to manage frame reception on channel.
received_user_datadata to be passed in to received handler.
on_channel_createdAn async callback where the channel creation is notified. Defining this callback makes the function to not block the caller.
user_datauser data to be passed in to on_channel_created.
Returns
The newly created channel or NULL if fails under non-threaded model. Under threaded model returned value will always be NULL and newly channel created will be notified on on_channel_created.

References EncodingUnknown, and vortex_channel_new_full().