Next: mod-httpd, Previous: mod-ogg, Up: C API [Contents][Index]

### 5.43 libsrv

#### 5.43.1 Overview

View lcov test coverage results on http://www.gnu.org/software/liquidwar6/coverage/src/lib/srv/index.html.

#### 5.43.2 API

Function: int lw6srv_init (lw6srv_backend_t * backend, lw6srv_listener_t * listener)

  backend: backend to use

  listener: listener object to use when constructing the backend.

  Initializes a server backend. Must be performed before any other call.

  Return value: 1 on success, 0 on failure

Function: void lw6srv_quit (lw6srv_backend_t * backend)

  backend: unitialize a srv backend

  Closes a srv, but does not free all ressources.

Function: int lw6srv_analyse_tcp (lw6srv_backend_t * backend, lw6srv_tcp_accepter_t * tcp_accepter, lw6nod_info_t * node_info, u_int64_t * remote_id, char ** remote_url)

  backend: server backend to use

  tcp_accepter: TCP mode accepter

  node_info: this node information

  remote_id: remote host id (out param)

  remote_url: remote host URL (out param, dynamically allocated)

  Analyzes new TCP messages, typically handled within the accepter object. The result is a combination of bitwise flags, namely namely `LW6SRV_ANALYSE_DEAD`, `LW6SRV_ANALYSE_UNDERSTANDABLE`, and `LW6SRV_ANALYSE_OOB` which helps knowing what to do with message.

  Return value: bitwise flag.

Function: int lw6srv_analyse_udp (lw6srv_backend_t * backend, lw6srv_udp_buffer_t * udp_buffer, lw6nod_info_t * node_info, u_int64_t * remote_id, char ** remote_url)

  backend: server backend to use

  udp_buffer: UDP buffer

  node_info: this node information

  remote_id: remote host id (out param)

  remote_url: remote host URL (out param, dynamically allocated)

  Analyzes an UDP buffer, received on a socket. The result is a combination of bitwise flags, namely namely `LW6SRV_ANALYSE_DEAD`, `LW6SRV_ANALYSE_UNDERSTANDABLE`, and `LW6SRV_ANALYSE_OOB` which helps knowing what to do with message.

  Return value: bitwise flag.

Function: int lw6srv_process_oob (lw6srv_backend_t * backend, lw6nod_info_t * node_info, lw6srv_oob_data_t * oob_data)

  backend: server backend to use

  node_info: this node information

  oob_data: OOB data received

  Processes an OOB message sent from a client.

  Return value: 1 if OK, 0 if not.

Function: lw6cnx_connection_t * lw6srv_open (lw6srv_backend_t * backend, lw6srv_listener_t * listener, const char * local_url, const char * remote_url, const char * remote_ip, int remote_port, const char * password, u_int64_t local_id, u_int64_t remote_id, int dns_ok, int network_reliability, lw6cnx_recv_callback_t recv_callback_func, void * recv_callback_data)

  backend: server backend to use

  local_url: local url to use (to send to peer)

  remote_url: remote url to communicate with

  remote_ip: remote ip to communicate with

  remote_port: remote port to communicate with

  password: password to use (the real password, not a hash)

  local_id: the local 64-bit id

  remote_id: the remove 64-bit id

  dns_ok: 1 if no DNS mismatch, 0 if situation is unclear

  network_reliability: the greater, the more reliable it is

  recv_callback_func: callback fired when receiving data

  recv_callback_data: additionnal data passed to callback

  Opens a server connection. One might wonder, clients open connections, but servers? To some extent, this is the equivalent of `accept` in the socket API, it will actually create an object one can then use to communicate. Be carefull with the implementation of the callback, keep in mind it can be called any time in multithreaded mode, you need to set up locks when accessing shared objects, including, but not limited to, your own data buffers.

  Return value: new connection object.

Function: int lw6srv_feed_with_tcp (lw6srv_backend_t * backend, lw6cnx_connection_t * connection, lw6srv_tcp_accepter_t * tcp_accepter)

  connection: connection to use

  tcp_accepter: TCP accepter holding data

  When data is receivedm feeds the server object with data. Will typically fire the callback receive function if there are actually some data stuff.

  Return value: 1 some data processed, else 0

Function: int lw6srv_feed_with_udp (lw6srv_backend_t * backend, lw6cnx_connection_t * connection, lw6srv_udp_buffer_t * udp_buffer)

  connection: connection to use

  When data is receivedm feeds the server object with data. Will typically fire the callback receive function if there are actually some data stuff.

  Return value: 1 some data processed, else 0

Function: void lw6srv_close (lw6srv_backend_t * backend, lw6cnx_connection_t * connection)

  backend: server backend to use

  connection: connection to close

  Closes a connection, will also free it.

  Return value: none.

Function: int lw6srv_send (lw6srv_backend_t * backend, lw6cnx_connection_t * connection, int64_t now, u_int32_t physical_ticket_sig, u_int32_t logical_ticket_sig, u_int64_t logical_from_id, u_int64_t logical_to_id, const char * message)

  backend: server backend to use

  connection: connection to use

  now: current timestamp

  physical_ticket_sig: physical ticket

  logical_ticket_sig: logical ticket

  logical_from_id: logical id of sender

  logical_to_id: logical id of receiver

  message: string with the message to send

  Sends a message. The added value with a plain send is that it handles all the special ticket fields.

  Return value: 1 on success, 0 if not

Function: void lw6srv_poll (lw6srv_backend_t * backend, lw6cnx_connection_t * connection)

  backend: server backend to use

  connection: connection to use

  Polling function, to be called on a regular basis.

  Return value: none.

Function: char * lw6srv_repr (lw6srv_backend_t * backend, lw6cnx_connection_t * connection)

  backend: backend to use

  connection: connection to represent

  Gives a human readable representation of the connection.

  Return value: dynamically allocated string.

Function: lw6srv_listener_t * lw6srv_start (const char * ip, int port)

  ip: ip address to listen on

  port: port IP to bind to

  Starts a server, binds the socket(s) and returns a listener object which can in turn be used to create connections.

  Return value: new listener object.

Function: void lw6srv_stop (lw6srv_listener_t * listener)

  listener: listener to stop

  Stops a listener object, and frees it.

  Return value: none.

Function: lw6srv_oob_t * lw6srv_oob_new (const char * remote_ip, int remote_port, int sock, const char * first_line)

  remote_ip: remote IP address

  remote_port: remote port

  sock: the socket handler (either TCP or UDP)

  first_line: the first line of data (can be NULL)

  Create a new OOB structure, copying required objects. We need to make copies for this is for usage in a separate thread. The thread member is not set here since the right way to do things is first to set up data then to fire the thread.

  Return value: new object

Function: void lw6srv_oob_free (lw6srv_oob_t * oob)

  oob: the object to free

  Frees an OOB structure.

  Return value: none

Function: char * lw6srv_default_backends ()

  Returns the list of the default srv backends.

  Return value: comma separated string, must not be freed.

Function: lw6sys_assoc_t * lw6srv_get_backends (int argc, const char * [] argv)

  argc: argc, as passed to `main`

  argv: argv, as passed to `main`

  List available srv backends. The hash contains pairs with id and name for each backend. The id is the technical key you can use to load the backend, the name is something more readable you can display in an interface. The backend objects themselves are not instanciated by this (in fact, they are, but released on the fly) you need to load and initialize them afterwards.

  Return value: hash containing id/name pairs.

Function: lw6srv_backend_t * lw6srv_create_backend (int argc, const char * [] argv, const char * name)

  argc: argc, as passed to `main`

  argv: argv, as passed to `main`

  name: string containing srv key, typically got from `lw6srv_get_backends`

  Creates a srv backend, this is just about loading the dynamic library if needed, and/or check srv engine is available, and connect to it. It does not perform initialization.

  Return value: srv backend.

Function: void lw6srv_destroy_backend (lw6srv_backend_t * backend)

  backend: backend to destroy

  Destroys a srv backend.

  Return value: none.

Function: lw6srv_tcp_accepter_t * lw6srv_tcp_accepter_new (char * client_ip, int client_port, int sock)

  client_ip: the client ip, will be freed when accepter is freed, do not copy it

  client_port: the client port

  sock: the socket used

  Creates a tcp_accepter object.

  Return value: none

Function: void lw6srv_tcp_accepter_free (lw6srv_tcp_accepter_t * tcp_accepter)

  tcp_accepter: the object to free

  Frees a tcp_accepter object.

  Return value: none

Function: int lw6srv_test_register (int mode)

  mode: test mode (bitmask)

  Registers all tests for the libsrv module.

  Return value: 1 if test is successfull, 0 on error.

Function: int lw6srv_test_run (int mode)

  mode: test mode (bitmask)

  Runs the `srv` module test suite, testing most (if not all...) functions.

  Return value: 1 if test is successfull, 0 on error.

Function: lw6srv_udp_buffer_t * lw6srv_udp_buffer_new (char * client_ip, int client_port, char * line)

  client_ip: the client ip, will be freed when object is freed, do not free it

  client_port: the client port

  line: the line received, will be freed when object is freed, do not free it

  Creates an udp_buffer object.

  Return value: none

Function: void lw6srv_udp_buffer_free (lw6srv_udp_buffer_t * udp_buffer)

  udp_buffer: the object to free

  Frees a udp_buffer object.

  Return value: none

Struct: lw6srv_backend_s

  The srv backend is the first argument passed to any srv function, it contains reference to all the functions which can be used as well as a pointer on associated data. In OO, this would just be an object, with members and methods, using polymorphism through opaque pointers.

Member of lw6srv_backend_s: dl_handle

  Type: `lw6dyn_dl_handle_t *`

  Definition: `lw6dyn_dl_handle_t* lw6srv_backend_s::dl_handle`

  Handle on dynamic library (if it makes sense).

Member of lw6srv_backend_s: srv_context

  Type: `void *`

  Definition: `void* lw6srv_backend_s::srv_context`

  Srv specific data, what is behind this pointer really depends on the srv engine.

Member of lw6srv_backend_s: argc

  Type: `int`

  Definition: `int lw6srv_backend_s::argc`

  The argc value passed to main.

Member of lw6srv_backend_s: argv

  Type: `const char **`

  Definition: `const char** lw6srv_backend_s::argv`

  The argv value passed to main.

Member of lw6srv_backend_s: id

  Type: `u_int32_t`

  Definition: `u_int32_t lw6srv_backend_s::id`

  The id of the object, this is non-zero and unique within one run session, incremented at each object creation.

Member of lw6srv_backend_s: name

  Type: `char *`

  Definition: `char* lw6srv_backend_s::name`

  Module name.

Member of lw6srv_backend_s: properties

  Type: `lw6cnx_properties_t`

  Definition: `lw6cnx_properties_t lw6srv_backend_s::properties`

  General backend properties.

Member of lw6srv_backend_s: info

  Type: `lw6nod_info_t *`

  Definition: `lw6nod_info_t* lw6srv_backend_s::info`

  Information about local node.

Member of lw6srv_backend_s: init

  Type: `void *(*`

  Definition: `void*(* lw6srv_backend_s::init)(int argc, const char *argv[], lw6cnx_properties_t *properties, lw6srv_listener_t *listener)`

  Pointer on lw6srv_init callback code.

Member of lw6srv_backend_s: quit

  Type: `void(*`

  Definition: `void(* lw6srv_backend_s::quit)(void *srv_context)`

  Pointer on lw6srv_quit callback code.

Member of lw6srv_backend_s: analyse_tcp

  Type: `int(*`

  Definition: `int(* lw6srv_backend_s::analyse_tcp)(void *srv_context, lw6srv_tcp_accepter_t *tcp_accepter, lw6nod_info_t *node_info, u_int64_t *remote_id, char **remote_url)`

  Pointer on lw6srv_analyse_tcp callback code.

Member of lw6srv_backend_s: analyse_udp

  Type: `int(*`

  Definition: `int(* lw6srv_backend_s::analyse_udp)(void *srv_context, lw6srv_udp_buffer_t *udp_buffer, lw6nod_info_t *node_info, u_int64_t *remote_id, char **remote_url)`

  Pointer on lw6srv_analyse_udp callback code.

Member of lw6srv_backend_s: process_oob

  Type: `int(*`

  Definition: `int(* lw6srv_backend_s::process_oob)(void *srv_context, lw6nod_info_t *node_info, lw6srv_oob_data_t *oob_data)`

  Pointer on lw6srv_process_oob callback code.

Member of lw6srv_backend_s: open

  Type: `lw6cnx_connection_t *(*`

  Definition: `lw6cnx_connection_t*(* lw6srv_backend_s::open)(void *srv_context, lw6srv_listener_t *listener, const char *local_url, const char *remote_url, const char *remote_ip, int remote_port, const char *password, u_int64_t local_id, u_int64_t remote_id, int dns_ok, int network_reliability, lw6cnx_recv_callback_t recv_callback_func, void *recv_callback_data)`

  Pointer on lw6srv_open callback code.

Member of lw6srv_backend_s: feed_with_tcp

  Type: `int(*`

  Definition: `int(* lw6srv_backend_s::feed_with_tcp)(void *srv_context, lw6cnx_connection_t *connection, lw6srv_tcp_accepter_t *tcp_accepter)`

  Pointer on lw6srv_feed_with_tcp callback code.

Member of lw6srv_backend_s: feed_with_udp

  Type: `int(*`

  Definition: `int(* lw6srv_backend_s::feed_with_udp)(void *srv_context, lw6cnx_connection_t *connection, lw6srv_udp_buffer_t *udp_buffer)`

  Pointer on lw6srv_feed_with_udp callback code.

Member of lw6srv_backend_s: close

  Type: `void(*`

  Definition: `void(* lw6srv_backend_s::close)(void *srv_context, lw6cnx_connection_t *connection)`

  Pointer on lw6srv_close callback code.

Member of lw6srv_backend_s: send

  Type: `int(*`

  Definition: `int(* lw6srv_backend_s::send)(void *srv_context, lw6cnx_connection_t *connection, int64_t now, u_int32_t physical_ticket_sig, u_int32_t logical_ticket_sig, u_int64_t logical_from_id, u_int64_t logical_to_id, const char *message)`

  Pointer on lw6srv_send callback code.

Member of lw6srv_backend_s: poll

  Type: `void(*`

  Definition: `void(* lw6srv_backend_s::poll)(void *srv_context, lw6cnx_connection_t *connection)`

  Pointer on lw6srv_poll callback code.

Member of lw6srv_backend_s: repr

  Type: `char *(*`

  Definition: `char*(* lw6srv_backend_s::repr)(void *srv_context, lw6cnx_connection_t *connection)`

  Pointer on lw6srv_repr callback code.

Struct: lw6srv_client_id_s

  Parsed client ID, this is not the numerical 64-bit ID but an IP:port pair which uniquely and physically identifies the peer.

Member of lw6srv_client_id_s: client_ip

  Type: `char *`

  Definition: `char* lw6srv_client_id_s::client_ip`

  Client IP address, as a string.

Member of lw6srv_client_id_s: client_port

  Type: `int`

  Definition: `int lw6srv_client_id_s::client_port`

  Client IP port.

Struct: lw6srv_listener_s

  The listener is the object which listens on the network and can create tcp accepters or udp buffers depending on what is received.

Member of lw6srv_listener_s: ip

  Type: `char *`

  Definition: `char* lw6srv_listener_s::ip`

  IP address we are binded to.

Member of lw6srv_listener_s: port

  Type: `int`

  Definition: `int lw6srv_listener_s::port`

  IP port we are binded to.

Member of lw6srv_listener_s: tcp_sock

  Type: `int`

  Definition: `int lw6srv_listener_s::tcp_sock`

  TCP socket, binded in listening mode.

Member of lw6srv_listener_s: tcp_accepters

  Type: `lw6sys_list_t *`

  Definition: `lw6sys_list_t* lw6srv_listener_s::tcp_accepters`

  List of lw6srv_tcp_accepter_t objects, created when data is received.

Member of lw6srv_listener_s: udp_sock

  Type: `int`

  Definition: `int lw6srv_listener_s::udp_sock`

  UDP socket, binded.

Member of lw6srv_listener_s: udp_buffers

  Type: `lw6sys_list_t *`

  Definition: `lw6sys_list_t* lw6srv_listener_s::udp_buffers`

  List of lw6srv_udp_buffer_t objects, created when data is received.

Struct: lw6srv_oob_data_s

  Used to store out of band data. Typically, when data is recognized as out of band, it’s treated in a separate thread, and not mainstream. This is both because out-of-band data is the default (anything not recognized and/or not trusted is OOB) and because this can easily be treated separately as all we need is to server nearly static informations.

Member of lw6srv_oob_data_s: creation_timestamp

  Type: `int64_t`

  Definition: `int64_t lw6srv_oob_data_s::creation_timestamp`

  Date of the request.

Member of lw6srv_oob_data_s: do_not_finish

  Type: `int`

  Definition: `int lw6srv_oob_data_s::do_not_finish`

  Used to interrupt the OOB process before it’s over.

Member of lw6srv_oob_data_s: remote_ip

  Type: `char *`

  Definition: `char* lw6srv_oob_data_s::remote_ip`

  IP address of peer.

Member of lw6srv_oob_data_s: remote_port

  Type: `int`

  Definition: `int lw6srv_oob_data_s::remote_port`

  IP port of peer.

Member of lw6srv_oob_data_s: sock

  Type: `int`

  Definition: `int lw6srv_oob_data_s::sock`

  Socket used, can either be TCP or UDP, depends on backend.

Member of lw6srv_oob_data_s: first_line

  Type: `char *`

  Definition: `char* lw6srv_oob_data_s::first_line`

  First line of data.

Struct: lw6srv_oob_s

  Used to handle OOB requests. This is a container over the OOB data and its treatment thread.

Member of lw6srv_oob_s: thread

  Type: `lw6sys_thread_handler_t *`

  Definition: `lw6sys_thread_handler_t* lw6srv_oob_s::thread`

  Thread use to handle the data.

Member of lw6srv_oob_s: data

  Type: `lw6srv_oob_data_t`

  Definition: `lw6srv_oob_data_t lw6srv_oob_s::data`

  The OOB data, what we received from the network.

Struct: lw6srv_tcp_accepter_s

  A TCP accepter is an object which is created after a listening socket received some random information (in TCP mode, hence its name). Itprovides basic support to accept/reject requests and choose the right protocol/backend for the answer.

Member of lw6srv_tcp_accepter_s: client_id

  Type: `lw6srv_client_id_t`

  Definition: `lw6srv_client_id_t lw6srv_tcp_accepter_s::client_id`

  Where the data does come from.

Member of lw6srv_tcp_accepter_s: sock

  Type: `int`

  Definition: `int lw6srv_tcp_accepter_s::sock`

  Socket returned by the accept POSIX function, this is the one we can use to reply and send data back.

Member of lw6srv_tcp_accepter_s: first_line

  Type: `char`

  Definition: `char lw6srv_tcp_accepter_s::first_line[LW6SRV_PROTOCOL_BUFFER_SIZE+1]`

  First line received over the network. This is "peeked" so it’s still available for the actual backend, in fact that’s the very thing we need an object for, with the information "these bytes came from ip:port" one can take a decision on what to do with the request.

Member of lw6srv_tcp_accepter_s: creation_timestamp

  Type: `int64_t`

  Definition: `int64_t lw6srv_tcp_accepter_s::creation_timestamp`

  Timestamp of accepter creation. This is more or less the same that the instant we received data on the network. There’s a small lag, but not that bad. This is mostly used for timeout.

Struct: lw6srv_udp_buffer_s

  A UDP datagram, this structure contains both the data and information about who sent it.

Member of lw6srv_udp_buffer_s: client_id

  Type: `lw6srv_client_id_t`

  Definition: `lw6srv_client_id_t lw6srv_udp_buffer_s::client_id`

  Where the data does come from.

Member of lw6srv_udp_buffer_s: line

  Type: `char *`

  Definition: `char* lw6srv_udp_buffer_s::line`

  The data itself. This is typically a C-string with a 0 char at the end, anything else will be rejected anyway.

Next: mod-httpd, Previous: mod-ogg, Up: C API [Contents][Index]