Allows to create a new BEEP session (connection) to the given host:port.
While working with BEEP frameworks, you need to create a new connection (VortexConnection), and over it, create channels (VortexChannel), which will allow you to send and receive data. Keep in mind connection doesn't send and receive data, this is actually done by channels.
Once you have created an connection, using this function, you can use vortex_channel_new function to create new channels, using the profile you have selected.
Profiles are semantic definitions, representing an agreement between peers for those message to be exchanged inside a channel, and what they mean. You can read the following tutorial to know more about profiles and how they interact with Vortex Library.
This function will block you until the connection is created with remote site or until timeout mechanism is reached. You can define vortex timeout for connections creation by using vortex_connection_timeout.
If the on_connected handler is defined the connection creation will be performed in an independent thread. This will allow the caller to keep on doing other tasks while the connection is being created. This means vortex_connection_new function will never block the caller if the on_connected handler is defined.
Inside the connection process, a session negotiation will take place. BEEP RFC defines that remote server peer must send its supported profiles. Due to this, VortexConnection will hold all remote supported profiles. You will need this information to know which profiles supports the remote peer, so you can check if your BEEP client application can actually talk to the remote server. Use vortex_connection_get_remote_profiles or vortex_connection_is_profile_supported for this issue.
BEEP framework also allows to define special features and localize options to be notified to the remote peer we are going to connect to. This is actually done by using vortex_greetings_set_features and vortex_greetings_set_localize. Values set on that function will be used for all connections created.
Once finished with the connection, at the client side, you have to call to vortex_connection_close function close and dispose the BEEP session.
If you are interested on getting notifications once your connection is broken, in unix environments know as "broken pipe", you can use the following handler:
At listener side, it could be required to get notifications about new incoming connections accepted, mainly to perform some special initialization task. Then you can use the following:
Additionally, you may be interested on securing the connection created using the TLS profile. This is actually done with vortex_tls_start_negotiation. Optionally, you can configure your Vortex Library client peer to automatically negotiate the TLS profile for every connection created, allowing to get from this function a connection that already have TLS profile activated. You can configure this behavior using vortex_connection_set_auto_tls.
Finally, while considering how to transport user space data that actually applies to the connection being created consider using vortex_connection_set_data and vortex_connection_set_data_full. This function will allow you to store user space data in a hash-index manner that could be automatically deallocated while using vortex_connection_set_data_full.