1
/* $Id: master_port.h 3553 2011-05-05 06:14:19Z nanang $ */
3
* Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
4
* Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
6
* This program is free software; you can redistribute it and/or modify
7
* it under the terms of the GNU General Public License as published by
8
* the Free Software Foundation; either version 2 of the License, or
9
* (at your option) any later version.
11
* This program is distributed in the hope that it will be useful,
12
* but WITHOUT ANY WARRANTY; without even the implied warranty of
13
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14
* GNU General Public License for more details.
16
* You should have received a copy of the GNU General Public License
17
* along with this program; if not, write to the Free Software
18
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
20
#ifndef __PJMEDIA_MASTER_PORT_H__
21
#define __PJMEDIA_MASTER_PORT_H__
28
#include <pjmedia/port.h>
31
* @defgroup PJMEDIA_MASTER_PORT Master Port
32
* @ingroup PJMEDIA_PORT_CLOCK
33
* @brief Thread based media clock provider
36
* A master port has two media ports connected to it, and by convention
37
* thay are called downstream and upstream ports. The media stream flowing to
38
* the downstream port is called encoding or send direction, and media stream
39
* flowing to the upstream port is called decoding or receive direction
40
* (imagine the downstream as stream to remote endpoint, and upstream as
41
* local media port; media flowing to remote endpoint (downstream) will need
42
* to be encoded before it is transmitted to remote endpoint).
44
* A master port internally has an instance of @ref PJMEDIA_CLOCK, which
45
* provides the essensial timing for the master port. The @ref PJMEDIA_CLOCK
46
* runs asynchronously, and whenever a clock <b>tick</b> expires, a callback
47
* will be called, and the master port performs the following tasks:
48
* - it calls <b><tt>get_frame()</tt></b> from the downstream port,
49
* when give the frame to the upstream port by calling <b><tt>put_frame
50
* </tt></b> to the upstream port, and
51
* - performs the same task, but on the reverse direction (i.e. get the stream
52
* from upstream port and give it to the downstream port).
54
* Because master port enables media stream to flow automatically, it is
55
* said that the master port supplies @ref PJMEDIA_PORT_CLOCK to the
56
* media ports interconnection.
64
* Opaque declaration for master port.
66
typedef struct pjmedia_master_port pjmedia_master_port;
70
* Create a master port.
72
* @param pool Pool to allocate master port from.
73
* @param u_port Upstream port.
74
* @param d_port Downstream port.
75
* @param options Options flags, from bitmask combinations from
76
* pjmedia_clock_options.
77
* @param p_m Pointer to receive the master port instance.
79
* @return PJ_SUCCESS on success.
81
PJ_DECL(pj_status_t) pjmedia_master_port_create(pj_pool_t *pool,
85
pjmedia_master_port **p_m);
89
* Start the media flow.
91
* @param m The master port.
93
* @return PJ_SUCCESS on success.
95
PJ_DECL(pj_status_t) pjmedia_master_port_start(pjmedia_master_port *m);
99
* Stop the media flow.
101
* @param m The master port.
103
* @return PJ_SUCCESS on success.
105
PJ_DECL(pj_status_t) pjmedia_master_port_stop(pjmedia_master_port *m);
109
* Poll the master port clock and execute the callback when the clock tick has
110
* elapsed. This operation is only valid if the master port is created with
111
* #PJMEDIA_CLOCK_NO_ASYNC flag.
113
* @param m The master port.
114
* @param wait If non-zero, then the function will block until
115
* a clock tick elapsed and callback has been called.
116
* @param ts Optional argument to receive the current
119
* @return Non-zero if clock tick has elapsed, or FALSE if
120
* the function returns before a clock tick has
123
PJ_DECL(pj_bool_t) pjmedia_master_port_wait(pjmedia_master_port *m,
129
* Change the upstream port. Note that application is responsible to destroy
130
* current upstream port (the one that is going to be replaced with the
133
* @param m The master port.
134
* @param port Port to be used for upstream port.
136
* @return PJ_SUCCESS on success.
138
PJ_DECL(pj_status_t) pjmedia_master_port_set_uport(pjmedia_master_port *m,
143
* Get the upstream port.
145
* @param m The master port.
147
* @return The upstream port.
149
PJ_DECL(pjmedia_port*) pjmedia_master_port_get_uport(pjmedia_master_port*m);
153
* Change the downstream port. Note that application is responsible to destroy
154
* current downstream port (the one that is going to be replaced with the
157
* @param m The master port.
158
* @param port Port to be used for downstream port.
160
* @return PJ_SUCCESS on success.
162
PJ_DECL(pj_status_t) pjmedia_master_port_set_dport(pjmedia_master_port *m,
167
* Get the downstream port.
169
* @param m The master port.
171
* @return The downstream port.
173
PJ_DECL(pjmedia_port*) pjmedia_master_port_get_dport(pjmedia_master_port*m);
177
* Destroy the master port, and optionally destroy the upstream and
180
* @param m The master port.
181
* @param destroy_ports If non-zero, the function will destroy both
182
* upstream and downstream ports too.
184
* @return PJ_SUCCESS on success.
186
PJ_DECL(pj_status_t) pjmedia_master_port_destroy(pjmedia_master_port *m,
187
pj_bool_t destroy_ports);
198
#endif /* __PJMEDIA_MASTER_PORT_H__ */