Bctoolbox socket API

Introduction

The socket api defined in the bctoolbox submodule in the files vconnect.h and vconnect.c aims at providing an abstract layer around a set of functions to handle all socket operations, namely : socket, connect, bind, close, shutdown, getsokname, getsockopt, setsockopt.

The goal is to have an API where developers can customize how the connection is done, adding encryption for instance. This is done using function pointers which are initialized to the adequate functions in the bctoolbox and belle-sip submodules .

The vconnect files define:

• a set of methods to interact with sockets, defined in the structure bctbx_vsocket_methods_t.
• the socket api structure definition, bctbx_vsocket_api_t which includes the name of the api and the bctbx_vsocket_methods_t for this API
• a standard implementation for this API which is used as default.
• an API to set/get the bctbx_vsocket_api_t in use.

Implementation details

Socket API usage

The socket API is used when calling the following functions :

• bctbx_socket
• bctbx_connect
• bctbx_bind
• bctbx_shutdown
• bctbx_getsockname
• bctbx_getsockopt
• bctbx_setsockopt
• bctbx_socket_close
• bctbx_socket_error

These function use bctbx_vsocket_methods_t function pointers to call the associated function. 

Avoid using direct calls to the libc functions if you want consistency throughout the code. 

The methods bctbx_vsocket_methods_t

Defined in the file vconnect.h, they are defining the following function pointer methods prototypes:

pFuncSocket
pFuncConnect
pFuncBind
pFuncGetSockName
pFuncGetSockOpt
pFuncSetSockOpt
pFuncClose
pFuncGetError
pFuncShutdown

A default implementation of these methods relying on libc functions is defined through the static bctbx_vsocket_methods_t  bcSocketAPI in vconnect.c .

The bctbx_vsocket_api_t

This structure gives a name vSockName to the socket api used and associates it with a pointer pSocketMethods to the methods used for this API. 

A default implementation is defined in vconnect.c . Called bcvSocket, this sets the API name to bctbx_socket and uses bcSocketAPI as a reference for the methods used. This is the implementation used by linphone through  the pointer pDefaultvSocket  which is initialized to reference this structure,.

To change the value of pDefaultvSocket, use  void bctbx_vsocket_api_set_default(bctbx_vsocket_api_t* my_vsocket_api)  and provide a valid pointer to your bctbx_vsocket_api_t of choice. To get the current api used, use  bctbx_vsocket_api_t* bctbx_vsocket_api_get_default(void)  which will return the value of pDefaultvSocket.

 bctbx_vsocket_api_t*  bctbx_vsocket_api_get_standard(void)  will return a reference to bcvSocket. 

Changing the socket API

To modify the behavior of the socket API:

1. Implement the functions defined by the function pointers 'prototypes in the bctbx_vsocket_methods_t structure.
2. Initialize an instance of bctbx_vsocket_methods_t with the function pointers set to the functions you've just implemented.
3. Define a bctbx_vsocket_api_t with a name and a reference to your bctbx_vsocket_methods_t structure. 
4. Call bctbx_vsocket_api_set_default(with_your_vsocket_api_t_ref_here) 

Belle-sip

Modifying the default socket api used can be done through  void belle_sip_set_socket_api(bctbx_vsocket_api_t* my_api)  . 

This is what is done in: 

• stream_listeningpoint.c : in  belle_sip_socket_t create_server_socket(const char *addr, int * port, int *family)
• udp_listeningpoint.c : in  belle_sip_socket_t create_udp_socket(const char *addr, int *port, int *family)