VortexConnection * vortex_listener_new ( const char *  host,
const char *  port,
VortexListenerReady  on_ready,
axlPointer  user_data 
)

Creates a new Vortex Listener accepting incoming connections on the given host:port configuration.

If user provies an on_ready callback, it will be notified on it, in a separated thread, once the process have finished. Check documentation for the VortexListenerReady handler which is the async definition for on_ready handler.

On that notification will also be passed the host and port actually allocated. Think about using as host 0.0.0.0 and port 0. These values will cause to vortex_listener_new to allocate the system configured hostname and a randomly free port. See this section for more info about on_ready.

Host and port value provided to this function could be unrefered once returning from this function. The function performs a local copy for those values, that are deallocated at the appropriate moment.

Keep in mind that you can actually call several times to this function before calling to vortex_listener_wait, to make your process to be able to accept connections from several ports and host names at the same time.

While providing the port information, make sure your process will have enough rights to allocate the port provided. Usually, ports from 1 to 1024 are reserved to listener programms that runs with priviledges.

There is an alternative API that perform the same function but receive the TCP port value as integer: vortex_listener_new2

In the case the optional handler on_ready is not provided, the function will return a reference to the VortexConnection representing the listener created. This reference will have the role VortexRoleMasterListener, (using vortex_connection_get_role) to indicate that the connection reference is a listener.

In the case the on_ready handler is provided, the function will return NULL.

Here is an little example to start a vortex listener server:

 // On this example you'll find:
 //   - 3 handlers: frame_received, start_channel and
 //                 close_channel (which handle the event
 //                 they represent).
 //   - An entry point (main function) which creates a
 //     a simple listener server, using previous three
 //     basic handlers.

 // a frame handler
 void frame_received (VortexChannel    * channel,
                      VortexConnection * connection,
                      VortexFrame      * frame,
                      axlPointer         user_data)
 {
        // Received a frame from the remote side.
        // process it and reply to it if it is a MSG.
        return;
 }

 axl_bool  start_channel (int                channel_num, 
                          VortexConnection * connection, 
                          axlPointer         user_data)
 {
        printf ("Received an start message=%d!!\n",
                 channel_num);
        // if the async notifier returns axl_true, the channel
        // is implicitly created, if axl_false is returned the
        // channel creation is denied and a reply error
        // is sent.
        return axl_true;
 }

 axl_bool      close_channel (int                channel_num, 
                              VortexConnection * connection, 
                              axlPointer         user_data)
 {
        printf ("Got a close message notification!!\n");

        // if axl_true is returned, the channel is
        // accepted to be closed. Otherwise the channel
        // will not be closed and an error reply will be
        // sent to the remote peer.
        return axl_true;
 }
 int main (int argc, char ** argv) {
      // enable log to see whats going on 
      vortex_log_enable (axl_true);
      
      // init vortex library (and check its result!)
      if (! vortex_init ()) {
           printf ("Unable to initialize vortex library\n");
           exit (-1);
      }
 
      // register a profile
      vortex_profiles_register ("http://vortex.aspl.es/profiles/example", 
                                start_channel, NULL,
                                close_channel, NULL,
                                frame_received, NULL);
 
      // now create a vortex server
      vortex_listener_new ("0.0.0.0", "3000", NULL, NULL);
      
      // wait for listener to finish (maybe due to vortex_exit call)
      vortex_listener_wait ();
  
      // end vortex internal subsystem (if no one have done it yet!)
      vortex_exit ();
 
      // that's all to start BEEPing!
      return 0;     
 }  

Parameters:
host The host to listen to.
port The port to listen to.
on_ready A optional notify callback to get when vortex listener is ready to perform replies.
user_data A user defined pointer to be passed in to on_ready handler.
Returns:
The listener connection created, or NULL if the optional handler is provided (on_ready).
NOTE: the reference returned is only owned by the vortex engine. This is not the case of vortex_connection_new where the caller acquires automatically a reference to the connection (as well as the vortex engine).

In this case, if your intention is to keep a reference for later operations, you must call to vortex_connection_ref to avoid losing the reference if the system drops the connection. In the same direction, you can't call to vortex_connection_close if you don't own the reference returned by this function.

To close immediately a listener you can use vortex_connection_shutdown.