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:
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).
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.
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.