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 have 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 TRUE if channel can be closed or 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 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 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: on 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.
Because connection creation is made only once, and channel creation many, the model to check values for new channel created is to check if returned values is not NULL.
|connection ||session where channel will be created. |
|channel_num ||the channel number. Using 0 automatically assigns the next channel number free. |
|profile ||the profile under the channel will be created. |
|close ||handler to manage channel closing. |
|close_user_data ||user data to be passed in to close handler. |
|received ||handler to manage frame reception on channel. |
|received_user_data ||data to be passed in to received handler. |
|on_channel_created ||a callback to be able to make channel process to be async. |
|user_data ||user data to be passed in to on_channel_created.|
- 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.