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.
Optionally you can define an on_connected handler to process response, avoiding getting blocked on vortex_connection_new call.
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.
To actually get features and localize requested by the peer we have connected to, you have to use vortex_connection_get_features and vortex_connection_get_localize.
Additionally, you may be interesting on securing the connection created using the TLS profile. This is actually done with vortex_tls_start_negociation. 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.
Check out the documentation for vortex_connection_set_auto_tls to know more about using automatic TLS profile negotiation.
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.
|host ||The remote peer to connect to. |
|port ||The peer's port to connect to. |
|on_connected ||Optional handler to process connection new status. |
|user_data ||Optional handler to process connection new status|
- a new VortexConnection. You should use vortex_connection_is_ok to check if you have already connected.