libsrv - Liquid War 6
Description: Liquid War 6

Next: mod-httpd, Previous: mod-ogg, Up: C API

### 5.43 libsrv

#### 5.43.1 Overview

View lcov test coverage results on http://www.ufoot.org/liquidwar/v6/doc/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: int lw6srv_can_send (lw6srv_backend_t * backend, lw6cnx_connection_t * connection)

> backend: server backend to use

> connection: connection to use

> Tells wether a server connection can technically send messages. This does not garantee send will succeed, but if it's not OK at this stage, it's not even worth trying.

> Return value: 1 if it can be used to send messages, 0 if not ready.

— 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 (const 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: can_send

> Type: `int(*`

> Definition: `int(* lw6srv_backend_s::can_send)(void *srv_context, lw6cnx_connection_t *connection)`

> Pointer on lw6srv_can_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: `volatile 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.