Media Sessions

Detailed Description

A media session represents multimedia communication between two parties. A media session represents the multimedia session that is described by SDP session descriptor. A media session consists of one or more media streams (pjmedia_stream), where each stream represents one media line (m= line) in SDP.

This module provides functions to create and manage multimedia sessions.

Application creates the media session by calling pjmedia_session_create(), normally after it has completed negotiating both SDP offer and answer. The session creation function creates the media session (including media streams) based on the content of local and remote SDP.

Typedef Documentation

typedef struct pjmedia_session pjmedia_session

Opaque declaration of media session.

typedef struct pjmedia_session_info pjmedia_session_info

See also:: pjmedia_session_info.

Function Documentation

pj_status_t pjmedia_session_info_from_sdp	(	pj_pool_t *	pool,
		pjmedia_endpt *	endpt,
		unsigned	max_streams,
		pjmedia_session_info *	si,
		const pjmedia_sdp_session *	local,
		const pjmedia_sdp_session *	remote
	)

This function will initialize the session info based on information in both SDP session descriptors. The remaining information will be taken from default codec parameters. If socket info array is specified, the socket will be copied to the session info as well.

Parameters:

	pool	Pool to allocate memory.
	endpt	Pjmedia endpoint.
	max_streams	Maximum number of stream infos to be created.
	si	Session info structure to be initialized.
	local	Local SDP session descriptor.
	remote	Remote SDP session descriptor.

Returns:: PJ_SUCCESS if stream info is successfully initialized.

pj_status_t pjmedia_stream_info_from_sdp	(	pjmedia_stream_info *	si,
		pj_pool_t *	pool,
		pjmedia_endpt *	endpt,
		const pjmedia_sdp_session *	local,
		const pjmedia_sdp_session *	remote,
		unsigned	stream_idx
	)

This function will initialize the stream info based on information in both SDP session descriptors for the specified stream index. The remaining information will be taken from default codec parameters. If socket info array is specified, the socket will be copied to the session info as well.

Parameters:

	si	Stream info structure to be initialized.
	pool	Pool to allocate memory.
	endpt	PJMEDIA endpoint instance.
	local	Local SDP session descriptor.
	remote	Remote SDP session descriptor.
	stream_idx	Media stream index in the session descriptor.

Returns:: PJ_SUCCESS if stream info is successfully initialized.

pj_status_t pjmedia_session_create	(	pjmedia_endpt *	endpt,
		const pjmedia_session_info *	si,
		pjmedia_transport *	transports[],
		void *	user_data,
		pjmedia_session **	p_session
	)

Create media session based on the local and remote SDP. After the session has been created, application normally would want to get the media port interface of each streams, by calling pjmedia_session_get_port(). The media port interface exports put_frame() and get_frame() function, used to transmit and receive media frames from the stream.

Without application calling put_frame() and get_frame(), there will be no media frames transmitted or received by the session.

Parameters:

	endpt	The PJMEDIA endpoint instance.
	si	Session info containing stream count and array of stream info. The stream count indicates how many streams to be created in the session.
	transports	Array of media stream transports, with sufficient number of elements (one for each stream).
	user_data	Arbitrary user data to be kept in the session.
	p_session	Pointer to receive the media session.

Returns:: PJ_SUCCESS if media session can be created successfully.

pj_status_t pjmedia_session_get_info	(	pjmedia_session *	session,
		pjmedia_session_info *	info
	)

Get media session info of the session.

Parameters:

	session	The session which info is being queried.
	info	Pointer to receive session info.

Returns:: PJ_SUCCESS on success.

void* pjmedia_session_get_user_data ( pjmedia_session * session )

Get user data of the session.

Parameters:

session

The session being queried.

Returns:: User data of the session.

pj_status_t pjmedia_session_resume	(	pjmedia_session *	session,
		pjmedia_dir	dir
	)

Activate all streams in media session for the specified direction. Application only needs to call this function if it previously paused the session.

Parameters:

	session	The media session.
	dir	The direction to activate.

Returns:: PJ_SUCCESS if success.

pj_status_t pjmedia_session_pause	(	pjmedia_session *	session,
		pjmedia_dir	dir
	)

Suspend receipt and transmission of all streams in media session for the specified direction.

Parameters:

	session	The media session.
	dir	The media direction to suspend.

Returns:: PJ_SUCCESS if success.

pj_status_t pjmedia_session_pause_stream	(	pjmedia_session *	session,
		unsigned	index,
		pjmedia_dir	dir
	)

Suspend receipt and transmission of individual stream in media session for the specified direction.

Parameters:

	session	The media session.
	index	The stream index.
	dir	The media direction to pause.

Returns:: PJ_SUCCESS on success.

pj_status_t pjmedia_session_resume_stream	(	pjmedia_session *	session,
		unsigned	index,
		pjmedia_dir	dir
	)

Activate individual stream in media session for the specified direction.

Parameters:

	session	The media session.
	index	The stream index.
	dir	The media direction to activate.

Returns:: PJ_SUCCESS on success.

pj_status_t pjmedia_session_enum_streams	(	const pjmedia_session *	session,
		unsigned *	count,
		pjmedia_stream_info	strm_info[]
	)

Enumerate media streams in the session.

Parameters:

	session	The media session.
	count	On input, specifies the number of elements in the array. On output, the number will be filled with number of streams in the session.
	strm_info	Array of stream info.

Returns:: PJ_SUCCESS on success.

pj_status_t pjmedia_session_get_port	(	pjmedia_session *	session,
		unsigned	index,
		pjmedia_port **	p_port
	)

Get the media port interface of the specified stream. The media port interface declares put_frame() and get_frame() function, which is the only way for application to transmit and receive media frames from the stream.

Parameters:

	session	The media session.
	index	Stream index.
	p_port	Pointer to receive the media port interface for the specified stream.

Returns:: PJ_SUCCESS on success.

pj_status_t pjmedia_session_get_stream_stat	(	pjmedia_session *	session,
		unsigned	index,
		pjmedia_rtcp_stat *	stat
	)

Get session statistics. The stream statistic shows various indicators such as packet count, packet lost, jitter, delay, etc. See also pjmedia_session_get_stream_stat_jbuf()

Parameters:

	session	The media session.
	index	Stream index.
	stat	Stream statistic.

Returns:: PJ_SUCCESS on success.

pj_status_t pjmedia_session_get_stream_stat_jbuf	(	pjmedia_session *	session,
		unsigned	index,
		pjmedia_jb_state *	state
	)

Get current jitter buffer state for the specified stream. See also pjmedia_session_get_stream_stat()

Parameters:

	session	The media session.
	index	Stream index.
	state	Jitter buffer state.

Returns:: PJ_SUCCESS on success.

pj_status_t pjmedia_session_dial_dtmf	(	pjmedia_session *	session,
		unsigned	index,
		const pj_str_t *	ascii_digits
	)

Dial DTMF digit to the stream, using RFC 2833 mechanism.

Parameters:

	session	The media session.
	index	The stream index.
	ascii_digits	String of ASCII digits (i.e. 0-9*#A-B).

Returns:: PJ_SUCCESS on success.

pj_status_t pjmedia_session_check_dtmf	(	pjmedia_session *	session,
		unsigned	index
	)

Check if the specified stream has received DTMF digits.

Parameters:

	session	The media session.
	index	The stream index.

Returns:: Non-zero (PJ_TRUE) if the stream has DTMF digits.

pj_status_t pjmedia_session_get_dtmf	(	pjmedia_session *	session,
		unsigned	index,
		char *	ascii_digits,
		unsigned *	size
	)

Retrieve DTMF digits from the specified stream.

Parameters:

	session	The media session.
	index	The stream index.
	ascii_digits	Buffer to receive the digits. The length of this buffer is indicated in the "size" argument.
	size	On input, contains the maximum digits to be copied to the buffer. On output, it contains the actual digits that has been copied to the buffer.

Returns:: PJ_SUCCESS on success.

pj_status_t pjmedia_session_set_dtmf_callback	(	pjmedia_session *	session,
		unsigned	index,
		void()(pjmedia_stream , void *user_data, int digit)	cb,
		void *	user_data
	)

Set callback to be called upon receiving DTMF digits. If callback is registered, the stream will not buffer incoming DTMF but rather call the callback as soon as DTMF digit is received completely.

Parameters:

	session	The media session.
	index	The stream index.
	cb	Callback to be called upon receiving DTMF digits. The DTMF digits will be given to the callback as ASCII digits.
	user_data	User data to be returned back when the callback is called.

Returns:: PJ_SUCCESS on success.

pj_status_t pjmedia_session_destroy ( pjmedia_session * session )

Destroy media session.

Parameters:

session

The media session.

Returns:: PJ_SUCCESS if success.

Media Sessions

Detailed Description

Modules

Data Structures

Typedefs

Functions

Typedef Documentation

Function Documentation