VortexConnection * vortex_listener_new ( VortexCtx ctx,
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 provides an on_ready callback, the listener will be notified on it, in a separated thread, once the process has finished. Check VortexListenerReady handler documentation which is on_ready handler type.

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 random free port. See this section for more info about on_ready parameter.

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 example to start a vortex listener server:

1 // On this example you'll find:
2 // - 3 handlers: frame_received, start_channel and
3 // close_channel (which handle the event
4 // they represent).
5 // - An entry point (main function) which creates a
6 // a simple listener server, using previous three
7 // basic handlers.
8 
9 // vortex context
10 VortexCtx * ctx = NULL;
11 
12 // a frame handler
13 void frame_received (VortexChannel * channel,
14  VortexConnection * connection,
15  VortexFrame * frame,
16  axlPointer user_data)
17 {
18  // Received a frame from the remote side.
19  // process it and reply to it if it is a MSG.
20  return;
21 }
22 
23 axl_bool start_channel (int channel_num,
24  VortexConnection * connection,
25  axlPointer user_data)
26 {
27  printf ("Received an start message=%d!!\n",
28  channel_num);
29  // if the async notifier returns axl_true, the channel
30  // is implicitly created, if axl_false is returned the
31  // channel creation is denied and a reply error
32  // is sent.
33  return axl_true;
34 }
35 
36 axl_bool close_channel (int channel_num,
37  VortexConnection * connection,
38  axlPointer user_data)
39 {
40  printf ("Got a close message notification!!\n");
41 
42  // if axl_true is returned, the channel is
43  // accepted to be closed. Otherwise the channel
44  // will not be closed and an error reply will be
45  // sent to the remote peer.
46  return axl_true;
47 }
48 int main (int argc, char ** argv) {
49 
50  VortexConnection * listener;
51 
52  // create a context
53  ctx = vortex_ctx_new ();
54 
55  // enable log to see whats going on
56  vortex_log_enable (ctx, axl_true);
57 
58  // init vortex library (and check its result!)
59  if (! vortex_init_ctx (ctx)) {
60  printf ("Unable to initialize vortex library\n");
61  exit (-1);
62  }
63 
64  // register a profile
65  vortex_profiles_register (ctx, "http://vortex.aspl.es/profiles/example",
66  start_channel, NULL,
67  close_channel, NULL,
68  frame_received, NULL);
69 
70  // now create a vortex server
71  listener = vortex_listener_new (ctx, "0.0.0.0", "3000", NULL, NULL);
72  if (! vortex_connection_is_ok (listener, axl_false)) {
73  printf ("ERROR: failed to start listener, error found (code: %d) %s\n",
74  vortex_connection_get_status (listener),
75  vortex_connection_get_message (listener));
76  reutrn -1;
77  }
78 
79  // wait for listener to finish (maybe due to vortex_exit call)
80  vortex_listener_wait (ctx);
81 
82  // end vortex internal subsystem (if no one have done it yet!)
83  vortex_ctx_exit (ctx, axl_true);
84 
85  // that's all to start BEEPing!
86  return 0;
87 }
Parameters
ctxThe context where the operation will be performed.
hostThe host to listen on.
portThe port to listen on.
on_readyA optional callback to get a notification when vortex listener is ready to accept requests.
user_dataA user defined pointer to be passed in to on_ready handler.
Returns
The listener connection created (represented by a VortexConnection reference). You must use vortex_connection_is_ok to check if the server was started.

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. In the case the listener was not started (because vortex_connection_is_ok returned axl_false), you must use vortex_connection_close to terminate the reference (NOT vortex_connection_shutdown).

Note about old connecting clients, previous to 1.1.3

Until Vortex Library 1.1.3, listener accepting incoming connections were sending the BEEP greetings reply just after the remote peer connects. However, this was changed to allow listener side developers to react, modify or deny greetings at such phase (CONNECTION_STAGE_PROCESS_GREETINGS_FEATURES), hooking into that event, waiting first for the client BEEP greetings (especially to check which features it is providing).

This behaviour causes problems with clients from previous releases which are waiting for the listener to issue its BEEP peer greetings (where the listener is also waiting) to issue theirs. That is, old client never connects because he never receives greetings from BEEP listener, and BEEP listener never sends its greetings because the client never sent its greetings (circular problem).

To solve this issue you can either update the connecting client software or configure your listener to don't wait for client greetings to send its greetings:

This problem do not affect to new clients connecting to old servers.

References VORTEX_IPv4.

Referenced by vortex_listener_parse_conf_and_start().