Group PJMEDIA_SESSION

group PJMEDIA_SESSION

Management of media sessions.

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.

Typedefs

typedef struct pjmedia_session pjmedia_session

Opaque declaration of media 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)

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_send_rtcp_sdes(const pjmedia_session *session)

Send RTCP SDES for the session.

Parameters

session – The 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

session – The 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

  • 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_reset_stream_stat(pjmedia_session *session, unsigned index)

Reset session statistics.

Parameters

  • session – The media session.

  • index – Stream 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

  • 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 (*cb)(pjmedia_stream*, void *user_data, int digit), 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.

struct pjmedia_session_info
#include <session.h>

Session info, retrieved from a session by calling pjmedia_session_get_info().

See

pjmedia_session_info.