Group PJMEDIA_MASTER_PORT

group PJMEDIA_MASTER_PORT

Thread based media clock provider.

A master port has two media ports connected to it, and by convention thay are called downstream and upstream ports. The media stream flowing to the downstream port is called encoding or send direction, and media stream flowing to the upstream port is called decoding or receive direction (imagine the downstream as stream to remote endpoint, and upstream as local media port; media flowing to remote endpoint (downstream) will need to be encoded before it is transmitted to remote endpoint).

A master port internally has an instance of Clock Generator, which provides the essensial timing for the master port. The Clock Generator runs asynchronously, and whenever a clock tick expires, a callback will be called, and the master port performs the following tasks:

• it calls from the downstream port, when give the frame to the upstream port by calling to the upstream port, and

• performs the same task, but on the reverse direction (i.e. get the stream from upstream port and give it to the downstream port).

Because master port enables media stream to flow automatically, it is said that the master port supplies Clock/Timing to the media ports interconnection.

Typedefs

typedefPJ_BEGIN_DECL struct pjmedia_master_port pjmedia_master_port

Opaque declaration for master port.

Functions

pj_status_t pjmedia_master_port_create(pj_pool_t *pool, pjmedia_port *u_port, pjmedia_port *d_port, unsigned options, pjmedia_master_port **p_m)

Create a master port.

Parameters

• pool – Pool to allocate master port from.

• u_port – Upstream port.

• d_port – Downstream port.

• options – Options flags, from bitmask combinations from pjmedia_clock_options.

• p_m – Pointer to receive the master port instance.

Returns

PJ_SUCCESS on success.

pj_status_t pjmedia_master_port_start(pjmedia_master_port *m)

Start the media flow.

Parameters

m – The master port.

Returns

PJ_SUCCESS on success.

pj_status_t pjmedia_master_port_stop(pjmedia_master_port *m)

Stop the media flow.

Parameters

m – The master port.

Returns

PJ_SUCCESS on success.

pj_bool_t pjmedia_master_port_wait(pjmedia_master_port *m, pj_bool_t wait, pj_timestamp *ts)

Poll the master port clock and execute the callback when the clock tick has elapsed. This operation is only valid if the master port is created with PJMEDIA_CLOCK_NO_ASYNC flag.

Parameters

• m – The master port.

• wait – If non-zero, then the function will block until a clock tick elapsed and callback has been called.

• ts – Optional argument to receive the current timestamp.

Returns

Non-zero if clock tick has elapsed, or FALSE if the function returns before a clock tick has elapsed.

pj_status_t pjmedia_master_port_set_uport(pjmedia_master_port *m, pjmedia_port *port)

Change the upstream port. Note that application is responsible to destroy current upstream port (the one that is going to be replaced with the new port).

Parameters

• m – The master port.

• port – Port to be used for upstream port.

Returns

PJ_SUCCESS on success.

pjmedia_port *pjmedia_master_port_get_uport(pjmedia_master_port *m)

Get the upstream port.

Parameters

m – The master port.

Returns

The upstream port.

pj_status_t pjmedia_master_port_set_dport(pjmedia_master_port *m, pjmedia_port *port)

Change the downstream port. Note that application is responsible to destroy current downstream port (the one that is going to be replaced with the new port).

Parameters

• m – The master port.

• port – Port to be used for downstream port.

Returns

PJ_SUCCESS on success.

pjmedia_port *pjmedia_master_port_get_dport(pjmedia_master_port *m)

Get the downstream port.

Parameters

m – The master port.

Returns

The downstream port.

pj_status_t pjmedia_master_port_destroy(pjmedia_master_port *m, pj_bool_t destroy_ports)

Destroy the master port, and optionally destroy the upstream and downstream ports.

Parameters

• m – The master port.

• destroy_ports – If non-zero, the function will destroy both upstream and downstream ports too.

Returns

PJ_SUCCESS on success.