ICE Media Transport

Interactive Connectivity Establishment (ICE) transport. More...

Data Structures
struct	pjmedia_ice_cb
struct	pjmedia_ice_transport_info

Enumerations
enum	pjmedia_transport_ice_options {   PJMEDIA_ICE_NO_SRC_ADDR_CHECKING = 1 ,   PJMEDIA_ICE_DISABLE_ICE_MISMATCH = 2 }

Functions
pj_status_t	pjmedia_ice_create (pjmedia_endpt *endpt, const char *name, unsigned comp_cnt, const pj_ice_strans_cfg *cfg, const pjmedia_ice_cb *cb, pjmedia_transport **p_tp)
pj_status_t	pjmedia_ice_create2 (pjmedia_endpt *endpt, const char *name, unsigned comp_cnt, const pj_ice_strans_cfg *cfg, const pjmedia_ice_cb *cb, unsigned options, pjmedia_transport **p_tp)
pj_status_t	pjmedia_ice_create3 (pjmedia_endpt *endpt, const char *name, unsigned comp_cnt, const pj_ice_strans_cfg *cfg, const pjmedia_ice_cb *cb, unsigned options, void *user_data, pjmedia_transport **p_tp)
pj_grp_lock_t *	pjmedia_ice_get_grp_lock (pjmedia_transport *tp)
pj_status_t	pjmedia_ice_add_ice_cb (pjmedia_transport *tp, const pjmedia_ice_cb *cb, void *user_data)
pj_status_t	pjmedia_ice_remove_ice_cb (pjmedia_transport *tp, const pjmedia_ice_cb *cb, void *user_data)
pj_bool_t	pjmedia_ice_sdp_has_trickle (const pjmedia_sdp_session *sdp, unsigned med_idx)
pj_status_t	pjmedia_ice_trickle_update (pjmedia_transport *tp, const pj_str_t *rem_ufrag, const pj_str_t *rem_passwd, unsigned rcand_cnt, const pj_ice_sess_cand rcand[], pj_bool_t rcand_end)
pj_status_t	pjmedia_ice_trickle_decode_sdp (const pjmedia_sdp_session *sdp, unsigned media_index, pj_str_t *mid, pj_str_t *ufrag, pj_str_t *passwd, unsigned *cand_cnt, pj_ice_sess_cand cand[], pj_bool_t *end_of_cand)
pj_status_t	pjmedia_ice_trickle_encode_sdp (pj_pool_t *sdp_pool, pjmedia_sdp_session *sdp, const pj_str_t *mid, const pj_str_t *ufrag, const pj_str_t *passwd, unsigned cand_cnt, const pj_ice_sess_cand cand[], pj_bool_t end_of_cand)
pj_bool_t	pjmedia_ice_trickle_has_new_cand (pjmedia_transport *tp)
pj_status_t	pjmedia_ice_trickle_send_local_cand (pjmedia_transport *tp, pj_pool_t *sdp_pool, pjmedia_sdp_session *sdp, pj_bool_t *p_end_of_cand)

Detailed Description

This describes the implementation of media transport using Interactive Connectivity Establishment (ICE) protocol.

Enumeration Type Documentation

pjmedia_transport_ice_options

enum pjmedia_transport_ice_options

Options that can be specified when creating ICE transport.

Enumerator
PJMEDIA_ICE_NO_SRC_ADDR_CHECKING	Normally when remote doesn't use ICE, the ICE transport will continuously check the source address of incoming packets to see if it is different than the configured remote address, and switch the remote address to the source address of the packet if they are different after several packets are received. Specifying this option will disable this feature.
PJMEDIA_ICE_DISABLE_ICE_MISMATCH	The standard (rfc5245) specify that ice-mismatch attribute is used due to a mismatch of candidates with the default destination for media signaled in the SDP. The purpose is to identify some poorly ALGs that alter signaling information in ways that break ICE (e.g., by rewriting IP addresses in SDP). Specifying this option is to disable the ice mismatch check and allow ICE to continue if such scenario occur.

Function Documentation

pjmedia_ice_create()

pj_status_t pjmedia_ice_create	(	pjmedia_endpt *	endpt,
		const char *	name,
		unsigned	comp_cnt,
		const pj_ice_strans_cfg *	cfg,
		const pjmedia_ice_cb *	cb,
		pjmedia_transport **	p_tp
	)

Create the Interactive Connectivity Establishment (ICE) media transport using the specified configuration. When STUN or TURN (or both) is used, the creation operation will complete asynchronously, when STUN resolution and TURN allocation completes. When the initialization completes, the on_ice_complete() complete will be called with op parameter equal to PJ_ICE_STRANS_OP_INIT.

In addition, this transport will also notify the application about the result of ICE negotiation, also in on_ice_complete() callback. In this case the callback will be called with op parameter equal to PJ_ICE_STRANS_OP_NEGOTIATION.

Other than this, application should use the Media Transport API to manipulate this media transport.

Parameters

endpt	The media endpoint.
name	Optional name to identify this ICE media transport for logging purposes.
comp_cnt	Number of components to be created.
cfg	Pointer to configuration settings.
cb	Optional structure containing ICE specific callbacks.
p_tp	Pointer to receive the media transport instance.

Returns

PJ_SUCCESS on success, or the appropriate error code.

pjmedia_ice_create2()

pj_status_t pjmedia_ice_create2	(	pjmedia_endpt *	endpt,
		const char *	name,
		unsigned	comp_cnt,
		const pj_ice_strans_cfg *	cfg,
		const pjmedia_ice_cb *	cb,
		unsigned	options,
		pjmedia_transport **	p_tp
	)

The same as pjmedia_ice_create() with additional options param.

Parameters

endpt	The media endpoint.
name	Optional name to identify this ICE media transport for logging purposes.
comp_cnt	Number of components to be created.
cfg	Pointer to configuration settings.
cb	Optional structure containing ICE specific callbacks.
options	Options, see pjmedia_transport_ice_options.
p_tp	Pointer to receive the media transport instance.

Returns

PJ_SUCCESS on success, or the appropriate error code.

pjmedia_ice_create3()

pj_status_t pjmedia_ice_create3	(	pjmedia_endpt *	endpt,
		const char *	name,
		unsigned	comp_cnt,
		const pj_ice_strans_cfg *	cfg,
		const pjmedia_ice_cb *	cb,
		unsigned	options,
		void *	user_data,
		pjmedia_transport **	p_tp
	)

The same as pjmedia_ice_create2() with additional user_data param.

Parameters

endpt	The media endpoint.
name	Optional name to identify this ICE media transport for logging purposes.
comp_cnt	Number of components to be created.
cfg	Pointer to configuration settings.
cb	Optional structure containing ICE specific callbacks.
options	Options, see pjmedia_transport_ice_options.
user_data	User data to be attached to the transport.
p_tp	Pointer to receive the media transport instance.

Returns

PJ_SUCCESS on success, or the appropriate error code.

pjmedia_ice_get_grp_lock()

pj_grp_lock_t * pjmedia_ice_get_grp_lock

(

pjmedia_transport *

tp

)

Get the group lock for the ICE media transport.

Parameters

tp	The ICE media transport.

Returns

The group lock.

pjmedia_ice_add_ice_cb()

pj_status_t pjmedia_ice_add_ice_cb	(	pjmedia_transport *	tp,
		const pjmedia_ice_cb *	cb,
		void *	user_data
	)

Add application to receive ICE notifications from the specified ICE media transport.

Parameters

tp	The ICE media transport.
cb	The ICE specific callbacks.
user_data	Optional application user data.

Returns

PJ_SUCCESS on success, or the appropriate error code.

pjmedia_ice_remove_ice_cb()

pj_status_t pjmedia_ice_remove_ice_cb	(	pjmedia_transport *	tp,
		const pjmedia_ice_cb *	cb,
		void *	user_data
	)

Remove application to stop receiving ICE notifications from the specified ICE media transport.

Parameters

tp	The ICE media transport.
cb	The ICE specific callbacks.
user_data	Optional application user data. The same user data passed to pjmedia_ice_add_ice_cb(), this is for validation purpose.

Returns

PJ_SUCCESS on success, or the appropriate error code.

pjmedia_ice_sdp_has_trickle()

pj_bool_t pjmedia_ice_sdp_has_trickle	(	const pjmedia_sdp_session *	sdp,
		unsigned	med_idx
	)

Check if trickle support is signalled in the specified SDP. This function will check trickle indication in the media level first, if not found, it will check in the session level.

Parameters

sdp	The SDP.
med_idx	The media index to be checked.

Returns

PJ_TRUE if trickle ICE indication is found.

pjmedia_ice_trickle_update()

pj_status_t pjmedia_ice_trickle_update	(	pjmedia_transport *	tp,
		const pj_str_t *	rem_ufrag,
		const pj_str_t *	rem_passwd,
		unsigned	rcand_cnt,
		const pj_ice_sess_cand	rcand[],
		pj_bool_t	rcand_end
	)

Update check list after remote ICE candidates list are received or after or local ICE candidates are conveyed. This function may also be called after end-of-candidates indication is received or conveyed. ICE connectivity checks will automatically be started if both sides have conveyed ICE info (ICE user fragment and/or candidate list).

To update the check list after conveying any new local candidates, application can set the remote ICE parameters to NULL or zero. Note that the checklist should only be updated after any newly found local candidates are conveyed to remote, instead of immediately after the finding.

This function is only applicable when trickle ICE is not disabled.

Parameters

tp	The ICE media transport.
rem_ufrag	Remote ufrag, as seen in the SDP received from the remote agent.
rem_passwd	Remote password, as seen in the SDP received from the remote agent.
rcand_cnt	Number of new remote candidates in the array.
rcand	New remote candidates array.
rcand_end	Set to PJ_TRUE if remote has signalled end-of-candidate.

Returns

PJ_SUCCESS, or the appropriate error code.

pjmedia_ice_trickle_decode_sdp()

pj_status_t pjmedia_ice_trickle_decode_sdp	(	const pjmedia_sdp_session *	sdp,
		unsigned	media_index,
		pj_str_t *	mid,
		pj_str_t *	ufrag,
		pj_str_t *	passwd,
		unsigned *	cand_cnt,
		pj_ice_sess_cand	cand[],
		pj_bool_t *	end_of_cand
	)

Decode trickle ICE info from the specified SDP.

Parameters

sdp	The SDP containing trickle ICE info.
media_index	The media index.
mid	Output, media ID.
ufrag	Output, ufrag.
passwd	Output, password.
cand_cnt	On input, maximum number of candidate array. On output, the number of candidates.
cand	Output, the candidates.
end_of_cand	Output, end of candidate indication.

Returns

PJ_SUCCESS, or the appropriate error code.

pjmedia_ice_trickle_encode_sdp()

pj_status_t pjmedia_ice_trickle_encode_sdp	(	pj_pool_t *	sdp_pool,
		pjmedia_sdp_session *	sdp,
		const pj_str_t *	mid,
		const pj_str_t *	ufrag,
		const pj_str_t *	passwd,
		unsigned	cand_cnt,
		const pj_ice_sess_cand	cand[],
		pj_bool_t	end_of_cand
	)

Encode trickle ICE info into the specified SDP. This function may generate the following SDP attributes:

• Media ID, "a=mid".
• ICE ufrag & password, "a=ice-ufrag" & "a=ice-pwd".
• Trickle ICE support indication, "a=ice-options:trickle".
• ICE candidates, "a=candidate".
• End of candidate indication, "a=end-of-candidates".

Parameters

sdp_pool	The memory pool for generating SDP attributes.
sdp	The SDP to be updated.
mid	The media ID.
ufrag	The ufrag, optional.
passwd	The password, optional.
cand_cnt	The number of local candidates, can be zero.
cand	The local candidates.
end_of_cand	End of candidate indication.

Returns

PJ_SUCCESS, or the appropriate error code.

pjmedia_ice_trickle_has_new_cand()

pj_bool_t pjmedia_ice_trickle_has_new_cand

(

pjmedia_transport *

tp

)

Check if trickling ICE has found any new local candidates since the last conveyance (via pjmedia_ice_trickle_send_local_cand()).

Parameters

tp	The ICE media transport.

Returns

PJ_TRUE if new local canditates are available.

pjmedia_ice_trickle_send_local_cand()

pj_status_t pjmedia_ice_trickle_send_local_cand	(	pjmedia_transport *	tp,
		pj_pool_t *	sdp_pool,
		pjmedia_sdp_session *	sdp,
		pj_bool_t *	p_end_of_cand
	)

Convey all local candidates via the specified SDP.

Parameters

tp	The ICE media transport.
sdp_pool	The memory pool for generating SDP attributes.
sdp	The SDP.
p_end_of_cand	Optional, pointer to receive the indication that candidate gathering has been completed.

Returns

PJ_SUCCESS, or the appropriate error code.

References PJ_END_DECL.