VortexConnection * vortex_connection_new_full ( VortexCtx ctx,
const char *  host,
const char *  port,
VortexConnectionOpts options,
VortexConnectionNew  on_connected,
axlPointer  user_data 

Allows to create a new BEEP session (connection) to the given host:port using provided options.

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 (if configured). You can define the connect timeout by using vortex_connection_connect_timeout. Note that if nothing is configured, no timeout is implemented. There is also a separate timeout that is used for general receive operations: vortex_connection_timeout (though this timeout is not used for this connect operation).

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.

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_tls_set_auto_tls.

Check out the documentation for vortex_tls_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.

ctxThe context where the operation will be performed.
hostThe remote peer to connect to.
portThe peer's port to connect to.
optionsAdditional connection options to be used for this particular operation. This is mainly used to provide feature notification to remote BEEP listener. See vortex_connection_opts_new and VortexConnectionOptItem for more details.
on_connectedOptional handler to process connection new status.
user_dataOptional handler to process connection new status
A newly created VortexConnection if called in a blocking manner, that is, without providing the on_connected handler. If you provide the on_connected handler, the function will return NULL, and the connection created will be notified on the handler on_connected. In both cases, you must use vortex_connection_is_ok to check if you are already connected.

Note about reference returned by this function

VortexConnection and VortexChannel objects implements a reference counting that tries to be as much automatic as possible.

In this context, when you actively create a connection, via vortex_connection_new (or this one), you are acquiring a reference that must be terminated either with vortex_connection_close, or if you know that you are doing, with vortex_connection_unref.

At the same time, the connection you create is also used by vortex internals (specially vortex reader) which also acquires a reference to the connection, to ensure he can access to those connections even if the user has closed it.

Having said that, let's take a look at the listener side.

What happens when you receive a server side notification, that involves a connection you didn't create and your code has no reference to it? How do you release that memory when server stops, or a connection is closed?

As you are guessing, those connections has references that are only owned by your vortex engine at the listener side, and temporally, those references are incremented to implement handler notifications, but, again, those references will be removed when those listener side handler finishes.

Now, assuming this context, you now know that a vortex_connection_close is not required at the listener side, because you didn't create that connection, and that those connections will be eventually collected, and that you must do a vortex_connection_close at client side because you did create the connection, not only to initiate the BEEP close protocol, but to also release the reference you acquired previously.

Calling to create connections when vortex is being finished or uninitialized

If a call to vortex_exit_ctx was done before calling to create a new connection, then the function will return NULL.

Referenced by vortex_connection_new().