ice.h 14.9 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

Ghislain MARY's avatar
Ghislain MARY committed
23
#include "mscommon.h"
24
#include "msticker.h"
Ghislain MARY's avatar
Ghislain MARY committed
25 26 27 28 29
#include "ortp/stun_udp.h"
#include "ortp/stun.h"
#include "ortp/ortp.h"


Ghislain MARY's avatar
Ghislain MARY committed
30 31 32 33 34 35 36 37 38 39 40 41 42
/**
 * @file ice.h
 * @brief mediastreamer2 ice.h include file
 *
 * This file provides the API to handle the ICE protocol defined in the RFC 5245.
 */


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

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

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

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

Ghislain MARY's avatar
Ghislain MARY committed
84 85 86
/**
 * Structure representing an ICE session.
 */
Ghislain MARY's avatar
Ghislain MARY committed
87
typedef struct _IceSession {
88 89
	MSList *streams;	/**< List of IceChecklist structures. Each element of the list represents a media stream */
	MSTicker *ticker;	/**< Ticker used to handle retransmissions of connectivity checks */
Ghislain MARY's avatar
Ghislain MARY committed
90 91 92 93 94 95
	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 */
	uint64_t tie_breaker;	/**< Random number used to resolve role conflicts (see paragraph 5.2 of the RFC 5245) */
96
	uint32_t ta;	/**< Duration of timer for sending connectivity checks in ms */
Ghislain MARY's avatar
Ghislain MARY committed
97
	uint8_t max_connectivity_checks;	/**< Configuration parameter to limit the number of connectivity checks performed by the agent (default is 100) */
Ghislain MARY's avatar
Ghislain MARY committed
98 99
} IceSession;

Ghislain MARY's avatar
Ghislain MARY committed
100 101 102
/**
 * Structure representing an ICE transport address.
 */
103
typedef struct _IceTransportAddress {
Ghislain MARY's avatar
Ghislain MARY committed
104 105
	char ip[64];
	int port;
106
	// TODO: Handling of IP version (4 or 6) and transport type: TCP, UDP...
Ghislain MARY's avatar
Ghislain MARY committed
107 108
} IceTransportAddress;

Ghislain MARY's avatar
Ghislain MARY committed
109 110 111
/**
 * Structure representing an ICE candidate.
 */
112
typedef struct _IceCandidate {
Ghislain MARY's avatar
Ghislain MARY committed
113 114 115 116
	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 */
117
	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
118 119
	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 */
120
	// TODO: relatedAddr
Ghislain MARY's avatar
Ghislain MARY committed
121 122
} IceCandidate;

Ghislain MARY's avatar
Ghislain MARY committed
123 124 125
/**
 * Structure representing an ICE candidate pair.
 */
126
typedef struct _IceCandidatePair {
Ghislain MARY's avatar
Ghislain MARY committed
127 128 129 130
	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 */
131
	UInt96 transactionID;	/**< Transaction ID of the connectivity check sent for the candidate pair */
132
	uint64_t transmission_time;	/**< Time when the connectivity check for the candidate pair has been sent */
133 134
	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 */
Ghislain MARY's avatar
Ghislain MARY committed
135
	IceRole role;	/**< Role of the agent when the connectivity check has been sent for the candidate pair */
Ghislain MARY's avatar
Ghislain MARY committed
136
	bool_t is_default;	/**< Boolean value telling whether this candidate pair is a default candidate pair or not */
Ghislain MARY's avatar
Ghislain MARY committed
137 138 139
	bool_t is_nominated;
} IceCandidatePair;

Ghislain MARY's avatar
Ghislain MARY committed
140 141 142 143 144
/**
 * 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.
 */
145
typedef struct _IcePairFoundation {
Ghislain MARY's avatar
Ghislain MARY committed
146 147
	char local[32];	/**< Foundation of the local candidate */
	char remote[32];	/**< Foundation of the remote candidate */
148 149
} IcePairFoundation;

150 151 152 153 154
typedef struct _IceValidCandidatePair {
	IceCandidatePair *valid;
	IceCandidatePair *generated_from;
} IceValidCandidatePair;

Ghislain MARY's avatar
Ghislain MARY committed
155 156 157 158 159 160
/**
 * 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.
 */
161
typedef struct _IceCheckList {
Ghislain MARY's avatar
Ghislain MARY committed
162
	IceSession *session;
Ghislain MARY's avatar
Ghislain MARY committed
163 164
	char *remote_ufrag;
	char *remote_pwd;
165 166 167
	MSList *local_candidates;	/**< List of IceCandidate structures */
	MSList *remote_candidates;	/**< List of IceCandidate structures */
	MSList *pairs;	/**< List of IceCandidatePair structures */
168
	MSList *triggered_checks_queue;	/**< List of IceCandidatePair structures */
169
	MSList *valid_list;	/**< List of IceValidCandidatePair structures */
170
	MSList *foundations;	/**< List of IcePairFoundation structures */
171
	MSList *componentIDs;	/**< List of uint16_t */
172
	IceCheckListState state;
173
	uint64_t ta_time;	/**< Time when the Ta timer has been processed for the last time */
174
	uint32_t foundation_generator;
Ghislain MARY's avatar
Ghislain MARY committed
175 176 177 178 179 180 181
} IceCheckList;


#ifdef __cplusplus
extern "C"{
#endif

Ghislain MARY's avatar
Ghislain MARY committed
182 183 184 185 186 187 188 189
/**
 * 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
190

Ghislain MARY's avatar
Ghislain MARY committed
191 192 193 194 195 196 197 198
/**
 * 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
199

Ghislain MARY's avatar
Ghislain MARY committed
200 201 202 203 204 205 206 207
/**
 * 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.
 */
MS2_PUBLIC IceCheckList * ice_check_list_new(void);
208

Ghislain MARY's avatar
Ghislain MARY committed
209 210 211 212 213 214
/**
 * Destroy a previously allocated ICE check list.
 *
 * @param cl The check list to destroy
 */
MS2_PUBLIC void ice_check_list_destroy(IceCheckList *cl);
215

Ghislain MARY's avatar
Ghislain MARY committed
216 217 218 219 220 221 222
/**
 * 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
 */
MS2_PUBLIC const char * ice_session_local_ufrag(IceSession *session);
Ghislain MARY's avatar
Ghislain MARY committed
223

Ghislain MARY's avatar
Ghislain MARY committed
224 225 226 227 228 229 230
/**
 * 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
 */
MS2_PUBLIC const char * ice_session_local_pwd(IceSession *session);
Ghislain MARY's avatar
Ghislain MARY committed
231

Ghislain MARY's avatar
Ghislain MARY committed
232 233 234 235 236 237 238
/**
 * 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
 */
MS2_PUBLIC const char * ice_session_remote_ufrag(IceSession *session);
Ghislain MARY's avatar
Ghislain MARY committed
239

Ghislain MARY's avatar
Ghislain MARY committed
240 241 242 243 244 245 246
/**
 * 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
 */
MS2_PUBLIC const char * ice_session_remote_pwd(IceSession *session);
Ghislain MARY's avatar
Ghislain MARY committed
247

Ghislain MARY's avatar
Ghislain MARY committed
248 249 250 251 252 253 254
/**
 * 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
255

Ghislain MARY's avatar
Ghislain MARY committed
256
/**
Ghislain MARY's avatar
Ghislain MARY committed
257 258
 * Set the local credentials of an ICE session.
 *
Ghislain MARY's avatar
Ghislain MARY committed
259 260 261
 * 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.
 */
Ghislain MARY's avatar
Ghislain MARY committed
262
MS2_PUBLIC void ice_session_set_local_credentials(IceSession *session, const char *ufrag, const char *pwd);
Ghislain MARY's avatar
Ghislain MARY committed
263

Ghislain MARY's avatar
Ghislain MARY committed
264 265 266 267 268 269 270 271 272 273
/**
 * 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
274

Ghislain MARY's avatar
Ghislain MARY committed
275 276 277 278 279 280 281 282 283 284
/**
 * 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);
285

Ghislain MARY's avatar
Ghislain MARY committed
286 287 288 289 290 291 292
/**
 * 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
 */
MS2_PUBLIC void ice_session_add_check_list(IceSession *session, IceCheckList *cl);
Ghislain MARY's avatar
Ghislain MARY committed
293

Ghislain MARY's avatar
Ghislain MARY committed
294 295 296 297 298 299 300
/**
 * Get the state of an ICE check list.
 *
 * @param cl A pointer to a check list
 * @return The check list state
 */
MS2_PUBLIC IceCheckListState ice_check_list_state(IceCheckList *cl);
301

Ghislain MARY's avatar
Ghislain MARY committed
302 303 304 305 306 307 308
/**
 * 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
 */
MS2_PUBLIC const char * ice_check_list_local_ufrag(IceCheckList *cl);
Ghislain MARY's avatar
Ghislain MARY committed
309

Ghislain MARY's avatar
Ghislain MARY committed
310 311 312 313 314 315 316
/**
 * 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
 */
MS2_PUBLIC const char * ice_check_list_local_pwd(IceCheckList *cl);
Ghislain MARY's avatar
Ghislain MARY committed
317

Ghislain MARY's avatar
Ghislain MARY committed
318 319 320 321 322 323 324
/**
 * 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
 */
MS2_PUBLIC const char * ice_check_list_remote_ufrag(IceCheckList *cl);
Ghislain MARY's avatar
Ghislain MARY committed
325

Ghislain MARY's avatar
Ghislain MARY committed
326 327 328 329 330 331 332
/**
 * 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
 */
MS2_PUBLIC const char * ice_check_list_remote_pwd(IceCheckList *cl);
Ghislain MARY's avatar
Ghislain MARY committed
333

334
/**
Ghislain MARY's avatar
Ghislain MARY committed
335 336
 * Add a local candidate to an ICE check list.
 *
337
 * This function is not to be used directly. The ice_session_gather_candidates() function SHOULD be used instead.
338 339
 * However, it is used by mediastream for testing purpose since it does not use gathering.
 */
340
IceCandidate * ice_add_local_candidate(IceCheckList *cl, const char *type, const char *ip, int port, uint16_t componentID, IceCandidate *base);
341

Ghislain MARY's avatar
Ghislain MARY committed
342 343 344 345 346 347 348 349 350 351 352 353 354 355
/**
 * 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
 *
 * This function is to be called once the remote candidate list has been received via SDP.
 */
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);
356

357 358 359 360 361 362
/**
 * Gather the local candidates for an ICE session.
 *
 * TODO: Define more precisely, probably provide a callback function to call when the gathering is finished.
 */
MS2_PUBLIC void ice_session_gather_candidates(IceSession *session);
Ghislain MARY's avatar
Ghislain MARY committed
363

364 365 366 367 368 369 370 371
/**
 * 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.
 */
void ice_session_set_base_for_srflx_candidates(IceSession *session);
372

373 374 375 376 377 378 379 380
/**
 * Compute the foundations of the local 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.
 */
void ice_session_compute_candidates_foundations(IceSession *session);
381

382 383 384 385 386 387 388 389 390 391 392 393
/**
 * Choose the default candidates of an ICE session.
 *
 * @param session A pointer to a session
 *
 * This function is to be called once the remote candidate list has been received from the peer via SDP
 * and each candidate as been added to the check lists using ice_add_remote_candidate(), but before calling
 * ice_session_pair_candidates().
 *
 * TODO: Maybe incorporate this one directly in ice_session_pair_candidates().
 */
MS2_PUBLIC void ice_session_choose_default_candidates(IceSession *session);
Ghislain MARY's avatar
Ghislain MARY committed
394

395 396 397 398 399 400
/**
 * Pair the local and the remote candidates for an ICE session.
 *
 * @param session A pointer to a session
 */
MS2_PUBLIC void ice_session_pair_candidates(IceSession *session);
Ghislain MARY's avatar
Ghislain MARY committed
401

Ghislain MARY's avatar
Ghislain MARY committed
402
void ice_check_list_process(IceCheckList *cl, RtpSession *rtp_session);
403

Ghislain MARY's avatar
Ghislain MARY committed
404
void ice_handle_stun_packet(IceCheckList *cl, RtpSession *session, OrtpEventData *evt_data);
405

Ghislain MARY's avatar
Ghislain MARY committed
406 407 408 409
/**
 * Dump an ICE session in the traces (debug function).
 */
MS2_PUBLIC void ice_dump_session(IceSession *session);
Ghislain MARY's avatar
Ghislain MARY committed
410

Ghislain MARY's avatar
Ghislain MARY committed
411 412 413 414
/**
 * Dump the candidates of an ICE check list in the traces (debug function).
 */
MS2_PUBLIC void ice_dump_candidates(IceCheckList *cl);
415

Ghislain MARY's avatar
Ghislain MARY committed
416 417 418 419
/**
 * Dump the candidate pairs of an ICE check list in the traces (debug function).
 */
MS2_PUBLIC void ice_dump_candidate_pairs(IceCheckList *cl);
Ghislain MARY's avatar
Ghislain MARY committed
420

421 422 423 424 425
/**
 * Dump the valid list of an ICE check list in the traces (debug function).
 */
MS2_PUBLIC void ice_dump_valid_list(IceCheckList *cl);

Ghislain MARY's avatar
Ghislain MARY committed
426 427 428 429
/**
 * Dump the list of candidate pair foundations of an ICE check list in the traces (debug function).
 */
MS2_PUBLIC void ice_dump_candidate_pairs_foundations(IceCheckList *cl);
430

431 432 433 434 435
/**
 * Dump the list of component IDs of an ICE check list in the traces (debug function).
 */
MS2_PUBLIC void ice_dump_componentIDs(IceCheckList *cl);

Ghislain MARY's avatar
Ghislain MARY committed
436 437 438 439 440
#ifdef __cplusplus
}
#endif

#endif