Show last authors
1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc /}}
3 {{/box}}
4
5 = Bctoolbox socket API =
6
7 == Introduction ==
8
9 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.
10
11 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 .
12
13 The vconnect files define:
14
15 * a set of methods to interact with sockets, defined in the structure //bctbx_vsocket_methods_t.//
16 * 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
17 * a standard implementation for this API which is used as default.
18 * an API to set/get the //bctbx_vsocket_api_t// in use//.//
19
20 == Implementation details ==
21
22 === Socket API usage ===
23
24 The socket API is used when calling the following functions :
25
26 * bctbx_socket
27 * bctbx_connect
28 * bctbx_bind
29 * bctbx_shutdown
30 * bctbx_getsockname
31 * bctbx_getsockopt
32 * bctbx_setsockopt
33 * bctbx_socket_close
34 * bctbx_socket_error
35
36 These function use //bctbx_vsocket_methods_t //function pointers to call the associated function.
37
38 Avoid using direct calls to the libc functions if you want consistency throughout the code.
39
40 === The methods //bctbx_vsocket_methods_t// ===
41
42 //Defined in the file vconnect.h, they are defining the following function pointer methods prototypes~://
43
44 pFuncSocket
45 pFuncConnect
46 pFuncBind
47 pFuncGetSockName
48 pFuncGetSockOpt
49 pFuncSetSockOpt
50 pFuncClose
51 pFuncGetError
52 pFuncShutdown
53
54 A default implementation of these methods relying on libc functions is defined through the static //bctbx_vsocket_methods_t // **bcSocketAPI** in vconnect.c .
55
56 === The bctbx_vsocket_api_t ===
57
58 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.
59
60 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,.
61
62 To change the value of **pDefaultvSocket**, use **{{code}} void bctbx_vsocket_api_set_default(bctbx_vsocket_api_t* my_vsocket_api){{/code}} ** and provide a valid pointer to your bctbx_vsocket_api_t of choice. To get the current api used, use **{{code}} bctbx_vsocket_api_t* bctbx_vsocket_api_get_default(void) {{/code}}** which will return the value of **pDefaultvSocket.**
63
64 **{{code}} bctbx_vsocket_api_t* bctbx_vsocket_api_get_standard(void) {{/code}}** will return a reference to **bcvSocket**.
65
66 == Changing the socket API ==
67
68 To modify the behavior of the socket API:
69
70 1. Implement the functions defined by the function pointers 'prototypes in the //bctbx_vsocket_methods_t structure.//
71 1. //Initialize an instance of bctbx_vsocket_methods_t with the function pointers set to the functions you've just implemented.//
72 1. Define// a //bctbx_vsocket_api_t with a name and a reference to your //bctbx_vsocket_methods_t structure. //
73 1. Call bctbx_vsocket_api_set_default(with_your_vsocket_api_t_ref_here)
74
75 == Belle-sip ==
76
77 Modifying the default socket api used can be done through **{{code}} void belle_sip_set_socket_api(bctbx_vsocket_api_t* my_api) {{/code}} **.
78
79 This is what is done in:
80
81 * stream_listeningpoint.c : in {{code}} belle_sip_socket_t create_server_socket(const char *addr, int * port, int *family){{/code}}
82 * udp_listeningpoint.c : in {{code}} belle_sip_socket_t create_udp_socket(const char *addr, int *port, int *family){{/code}}
83