Group PJMEDIA_TRANSPORT

group PJMEDIA_TRANSPORT

Transports.

The media transport (pjmedia_transport) is the object to send and receive media packets over the network. The media transport interface allows the library to be extended to support different types of transports to send and receive packets.

The media transport is declared as pjmedia_transport “class”, which declares “interfaces” to use the class in pjmedia_transport_op structure. For the user of the media transport (normally the user of media transport is media stream, see Streams), these transport “methods” are wrapped with API such as pjmedia_transport_attach(), so it should not need to call the function pointer inside pjmedia_transport_op directly.

The connection between Streams and media transport is shown in the diagram below:

pjproject/pjmedia/docs/xml/media-transport.PNG

Typedefs

typedef typedefPJ_BEGIN_DECL struct pjmedia_transport pjmedia_transport

Forward declaration for media transport.

Enums

enum pjmedia_tranport_media_option

This enumeration specifies the general behaviour of media processing

Values:

PJMEDIA_TPMED_NO_TRANSPORT_CHECKING = 1

When this flag is specified, the transport will not perform media transport validation, this is useful when transport is stacked with other transport, for example when transport UDP is stacked under transport SRTP, media transport validation only need to be done by transport SRTP.

PJMEDIA_TPMED_RTCP_MUX = 2

When this flag is specified, the transport will allow multiplexing RTP and RTCP, i.e. if the remote agrees, RTCP will be sent using the same socket for RTP.

enum pjmedia_transport_type

Media transport type.

Values:

PJMEDIA_TRANSPORT_TYPE_UDP

Media transport using standard UDP

PJMEDIA_TRANSPORT_TYPE_ICE

Media transport using ICE

PJMEDIA_TRANSPORT_TYPE_SRTP

Media transport SRTP, this transport is actually security adapter to be stacked with other transport to enable encryption on the underlying transport.

PJMEDIA_TRANSPORT_TYPE_LOOP

Loopback media transport

PJMEDIA_TRANSPORT_TYPE_USER

Start of user defined transport.

Functions

void pjmedia_transport_info_init(pjmedia_transport_info *info)

Initialize transport info.

Parameters
  • info: Transport info to be initialized.

pj_status_t pjmedia_transport_get_info(pjmedia_transport *tp, pjmedia_transport_info *info)

Get media transport info from the specified transport and all underlying transports if any. The transport also contains information about socket info which describes the local address of the transport, and would be needed for example to fill in the “c=” and “m=” line of local SDP.

Return

PJ_SUCCESS on success.

Parameters
  • tp: The transport.

  • info: Media transport info to be initialized.

void *pjmedia_transport_info_get_spc_info(pjmedia_transport_info *info, pjmedia_transport_type type)

Utility API to get transport type specific info from the specified media transport info.

Return

Pointer to media transport specific info, or NULL if specific info for the transport type is not found.

Parameters
  • info: Media transport info.

  • type: Media transport type.

pj_status_t pjmedia_transport_attach2(pjmedia_transport *tp, pjmedia_transport_attach_param *att_param)

Attach callbacks to be called on receipt of incoming RTP/RTCP packets. This is just a simple wrapper which calls attach2() member of the transport if it is implemented, otherwise it calls attach() member of the transport.

Return

PJ_SUCCESS on success, or the appropriate error code.

Parameters
  • tp: The media transport.

  • att_param: The transport attach param.

pj_status_t pjmedia_transport_attach(pjmedia_transport *tp, void *user_data, const pj_sockaddr_t *rem_addr, const pj_sockaddr_t *rem_rtcp, unsigned addr_len, void (*rtp_cb)(void *user_data, void *pkt, pj_ssize_t), void (*rtcp_cb)(void *usr_data, void *pkt, pj_ssize_t))

Attach callbacks to be called on receipt of incoming RTP/RTCP packets. This is just a simple wrapper which calls attach() member of the transport.

Return

PJ_SUCCESS on success, or the appropriate error code.

Parameters
  • tp: The media transport.

  • user_data: Arbitrary user data to be set when the callbacks are called.

  • rem_addr: Remote RTP address to send RTP packet to.

  • rem_rtcp: Optional remote RTCP address. If the argument is NULL or if the address is zero, the RTCP address will be calculated from the RTP address (which is RTP port plus one).

  • addr_len: Length of the remote address.

  • rtp_cb: Callback to be called when RTP packet is received on the transport.

  • rtcp_cb: Callback to be called when RTCP packet is received on the transport.

void pjmedia_transport_detach(pjmedia_transport *tp, void *user_data)

Detach callbacks from the transport. This is just a simple wrapper which calls detach() member of the transport. After the transport is detached, it will ignore incoming RTP/RTCP packets, and will refuse to send outgoing RTP/RTCP packets. Application may re-attach the media transport to another transport user (e.g. stream) after the transport has been detached.

Parameters
  • tp: The media transport.

  • user_data: User data which must match the previously set value on attachment.

pj_status_t pjmedia_transport_send_rtp(pjmedia_transport *tp, const void *pkt, pj_size_t size)

Send RTP packet with the specified media transport. This is just a simple wrapper which calls send_rtp() member of the transport. The RTP packet will be delivered to the destination address specified in pjmedia_transport_attach() function.

Return

PJ_SUCCESS on success, or the appropriate error code.

Parameters
  • tp: The media transport.

  • pkt: The packet to send.

  • size: Size of the packet.

pj_status_t pjmedia_transport_send_rtcp(pjmedia_transport *tp, const void *pkt, pj_size_t size)

Send RTCP packet with the specified media transport. This is just a simple wrapper which calls send_rtcp() member of the transport. The RTCP packet will be delivered to the destination address specified in pjmedia_transport_attach() function.

Return

PJ_SUCCESS on success, or the appropriate error code.

Parameters
  • tp: The media transport.

  • pkt: The packet to send.

  • size: Size of the packet.

pj_status_t pjmedia_transport_send_rtcp2(pjmedia_transport *tp, const pj_sockaddr_t *addr, unsigned addr_len, const void *pkt, pj_size_t size)

Send RTCP packet with the specified media transport. This is just a simple wrapper which calls send_rtcp2() member of the transport. The RTCP packet will be delivered to the destination address specified in param addr, if addr is NULL, RTCP packet will be delivered to destination address specified in pjmedia_transport_attach() function.

Return

PJ_SUCCESS on success, or the appropriate error code.

Parameters
  • tp: The media transport.

  • addr: The destination address.

  • addr_len: Length of destination address.

  • pkt: The packet to send.

  • size: Size of the packet.

pj_status_t pjmedia_transport_media_create(pjmedia_transport *tp, pj_pool_t *sdp_pool, unsigned options, const pjmedia_sdp_session *rem_sdp, unsigned media_index)

Prepare the media transport for a new media session, Application must call this function before starting a new media session using this transport.

This is just a simple wrapper which calls media_create() member of the transport.

Return

PJ_SUCCESS on success, or the appropriate error code.

Parameters
  • tp: The media transport.

  • sdp_pool: Pool object to allocate memory related to SDP messaging components.

  • options: Option flags, from pjmedia_tranport_media_option

  • rem_sdp: Remote SDP if local SDP is an answer, otherwise specify NULL if SDP is an offer.

  • media_index: Media index in SDP.

pj_status_t pjmedia_transport_encode_sdp(pjmedia_transport *tp, pj_pool_t *sdp_pool, pjmedia_sdp_session *sdp, const pjmedia_sdp_session *rem_sdp, unsigned media_index)

Put transport specific information into the SDP. This function can be called to put transport specific information in the initial or subsequent SDP offer or answer.

This is just a simple wrapper which calls encode_sdp() member of the transport.

Return

PJ_SUCCESS on success, or the appropriate error code.

Parameters
  • tp: The media transport.

  • sdp_pool: Pool object to allocate memory related to SDP messaging components.

  • sdp: The local SDP to be filled in information from the media transport.

  • rem_sdp: Remote SDP if local SDP is an answer, otherwise specify NULL if SDP is an offer.

  • media_index: Media index in SDP.

pj_status_t pjmedia_transport_media_start(pjmedia_transport *tp, pj_pool_t *tmp_pool, const pjmedia_sdp_session *sdp_local, const pjmedia_sdp_session *sdp_remote, unsigned media_index)

Start the transport session with the settings in both local and remote SDP. The actual work that is done by this function depends on the underlying transport type. For SRTP, this will activate the encryption and decryption based on the keys found the SDPs. For ICE, this will start ICE negotiation according to the information found in the SDPs.

This is just a simple wrapper which calls media_start() member of the transport.

Return

PJ_SUCCESS on success, or the appropriate error code.

Parameters
  • tp: The media transport.

  • tmp_pool: The memory pool for allocating temporary objects.

  • sdp_local: Local SDP.

  • sdp_remote: Remote SDP.

  • media_index: Media index in the SDP.

pj_status_t pjmedia_transport_media_stop(pjmedia_transport *tp)

This API should be called when the session is stopped, to allow the media transport to release its resources used for the session.

This is just a simple wrapper which calls media_stop() member of the transport.

Return

PJ_SUCCESS on success, or the appropriate error code.

Parameters
  • tp: The media transport.

pj_status_t pjmedia_transport_close(pjmedia_transport *tp)

Close media transport. This is just a simple wrapper which calls destroy() member of the transport. This function will free all resources created by this transport (such as sockets, memory, etc.).

Return

PJ_SUCCESS on success, or the appropriate error code.

Parameters
  • tp: The media transport.

pj_status_t pjmedia_transport_simulate_lost(pjmedia_transport *tp, pjmedia_dir dir, unsigned pct_lost)

Simulate packet lost in the specified direction (for testing purposes). When enabled, the transport will randomly drop packets to the specified direction.

Return

PJ_SUCCESS on success.

Parameters
  • tp: The media transport.

  • dir: Media direction to which packets will be randomly dropped.

  • pct_lost: Percent lost (0-100). Set to zero to disable packet lost simulation.

struct pjmedia_sock_info
#include <transport.h>

Media socket info is used to describe the underlying sockets to be used as media transport.

struct pjmedia_transport_op
#include <transport.h>

This structure describes the operations for the stream transport.

See

pjmedia_transport_op.

struct pjmedia_transport
#include <transport.h>

This structure declares media transport. A media transport is called by the stream to transmit a packet, and will notify stream when incoming packet is arrived.

struct pjmedia_transport_specific_info
#include <transport.h>

This structure describes storage buffer of transport specific info. The actual transport specific info contents will be defined by transport implementation. Note that some transport implementations do not need to provide specific info, since the general socket info is enough.

struct pjmedia_transport_info
#include <transport.h>

This structure describes transport informations, including general socket information and specific information of single transport or stacked transports (e.g: SRTP stacked on top of UDP)

Forward declaration for media transport info.

struct pjmedia_tp_cb_param
#include <transport.h>

This structure describes the data passed when calling #rtp_cb2().

struct pjmedia_transport_attach_param
#include <transport.h>

This structure describes the data passed when calling pjmedia_transport_attach2().

Forward declaration for media transport attach param.