Next: , 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