Streams
[Media Ports Framework]

---

Detailed Description

A media stream is a bidirectional multimedia communication between two endpoints. It corresponds to a media description (m= line) in SDP session descriptor.

A media stream consists of two unidirectional channels:

• encoding channel, which transmits unidirectional media to remote, and
• decoding channel, which receives unidirectional media from remote.

A media stream exports media port interface (see Media Ports Framework) and application normally uses this interface to interconnect the stream to other PJMEDIA components.

A media stream internally manages the following objects:

• an instance of media codec (see Codec Framework),
• an Adaptive jitter buffer,
• two instances of RTP sessions (pjmedia_rtp_session, one for each direction),
• one instance of RTCP session (pjmedia_rtcp_session),
• and a reference to media transport to send and receive packets to/from the network (see Media Transport).

Streams are created by calling pjmedia_stream_create(), specifying pjmedia_stream_info structure in the parameter. Application can construct the pjmedia_stream_info structure manually, or use pjmedia_stream_info_from_sdp() or pjmedia_session_info_from_sdp() functions to construct the pjmedia_stream_info from local and remote SDP session descriptors.

Application can also use Media Sessions to indirectly create the streams.

Data Structures
struct	pjmedia_stream_info
Typedefs
typedef struct pjmedia_channel	pjmedia_channel
typedef struct pjmedia_stream_info	pjmedia_stream_info
Functions
pj_status_t	pjmedia_stream_create (pjmedia_endpt *endpt, pj_pool_t *pool, const pjmedia_stream_info *info, pjmedia_transport *tp, void *user_data, pjmedia_stream **p_stream)
pj_status_t	pjmedia_stream_destroy (pjmedia_stream *stream)
pj_status_t	pjmedia_stream_get_port (pjmedia_stream *stream, pjmedia_port **p_port)
pjmedia_transport *	pjmedia_stream_get_transport (pjmedia_stream *st)
pj_status_t	pjmedia_stream_start (pjmedia_stream *stream)
pj_status_t	pjmedia_stream_get_stat (const pjmedia_stream *stream, pjmedia_rtcp_stat *stat)
pj_status_t	pjmedia_stream_pause (pjmedia_stream *stream, pjmedia_dir dir)
pj_status_t	pjmedia_stream_resume (pjmedia_stream *stream, pjmedia_dir dir)
pj_status_t	pjmedia_stream_dial_dtmf (pjmedia_stream *stream, const pj_str_t *ascii_digit)
pj_bool_t	pjmedia_stream_check_dtmf (pjmedia_stream *stream)
pj_status_t	pjmedia_stream_get_dtmf (pjmedia_stream *stream, char *ascii_digits, unsigned *size)
pj_status_t	pjmedia_stream_set_dtmf_callback (pjmedia_stream *stream, void(*cb)(pjmedia_stream *, void *user_data, int digit), void *user_data)

---

Typedef Documentation

typedef struct pjmedia_channel pjmedia_channel

Opaque declaration for media channel. Media channel is unidirectional flow of media from sender to receiver.

typedef struct pjmedia_stream_info pjmedia_stream_info

See also:

pjmedia_stream_info.

---

Function Documentation

pj_status_t pjmedia_stream_create	(	pjmedia_endpt *	endpt,
		pj_pool_t *	pool,
		const pjmedia_stream_info *	info,
		pjmedia_transport *	tp,
		void *	user_data,
		pjmedia_stream **	p_stream
	)

Create a media stream based on the specified parameter. After the stream has been created, application normally would want to get the media port interface of the streams, by calling pjmedia_stream_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 stream.

Parameters:

	endpt	Media endpoint.
	pool	Pool to allocate memory for the stream. A large number of memory may be needed because jitter buffer needs to preallocate some storage.
	info	Stream information.
	tp	Stream transport instance used to transmit and receive RTP/RTCP packets to/from the underlying transport.
	user_data	Arbitrary user data (for future callback feature).
	p_stream	Pointer to receive the media stream.

Returns:

PJ_SUCCESS on success.

pj_status_t pjmedia_stream_destroy

(

pjmedia_stream *

stream

)

Destroy the media stream.

Parameters:

stream

The media stream.

Returns:

PJ_SUCCESS on success.

pj_status_t pjmedia_stream_get_port	(	pjmedia_stream *	stream,
		pjmedia_port **	p_port
	)

Get the media port interface of the 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:

	stream	The media stream.
	p_port	Pointer to receive the port interface.

Returns:

PJ_SUCCESS on success.

pjmedia_transport* pjmedia_stream_get_transport

(

pjmedia_stream *

st

)

Get the media transport object associated with this stream.

Parameters:

st

The media stream.

Returns:

The transport object being used by the stream.

pj_status_t pjmedia_stream_start

(

pjmedia_stream *

stream

)

Start the media stream. This will start the appropriate channels in the media stream, depending on the media direction that was set when the stream was created.

Parameters:

stream

The media stream.

Returns:

PJ_SUCCESS on success.

pj_status_t pjmedia_stream_get_stat	(	const pjmedia_stream *	stream,
		pjmedia_rtcp_stat *	stat
	)

Get the stream statistics.

Parameters:

	stream	The media stream.
	stat	Media stream statistics.

Returns:

PJ_SUCCESS on success.

pj_status_t pjmedia_stream_pause	(	pjmedia_stream *	stream,
		pjmedia_dir	dir
	)

Pause the individual channel in the stream.

Parameters:

	stream	The media channel.
	dir	Which direction to pause.

Returns:

PJ_SUCCESS on success.

pj_status_t pjmedia_stream_resume	(	pjmedia_stream *	stream,
		pjmedia_dir	dir
	)

Resume the individual channel in the stream.

Parameters:

	stream	The media channel.
	dir	Which direction to resume.

Returns:

PJ_SUCCESS on success;

pj_status_t pjmedia_stream_dial_dtmf	(	pjmedia_stream *	stream,
		const pj_str_t *	ascii_digit
	)

Transmit DTMF to this stream. The DTMF will be transmitted uisng RTP telephone-events as described in RFC 2833. This operation is only valid for audio stream.

Parameters:

	stream	The media stream.
	ascii_digit	String containing digits to be sent to remote. Currently the maximum number of digits are 32.

Returns:

PJ_SUCCESS on success.

pj_bool_t pjmedia_stream_check_dtmf

(

pjmedia_stream *

stream

)

Check if the stream has incoming DTMF digits in the incoming DTMF queue. Incoming DTMF digits received via RFC 2833 mechanism are saved in the incoming digits queue.

Parameters:

stream

The media stream.

Returns:

Non-zero (PJ_TRUE) if the stream has received DTMF digits in the .

pj_status_t pjmedia_stream_get_dtmf	(	pjmedia_stream *	stream,
		char *	ascii_digits,
		unsigned *	size
	)

Retrieve the incoming DTMF digits from the stream, and remove the digits from stream's DTMF buffer. Note that the digits buffer will not be NULL terminated.

Parameters:

	stream	The media stream.
	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:

Non-zero (PJ_TRUE) if the stream has received DTMF digits in the .

pj_status_t pjmedia_stream_set_dtmf_callback	(	pjmedia_stream *	stream,
		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:

	stream	The media stream.
	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.