Master Port
[Clock/Timing]

Thread based media clock provider. More...

Typedefs
typedef typedefPJ_BEGIN_DECL struct pjmedia_master_port	pjmedia_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)
pj_status_t	pjmedia_master_port_start (pjmedia_master_port *m)
pj_status_t	pjmedia_master_port_stop (pjmedia_master_port *m)
pj_bool_t	pjmedia_master_port_wait (pjmedia_master_port *m, pj_bool_t wait, pj_timestamp *ts)
pj_status_t	pjmedia_master_port_set_uport (pjmedia_master_port *m, pjmedia_port *port)
pjmedia_port *	pjmedia_master_port_get_uport (pjmedia_master_port *m)
pj_status_t	pjmedia_master_port_set_dport (pjmedia_master_port *m, pjmedia_port *port)
pjmedia_port *	pjmedia_master_port_get_dport (pjmedia_master_port *m)
pj_status_t	pjmedia_master_port_destroy (pjmedia_master_port *m, pj_bool_t destroy_ports)

---

Detailed Description

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 get_frame() from the downstream port, when give the frame to the upstream port by calling put_frame 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.

---

Typedef Documentation

typedef typedefPJ_BEGIN_DECL struct pjmedia_master_port pjmedia_master_port

Opaque declaration for master port.

---

Function Documentation

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.