The next diagram represents the state machine executed when a message is sent by the OpenSIPS core or modules.

!! Transport API (@@trans@@)

// looks for the transport protocol that knows how to handle the proto and calls the corresponding add_listener() function
int add_listener(char* host, int proto, int port);

// used to tune connection attributes
int dst_fcntl(int id, union sockaddr_union* to, int attr, void *value);

// called by the transport protocol when a whole message was received
int recv_msg(char* buf, unsigned int len, struct receive_info* rcv_info);

// used to send a buffer over the network

union sockaddr_union* to, int id, char* buf, int len);

// the id of the protocol
int proto;

// the name of the protocol: UDP, SCTP. Used for detecting the outgoing/incoming socket
char *name;

// the default port for the protocol
int default_port;

// function called when the module is loaded
int (*proto_init)(void);

// function called to destroy the data initialized at startup
void (*proto_destroy)(void);

// adds a new listener read by the parser. The port might be missing, and the default_port is used further
int (*add_listener)(char* host, int port);

// binds the listener and returns a file descriptor (used by the WebSocket library)
int (*bind)(char *host, int port);

// connects to a different peer
int (*connect)(union sockaddr_union* to);

// initializes a new connection
int (*conn_init)(struct connection *conn, void *ctx);

// reads the data received on the connection
int (*recv)(struct connection *conn, void *ctx);

// used to send a buffer over the network
int (*send)(struct connection *conn, char* buf, int len);

// binds the interface and adds the socket to the listening sockets
int add_listener(char* host, int proto, int port);

// used to return a listener
struct socket_info* find_listener(union sockaddr_union* to, int proto);

// initializes the structures
int (*init_tcp)(void);

// initializes the listeners
int (*init_listeners)(void);

// destroys the TCP data
void (*destroy_udp)(void);

// returns the connection identified by either the id or the destination to
struct connection* (*conn_get)(int id, union sockaddr_union* to);

// used to tune connection attributes
int (*conn_fcntl)(struct connection *conn, int attr, void *value);

// initializes the TCP structures
int init_tcp(void);

// initializes the TCP listeners
int init_tcp_listeners(void);

// destroys the TCP data
void destroy_tcp(void);

// returns the connection identified by either the id or the destination to
struct connection* conn_get(int id, union sockaddr_union* to);

// used to tune connection attributes
int conn_fcntl(struct connection *conn, int attr, void *value);

// initializes the UDP structures
int init_udp(void);

// initializes the UDP listeners
int init_udp_listeners(void);

// destroys the UDP data
void destroy_udp(void);

void destroy_tcp(void); // destroys the TCP data

The following diagrams represent the execution flows for the TCP network protocol.

!!! Receive Message
The following scenario represents the state machine executed when a message is received.

|| http://opensips.org/images/opensips-TransportInterface-recv.png ||

!!! Send Message
The next diagram represents the state machine executed when a message is send by the OpenSIPS core or modules.
|| http://opensips.org/images/opensips-TransportInterface-send.png ||

|| http://opensips.org/images/opensips-TransportInterface-recv.png || http://opensips.org/images/opensips-TransportInterface-send.png ||

int dst_fcntl(int id, union sockaddr_union* to, int attr, void *value); // used to tune connection attributes

int proto; // the id of the protocol
char *name; // the name of the protocol: UDP, SCTP. Used for detecting the outgoing/incoming socket
int default_port; // the default port for the protocol
int (*proto_init)(void); // function called when the module is loaded
void (*proto_destroy)(void); // function called to destroy the data initialized at startup
int (*add_listener)(char* host, int port); // adds a new listener read by the parser. The port might be missing, and the default_port is used further
int (*bind)(char *host, int port); // binds the listener and returns a file descriptor (used by the WebSocket library)
int (*connect)(union sockaddr_union* to); // connects to a different peer
int (*conn_init)(struct connection *conn, void *ctx); // initializes a new connection
int (*recv)(struct connection *conn, void *ctx); // reads the data received on the connection
int (*send)(struct connection *conn, char* buf, int len); // used to send a buffer over the network

int add_listener(char* host, int proto, int port); // binds the interface and adds the socket to the listening sockets
struct socket_info* find_listener(union sockaddr_union* to, int proto); // used to return a listener

struct net_proto {
int (*init_tcp)(void); // initializes the structures
int (*init_listeners)(void); // initializes the listeners
void (*destroy_udp)(void); // destroys the TCP data
struct connection* (*conn_get)(int id, union sockaddr_union* to); // returns the connection identified by either the id or the destination to
int (*conn_fcntl)(struct connection *conn, int attr, void *value); // used to tune connection attributes
}
@]

!!! TCP network proto

[@
int init_tcp(void); // initializes the TCP structures
int init_tcp_listeners(void); // initializes the TCP listeners
void destroy_udp(void); // destroys the TCP data
struct connection* conn_get(int id, union sockaddr_union* to); // returns the connection identified by either the id or the destination to
int conn_fcntl(struct connection *conn, int attr, void *value); // used to tune connection attributes
@]


!!! UDP network proto

[@
int init_udp(void); // initializes the UDP structures
int init_udp_listeners(void); // initializes the UDP listeners
void destroy_udp(void); // destroys the UDP data

int proto; // the id of the protocol
char *name; // the name of the protocol: UDP, SCTP. Used for detecting the outgoing/incoming socket
int default_port; // the default port for the protocol
int (*proto_init)(void); // function called when the module is loaded
void (*proto_destroy)(void); // function called to destroy the data initialized at startup
int (*add_listener)(char* host, int port); // adds a new listener read by the parser. The port might be missing, and the default_port is used further
int (*bind)(char *host, int port); // binds the listener and returns a file descriptor (used by the WebSocket library)
int (*conn_init)(struct connection *conn, void *ctx); // initializes a new connection
int (*recv)(struct connection *conn, void *ctx); // reads the data received on the connection

int send_msg(struct socket_info *send_socket, int proto, \
union sockaddr_union* to, int id, char* buf, int len); // used to send a buffer over the network

int (*proto_init)(void); // function called when the module is loaded
void (*proto_destroy)(void); // function called to destroy the data initialized at startup

int init_tcp(void); // initializes the TCP structures
int init_tcp_listeners(void); // initializes the TCP listeners

The following diagrams represent the execution flows for the TCP network protocol. The left scenario represents the state machine executed when a message is received, and the right one when a message is sent.

In order to interact between the three layers, the Transport Interface will provide three different APIs: Application(@@app@@), Transport(@@trans@@) and Network(@@net@@).

!! Application API (@@app@@)

int add_listener(char* host, int proto, int port); // looks for the transport protocol that knows how to handle the proto and calls the corresponding add_listener() function
int recv_msg(char* buf, unsigned int len, struct receive_info* rcv_info); // called by the transport protocol when a whole message was received

!! Trasport API (@@trans@@)

int (*add_listener)(char* host, int port); // adds a new listener read by the parser. The port might be missing, and the default_port is used further
int (*bind)(char *host, int port); // binds the listener and returns a file descriptor (used by the WebSocket library)
int (*recv)(struct connection *conn, void *ctx); // reads the data received on the connection

!! Network API (@@net@@)

@]

!! Flow Charts

The following diagrams represent the execution flows in different scenarios. The left scenario is the state machine executed when a message is received, and the right one when a message is sent.

|| http://opensips.org/images/opensips-TransportInterface-recv.png || http://opensips.org/images/opensips-TransportInterface-recv.png ||

!! Application API

int add_listener(char* host, int proto, int port); // looks for the transport protocol that knows how to handle the proto and calls the corresponding add_listener() function

!! Trasport API

Each type of transport has to implement this structure

int proto; // the id of the protocol
char *name; // the name of the protocol: UDP, SCTP. Used for detecting the outgoing/incoming socket
int default_port; // the default port for the protocol
int add_listener(char* host, int port); // adds a new listener read by the parser. The port might be missing, and the default_port is used further
int get_listener_fd(char *host, int port); // creates a listener and returns a file descriptor (used by the WebSocket library)

!! Network API

!!! TCP network proto

int add_tcp_listener(char* host, int proto, int port); // binds the interface and adds the socket to the listening sockets
struct tcp_proto {

!!! Application API

struct app_proto {
int add_listener(char* host, int proto, int port); // adds a new listener read by the parser

!!! Trasport API

struct trans_proto {
int add_listener(char* host, int proto, int port); // ad
char *name; /* the name of the protocol: UDP, SCTP. Used for detecting the outgoing/incomming socket */
int default_port; /* the default port for the protocol */
int (*proto_init)(void); /* function called when the module is loaded */
void (*proto_destroy)(void); /* function called to destroy the data initialized at startup */
int (*send_sip_msg)(struct socket_info* send_sock,
int type, char* buf, unsigned len,
union sockaddr_union* to, int id); /* function used to send a sip message over whatever connection */
}

!!! Network API

struct net_proto {
char *name; /* the name of the protocol: TCP, TLS, WS. Mostly used for debugging */

int (*proto_init_listener)(struct socket_info *si); /* function called for each listener */
int (*proto_recv_msg)(struct connection* con); /* function called when data is available - errors are signaled in the connection */

@]

|| http://opensips.org/images/opensips-TransportInterface.png ||

The picture consists of three layers, from top down:
# OpenSIPS Core and Modules - here stand the already existing OpenSIPS modules and core functions, that send and receive SIP messages over the network. This layer will not suffer too many changes, only align to the new interface.
# Transport layer - here are the specific transport modules (such as UDP, SCTP, TCP, TLS, WebSocket) that handle the sending and receiving over the network. Some of these protocols will be implemented as separate modules that will be automatically loaded when used in the script, and some of them will be developed directly in OpenSIPS's core (i.e. UDP and TCP).
# Network layer - this layer takes care of the listeners and connections management, and provides an interface for the TCP reactor.

The last two points above will represent a separation of the current TCP/UDP implementations and will suffer major changes.

In order to interact between the three layers, the Transport Interface will provide three different APIs: Application, Transport and Network.

Another function that the TCP Interface has to provide is a way to control the interaction with the TCP reactor. The signature can be something like this:
[@
int tcp_op(struct connection *con, int op);
@]

This structure has to be implemented by each module that uses TCP/UDP, such as TLS and Websocket and registers to the TCP/UDP interface.

struct net_proto {

int (*proto_recv_msg)(struct connection* con); /* function called when data is available - errors are signaled in the connection */

The @@connection@@ structure should contain a "handler" to the connection, a buffer, and the number of bytes read.
TODO: should we keep a static buffer and each implementation copies its data into the connection buffer?

For sending messages, the TCP/UDP Interfaces have to "advertise" a function that can send the buffer over a TCP connection. The signature should look like this:

int buffer_send(struct socket_info* send_sock, int type, char* buf, unsigned len, union sockaddr_union* to, int id);
@]
This function sends the encoded bytes in the buffer.

!!! Transport Interface

This structure has to be implemented by each module and registers to the transport interface in OpenSIPS.
[@
struct trans_proto {
char *name; /* the name of the protocol: UDP, SCTP. Used for detecting the outgoing/incomming socket */
int default_port; /* the default port for the protocol */
int (*proto_init)(void); /* function called when the module is loaded */
void (*proto_destroy)(void); /* function called to destroy the data initialized at startup */
int (*send_sip_msg)(struct socket_info* send_sock,
int type, char* buf, unsigned len,
union sockaddr_union* to, int id); /* function used to send a sip message over whatever connection */
}
@]

When the messages receive an entire message, they call the @@receive_msg@@ function that is already implemented.

|| %color=#185662%[+'''Transport Interface Design'''+]%% ||

\\

This document contains the design of the new Transport Interface that will be deployed in '''OpenSIPS 2.1'''.

----

!! Description

The current transport protocols (UDP, TCP, TLS, etc.) are embedded directly in the OpenSIPS core. This makes the management of these protocols in script more difficult and also complicates the addition of new ones (such as WebSockets).

In order to simplify this, we designed a new Transport Interface that aims to provide a new transport layer in OpenSIPS's core. This interface will separate the network level transport protocols (such as TCP and UDP) from higher level, SIP aware, protocols (such as TLS, WebSocket, SCTP). This clear separation will facilitate the addition of higher level protocols while efficiently reusing the lower network level protocols implementations.

!! Design

The architecture of the new Transport Interface is presented in the picture below.

|| http://opensips.org/images/opensips-transport-interface.png ||

The picture can be split in three layers, from bottom up:
# Transport layer - contains the primitive network transport protocols, such as TCP and UDP. This layer will manage all the connections in an efficient and centralized manner.
# SIP layer - consists of several protocols that use the transport layer to send and receive messages to and from the network, while being SIP aware. These modules will not do any connection managing, but only process the data received from the transport layer according to SIP requirements. The protocols (SCTP, TLS, WebSocket) will be implemented as standalone modules and will be automatically loaded when listening interfaces are defined for them.
# Routing layer - here stand the OpenSIPS modules and core that will use a set of simple generic send/receive functions. The underneath transport protocol will be transparent for them.

!! API

!!! TCP Interface

This structure has to be implemented by each module that uses TCP, such as TLS and Websocket and registered to the TCP interface.
[@
struct tcp_proto {
char *name; /* the name of the protocol: TCP, TLS, WS. Mostly used for debugging */
int default_port; /* the default port for the protocol */
int (*proto_init)(void); /* function called when the module is loaded */
void (*proto_destroy)(void); /* function called to destroy the data initialized at startup */
int (*proto_init_listener)(struct socket_info *si); /* function called for each listener */
int (*proto_recv_msg)(struct tcp_connection* con); /* function called when data is available */
}
@]

The @@tcp_connection@@ structure should contains a "handler" to the connection, a buffer, and the number of bytes read. TODO: should we keep a static buffer and each implementation copies its data into the connection buffer?

For sending messages, the TCP Interface has to "advertise" a function that can send the buffer over a TCP connection. The signature should look like this:
[@
int tcp_send(struct socket_info* send_sock, int type, char* buf, unsigned len, union sockaddr_union* to, int id);
@]