BLOG | DOCUMENTATION | TRAC

Home --> Documentations --> PJMEDIA Reference

Media Sessions

Management of media sessions. More...

Modules

 RTCP Session and Encapsulation (RFC 3550)
 RTCP format and session management.
 
 RTCP Extended Report (XR) - RFC 3611
 RTCP XR extension to RTCP session.
 
 RTP Session and Encapsulation (RFC 3550)
 RTP format and session management.
 
 SDP Parsing and Data Structure
 SDP data structure representation and parsing.
 
 SDP Negotiation State Machine (Offer/Answer Model, RFC 3264)
 SDP Negotiation State Machine (Offer/Answer Model, RFC 3264)
 

Data Structures

struct  pjmedia_session_info
 

Typedefs

typedef struct pjmedia_session pjmedia_session
 

Functions

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)
 
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)
 
pj_status_t pjmedia_session_create (pjmedia_endpt *endpt, const pjmedia_session_info *si, pjmedia_transport *transports[], void *user_data, pjmedia_session **p_session)
 
pj_status_t pjmedia_session_get_info (pjmedia_session *session, pjmedia_session_info *info)
 
void * pjmedia_session_get_user_data (pjmedia_session *session)
 
pj_status_t pjmedia_session_resume (pjmedia_session *session, pjmedia_dir dir)
 
pj_status_t pjmedia_session_pause (pjmedia_session *session, pjmedia_dir dir)
 
pj_status_t pjmedia_session_pause_stream (pjmedia_session *session, unsigned index, pjmedia_dir dir)
 
pj_status_t pjmedia_session_resume_stream (pjmedia_session *session, unsigned index, pjmedia_dir dir)
 
pj_status_t pjmedia_session_send_rtcp_sdes (const pjmedia_session *session)
 
pj_status_t pjmedia_session_send_rtcp_bye (const pjmedia_session *session)
 
pj_status_t pjmedia_session_enum_streams (const pjmedia_session *session, unsigned *count, pjmedia_stream_info strm_info[])
 
pj_status_t pjmedia_session_get_port (pjmedia_session *session, unsigned index, pjmedia_port **p_port)
 
pj_status_t pjmedia_session_get_stream_stat (pjmedia_session *session, unsigned index, pjmedia_rtcp_stat *stat)
 
pj_status_t pjmedia_session_reset_stream_stat (pjmedia_session *session, unsigned index)
 
pj_status_t pjmedia_session_get_stream_stat_jbuf (pjmedia_session *session, unsigned index, pjmedia_jb_state *state)
 
pj_status_t pjmedia_session_dial_dtmf (pjmedia_session *session, unsigned index, const pj_str_t *ascii_digits)
 
pj_status_t pjmedia_session_check_dtmf (pjmedia_session *session, unsigned index)
 
pj_status_t pjmedia_session_get_dtmf (pjmedia_session *session, unsigned index, char *ascii_digits, unsigned *size)
 
pj_status_t pjmedia_session_set_dtmf_callback (pjmedia_session *session, unsigned index, void(*cb)(pjmedia_stream *, void *user_data, int digit), void *user_data)
 
pj_status_t pjmedia_session_destroy (pjmedia_session *session)
 

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

Opaque declaration of media session.

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
poolPool to allocate memory.
endptPjmedia endpoint.
max_streamsMaximum number of stream infos to be created.
siSession info structure to be initialized.
localLocal SDP session descriptor.
remoteRemote 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
siStream info structure to be initialized.
poolPool to allocate memory.
endptPJMEDIA endpoint instance.
localLocal SDP session descriptor.
remoteRemote SDP session descriptor.
stream_idxMedia 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
endptThe PJMEDIA endpoint instance.
siSession info containing stream count and array of stream info. The stream count indicates how many streams to be created in the session.
transportsArray of media stream transports, with sufficient number of elements (one for each stream).
user_dataArbitrary user data to be kept in the session.
p_sessionPointer 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
sessionThe session which info is being queried.
infoPointer 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
sessionThe 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
sessionThe media session.
dirThe 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
sessionThe media session.
dirThe 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
sessionThe media session.
indexThe stream index.
dirThe 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
sessionThe media session.
indexThe stream index.
dirThe media direction to activate.
Returns
PJ_SUCCESS on success.
pj_status_t pjmedia_session_send_rtcp_sdes ( const pjmedia_session session)

Send RTCP SDES for the session.

Parameters
sessionThe media session.
Returns
PJ_SUCCESS on success.
pj_status_t pjmedia_session_send_rtcp_bye ( const pjmedia_session session)

Send RTCP BYE for the session.

Parameters
sessionThe media session.
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
sessionThe media session.
countOn input, specifies the number of elements in the array. On output, the number will be filled with number of streams in the session.
strm_infoArray 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
sessionThe media session.
indexStream index.
p_portPointer 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
sessionThe media session.
indexStream index.
statStream statistic.
Returns
PJ_SUCCESS on success.
pj_status_t pjmedia_session_reset_stream_stat ( pjmedia_session session,
unsigned  index 
)

Reset session statistics.

Parameters
sessionThe media session.
indexStream index.
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
sessionThe media session.
indexStream index.
stateJitter 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
sessionThe media session.
indexThe stream index.
ascii_digitsString 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
sessionThe media session.
indexThe 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
sessionThe media session.
indexThe stream index.
ascii_digitsBuffer to receive the digits. The length of this buffer is indicated in the "size" argument.
sizeOn 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
sessionThe media session.
indexThe stream index.
cbCallback to be called upon receiving DTMF digits. The DTMF digits will be given to the callback as ASCII digits.
user_dataUser 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
sessionThe media session.
Returns
PJ_SUCCESS if success.

 


PJMEDIA small footprint Open Source media stack
Copyright (C) 2006-2008 Teluu Inc.