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

### 5.37 libsrv

#### 5.37.1 Overview

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

#### 5.37.2 API

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

> backend: backend to use

> 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, char * local_url, char * remote_url, char * remote_ip, int remote_port, 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, u_int32_t physical_ticket_sig, u_int32_t logical_ticket_sig, u_int64_t logical_from_id, u_int64_t logical_to_id, char * message)

> backend: server backend to use

> connection: connection to use

> 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 (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 (char * remote_ip, int remote_port, int sock, 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, 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, char * [] argv, 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 (int mode)

> mode: 0 for check only, 1 for full test

> Runs the `srv` module test suite.

> 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