PageRenderTime 51ms CodeModel.GetById 22ms RepoModel.GetById 0ms app.codeStats 0ms

/include/eXosip2/eX_setup.h

#
C Header | 376 lines | 104 code | 51 blank | 221 comment | 0 complexity | e6156e0c663ca8a10e64d0477aac3a07 MD5 | raw file
Possible License(s): GPL-2.0
  1. /*
  2. eXosip - This is the eXtended osip library.
  3. Copyright (C) 2001-2012 Aymeric MOIZARD amoizard@antisip.com
  4. eXosip is free software; you can redistribute it and/or modify
  5. it under the terms of the GNU General Public License as published by
  6. the Free Software Foundation; either version 2 of the License, or
  7. (at your option) any later version.
  8. eXosip is distributed in the hope that it will be useful,
  9. but WITHOUT ANY WARRANTY; without even the implied warranty of
  10. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  11. GNU General Public License for more details.
  12. You should have received a copy of the GNU General Public License
  13. along with this program; if not, write to the Free Software
  14. Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
  15. In addition, as a special exception, the copyright holders give
  16. permission to link the code of portions of this program with the
  17. OpenSSL library under certain conditions as described in each
  18. individual source file, and distribute linked combinations
  19. including the two.
  20. You must obey the GNU General Public License in all respects
  21. for all of the code used other than OpenSSL. If you modify
  22. file(s) with this exception, you may extend this exception to your
  23. version of the file(s), but you are not obligated to do so. If you
  24. do not wish to do so, delete this exception statement from your
  25. version. If you delete this exception statement from all source
  26. files in the program, then also delete it here.
  27. */
  28. #ifdef ENABLE_MPATROL
  29. #include <mpatrol.h>
  30. #endif
  31. #ifndef __EX_SETUP_H__
  32. #define __EX_SETUP_H__
  33. #include <eXosip2/eXosip.h>
  34. #include <osipparser2/osip_message.h>
  35. #include <time.h>
  36. #ifdef __cplusplus
  37. extern "C" {
  38. #endif
  39. struct eXosip_t;
  40. struct osip_srv_record;
  41. struct osip_naptr;
  42. /**
  43. * @file eX_setup.h
  44. * @brief eXosip setup API
  45. *
  46. * This file provide the API needed to setup and configure
  47. * the SIP endpoint.
  48. *
  49. */
  50. /**
  51. * @defgroup eXosip2_conf eXosip2 configuration API
  52. * @ingroup eXosip2_setup
  53. * @{
  54. */
  55. /**
  56. * Allocate an eXosip context.
  57. *
  58. * @return a new allocated eXosip_t instance.
  59. */
  60. struct eXosip_t *eXosip_malloc (void);
  61. /**
  62. * Initiate the eXtented oSIP library.
  63. *
  64. * @param excontext eXosip_t instance.
  65. */
  66. int eXosip_init (struct eXosip_t *excontext);
  67. /**
  68. * Release ressource used by the eXtented oSIP library.
  69. *
  70. * @param excontext eXosip_t instance.
  71. */
  72. void eXosip_quit (struct eXosip_t *excontext);
  73. /**
  74. * Lock the eXtented oSIP library.
  75. *
  76. * @param excontext eXosip_t instance.
  77. */
  78. int eXosip_lock (struct eXosip_t *excontext);
  79. /**
  80. * UnLock the eXtented oSIP library.
  81. *
  82. * @param excontext eXosip_t instance.
  83. */
  84. int eXosip_unlock (struct eXosip_t *excontext);
  85. /**
  86. * Process (non-threaded mode ONLY) eXosip events.
  87. *
  88. * @param excontext eXosip_t instance.
  89. */
  90. int eXosip_execute (struct eXosip_t *excontext);
  91. #define EXOSIP_OPT_BASE_OPTION 0
  92. #define EXOSIP_OPT_UDP_KEEP_ALIVE (EXOSIP_OPT_BASE_OPTION+1) /**< int *: interval for keep alive packets (UDP, TCP, TLS, DTLS) */
  93. #define EXOSIP_OPT_AUTO_MASQUERADE_CONTACT (EXOSIP_OPT_BASE_OPTION+2) /**< int *: specific re-usage of "rport" */
  94. #define EXOSIP_OPT_UDP_LEARN_PORT EXOSIP_OPT_AUTO_MASQUERADE_CONTACT /** EXOSIP_OPT_UDP_LEARN_PORT is obsolete / replaced by EXOSIP_OPT_AUTO_MASQUERADE_CONTACT */
  95. #define EXOSIP_OPT_USE_RPORT (EXOSIP_OPT_BASE_OPTION+7) /**< int *: enable or disable rport in via */
  96. #define EXOSIP_OPT_SET_IPV4_FOR_GATEWAY (EXOSIP_OPT_BASE_OPTION+8) /**< char *: usually, this is the proxy address */
  97. #define EXOSIP_OPT_ADD_DNS_CACHE (EXOSIP_OPT_BASE_OPTION+9) /**< struct eXosip_dns_cache *: force some cache entry to avoid DNS */
  98. #define EXOSIP_OPT_DELETE_DNS_CACHE (EXOSIP_OPT_BASE_OPTION+10) /**< struct eXosip_dns_cache *: force removal of some cache entry to avoid DNS */
  99. #define EXOSIP_OPT_SET_IPV6_FOR_GATEWAY (EXOSIP_OPT_BASE_OPTION+12) /**< char *: usually, this is the proxy address */
  100. #define EXOSIP_OPT_ADD_ACCOUNT_INFO (EXOSIP_OPT_BASE_OPTION+13) /**< struct eXosip_account_info *: internal stuff */
  101. #define EXOSIP_OPT_DNS_CAPABILITIES (EXOSIP_OPT_BASE_OPTION+14) /**< int *: 0 to disable, 2 to use NAPTR/SRV record */
  102. #define EXOSIP_OPT_SET_DSCP (EXOSIP_OPT_BASE_OPTION+15) /**< int *: set a dscp value for SIP socket */
  103. #define EXOSIP_OPT_REGISTER_WITH_DATE (EXOSIP_OPT_BASE_OPTION+16) /**< int *: enable usage of Date header in REGISTER */
  104. #define EXOSIP_OPT_SET_HEADER_USER_AGENT (EXOSIP_OPT_BASE_OPTION+17) /**< char *: set the User-Agent header */
  105. #define EXOSIP_OPT_ENABLE_DNS_CACHE (EXOSIP_OPT_BASE_OPTION+18) /**< int *: 0 to disable use of cache*/
  106. #define EXOSIP_OPT_ENABLE_AUTOANSWERBYE (EXOSIP_OPT_BASE_OPTION+19) /**< int *: 0 to disable automatic answer of BYE */
  107. #define EXOSIP_OPT_ENABLE_IPV6 (EXOSIP_OPT_BASE_OPTION+20) /**< int *: 0 to disable -this is a per-eXosip_t parameter for using IPv6 DNS request */
  108. #define EXOSIP_OPT_ENABLE_REUSE_TCP_PORT (EXOSIP_OPT_BASE_OPTION+21) /**< int *: 0 to disable, 1 to enable reusing local tcp port for outgoing tcp connection */
  109. #define EXOSIP_OPT_ENABLE_USE_EPHEMERAL_PORT (EXOSIP_OPT_BASE_OPTION+22) /**< int *: 0 to disable, 1 to enable usage of emphemeral tcp port in Contact headers instead of local listening port for TCP/TLS */
  110. #define EXOSIP_OPT_SET_TLS_VERIFY_CERTIFICATE (EXOSIP_OPT_BASE_OPTION+500) /**< int *: enable verification of certificate for TLS connection */
  111. #define EXOSIP_OPT_SET_TLS_CERTIFICATES_INFO (EXOSIP_OPT_BASE_OPTION+501) /**< eXosip_tls_ctx_t *: client and/or server certificate/ca-root/key info */
  112. #define EXOSIP_OPT_SET_TLS_CLIENT_CERTIFICATE_NAME (EXOSIP_OPT_BASE_OPTION+502) /**< char*: user can choose a specific certifcate present in Windows Certificate Store */
  113. #define EXOSIP_OPT_SET_TLS_SERVER_CERTIFICATE_NAME (EXOSIP_OPT_BASE_OPTION+503) /**< char*: user can choose a specific certifcate present in Windows Certificate Store */
  114. /* non standard option: need a compilation flag to activate */
  115. #define EXOSIP_OPT_KEEP_ALIVE_OPTIONS_METHOD (EXOSIP_OPT_BASE_OPTION+1000)
  116. #define EXOSIP_OPT_SET_TSC_SERVER (EXOSIP_OPT_BASE_OPTION+1001) /**< void*: set the tsc tunnel handle */
  117. /**
  118. * structure used to for inserting a DNS cache entry and avoid DNS resolution.
  119. * @struct eXosip_dns_cache
  120. */
  121. struct eXosip_dns_cache {
  122. char host[1024];
  123. char ip[256];
  124. };
  125. struct eXosip_account_info {
  126. char proxy[1024];
  127. char nat_ip[256];
  128. int nat_port;
  129. };
  130. struct eXosip_http_auth {
  131. char pszCallId[64];
  132. osip_proxy_authenticate_t *wa;
  133. char pszCNonce[64];
  134. int iNonceCount;
  135. int answer_code;
  136. };
  137. /**
  138. * Set eXosip options.
  139. * See eXosip_option for available options.
  140. *
  141. * @param excontext eXosip_t instance.
  142. * @param opt option to configure.
  143. * @param value value for options.
  144. *
  145. */
  146. int eXosip_set_option (struct eXosip_t *excontext, int opt, const void *value);
  147. /**
  148. * structure used to describe credentials for a client or server
  149. * consists of a certificate, a corresponding private key and its password
  150. * @struct eXosip_tls_credentials_s
  151. */
  152. typedef struct eXosip_tls_credentials_s {
  153. char priv_key[1024];
  154. char priv_key_pw[1024];
  155. char cert[1024];
  156. } eXosip_tls_credentials_t;
  157. /**
  158. * structure to describe the whole TLS-context for eXosip
  159. * consists of a certificate, a corresponding private key and its password
  160. * @struct eXosip_tls_ctx_s
  161. */
  162. typedef struct eXosip_tls_ctx_s {
  163. char random_file[1024]; /**< absolute path to a file with random(!) data */
  164. char dh_param[1024]; /**< absolute path to a file necessary for diffie hellman key exchange */
  165. char root_ca_cert[1024]; /**< absolute path to the file with known rootCAs */
  166. eXosip_tls_credentials_t client; /**< credential of the client */
  167. eXosip_tls_credentials_t server; /**< credential of the server */
  168. } eXosip_tls_ctx_t;
  169. /**
  170. * An enumeration which describes the error which can occur while setting the eXosip_tls_ctx
  171. */
  172. typedef enum {
  173. TLS_OK = 0, /**< yippieh, everything is fine :) */
  174. TLS_ERR_NO_RAND = -1, /**< no absolute path to the random file was specified */
  175. TLS_ERR_NO_DH_PARAM = -2, /**< no absolute path to the diifie hellman file was specified */
  176. TLS_ERR_NO_PW = -3, /**< no password was specified */
  177. TLS_ERR_NO_ROOT_CA = -4, /**< no absolute path to the rootCA file was specified */
  178. TLS_ERR_MISSING_AUTH_PART = -5 /**< something is missing: the private key or the certificate */
  179. } eXosip_tls_ctx_error;
  180. /**
  181. * Start and return osip_naptr context.
  182. * Note that DNS results might not yet be available.
  183. *
  184. * @param excontext eXosip_t instance.
  185. * @param domain domain name for NAPTR record
  186. * @param protocol protocol to use ("SIP")
  187. * @param transport transport to use ("UDP")
  188. * @param keep_in_cache keep result in cache if >0
  189. */
  190. struct osip_naptr *eXosip_dnsutils_naptr (struct eXosip_t *excontext, const char *domain, const char *protocol, const char *transport, int keep_in_cache);
  191. /**
  192. * Continue to process asynchronous DNS request (if implemented).
  193. *
  194. * @param output_record result structure.
  195. * @param force force waiting for final answer if >0
  196. */
  197. int eXosip_dnsutils_dns_process (struct osip_naptr *output_record, int force);
  198. /**
  199. * Rotate first SRV entry to last SRV entry.
  200. *
  201. * @param output_record result structure.
  202. */
  203. int eXosip_dnsutils_rotate_srv (struct osip_srv_record *output_record);
  204. /**
  205. * Listen on a specified socket.
  206. *
  207. * @param excontext eXosip_t instance.
  208. * @param transport IPPROTO_UDP for udp. (soon to come: TCP/TLS?)
  209. * @param addr the address to bind (NULL for all interface)
  210. * @param port the listening port. (0 for random port)
  211. * @param family the IP family (AF_INET or AF_INET6).
  212. * @param secure 0 for UDP or TCP, 1 for TLS (with TCP).
  213. */
  214. int eXosip_listen_addr (struct eXosip_t *excontext, int transport, const char *addr, int port, int family, int secure);
  215. /**
  216. * Reset transport sockets.
  217. *
  218. * @param excontext eXosip_t instance.
  219. */
  220. int eXosip_reset_transports (struct eXosip_t *excontext);
  221. /**
  222. * Listen on a specified socket.
  223. *
  224. * @param excontext eXosip_t instance.
  225. * @param transport IPPROTO_UDP for udp. (soon to come: TCP/TLS?)
  226. * @param socket socket to use for listening to UDP sip messages.
  227. * @param port the listening port for masquerading.
  228. */
  229. int eXosip_set_socket (struct eXosip_t *excontext, int transport, int socket, int port);
  230. /**
  231. * Set the SIP User-Agent: header string.
  232. *
  233. * @param excontext eXosip_t instance.
  234. * @param user_agent the User-Agent header to insert in messages.
  235. */
  236. void eXosip_set_user_agent (struct eXosip_t *excontext, const char *user_agent);
  237. /**
  238. * Get the eXosip version as a sring
  239. *
  240. */
  241. const char *eXosip_get_version (void);
  242. typedef void (*CbSipCallback) (osip_message_t * msg, int received);
  243. /**
  244. * Set a callback to get sent and received SIP messages.
  245. *
  246. * @param excontext eXosip_t instance.
  247. * @param cbsipCallback the callback to retreive messages.
  248. */
  249. int eXosip_set_cbsip_message (struct eXosip_t *excontext, CbSipCallback cbsipCallback);
  250. /**
  251. * Use IPv6 instead of IPv4. (global setting)
  252. *
  253. * DEPRECATED: you MUST use EXOSIP_OPT_ENABLE_IPV6 to configure each
  254. * eXosip_t independantly.
  255. *
  256. * **THIS CODE DOES NOTHING, REPLACE WITH**
  257. *
  258. * eXosip_set_option(excontext, EXOSIP_OPT_ENABLE_IPV6, &val);
  259. *
  260. * @param ipv6_enable This paramter should be set to 1 to enable IPv6 mode.
  261. */
  262. void eXosip_enable_ipv6 (int ipv6_enable);
  263. /**
  264. * This method is used to replace contact address with
  265. * the public address of your NAT. The ip address should
  266. * be retreived manually (fixed IP address) or with STUN.
  267. * This address will only be used when the remote
  268. * correspondant appears to be on an DIFFERENT LAN.
  269. *
  270. * @param excontext eXosip_t instance.
  271. * @param public_address the ip address.
  272. * @param port the port for masquerading.
  273. *
  274. * If set to NULL, then the local ip address will be guessed
  275. * automatically (returns to default mode).
  276. */
  277. void eXosip_masquerade_contact (struct eXosip_t *excontext, const char *public_address, int port);
  278. /**
  279. * This method is used to find out an free IPPROTO_UDP or IPPROTO_TCP port.
  280. *
  281. * @param excontext eXosip_t instance.
  282. * @param free_port initial port for search.
  283. * @param transport IPPROTO_UDP or IPPROTO_TCP protocol.
  284. *
  285. */
  286. int eXosip_find_free_port (struct eXosip_t *excontext, int free_port, int transport);
  287. #ifndef DOXYGEN
  288. /**
  289. * Wake Up the eXosip_event_wait method.
  290. *
  291. * @param excontext eXosip_t instance.
  292. */
  293. void eXosip_wakeup_event (struct eXosip_t *excontext);
  294. #endif
  295. /** @} */
  296. /**
  297. * @defgroup eXosip2_network eXosip2 network API
  298. * @ingroup eXosip2_setup
  299. * @{
  300. */
  301. /**
  302. * Modify the transport protocol used to send SIP message.
  303. *
  304. * @param msg The SIP message to modify
  305. * @param transport transport protocol to use ("UDP", "TCP" or "TLS")
  306. */
  307. int eXosip_transport_set (osip_message_t * msg, const char *transport);
  308. /**
  309. * Find the current localip (interface with default route).
  310. *
  311. * @param excontext eXosip_t instance.
  312. * @param family AF_INET or AF_INET6
  313. * @param address a string containing the local IP address.
  314. * @param size The size of the string
  315. */
  316. int eXosip_guess_localip (struct eXosip_t *excontext, int family, char *address, int size);
  317. /** @} */
  318. #ifdef __cplusplus
  319. }
  320. #endif
  321. #endif