Development |
Development.TransportInterfaceAPI HistoryHide minor edits - Show changes to markup February 02, 2015, at 04:21 PM
by
- Changed line 158 from:
The next diagram represents the state machine executed when a message is send by the OpenSIPS core or modules. to:
The next diagram represents the state machine executed when a message is sent by the OpenSIPS core or modules. February 02, 2015, at 03:09 PM
by
- Changed line 47 from:
Trasport API (
|
http://opensips.org/images/opensips-TransportInterface-recv.png | http://opensips.org/images/opensips-TransportInterface-send.png |
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-recv.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 (*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 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
TCP network proto
int init_tcp(void); // initializes the TCP structures int init_tcp_listeners(void); // initializes the TCP listeners int add_tcp_listener(char* host, int proto, int port); // binds the interface and adds the socket to the listening sockets
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 (*recv)(struct connection *conn, void *ctx); // reads the data received on the connection
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 (*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 */
int init_tcp(void); // initializes the TCP structures int init_tcp_listeners(void); // initializes the TCP listeners
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 connection* con); /* function called when data is available - errors are signaled in the connection */
}
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.
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, Transport and Network.
Application API
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 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
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 get_listener_fd(char *host, int port); // creates a listener and returns a file descriptor (used by the WebSocket library)
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
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 |
API
Application API
Application API
struct app_proto {
int add_listener(char* host, int proto, int port); // adds a new listener read by the parser
}
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
Trasport API
Each type of transport has to implement this structure
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; // 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
Network API
TCP network proto
struct net_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 {
TCP Interface
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.
Application API
struct net_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 connection* con); /* function called when data is available - errors are signaled in the connection */
struct app_proto {
int add_listener(char* host, int proto, int port); // adds a new listener read by the parser
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:
Trasport API
int buffer_send(struct socket_info* send_sock, int type, char* buf, unsigned len, union sockaddr_union* to, int id);
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 */
}
This function sends the encoded bytes in the buffer.
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:
Network API
int tcp_op(struct connection *con, int op); @]
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 */
struct net_proto {
char *name; /* the name of the protocol: TCP, TLS, WS. Mostly used for debugging */
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 */
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 */
@]
When the messages receive an entire message, they call the receive_msg
function that is already implemented.
@]
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.
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, such as TLS and Websocket and registered to the TCP interface.
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 tcp_proto {
struct net_proto {
int (*proto_recv_msg)(struct tcp_connection* con); /* function called when data is available */
int (*proto_recv_msg)(struct connection* con); /* function called when data is available - errors are signaled in the connection */
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:
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 tcp_send(struct socket_info* send_sock, int type, char* buf, unsigned len, union sockaddr_union* to, int id); @]
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.
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);