ice.h 32.3 KB
Newer Older
Ghislain MARY's avatar
Ghislain MARY committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
/*
mediastreamer2 library - modular sound and video processing and streaming
Copyright (C) 2012  Belledonne Communications

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
*/

#ifndef ice_h
#define ice_h

23 24
#include <mediastreamer2/mscommon.h>
#include <ortp/ortp.h>
Ghislain MARY's avatar
Ghislain MARY committed
25 26


Ghislain MARY's avatar
Ghislain MARY committed
27 28 29 30 31 32 33 34
/**
 * @file ice.h
 * @brief mediastreamer2 ice.h include file
 *
 * This file provides the API to handle the ICE protocol defined in the RFC 5245.
 */


35 36 37 38 39 40
/**
 * The maximum number of check lists in an ICE session.
 */
#define ICE_SESSION_MAX_CHECK_LISTS 8


Ghislain MARY's avatar
Ghislain MARY committed
41 42 43 44 45
/**
 * ICE agent role.
 *
 * See the terminology in paragraph 3 of the RFC 5245 for more details.
 */
Ghislain MARY's avatar
Ghislain MARY committed
46 47 48 49 50
typedef enum {
	IR_Controlling,
	IR_Controlled
} IceRole;

Ghislain MARY's avatar
Ghislain MARY committed
51 52 53 54 55
/**
 * ICE candidate type.
 *
 * See the terminology in paragraph 3 of the RFC 5245 for more details.
 */
Ghislain MARY's avatar
Ghislain MARY committed
56
typedef enum {
57 58 59 60
	ICT_HostCandidate,
	ICT_ServerReflexiveCandidate,
	ICT_PeerReflexiveCandidate,
	ICT_RelayedCandidate
Ghislain MARY's avatar
Ghislain MARY committed
61 62
} IceCandidateType;

Ghislain MARY's avatar
Ghislain MARY committed
63 64 65 66 67
/**
 * ICE candidate pair state.
 *
 * See paragraph 5.7.4 ("Computing states") of RFC 5245 for more details.
 */
68 69 70 71 72 73 74 75
typedef enum {
	ICP_Waiting,
	ICP_InProgress,
	ICP_Succeeded,
	ICP_Failed,
	ICP_Frozen
} IceCandidatePairState;

Ghislain MARY's avatar
Ghislain MARY committed
76 77 78 79 80
/**
 * ICE check list state.
 *
 * See paragraph 5.7.4 ("Computing states") of RFC 5245 for more details.
 */
81 82 83 84 85 86
typedef enum {
	ICL_Running,
	ICL_Completed,
	ICL_Failed
} IceCheckListState;

Ghislain MARY's avatar
Ghislain MARY committed
87 88 89 90 91 92 93 94 95 96
/**
 * ICE session state.
 */
typedef enum {
	IS_Stopped,
	IS_Running,
	IS_Completed,
	IS_Failed
} IceSessionState;

97 98
struct _IceCheckList;

Ghislain MARY's avatar
Ghislain MARY committed
99 100 101
/**
 * Structure representing an ICE session.
 */
Ghislain MARY's avatar
Ghislain MARY committed
102
typedef struct _IceSession {
103
	struct _IceCheckList * streams[ICE_SESSION_MAX_CHECK_LISTS];	/**< Table of IceChecklist structure pointers. Each element represents a media stream */
Ghislain MARY's avatar
Ghislain MARY committed
104 105 106 107 108
	char *local_ufrag;	/**< Local username fragment for the session (assigned during the session creation) */
	char *local_pwd;	/**< Local password for the session (assigned during the session creation) */
	char *remote_ufrag;	/**< Remote username fragment for the session (provided via SDP by the peer) */
	char *remote_pwd;	/**< Remote password for the session (provided via SDP by the peer) */
	IceRole role;	/**< Role played by the agent for this session */
Ghislain MARY's avatar
Ghislain MARY committed
109
	IceSessionState state;	/**< State of the session */
Ghislain MARY's avatar
Ghislain MARY committed
110
	uint64_t tie_breaker;	/**< Random number used to resolve role conflicts (see paragraph 5.2 of the RFC 5245) */
111
	uint32_t ta;	/**< Duration of timer for sending connectivity checks in ms */
112
	int event_value;	/** Value of the event to send */
113
	MSTimeSpec event_time;	/**< Time when an event must be sent */
114 115
	struct sockaddr_storage ss;	/**< STUN server address to use for the candidates gathering process */
	socklen_t ss_len;	/**< Length of the STUN server address to use for the candidates gathering process */
116 117
	MSTimeSpec gathering_start_ts;
	MSTimeSpec gathering_end_ts;
118
	bool_t check_message_integrity; /*set to false for backward compatibility only*/
119 120 121
	bool_t send_event;	/**< Boolean value telling whether an event must be sent or not */
	uint8_t max_connectivity_checks;	/**< Configuration parameter to limit the number of connectivity checks performed by the agent (default is 100) */
	uint8_t keepalive_timeout;	/**< Configuration parameter to define the timeout between each keepalive packets (default is 15s) */
Ghislain MARY's avatar
Ghislain MARY committed
122 123
} IceSession;

124 125 126 127 128 129
typedef struct _IceStunServerCheckTransaction {
	UInt96 transactionID;
	MSTimeSpec request_time;
	MSTimeSpec response_time;
} IceStunServerCheckTransaction;

130
typedef struct _IceStunServerCheck {
131
	RtpTransport *rtptp;
132
	int srcport;
133 134 135
	MSList *transactions;	/**< List of IceStunServerCheckTransaction structures. */
	MSTimeSpec next_transmission_time;
	bool_t responded;
136 137
} IceStunServerCheck;

Ghislain MARY's avatar
Ghislain MARY committed
138 139 140
/**
 * Structure representing an ICE transport address.
 */
141
typedef struct _IceTransportAddress {
Ghislain MARY's avatar
Ghislain MARY committed
142 143
	char ip[64];
	int port;
144
	// TODO: Handling of IP version (4 or 6) and transport type: TCP, UDP...
Ghislain MARY's avatar
Ghislain MARY committed
145 146
} IceTransportAddress;

Ghislain MARY's avatar
Ghislain MARY committed
147 148 149
/**
 * Structure representing an ICE candidate.
 */
150
typedef struct _IceCandidate {
Ghislain MARY's avatar
Ghislain MARY committed
151 152 153 154
	char foundation[32];	/**< Foundation of the candidate (see paragraph 3 of the RFC 5245 for more details */
	IceTransportAddress taddr;	/**< Transport address of the candidate */
	IceCandidateType type;	/**< Type of the candidate */
	uint32_t priority;	/**< Priority of the candidate */
155
	uint16_t componentID;	/**< component ID between 1 and 256: usually 1 for RTP component and 2 for RTCP component */
Ghislain MARY's avatar
Ghislain MARY committed
156 157
	struct _IceCandidate *base;	/**< Pointer to the candidate that is the base of the current one */
	bool_t is_default;	/**< Boolean value telling whether this candidate is a default candidate or not */
Ghislain MARY's avatar
Ghislain MARY committed
158 159
} IceCandidate;

Ghislain MARY's avatar
Ghislain MARY committed
160 161 162
/**
 * Structure representing an ICE candidate pair.
 */
163
typedef struct _IceCandidatePair {
Ghislain MARY's avatar
Ghislain MARY committed
164 165 166 167
	IceCandidate *local;	/**< Pointer to the local candidate of the pair */
	IceCandidate *remote;	/**< Pointer to the remote candidate of the pair */
	IceCandidatePairState state;	/**< State of the candidate pair */
	uint64_t priority;	/**< Priority of the candidate pair */
168
	MSTimeSpec transmission_time;	/**< Time when the connectivity check for the candidate pair has been sent */
169 170
	uint32_t rto;	/**< Duration of the retransmit timer for the connectivity check sent for the candidate pair in ms */
	uint8_t retransmissions;	/**< Number of retransmissions for the connectivity check sent for the candidate pair */
171
	IceRole role;	/**< Role of the agent when the connectivity check has been sent for the candidate pair */
Ghislain MARY's avatar
Ghislain MARY committed
172
	bool_t is_default;	/**< Boolean value telling whether this candidate pair is a default candidate pair or not */
173
	bool_t use_candidate;	/**< Boolean value telling if the USE-CANDIDATE attribute must be set for the connectivity checks send for the candidate pair */
174
	bool_t is_nominated;	/**< Boolean value telling whether this candidate pair is nominated or not */
175
	bool_t wait_transaction_timeout;	/**< Boolean value telling to create a new binding request on retransmission timeout */
176 177
	bool_t retry_with_dummy_message_integrity; /** use to tell to retry with dummy message integrity. Useful to keep backward compatibility with older version*/
	bool_t use_dummy_hmac; /*don't compute real hmac. used for backward compatibility*/
Ghislain MARY's avatar
Ghislain MARY committed
178 179
} IceCandidatePair;

Ghislain MARY's avatar
Ghislain MARY committed
180 181 182 183 184
/**
 * Structure representing the foundation of an ICE candidate pair.
 *
 * It is the concatenation of the foundation of a local candidate and the foundation of a remote candidate.
 */
185
typedef struct _IcePairFoundation {
Ghislain MARY's avatar
Ghislain MARY committed
186 187
	char local[32];	/**< Foundation of the local candidate */
	char remote[32];	/**< Foundation of the remote candidate */
188 189
} IcePairFoundation;

190
typedef struct _IceValidCandidatePair {
191 192
	IceCandidatePair *valid;	/**< Pointer to a valid candidate pair (it may be in the check list or not */
	IceCandidatePair *generated_from;	/**< Pointer to the candidate pair that generated the connectivity check producing the valid candidate pair */
193
	bool_t selected;	/**< Boolean value telling whether this valid candidate pair has been selected or not */
194 195
} IceValidCandidatePair;

196 197 198 199 200
typedef struct _IceTransaction {
	UInt96 transactionID;	/**< Transaction ID of the connectivity check sent for the candidate pair */
	IceCandidatePair *pair;	/**< A pointer to the candidate pair associated with the transaction. */
} IceTransaction;

Ghislain MARY's avatar
Ghislain MARY committed
201 202 203 204 205 206
/**
 * Structure representing an ICE check list.
 *
 * Each media stream must be assigned a check list.
 * Check lists are added to an ICE session using the ice_session_add_check_list() function.
 */
207
typedef struct _IceCheckList {
208
	IceSession *session;	/**< Pointer to the ICE session */
209
	RtpSession *rtp_session;	/**< Pointer to the RTP session associated with this ICE check list */
210 211
	char *remote_ufrag;	/**< Remote username fragment for this check list (provided via SDP by the peer) */
	char *remote_pwd;	/**< Remote password for this check list (provided via SDP by the peer) */
212
	MSList *stun_server_checks;	/**< List of IceStunServerCheck structures */
213 214 215
	MSList *local_candidates;	/**< List of IceCandidate structures */
	MSList *remote_candidates;	/**< List of IceCandidate structures */
	MSList *pairs;	/**< List of IceCandidatePair structures */
216
	MSList *losing_pairs;	/**< List of IceCandidatePair structures */
217
	MSList *triggered_checks_queue;	/**< List of IceCandidatePair structures */
218
	MSList *check_list;	/**< List of IceCandidatePair structures */
219
	MSList *valid_list;	/**< List of IceValidCandidatePair structures */
220
	MSList *foundations;	/**< List of IcePairFoundation structures */
Ghislain MARY's avatar
Ghislain MARY committed
221 222
	MSList *local_componentIDs;	/**< List of uint16_t */
	MSList *remote_componentIDs;	/**< List of uint16_t */
223
	MSList *transaction_list;	/**< List of IceTransaction structures */
224
	IceCheckListState state;	/**< Global state of the ICE check list */
225 226
	MSTimeSpec ta_time;	/**< Time when the Ta timer has been processed for the last time */
	MSTimeSpec keepalive_time;	/**< Time when the last keepalive packet has been sent for this stream */
227
	uint32_t foundation_generator;	/**< Autoincremented integer to generate unique foundation values */
Ghislain MARY's avatar
Ghislain MARY committed
228
	bool_t mismatch;	/**< Boolean value telling whether there was a mismatch during the answer/offer process */
229
	bool_t gathering_candidates;	/**< Boolean value telling whether a candidate gathering process is running or not */
230
	bool_t gathering_finished;	/**< Boolean value telling whether the candidate gathering process has finished or not */
231
	bool_t nomination_delay_running;	/**< Boolean value telling whether the nomination process has been delayed or not */
232
	MSTimeSpec gathering_start_time;	/**< Time when the gathering process was started */
233
	MSTimeSpec nomination_delay_start_time;	/**< Time when the nomination process has been delayed */
Ghislain MARY's avatar
Ghislain MARY committed
234 235 236
} IceCheckList;


237

Ghislain MARY's avatar
Ghislain MARY committed
238 239 240 241
#ifdef __cplusplus
extern "C"{
#endif

Ghislain MARY's avatar
Ghislain MARY committed
242 243 244 245 246 247 248 249
/**
 * Allocate a new ICE session.
 *
 * @return Pointer to the allocated session
 *
 * This must be performed for each media session that is to use ICE.
 */
MS2_PUBLIC IceSession * ice_session_new(void);
Ghislain MARY's avatar
Ghislain MARY committed
250

Ghislain MARY's avatar
Ghislain MARY committed
251 252 253 254 255 256 257 258
/**
 * Destroy a previously allocated ICE session.
 *
 * @param session The session to destroy.
 *
 * To be used when a media session using ICE is tore down.
 */
MS2_PUBLIC void ice_session_destroy(IceSession *session);
Ghislain MARY's avatar
Ghislain MARY committed
259

Ghislain MARY's avatar
Ghislain MARY committed
260 261 262 263 264 265 266
/**
 * Allocate a new ICE check list.
 *
 * @return Pointer to the allocated check list
 *
 * A check list must be allocated for each media stream of a media session and be added to an ICE session using the ice_session_add_check_list() function.
 */
267 268
MS2_PUBLIC IceCheckList * ice_check_list_new(void);

Ghislain MARY's avatar
Ghislain MARY committed
269 270 271 272 273 274
/**
 * Destroy a previously allocated ICE check list.
 *
 * @param cl The check list to destroy
 */
MS2_PUBLIC void ice_check_list_destroy(IceCheckList *cl);
275

276 277 278
/**
 * Tell whether ICE local candidates have been gathered for an ICE check list or not.
 *
279
 * @param cl A pointer to a check list
280 281 282 283
 * @return TRUE if local candidates have been gathered for the check list, FALSE otherwise.
 */
MS2_PUBLIC bool_t ice_check_list_candidates_gathered(const IceCheckList *cl);

284 285 286 287 288 289 290
/**
 * Get the nth check list of an ICE session.
 *
 * @param session A pointer to a session
 * @param n The number of the check list to access
 * @return A pointer to the nth check list of the session if it exists, NULL otherwise
 */
291
MS2_PUBLIC IceCheckList *ice_session_check_list(const IceSession *session, int n);
292

Ghislain MARY's avatar
Ghislain MARY committed
293 294 295 296 297 298
/**
 * Get the local username fragment of an ICE session.
 *
 * @param session A pointer to a session
 * @return A pointer to the local username fragment of the session
 */
299
MS2_PUBLIC const char * ice_session_local_ufrag(const IceSession *session);
Ghislain MARY's avatar
Ghislain MARY committed
300

Ghislain MARY's avatar
Ghislain MARY committed
301 302 303 304 305 306
/**
 * Get the local password of an ICE session.
 *
 * @param session A pointer to a session
 * @return A pointer to the local password of the session
 */
307
MS2_PUBLIC const char * ice_session_local_pwd(const IceSession *session);
Ghislain MARY's avatar
Ghislain MARY committed
308

Ghislain MARY's avatar
Ghislain MARY committed
309 310 311 312 313 314
/**
 * Get the remote username fragment of an ICE session.
 *
 * @param session A pointer to a session
 * @return A pointer to the remote username fragment of the session
 */
315
MS2_PUBLIC const char * ice_session_remote_ufrag(const IceSession *session);
Ghislain MARY's avatar
Ghislain MARY committed
316

Ghislain MARY's avatar
Ghislain MARY committed
317 318 319 320 321 322
/**
 * Get the remote password of an ICE session.
 *
 * @param session A pointer to a session
 * @return A pointer to the remote password of the session
 */
323
MS2_PUBLIC const char * ice_session_remote_pwd(const IceSession *session);
Ghislain MARY's avatar
Ghislain MARY committed
324

325 326 327 328 329 330 331 332
/**
 * Get the state of an ICE session.
 *
 * @param session A pointer to a session
 * @return The state of the session
 */
MS2_PUBLIC IceSessionState ice_session_state(const IceSession *session);

Ghislain MARY's avatar
Ghislain MARY committed
333 334 335 336 337 338
/**
 * Gte the role of the agent for an ICE session.
 *
 * @param session A pointer to a session
 * @return The role of the agent for the session
 */
339
MS2_PUBLIC IceRole ice_session_role(const IceSession *session);
Ghislain MARY's avatar
Ghislain MARY committed
340

Ghislain MARY's avatar
Ghislain MARY committed
341 342 343 344 345 346 347
/**
 * Set the role of the agent for an ICE session.
 *
 * @param session The session for which to set the role
 * @param role The role to set the session to
 */
MS2_PUBLIC void ice_session_set_role(IceSession *session, IceRole role);
Ghislain MARY's avatar
Ghislain MARY committed
348

Ghislain MARY's avatar
Ghislain MARY committed
349
/**
Ghislain MARY's avatar
Ghislain MARY committed
350 351
 * Set the local credentials of an ICE session.
 *
Ghislain MARY's avatar
Ghislain MARY committed
352 353 354
 * This function SHOULD not be used. However, it is used by mediastream for testing purpose to
 * apply the same credentials for local and remote agents because the SDP exchange is bypassed.
 */
355
MS2_PUBLIC void ice_session_set_local_credentials(IceSession *session, const char *ufrag, const char *pwd);
Ghislain MARY's avatar
Ghislain MARY committed
356

357 358 359 360 361 362 363 364 365 366
/**
 * Tell if remote credentials of an ICE session have changed or not.
 *
 * @param session A pointer to a session
 * @param ufrag The new remote username fragment
 * @param pwd The new remote password
 * @return TRUE if the remote credentials of the session have changed, FALSE otherwise.
 */
MS2_PUBLIC bool_t ice_session_remote_credentials_changed(IceSession *session, const char *ufrag, const char *pwd);

Ghislain MARY's avatar
Ghislain MARY committed
367 368 369 370 371 372 373 374 375 376
/**
 * Set the remote credentials of an ICE session.
 *
 * @param session A pointer to a session
 * @param ufrag The remote username fragment
 * @param pwd The remote password
 *
 * This function is to be called once the remote credentials have been received via SDP.
 */
MS2_PUBLIC void ice_session_set_remote_credentials(IceSession *session, const char *ufrag, const char *pwd);
Ghislain MARY's avatar
Ghislain MARY committed
377

378 379 380 381 382 383 384
/**
 * get the remote ufrag of an ICE check list.
 *
 * @param cl A pointer to a check list
 *
 * This function is to be called once the remote credentials have been received via SDP.
 */
385
MS2_PUBLIC const char* ice_check_list_get_remote_ufrag(const IceCheckList *cl);
386 387 388 389 390 391 392 393

/**
 * get the remote pwd of an ICE check list.
 *
 * @param cl A pointer to a check list
 *
 * This function is to be called once the remote credentials have been received via SDP.
 */
394
MS2_PUBLIC const char* ice_check_list_get_remote_pwd(const IceCheckList *cl);
395

Ghislain MARY's avatar
Ghislain MARY committed
396 397 398 399 400 401 402 403 404 405
/**
 * Define the maximum number of connectivity checks that will be performed by the agent.
 *
 * @param session A pointer to a session
 * @param max_connectivity_checks The maximum number of connectivity checks to perform
 *
 * This function is to be called just after the creation of the session, before any connectivity check is performed.
 * The default number of connectivity checks is 100.
 */
MS2_PUBLIC void ice_session_set_max_connectivity_checks(IceSession *session, uint8_t max_connectivity_checks);
406

Ghislain MARY's avatar
Ghislain MARY committed
407 408 409 410 411 412 413 414 415 416
/**
 * Define the timeout between each keepalive packet in seconds.
 *
 * @param session A pointer to a session
 * @param timeout The duration of the keepalive timeout in seconds
 *
 * The default keepalive timeout is set to 15 seconds.
 */
MS2_PUBLIC void ice_session_set_keepalive_timeout(IceSession *session, uint8_t timeout);

417 418 419 420 421 422 423 424
/**
 * Get the number of check lists in an ICE session.
 *
 * @param session A pointer to a session
 * @return The number of check lists in the ICE session
 */
MS2_PUBLIC int ice_session_nb_check_lists(IceSession *session);

425 426 427 428 429 430 431 432
/**
 * Tell whether an ICE session has at least one completed check list.
 *
 * @param session A pointer to a session
 * @return TRUE if the session has at least one completed check list, FALSE otherwise
 */
MS2_PUBLIC bool_t ice_session_has_completed_check_list(const IceSession *session);

Ghislain MARY's avatar
Ghislain MARY committed
433 434 435 436 437
/**
 * Add an ICE check list to an ICE session.
 *
 * @param session The session that is assigned the check list
 * @param cl The check list to assign to the session
438
 * @param idx The index of the check list to add
Ghislain MARY's avatar
Ghislain MARY committed
439
 */
440
MS2_PUBLIC void ice_session_add_check_list(IceSession *session, IceCheckList *cl, unsigned int idx);
Ghislain MARY's avatar
Ghislain MARY committed
441

442 443 444 445 446 447 448 449
/**
 * Remove an ICE check list from an ICE session.
 *
 * @param session The session from which to remove the check list
 * @param cl The check list to remove from the session
 */
MS2_PUBLIC void ice_session_remove_check_list(IceSession *session, IceCheckList *cl);

450 451 452 453 454 455 456 457
/**
 * Remove an ICE check list from an ICE session given its index.
 *
 * @param session The session from which to remove the check list
 * @param idx The index of the check list in the ICE session
 */
MS2_PUBLIC void ice_session_remove_check_list_from_idx(IceSession *session, unsigned int idx);

458 459 460 461 462 463 464 465
/**
 * Tell whether ICE local candidates have been gathered for an ICE session or not.
 *
 * @param session A pointer to a session
 * @return TRUE if local candidates have been gathered for the session, FALSE otherwise.
 */
MS2_PUBLIC bool_t ice_session_candidates_gathered(const IceSession *session);

466 467 468 469 470 471 472
/**
 * Gather ICE local candidates for an ICE session.
 *
 * @param session A pointer to a session
 * @param ss The STUN server address
 * @param ss_len The length of the STUN server address
 */
473
MS2_PUBLIC void ice_session_gather_candidates(IceSession *session, const struct sockaddr * ss, socklen_t ss_len);
474

475 476 477 478 479 480 481 482
/**
 * Tell the duration of the gathering process for an ICE session in ms.
 *
 * @param session A pointer to a session
 * @return -1 if gathering has not been run, the duration of the gathering process in ms otherwise.
 */
MS2_PUBLIC int ice_session_gathering_duration(IceSession *session);

483 484 485 486 487 488 489 490
/**
 * Tell the average round trip time during the gathering process for an ICE session in ms.
 *
 * @param session A pointer to a session
 * @return -1 if gathering has not been run, the average round trip time in ms otherwise.
 */
MS2_PUBLIC int ice_session_average_gathering_round_trip_time(IceSession *session);

491 492 493 494 495 496 497 498 499
/**
 * Select ICE candidates that will be used and notified in the SDP.
 *
 * @param session A pointer to a session
 *
 * This function is to be used by the Controlling agent when ICE processing has finished.
 */
MS2_PUBLIC void ice_session_select_candidates(IceSession *session);

500 501 502 503 504 505 506
/**
 * Restart an ICE session.
 *
 * @param session A pointer to a session
 */
MS2_PUBLIC void ice_session_restart(IceSession *session);

Ghislain MARY's avatar
Ghislain MARY committed
507 508 509 510 511 512
/**
 * Get the state of an ICE check list.
 *
 * @param cl A pointer to a check list
 * @return The check list state
 */
513
MS2_PUBLIC IceCheckListState ice_check_list_state(const IceCheckList *cl);
514

515 516 517 518 519 520 521
/**
 * Set the state of an ICE check list.
 *
 * @param cl A pointer to a check list
 * @param state The new state of the check list
 */
MS2_PUBLIC void ice_check_list_set_state(IceCheckList *cl, IceCheckListState state);
jehan's avatar
jehan committed
522 523 524 525 526 527 528
/**
 * Humanly readable IceCheckListState
 *
 * @param state The state of the check list
 * @return a humanly readable IceCheckListState.
 */
MS2_PUBLIC const char* ice_check_list_state_to_string(const IceCheckListState state);
529 530 531 532 533 534 535 536
/**
 * Assign an RTP session to an ICE check list.
 *
 * @param cl A pointer to a check list
 * @param rtp_session A pointer to the RTP session to assign to the check list
 */
MS2_PUBLIC void ice_check_list_set_rtp_session(IceCheckList *cl, RtpSession *rtp_session);

Ghislain MARY's avatar
Ghislain MARY committed
537 538 539 540 541 542
/**
 * Get the local username fragment of an ICE check list.
 *
 * @param cl A pointer to a check list
 * @return A pointer to the local username fragment of the check list
 */
543
MS2_PUBLIC const char * ice_check_list_local_ufrag(const IceCheckList *cl);
Ghislain MARY's avatar
Ghislain MARY committed
544

Ghislain MARY's avatar
Ghislain MARY committed
545 546 547 548 549 550
/**
 * Get the local password of an ICE check list.
 *
 * @param cl A pointer to a check list
 * @return A pointer to the local password of the check list
 */
551
MS2_PUBLIC const char * ice_check_list_local_pwd(const IceCheckList *cl);
Ghislain MARY's avatar
Ghislain MARY committed
552

Ghislain MARY's avatar
Ghislain MARY committed
553 554 555 556 557 558
/**
 * Get the remote username fragment of an ICE check list.
 *
 * @param cl A pointer to a check list
 * @return A pointer to the remote username fragment of the check list
 */
559
MS2_PUBLIC const char * ice_check_list_remote_ufrag(const IceCheckList *cl);
Ghislain MARY's avatar
Ghislain MARY committed
560

Ghislain MARY's avatar
Ghislain MARY committed
561 562 563 564 565 566
/**
 * Get the remote password of an ICE check list.
 *
 * @param cl A pointer to a check list
 * @return A pointer to the remote password of the check list
 */
567
MS2_PUBLIC const char * ice_check_list_remote_pwd(const IceCheckList *cl);
Ghislain MARY's avatar
Ghislain MARY committed
568

Ghislain MARY's avatar
Ghislain MARY committed
569 570 571 572 573 574 575 576
/**
 * Get the mismatch property of an ICE check list.
 *
 * @param cl A pointer to a check list
 * @return TRUE if there was a mismatch for the check list, FALSE otherwise
 */
MS2_PUBLIC bool_t ice_check_list_is_mismatch(const IceCheckList *cl);

577 578 579 580 581 582 583 584 585 586
/**
 * Tell if remote credentials of an ICE check list have changed or not.
 *
 * @param cl A pointer to a check list
 * @param ufrag The new remote username fragment
 * @param pwd The new remote password
 * @return TRUE if the remote credentials of the check list have changed, FALSE otherwise.
 */
MS2_PUBLIC bool_t ice_check_list_remote_credentials_changed(IceCheckList *cl, const char *ufrag, const char *pwd);

587 588 589 590 591 592 593 594 595 596 597
/**
 * Set the remote credentials of an ICE check list.
 *
 * @param cl A pointer to a check list
 * @param ufrag The remote username fragment
 * @param pwd The remote password
 *
 * This function is to be called once the remote credentials have been received via SDP.
 */
MS2_PUBLIC void ice_check_list_set_remote_credentials(IceCheckList *cl, const char *ufrag, const char *pwd);

598 599 600 601
/**
 * Get the default local candidate for an ICE check list.
 *
 * @param cl A pointer to a check list
602 603 604 605 606
 * @param rtp_addr A pointer to store the RTP address
 * @param rtp_port A pointer to store the RTP port
 * @param rtcp_addr A pointer to store the RTCP address
 * @param rtcp_port A pointer to store the RTCP port
 * @return TRUE if the information have been successfully retrieved, FALSE otherwise
607
 */
608
MS2_PUBLIC bool_t ice_check_list_default_local_candidate(const IceCheckList *cl, const char **rtp_addr, int *rtp_port, const char **rtcp_addr, int *rtcp_port);
609

Ghislain MARY's avatar
Ghislain MARY committed
610
/**
611
 * Get the selected valid local candidate for an ICE check list.
Ghislain MARY's avatar
Ghislain MARY committed
612 613
 *
 * @param cl A pointer to a check list
614 615 616 617 618
 * @param rtp_addr A pointer to store the RTP address
 * @param rtp_port A pointer to store the RTP port
 * @param rtcp_addr A pointer to store the RTCP address
 * @param rtcp_port A pointer to store the RTCP port
 * @return TRUE if the information have been successfully retrieved, FALSE otherwise
Ghislain MARY's avatar
Ghislain MARY committed
619
 */
620
MS2_PUBLIC bool_t ice_check_list_selected_valid_local_candidate(const IceCheckList *cl, const char **rtp_addr, int *rtp_port, const char **rtcp_addr, int *rtcp_port);
Ghislain MARY's avatar
Ghislain MARY committed
621

622
/**
623
 * Get the selected valid remote candidate for an ICE check list.
624 625 626 627 628 629 630 631
 *
 * @param cl A pointer to a check list
 * @param rtp_addr A pointer to store the RTP address
 * @param rtp_port A pointer to store the RTP port
 * @param rtcp_addr A pointer to store the RTCP address
 * @param rtcp_port A pointer to store the RTCP port
 * @return TRUE if the information have been successfully retrieved, FALSE otherwise
 */
632
MS2_PUBLIC bool_t ice_check_list_selected_valid_remote_candidate(const IceCheckList *cl, const char **rtp_addr, int *rtp_port, const char **rtcp_addr, int *rtcp_port);
633

634 635 636 637 638 639 640 641
/**
 * Get the type of the selected valid candidate for an ICE check list.
 *
 * @param cl A pointer to a check list
 * @return The type of the selected valid candidate
 */
MS2_PUBLIC IceCandidateType ice_check_list_selected_valid_candidate_type(const IceCheckList *cl);

642 643 644 645 646 647 648
/**
 * Check if an ICE check list can be set in the Completed state after handling losing pairs.
 *
 * @param cl A pointer to a check list
 */
MS2_PUBLIC void ice_check_list_check_completed(IceCheckList *cl);

649 650 651 652 653 654
/**
 * Get the candidate type as a string.
 *
 * @param candidate A pointer to a candidate
 * @return A pointer to the candidate type as a string
 */
655
MS2_PUBLIC const char * ice_candidate_type(const IceCandidate *candidate);
656

657
/**
Ghislain MARY's avatar
Ghislain MARY committed
658 659
 * Add a local candidate to an ICE check list.
 *
Ghislain MARY's avatar
Ghislain MARY committed
660 661 662 663 664 665 666 667
 * @param cl A pointer to a check list
 * @param type The type of the local candidate to add as a string (must be one of: "host", "srflx", "prflx" or "relay")
 * @param ip The IP address of the local candidate as a string (eg. 192.168.0.10)
 * @param port The port of the local candidate
 * @param componentID The component ID of the local candidate (usually 1 for RTP and 2 for RTCP)
 * @param base A pointer to the base candidate of the candidate to add.
 *
 * This function is to be called when gathering local candidates.
668
 */
Ghislain MARY's avatar
Ghislain MARY committed
669
MS2_PUBLIC IceCandidate * ice_add_local_candidate(IceCheckList *cl, const char *type, const char *ip, int port, uint16_t componentID, IceCandidate *base);
670

Ghislain MARY's avatar
Ghislain MARY committed
671 672 673 674 675 676 677 678 679 680
/**
 * Add a remote candidate to an ICE check list.
 *
 * @param cl A pointer to a check list
 * @param type The type of the remote candidate to add as a string (must be one of: "host", "srflx", "prflx" or "relay")
 * @param ip The IP address of the remote candidate as a string (eg. 192.168.0.10)
 * @param port The port of the remote candidate
 * @param componentID The component ID of the remote candidate (usually 1 for RTP and 2 for RTCP)
 * @param priority The priority of the remote candidate
 * @param foundation The foundation of the remote candidate
681
 * @param is_default Boolean value telling whether the remote candidate is a default candidate or not
Ghislain MARY's avatar
Ghislain MARY committed
682 683 684
 *
 * This function is to be called once the remote candidate list has been received via SDP.
 */
685
MS2_PUBLIC IceCandidate * ice_add_remote_candidate(IceCheckList *cl, const char *type, const char *ip, int port, uint16_t componentID, uint32_t priority, const char * const foundation, bool_t is_default);
686

687 688 689 690 691 692 693 694 695 696 697 698 699 700
/**
 * Add a losing pair to an ICE check list.
 *
 * @param cl A pointer to a check list
 * @param componentID The component ID of the candidates of the pair to add
 * @param local_addr The address of the local candidate of the pair to add
 * @param local_port The port of the local candidate of the pair to add
 * @param remote_addr The address of the remote candidate of the pair to add
 * @param remote_port The port of the remote candidate of the pair to add
 *
 * This function is to be called when a RE-INVITE with an SDP containing a remote-candidates attribute is received.
 */
MS2_PUBLIC void ice_add_losing_pair(IceCheckList *cl, uint16_t componentID, const char *local_addr, int local_port, const char *remote_addr, int remote_port);

701 702 703 704 705 706 707 708
/**
 * Get the number of losing candidate pairs for an ICE session.
 *
 * @param session A pointer to a session
 * @return The number of losing candidate pairs for the session.
 */
MS2_PUBLIC int ice_session_nb_losing_pairs(const IceSession *session);

709 710 711 712 713 714 715 716 717
/**
 * Unselect the previously selected valid pairs.
 *
 * @param cl A pointer to a check list
 *
 * This function is to be used to use the pairs given by the remote controlling agent instead of the pairs we found ourselves.
 */
MS2_PUBLIC void ice_check_list_unselect_valid_pairs(IceCheckList *cl);

718 719 720 721 722 723 724
/**
 * Set the base for the local server reflexive candidates of an ICE session.
 *
 * This function SHOULD not be used. However, it is used by mediastream for testing purpose to
 * work around the fact that it does not use candidates gathering.
 * It is to be called automatically when the gathering process finishes.
 */
725
MS2_PUBLIC void ice_session_set_base_for_srflx_candidates(IceSession *session);
726

727 728 729 730 731 732 733 734 735
/**
 * Remove local and remote RTCP candidates from an ICE check list.
 * 
 * @param cl A pointer to a check list
 *
 * This function MUST be called before calling ice_session_start_connectivity_checks(). It is useful when using rtcp-mux.
 */
MS2_PUBLIC void ice_check_list_remove_rtcp_candidates(IceCheckList *cl);

736 737 738
/**
 * Compute the foundations of the local candidates of an ICE session.
 *
Ghislain MARY's avatar
Ghislain MARY committed
739 740 741 742
 * @param session A pointer to a session
 *
 * This function is to be called at the end of the local candidates gathering process, before sending
 * the SDP to the remote agent.
743
 */
Ghislain MARY's avatar
Ghislain MARY committed
744
MS2_PUBLIC void ice_session_compute_candidates_foundations(IceSession *session);
745

746 747 748 749 750 751 752 753 754 755
/**
 * Eliminate the redundant candidates of an ICE session.
 *
 * @param session A pointer to a session
 *
 * This function is to be called at the end of the local candidates gathering process, before sending
 * the SDP to the remote agent.
 */
MS2_PUBLIC void ice_session_eliminate_redundant_candidates(IceSession *session);

756 757 758 759 760
/**
 * Choose the default candidates of an ICE session.
 *
 * @param session A pointer to a session
 *
Ghislain MARY's avatar
Ghislain MARY committed
761 762
 * This function is to be called at the end of the local candidates gathering process, before sending
 * the SDP to the remote agent.
763 764
 */
MS2_PUBLIC void ice_session_choose_default_candidates(IceSession *session);
765

Ghislain MARY's avatar
Ghislain MARY committed
766 767 768 769 770 771 772
/**
 * Choose the default remote candidates of an ICE session.
 *
 * This function SHOULD not be used. Instead, the default remote candidates MUST be defined as default
 * when creating them with ice_add_remote_candidate().
 * However, this function is used by mediastream for testing purpose.
 */
773
MS2_PUBLIC void ice_session_choose_default_remote_candidates(IceSession *session);
Ghislain MARY's avatar
Ghislain MARY committed
774

775
/**
Ghislain MARY's avatar
Ghislain MARY committed
776
 * Pair the local and the remote candidates for an ICE session and start sending connectivity checks.
777 778 779
 *
 * @param session A pointer to a session
 */
Ghislain MARY's avatar
Ghislain MARY committed
780
MS2_PUBLIC void ice_session_start_connectivity_checks(IceSession *session);
781

Ghislain MARY's avatar
Ghislain MARY committed
782 783 784 785 786 787 788
/**
 * Check whether all the ICE check lists of the session includes a default candidate for each component ID in its remote candidates list.
 *
 * @param session A pointer to a session
 */
MS2_PUBLIC void ice_session_check_mismatch(IceSession *session);

789 790 791 792 793 794 795 796 797 798

/**
 * Disable/enable strong message integrity check. Used for backward compatibility only
 * default value is enabled
 * @param session A pointer to a session
 * @param enable value
 *
 */
MS2_PUBLIC void ice_session_enable_message_integrity_check(IceSession *session,bool_t enable);

799 800 801 802 803
/**
 * Core ICE check list processing.
 *
 * This function is called from the audiostream or the videostream and is NOT to be called by the user.
 */
804
void ice_check_list_process(IceCheckList* cl, RtpSession* rtp_session);
805

806 807 808 809 810
/**
 * Handle a STUN packet that has been received.
 *
 * This function is called from the audiostream or the videostream and is NOT to be called by the user.
 */
811
void ice_handle_stun_packet(IceCheckList* cl, RtpSession* rtp_session, const OrtpEventData* evt_data);
812

813 814 815 816
/**
 * Get the remote address, RTP port and RTCP port to use to send the stream once the ICE process has finished successfully.
 *
 * @param cl A pointer to a check list
817
 * @param rtp_addr A pointer to the buffer to use to store the remote RTP address
818
 * @param rtp_port A pointer to the location to store the RTP port to
819
 * @param rtcp_addr A pointer to the buffer to use to store the remote RTCP address
820
 * @param rtcp_port A pointer to the location to store the RTCP port to
821
 * @param addr_len The size of the buffer to use to store the remote addresses
822 823 824
 *
 * This function will usually be called from within the success callback defined while creating the ICE check list with ice_check_list_new().
 */
825
MS2_PUBLIC void ice_get_remote_addr_and_ports_from_valid_pairs(const IceCheckList *cl, char *rtp_addr, int *rtp_port, char *rtcp_addr, int *rtcp_port, int addr_len);
826

827 828 829 830 831 832 833 834
/**
 * Print the route used to send the stream if the ICE process has finished successfully.
 *
 * @param cl A pointer to a check list
 * @param message A message to print before the route
 */
MS2_PUBLIC void ice_check_list_print_route(const IceCheckList *cl, const char *message);

Ghislain MARY's avatar
Ghislain MARY committed
835 836 837
/**
 * Dump an ICE session in the traces (debug function).
 */
838
MS2_PUBLIC void ice_dump_session(const IceSession *session);
Ghislain MARY's avatar
Ghislain MARY committed
839

Ghislain MARY's avatar
Ghislain MARY committed
840 841 842
/**
 * Dump the candidates of an ICE check list in the traces (debug function).
 */
843
MS2_PUBLIC void ice_dump_candidates(const IceCheckList *cl);
844

Ghislain MARY's avatar
Ghislain MARY committed
845 846 847
/**
 * Dump the candidate pairs of an ICE check list in the traces (debug function).
 */
848
MS2_PUBLIC void ice_dump_candidate_pairs(const IceCheckList *cl);
849

850 851 852
/**
 * Dump the valid list of an ICE check list in the traces (debug function).
 */
853
MS2_PUBLIC void ice_dump_valid_list(const IceCheckList *cl);
854

Ghislain MARY's avatar
Ghislain MARY committed
855 856 857
/**
 * Dump the list of candidate pair foundations of an ICE check list in the traces (debug function).
 */
858
MS2_PUBLIC void ice_dump_candidate_pairs_foundations(const IceCheckList *cl);
859

860 861 862
/**
 * Dump the list of component IDs of an ICE check list in the traces (debug function).
 */
863
MS2_PUBLIC void ice_dump_componentIDs(const IceCheckList *cl);
864

Ghislain MARY's avatar
Ghislain MARY committed
865 866 867
/**
 * Dump an ICE check list in the traces (debug function).
 */
868
MS2_PUBLIC void ice_dump_check_list(const IceCheckList *cl);
Ghislain MARY's avatar
Ghislain MARY committed
869 870 871 872

/**
 * Dump the triggered checks queue of an ICE check list in the traces (debug function).
 */
873
MS2_PUBLIC void ice_dump_triggered_checks_queue(const IceCheckList *cl);
Ghislain MARY's avatar
Ghislain MARY committed
874

875

Ghislain MARY's avatar
Ghislain MARY committed
876 877 878 879 880
#ifdef __cplusplus
}
#endif

#endif