Next: , Previous: , Up: C API   [Contents][Index]


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.


Next: , Previous: , Up: C API   [Contents][Index]