1 /* 2 eXosip - This is the eXtended osip library. 3 Copyright (C) 2001-2020 Aymeric MOIZARD amoizard@antisip.com 4 5 eXosip is free software; you can redistribute it and/or modify 6 it under the terms of the GNU General Public License as published by 7 the Free Software Foundation; either version 2 of the License, or 8 (at your option) any later version. 9 10 eXosip is distributed in the hope that it will be useful, 11 but WITHOUT ANY WARRANTY; without even the implied warranty of 12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 GNU General Public License for more details. 14 15 You should have received a copy of the GNU General Public License 16 along with this program; if not, write to the Free Software 17 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 18 19 In addition, as a special exception, the copyright holders give 20 permission to link the code of portions of this program with the 21 OpenSSL library under certain conditions as described in each 22 individual source file, and distribute linked combinations 23 including the two. 24 You must obey the GNU General Public License in all respects 25 for all of the code used other than OpenSSL. If you modify 26 file(s) with this exception, you may extend this exception to your 27 version of the file(s), but you are not obligated to do so. If you 28 do not wish to do so, delete this exception statement from your 29 version. If you delete this exception statement from all source 30 files in the program, then also delete it here. 31 */ 32 33 #ifdef ENABLE_MPATROL 34 #include <mpatrol.h> 35 #endif 36 37 #ifndef __EXOSIP_H__ 38 #define __EXOSIP_H__ 39 40 #include <eXosip2/eX_setup.h> 41 #include <eXosip2/eX_register.h> 42 #include <eXosip2/eX_call.h> 43 #include <eXosip2/eX_options.h> 44 #include <eXosip2/eX_subscribe.h> 45 #include <eXosip2/eX_message.h> 46 #include <eXosip2/eX_publish.h> 47 48 #include <osipparser2/osip_parser.h> 49 #include <osipparser2/sdp_message.h> 50 #include <time.h> 51 52 /** 53 * @file eXosip.h 54 * @brief eXosip API 55 * 56 * eXosip is a high layer library for rfc3261: the SIP protocol. 57 * It offers a simple API to make it easy to use. eXosip2 offers 58 * great flexibility for implementing SIP endpoint like: 59 * <ul> 60 * <li>SIP User-Agents</li> 61 * <li>SIP Voicemail or IVR</li> 62 * <li>any SIP server acting as an endpoint (music server...)</li> 63 * </ul> 64 * 65 * If you need to implement proxy or complex SIP applications, 66 * you should consider using osip instead. 67 * 68 * Here are the eXosip capabilities: 69 * <pre> 70 * REGISTER to handle registration. 71 * INVITE/BYE to start/stop VoIP sessions. 72 * INFO to send DTMF within a VoIP sessions. 73 * OPTIONS to simulate VoIP sessions. 74 * re-INVITE to modify VoIP sessions. 75 * REFER/NOTIFY to transfer calls. 76 * MESSAGE to send Instant Message. 77 * SUBSCRIBE/REFER/NOTIFY to handle presence capabilities. 78 * any other request to handle what you want (outside dialogs)! 79 * </pre> 80 * <P> 81 */ 82 83 #ifdef __cplusplus 84 extern "C" { 85 #endif 86 87 /** 88 * Structure for event description. 89 * @var eXosip_event_t 90 */ 91 typedef struct eXosip_event eXosip_event_t; 92 93 /** 94 * @defgroup eXosip2_authentication eXosip2 authentication API 95 * @ingroup eXosip2_msg 96 * @{ 97 */ 98 99 /** 100 * Add authentication credentials. These are used when an outgoing 101 * request comes back with an authorization required response. 102 * 103 * @param excontext eXosip_t instance. 104 * @param username username 105 * @param userid login (usually equals the username) 106 * @param passwd password 107 * @param ha1 MD5 ha1 108 * @param realm realm within which credentials apply, or NULL to apply credentials to unrecognized realms 109 */ 110 int eXosip_add_authentication_info(struct eXosip_t *excontext, const char *username, const char *userid, const char *passwd, const char *ha1, const char *realm); 111 112 /** 113 * Remove authentication credentials. 114 * 115 * @param excontext eXosip_t instance. 116 * @param username username 117 * @param realm realm must be exact same arg as for eXosip_add_authentication_info 118 */ 119 int eXosip_remove_authentication_info(struct eXosip_t *excontext, const char *username, const char *realm); 120 121 /** 122 * Clear all authentication credentials stored in eXosip 123 * 124 * @param excontext eXosip_t instance. 125 */ 126 int eXosip_clear_authentication_info(struct eXosip_t *excontext); 127 128 /** 129 * Initiate some default actions: 130 * 131 * Retry with credentials upon reception of 401/407. 132 * Retry with Contact header upon reception of 3xx request. 133 * 134 * Usefull & required when eXosip_automatic_action() can't do the automatic action: 135 * 1/ if you receive a 401 or 407 for BYE (event EXOSIP_CALL_MESSAGE_REQUESTFAILURE). 136 * 2/ if you receive 401 or 407 for any sip request outside of dialog (EXOSIP_MESSAGE_REQUESTFAILURE) 137 * 138 * @param excontext eXosip_t instance. 139 * @param je event to work on. 140 */ 141 int eXosip_default_action(struct eXosip_t *excontext, eXosip_event_t *je); 142 143 /** 144 * Initiate some automatic actions: 145 * 146 * Retry with credentials upon reception of 401/407. 147 * Retry with higher Session-Expires upon reception of 422. 148 * Refresh REGISTER and SUBSCRIBE/REFER before the expiration delay. 149 * Retry with Contact header upon reception of 3xx request. 150 * Send automatic UPDATE for session-timer feature. 151 * 152 * @param excontext eXosip_t instance. 153 */ 154 void eXosip_automatic_action(struct eXosip_t *excontext); 155 156 #ifndef MINISIZE 157 /** 158 * Automatic internal handling of dialog package. 159 * 160 * @param excontext eXosip_t instance. 161 * @param evt Incoming SUBSCRIBE for dialog package. 162 */ 163 int eXosip_insubscription_automatic(struct eXosip_t *excontext, eXosip_event_t *evt); 164 #endif 165 166 /** 167 * Generate random string: (only digit, and maximum unsigned int) 168 * 169 * @param buf destination buffer for random string. 170 * @param buf_size size of destination buffer 171 */ 172 int eXosip_generate_random(char *buf, int buf_size); 173 174 /** 175 * Generate random string: (low entropy, only hexa) 176 * 177 * @param buf destination buffer for random string. 178 * @param buf_size size of destination buffer 179 * @param str1 random1 input string 180 * @param str2 random2 input string 181 * @param str3 random3 input string 182 */ 183 int eXosip_hexa_generate_random(char *buf, int buf_size, char *str1, char *str2, char *str3); 184 185 /** 186 * Generate random string: (high entropy when compiled with openssl) 187 * 188 * @param buf destination buffer for random string. 189 * @param buf_size size of destination buffer 190 */ 191 int eXosip_byte_generate_random(char *buf, int buf_size); 192 193 /** @} */ 194 195 /** 196 * @defgroup eXosip2_sdp eXosip2 SDP helper API. 197 * @ingroup eXosip2_msg 198 * @{ 199 */ 200 201 /** 202 * Get remote SDP body for the latest INVITE of call. 203 * 204 * @param excontext eXosip_t instance. 205 * @param did dialog id of call. 206 */ 207 sdp_message_t *eXosip_get_remote_sdp(struct eXosip_t *excontext, int did); 208 209 /** 210 * Get local SDP body for the latest INVITE of call. 211 * 212 * @param excontext eXosip_t instance. 213 * @param did dialog id of call. 214 */ 215 sdp_message_t *eXosip_get_local_sdp(struct eXosip_t *excontext, int did); 216 217 /** 218 * Get local SDP body for the previous latest INVITE of call. 219 * 220 * @param excontext eXosip_t instance. 221 * @param did dialog id of call. 222 */ 223 sdp_message_t *eXosip_get_previous_local_sdp(struct eXosip_t *excontext, int did); 224 225 /** 226 * Get remote SDP body for the latest INVITE of call. 227 * 228 * @param excontext eXosip_t instance. 229 * @param tid transction id of transaction. 230 */ 231 sdp_message_t *eXosip_get_remote_sdp_from_tid(struct eXosip_t *excontext, int tid); 232 233 /** 234 * Get local SDP body for the latest INVITE of call. 235 * 236 * @param excontext eXosip_t instance. 237 * @param tid transction id of transaction. 238 */ 239 sdp_message_t *eXosip_get_local_sdp_from_tid(struct eXosip_t *excontext, int tid); 240 241 /** 242 * Get local SDP body for the given message. 243 * 244 * @param message message containing the SDP. 245 */ 246 sdp_message_t *eXosip_get_sdp_info(osip_message_t *message); 247 248 /** 249 * Get audio connection information for call. 250 * 251 * @param sdp sdp information. 252 */ 253 sdp_connection_t *eXosip_get_audio_connection(sdp_message_t *sdp); 254 255 /** 256 * Get audio media information for call. 257 * 258 * @param sdp sdp information. 259 */ 260 sdp_media_t *eXosip_get_audio_media(sdp_message_t *sdp); 261 262 /** 263 * Get video connection information for call. 264 * 265 * @param sdp sdp information. 266 */ 267 sdp_connection_t *eXosip_get_video_connection(sdp_message_t *sdp); 268 269 /** 270 * Get video media information for call. 271 * 272 * @param sdp sdp information. 273 */ 274 sdp_media_t *eXosip_get_video_media(sdp_message_t *sdp); 275 276 /** 277 * Get media connection information for call. 278 * 279 * @param sdp sdp information. 280 * @param media media to search. 281 */ 282 sdp_connection_t *eXosip_get_connection(sdp_message_t *sdp, const char *media); 283 284 /** 285 * Get media information for call. 286 * 287 * @param sdp sdp information. 288 * @param media media to search. 289 */ 290 sdp_media_t *eXosip_get_media(sdp_message_t *sdp, const char *media); 291 292 /** @} */ 293 294 /** 295 * @defgroup eXosip2_event eXosip2 event API 296 * @ingroup eXosip2_setup 297 * @{ 298 */ 299 300 /** 301 * Structure for event type description 302 * @var eXosip_event_type 303 */ 304 typedef enum eXosip_event_type { 305 /* REGISTER related events */ 306 EXOSIP_REGISTRATION_SUCCESS, /**< user is successfully registred. */ 307 EXOSIP_REGISTRATION_FAILURE, /**< user is not registred. */ 308 309 /* INVITE related events within calls */ 310 EXOSIP_CALL_INVITE, /**< announce a new call */ 311 EXOSIP_CALL_REINVITE, /**< announce a new INVITE within call */ 312 313 EXOSIP_CALL_NOANSWER, /**< announce no answer within the timeout */ 314 EXOSIP_CALL_PROCEEDING, /**< announce processing by a remote app */ 315 EXOSIP_CALL_RINGING, /**< announce ringback */ 316 EXOSIP_CALL_ANSWERED, /**< announce start of call */ 317 EXOSIP_CALL_REDIRECTED, /**< announce a redirection */ 318 EXOSIP_CALL_REQUESTFAILURE, /**< announce a request failure */ 319 EXOSIP_CALL_SERVERFAILURE, /**< announce a server failure */ 320 EXOSIP_CALL_GLOBALFAILURE, /**< announce a global failure */ 321 EXOSIP_CALL_ACK, /**< ACK received for 200ok to INVITE */ 322 323 EXOSIP_CALL_CANCELLED, /**< announce that call has been cancelled */ 324 325 /* request related events within calls (except INVITE) */ 326 EXOSIP_CALL_MESSAGE_NEW, /**< announce new incoming request. */ 327 EXOSIP_CALL_MESSAGE_PROCEEDING, /**< announce a 1xx for request. */ 328 EXOSIP_CALL_MESSAGE_ANSWERED, /**< announce a 200ok */ 329 EXOSIP_CALL_MESSAGE_REDIRECTED, /**< announce a failure. */ 330 EXOSIP_CALL_MESSAGE_REQUESTFAILURE, /**< announce a failure. */ 331 EXOSIP_CALL_MESSAGE_SERVERFAILURE, /**< announce a failure. */ 332 EXOSIP_CALL_MESSAGE_GLOBALFAILURE, /**< announce a failure. */ 333 334 EXOSIP_CALL_CLOSED, /**< a BYE was received for this call */ 335 336 /* for both UAS & UAC events */ 337 EXOSIP_CALL_RELEASED, /**< call context is cleared. */ 338 339 /* events received for request outside calls */ 340 EXOSIP_MESSAGE_NEW, /**< announce new incoming request. */ 341 EXOSIP_MESSAGE_PROCEEDING, /**< announce a 1xx for request. */ 342 EXOSIP_MESSAGE_ANSWERED, /**< announce a 200ok */ 343 EXOSIP_MESSAGE_REDIRECTED, /**< announce a failure. */ 344 EXOSIP_MESSAGE_REQUESTFAILURE, /**< announce a failure. */ 345 EXOSIP_MESSAGE_SERVERFAILURE, /**< announce a failure. */ 346 EXOSIP_MESSAGE_GLOBALFAILURE, /**< announce a failure. */ 347 348 /* Presence and Instant Messaging */ 349 EXOSIP_SUBSCRIPTION_NOANSWER, /**< announce no answer */ 350 EXOSIP_SUBSCRIPTION_PROCEEDING, /**< announce a 1xx */ 351 EXOSIP_SUBSCRIPTION_ANSWERED, /**< announce a 200ok */ 352 EXOSIP_SUBSCRIPTION_REDIRECTED, /**< announce a redirection */ 353 EXOSIP_SUBSCRIPTION_REQUESTFAILURE, /**< announce a request failure */ 354 EXOSIP_SUBSCRIPTION_SERVERFAILURE, /**< announce a server failure */ 355 EXOSIP_SUBSCRIPTION_GLOBALFAILURE, /**< announce a global failure */ 356 EXOSIP_SUBSCRIPTION_NOTIFY, /**< announce new NOTIFY request */ 357 358 EXOSIP_IN_SUBSCRIPTION_NEW, /**< announce new incoming SUBSCRIBE/REFER.*/ 359 360 EXOSIP_NOTIFICATION_NOANSWER, /**< announce no answer */ 361 EXOSIP_NOTIFICATION_PROCEEDING, /**< announce a 1xx */ 362 EXOSIP_NOTIFICATION_ANSWERED, /**< announce a 200ok */ 363 EXOSIP_NOTIFICATION_REDIRECTED, /**< announce a redirection */ 364 EXOSIP_NOTIFICATION_REQUESTFAILURE, /**< announce a request failure */ 365 EXOSIP_NOTIFICATION_SERVERFAILURE, /**< announce a server failure */ 366 EXOSIP_NOTIFICATION_GLOBALFAILURE, /**< announce a global failure */ 367 368 EXOSIP_EVENT_COUNT /**< MAX number of events */ 369 } eXosip_event_type_t; 370 371 /** 372 * Structure for event description 373 * @struct eXosip_event 374 */ 375 struct eXosip_event { 376 eXosip_event_type_t type; /**< type of the event */ 377 char textinfo[256]; /**< text description of event */ 378 void *external_reference; /**< external reference (for calls) */ 379 380 osip_message_t *request; /**< request within current transaction */ 381 osip_message_t *response; /**< last response within current transaction */ 382 osip_message_t *ack; /**< ack within current transaction */ 383 384 int tid; /**< unique id for transactions (to be used for answers) */ 385 int did; /**< unique id for SIP dialogs */ 386 387 int rid; /**< unique id for registration */ 388 int cid; /**< unique id for SIP calls (but multiple dialogs!) */ 389 int sid; /**< unique id for outgoing subscriptions */ 390 int nid; /**< unique id for incoming subscriptions */ 391 392 int ss_status; /**< current Subscription-State for subscription */ 393 int ss_reason; /**< current Reason status for subscription */ 394 }; 395 396 /** 397 * Free ressource in an eXosip event. 398 * 399 * @param je event to work on. 400 */ 401 void eXosip_event_free(eXosip_event_t *je); 402 403 /** 404 * Wait for an eXosip event. 405 * 406 * @param excontext eXosip_t instance. 407 * @param tv_s timeout value (seconds). 408 * @param tv_ms timeout value (mseconds). 409 */ 410 eXosip_event_t *eXosip_event_wait(struct eXosip_t *excontext, int tv_s, int tv_ms); 411 412 /** 413 * Wait for next eXosip event. 414 * **DEPRECATED API** 415 * This API will block - You should use eXosip_event_wait instead which is more convenient. 416 * limitation: This method will not process automatic 200ok retransmission for INVITE transaction. 417 * 418 * @param excontext eXosip_t instance. 419 */ 420 eXosip_event_t *eXosip_event_get(struct eXosip_t *excontext); 421 422 /** 423 * This socket receive some data yhen an event happens internally. 424 * NOTE: you must call eXosip_event_wait until there is no more events 425 * in the fifo. 426 * 427 * @param excontext eXosip_t instance. 428 */ 429 int eXosip_event_geteventsocket(struct eXosip_t *excontext); 430 431 /** @} */ 432 433 #ifdef __cplusplus 434 } 435 #endif 436 #endif 437