1 /* $Id$ */ 2 /* 3 * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com) 4 * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org> 5 * 6 * This program is free software; you can redistribute it and/or modify 7 * it under the terms of the GNU General Public License as published by 8 * the Free Software Foundation; either version 2 of the License, or 9 * (at your option) any later version. 10 * 11 * This program is distributed in the hope that it will be useful, 12 * but WITHOUT ANY WARRANTY; without even the implied warranty of 13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 14 * GNU General Public License for more details. 15 * 16 * You should have received a copy of the GNU General Public License 17 * along with this program; if not, write to the Free Software 18 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 19 */ 20 #ifndef __PJMEDIA_TRANSPORT_ICE_H__ 21 #define __PJMEDIA_TRANSPORT_ICE_H__ 22 23 24 /** 25 * @file transport_ice.h 26 * @brief ICE capable media transport. 27 */ 28 29 #include <pjmedia/stream.h> 30 #include <pjnath/ice_strans.h> 31 32 33 /** 34 * @defgroup PJMEDIA_TRANSPORT_ICE ICE Media Transport 35 * @ingroup PJMEDIA_TRANSPORT 36 * @brief Interactive Connectivity Establishment (ICE) transport 37 * @{ 38 * 39 * This describes the implementation of media transport using 40 * Interactive Connectivity Establishment (ICE) protocol. 41 */ 42 43 PJ_BEGIN_DECL 44 45 46 /** 47 * Structure containing callbacks to receive ICE notifications. 48 */ 49 typedef struct pjmedia_ice_cb 50 { 51 /** 52 * This callback will be called when ICE negotiation completes. 53 * 54 * @param tp PJMEDIA ICE transport. 55 * @param op The operation 56 * @param status Operation status. 57 */ 58 void (*on_ice_complete)(pjmedia_transport *tp, 59 pj_ice_strans_op op, 60 pj_status_t status); 61 62 /** 63 * This callback will be called when ICE negotiation completes, with 64 * application user data. Note that if both callbacks are implemented, 65 * only this callback will be invoked. 66 * 67 * @param tp PJMEDIA ICE transport. 68 * @param op The operation 69 * @param status Operation status. 70 * @param user_data User data for this callback. 71 */ 72 void (*on_ice_complete2)(pjmedia_transport *tp, 73 pj_ice_strans_op op, 74 pj_status_t status, 75 void *user_data); 76 77 /** 78 * Callback to report a new ICE local candidate, e.g: after successful 79 * STUN Binding, after a successful TURN allocation. Only new candidates 80 * whose type is server reflexive or relayed will be notified via this 81 * callback. This callback also indicates end-of-candidate via parameter 82 * 'last'. 83 * 84 * Trickle ICE can use this callback to convey the new candidate 85 * to remote agent and monitor end-of-candidate indication. 86 * 87 * @param tp PJMEDIA ICE transport. 88 * @param cand The new local candidate, can be NULL when the last 89 * local candidate initialization failed/timeout. 90 * @param last PJ_TRUE if this is the last of local candidate. 91 */ 92 void (*on_new_candidate)(pjmedia_transport *tp, 93 const pj_ice_sess_cand *cand, 94 pj_bool_t last); 95 96 } pjmedia_ice_cb; 97 98 99 /** 100 * This structure specifies ICE transport specific info. This structure 101 * will be filled in media transport specific info. 102 */ 103 typedef struct pjmedia_ice_transport_info 104 { 105 /** 106 * Specifies whether ICE is used, i.e. SDP offer and answer indicates 107 * that both parties support ICE and ICE should be used for the session. 108 */ 109 pj_bool_t active; 110 111 /** 112 * ICE sesion state. 113 */ 114 pj_ice_strans_state sess_state; 115 116 /** 117 * Session role. 118 */ 119 pj_ice_sess_role role; 120 121 /** 122 * Number of components in the component array. Before ICE negotiation 123 * is complete, the number represents the number of components of the 124 * local agent. After ICE negotiation has been completed successfully, 125 * the number represents the number of common components between local 126 * and remote agents. 127 */ 128 unsigned comp_cnt; 129 130 /** 131 * Array of ICE components. Typically the first element denotes RTP and 132 * second element denotes RTCP. 133 */ 134 struct 135 { 136 /** 137 * Local candidate type. 138 */ 139 pj_ice_cand_type lcand_type; 140 141 /** 142 * The local address. 143 */ 144 pj_sockaddr lcand_addr; 145 146 /** 147 * Remote candidate type. 148 */ 149 pj_ice_cand_type rcand_type; 150 151 /** 152 * Remote address. 153 */ 154 pj_sockaddr rcand_addr; 155 156 } comp[2]; 157 158 } pjmedia_ice_transport_info; 159 160 161 /** 162 * Options that can be specified when creating ICE transport. 163 */ 164 enum pjmedia_transport_ice_options 165 { 166 /** 167 * Normally when remote doesn't use ICE, the ICE transport will 168 * continuously check the source address of incoming packets to see 169 * if it is different than the configured remote address, and switch 170 * the remote address to the source address of the packet if they 171 * are different after several packets are received. 172 * Specifying this option will disable this feature. 173 */ 174 PJMEDIA_ICE_NO_SRC_ADDR_CHECKING = 1, 175 176 /** 177 * The standard (rfc5245) specify that ice-mismatch attribute is used 178 * due to a mismatch of candidates with the default destination for media 179 * signaled in the SDP. The purpose is to identify some poorly ALGs that 180 * alter signaling information in ways that break ICE 181 * (e.g., by rewriting IP addresses in SDP). Specifying this option is 182 * to disable the ice mismatch check and allow ICE to continue 183 * if such scenario occur. 184 */ 185 PJMEDIA_ICE_DISABLE_ICE_MISMATCH = 2 186 }; 187 188 189 /** 190 * Create the Interactive Connectivity Establishment (ICE) media transport 191 * using the specified configuration. When STUN or TURN (or both) is used, 192 * the creation operation will complete asynchronously, when STUN resolution 193 * and TURN allocation completes. When the initialization completes, the 194 * \a on_ice_complete() complete will be called with \a op parameter equal 195 * to PJ_ICE_STRANS_OP_INIT. 196 * 197 * In addition, this transport will also notify the application about the 198 * result of ICE negotiation, also in \a on_ice_complete() callback. In this 199 * case the callback will be called with \a op parameter equal to 200 * PJ_ICE_STRANS_OP_NEGOTIATION. 201 * 202 * Other than this, application should use the \ref PJMEDIA_TRANSPORT API 203 * to manipulate this media transport. 204 * 205 * @param endpt The media endpoint. 206 * @param name Optional name to identify this ICE media transport 207 * for logging purposes. 208 * @param comp_cnt Number of components to be created. 209 * @param cfg Pointer to configuration settings. 210 * @param cb Optional structure containing ICE specific callbacks. 211 * @param p_tp Pointer to receive the media transport instance. 212 * 213 * @return PJ_SUCCESS on success, or the appropriate error code. 214 */ 215 PJ_DECL(pj_status_t) pjmedia_ice_create(pjmedia_endpt *endpt, 216 const char *name, 217 unsigned comp_cnt, 218 const pj_ice_strans_cfg *cfg, 219 const pjmedia_ice_cb *cb, 220 pjmedia_transport **p_tp); 221 222 223 /** 224 * The same as #pjmedia_ice_create() with additional \a options param. 225 * 226 * @param endpt The media endpoint. 227 * @param name Optional name to identify this ICE media transport 228 * for logging purposes. 229 * @param comp_cnt Number of components to be created. 230 * @param cfg Pointer to configuration settings. 231 * @param cb Optional structure containing ICE specific callbacks. 232 * @param options Options, see #pjmedia_transport_ice_options. 233 * @param p_tp Pointer to receive the media transport instance. 234 * 235 * @return PJ_SUCCESS on success, or the appropriate error code. 236 */ 237 PJ_DECL(pj_status_t) pjmedia_ice_create2(pjmedia_endpt *endpt, 238 const char *name, 239 unsigned comp_cnt, 240 const pj_ice_strans_cfg *cfg, 241 const pjmedia_ice_cb *cb, 242 unsigned options, 243 pjmedia_transport **p_tp); 244 245 /** 246 * The same as #pjmedia_ice_create2() with additional \a user_data param. 247 * 248 * @param endpt The media endpoint. 249 * @param name Optional name to identify this ICE media transport 250 * for logging purposes. 251 * @param comp_cnt Number of components to be created. 252 * @param cfg Pointer to configuration settings. 253 * @param cb Optional structure containing ICE specific callbacks. 254 * @param options Options, see #pjmedia_transport_ice_options. 255 * @param user_data User data to be attached to the transport. 256 * @param p_tp Pointer to receive the media transport instance. 257 * 258 * @return PJ_SUCCESS on success, or the appropriate error code. 259 */ 260 PJ_DECL(pj_status_t) pjmedia_ice_create3(pjmedia_endpt *endpt, 261 const char *name, 262 unsigned comp_cnt, 263 const pj_ice_strans_cfg *cfg, 264 const pjmedia_ice_cb *cb, 265 unsigned options, 266 void *user_data, 267 pjmedia_transport **p_tp); 268 269 /** 270 * Get the group lock for the ICE media transport. 271 * 272 * @param tp The ICE media transport. 273 * 274 * @return The group lock. 275 */ 276 PJ_DECL(pj_grp_lock_t *) pjmedia_ice_get_grp_lock(pjmedia_transport *tp); 277 278 279 /** 280 * Add application to receive ICE notifications from the specified ICE media 281 * transport. 282 * 283 * @param tp The ICE media transport. 284 * @param cb The ICE specific callbacks. 285 * @param user_data Optional application user data. 286 * 287 * @return PJ_SUCCESS on success, or the appropriate error code. 288 */ 289 PJ_DECL(pj_status_t) pjmedia_ice_add_ice_cb(pjmedia_transport *tp, 290 const pjmedia_ice_cb *cb, 291 void *user_data); 292 293 294 /** 295 * Remove application to stop receiving ICE notifications from the specified 296 * ICE media transport. 297 * 298 * @param tp The ICE media transport. 299 * @param cb The ICE specific callbacks. 300 * @param user_data Optional application user data. The same user data 301 * passed to pjmedia_ice_add_ice_cb(), this is for 302 * validation purpose. 303 * 304 * @return PJ_SUCCESS on success, or the appropriate error code. 305 */ 306 PJ_DECL(pj_status_t) pjmedia_ice_remove_ice_cb(pjmedia_transport *tp, 307 const pjmedia_ice_cb *cb, 308 void *user_data); 309 310 311 /** 312 * Check if trickle support is signalled in the specified SDP. This function 313 * will check trickle indication in the media level first, if not found, it 314 * will check in the session level. 315 * 316 * @param sdp The SDP. 317 * @param med_idx The media index to be checked. 318 * 319 * @return PJ_TRUE if trickle ICE indication is found. 320 */ 321 PJ_DECL(pj_bool_t) pjmedia_ice_sdp_has_trickle(const pjmedia_sdp_session *sdp, 322 unsigned med_idx); 323 324 325 /** 326 * Update check list after remote ICE candidates list are received or after 327 * or local ICE candidates are conveyed. This function may also be called 328 * after end-of-candidates indication is received or conveyed. ICE 329 * connectivity checks will automatically be started if both sides have 330 * conveyed ICE info (ICE user fragment and/or candidate list). 331 * 332 * To update the check list after conveying any new local candidates, 333 * application can set the remote ICE parameters to NULL or zero. Note that 334 * the checklist should only be updated after any newly found local candidates 335 * are conveyed to remote, instead of immediately after the finding. 336 * 337 * This function is only applicable when trickle ICE is not disabled. 338 * 339 * @param tp The ICE media transport. 340 * @param rem_ufrag Remote ufrag, as seen in the SDP received from 341 * the remote agent. 342 * @param rem_passwd Remote password, as seen in the SDP received from 343 * the remote agent. 344 * @param rcand_cnt Number of new remote candidates in the array. 345 * @param rcand New remote candidates array. 346 * @param rcand_end Set to PJ_TRUE if remote has signalled 347 * end-of-candidate. 348 * 349 * @return PJ_SUCCESS, or the appropriate error code. 350 */ 351 PJ_DECL(pj_status_t) pjmedia_ice_trickle_update( 352 pjmedia_transport *tp, 353 const pj_str_t *rem_ufrag, 354 const pj_str_t *rem_passwd, 355 unsigned rcand_cnt, 356 const pj_ice_sess_cand rcand[], 357 pj_bool_t rcand_end); 358 359 360 /** 361 * Decode trickle ICE info from the specified SDP. 362 * 363 * @param sdp The SDP containing trickle ICE info. 364 * @param media_index The media index. 365 * @param mid Output, media ID. 366 * @param ufrag Output, ufrag. 367 * @param passwd Output, password. 368 * @param cand_cnt On input, maximum number of candidate array. 369 * On output, the number of candidates. 370 * @param cand Output, the candidates. 371 * @param end_of_cand Output, end of candidate indication. 372 * 373 * @return PJ_SUCCESS, or the appropriate error code. 374 */ 375 PJ_DECL(pj_status_t) pjmedia_ice_trickle_decode_sdp( 376 const pjmedia_sdp_session *sdp, 377 unsigned media_index, 378 pj_str_t *mid, 379 pj_str_t *ufrag, 380 pj_str_t *passwd, 381 unsigned *cand_cnt, 382 pj_ice_sess_cand cand[], 383 pj_bool_t *end_of_cand); 384 385 386 /** 387 * Encode trickle ICE info into the specified SDP. This function may generate 388 * the following SDP attributes: 389 * - Media ID, "a=mid". 390 * - ICE ufrag & password, "a=ice-ufrag" & "a=ice-pwd". 391 * - Trickle ICE support indication, "a=ice-options:trickle". 392 * - ICE candidates, "a=candidate". 393 * - End of candidate indication, "a=end-of-candidates". 394 * 395 * @param sdp_pool The memory pool for generating SDP attributes. 396 * @param sdp The SDP to be updated. 397 * @param mid The media ID. 398 * @param ufrag The ufrag, optional. 399 * @param passwd The password, optional. 400 * @param cand_cnt The number of local candidates, can be zero. 401 * @param cand The local candidates. 402 * @param end_of_cand End of candidate indication. 403 * 404 * @return PJ_SUCCESS, or the appropriate error code. 405 */ 406 PJ_DECL(pj_status_t) pjmedia_ice_trickle_encode_sdp( 407 pj_pool_t *sdp_pool, 408 pjmedia_sdp_session *sdp, 409 const pj_str_t *mid, 410 const pj_str_t *ufrag, 411 const pj_str_t *passwd, 412 unsigned cand_cnt, 413 const pj_ice_sess_cand cand[], 414 pj_bool_t end_of_cand); 415 416 417 /** 418 * Check if trickling ICE has found any new local candidates since the last 419 * conveyance (via pjmedia_ice_trickle_send_local_cand()). 420 * 421 * @param tp The ICE media transport. 422 * 423 * @return PJ_TRUE if new local canditates are available. 424 */ 425 PJ_DECL(pj_bool_t) pjmedia_ice_trickle_has_new_cand(pjmedia_transport *tp); 426 427 428 /** 429 * Convey all local candidates via the specified SDP. 430 * 431 * @param tp The ICE media transport. 432 * @param sdp_pool The memory pool for generating SDP attributes. 433 * @param sdp The SDP. 434 * @param p_end_of_cand Optional, pointer to receive the indication that 435 * candidate gathering has been completed. 436 * 437 * @return PJ_SUCCESS, or the appropriate error code. 438 */ 439 PJ_DECL(pj_status_t) pjmedia_ice_trickle_send_local_cand( 440 pjmedia_transport *tp, 441 pj_pool_t *sdp_pool, 442 pjmedia_sdp_session *sdp, 443 pj_bool_t *p_end_of_cand); 444 445 446 PJ_END_DECL 447 448 449 /** 450 * @} 451 */ 452 453 454 #endif /* __PJMEDIA_TRANSPORT_ICE_H__ */ 455 456 457