1 /* $Id$ */ 2 /* 3 * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com) 4 * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org> 5 * 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. 10 * 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. 15 * 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 19 */ 20 #ifndef __PJMEDIA_MASTER_PORT_H__ 21 #define __PJMEDIA_MASTER_PORT_H__ 22 23 24 /** 25 * @file master_port.h 26 * @brief Master port. 27 */ 28 #include <pjmedia/port.h> 29 30 /** 31 * @defgroup PJMEDIA_MASTER_PORT Master Port 32 * @ingroup PJMEDIA_PORT_CLOCK 33 * @brief Thread based media clock provider 34 * @{ 35 * 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). 43 * 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). 53 * 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. 57 * 58 */ 59 60 PJ_BEGIN_DECL 61 62 63 /** 64 * Opaque declaration for master port. 65 */ 66 typedef struct pjmedia_master_port pjmedia_master_port; 67 68 69 /** 70 * Create a master port. 71 * 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. 78 * 79 * @return PJ_SUCCESS on success. 80 */ 81 PJ_DECL(pj_status_t) pjmedia_master_port_create(pj_pool_t *pool, 82 pjmedia_port *u_port, 83 pjmedia_port *d_port, 84 unsigned options, 85 pjmedia_master_port **p_m); 86 87 88 /** 89 * Start the media flow. 90 * 91 * @param m The master port. 92 * 93 * @return PJ_SUCCESS on success. 94 */ 95 PJ_DECL(pj_status_t) pjmedia_master_port_start(pjmedia_master_port *m); 96 97 98 /** 99 * Stop the media flow. 100 * 101 * @param m The master port. 102 * 103 * @return PJ_SUCCESS on success. 104 */ 105 PJ_DECL(pj_status_t) pjmedia_master_port_stop(pjmedia_master_port *m); 106 107 108 /** 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. 112 * 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 117 * timestamp. 118 * 119 * @return Non-zero if clock tick has elapsed, or FALSE if 120 * the function returns before a clock tick has 121 * elapsed. 122 */ 123 PJ_DECL(pj_bool_t) pjmedia_master_port_wait(pjmedia_master_port *m, 124 pj_bool_t wait, 125 pj_timestamp *ts); 126 127 128 /** 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 131 * new port). 132 * 133 * @param m The master port. 134 * @param port Port to be used for upstream port. 135 * 136 * @return PJ_SUCCESS on success. 137 */ 138 PJ_DECL(pj_status_t) pjmedia_master_port_set_uport(pjmedia_master_port *m, 139 pjmedia_port *port); 140 141 142 /** 143 * Get the upstream port. 144 * 145 * @param m The master port. 146 * 147 * @return The upstream port. 148 */ 149 PJ_DECL(pjmedia_port*) pjmedia_master_port_get_uport(pjmedia_master_port*m); 150 151 152 /** 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 155 * new port). 156 * 157 * @param m The master port. 158 * @param port Port to be used for downstream port. 159 * 160 * @return PJ_SUCCESS on success. 161 */ 162 PJ_DECL(pj_status_t) pjmedia_master_port_set_dport(pjmedia_master_port *m, 163 pjmedia_port *port); 164 165 166 /** 167 * Get the downstream port. 168 * 169 * @param m The master port. 170 * 171 * @return The downstream port. 172 */ 173 PJ_DECL(pjmedia_port*) pjmedia_master_port_get_dport(pjmedia_master_port*m); 174 175 176 /** 177 * Destroy the master port, and optionally destroy the upstream and 178 * downstream ports. 179 * 180 * @param m The master port. 181 * @param destroy_ports If non-zero, the function will destroy both 182 * upstream and downstream ports too. 183 * 184 * @return PJ_SUCCESS on success. 185 */ 186 PJ_DECL(pj_status_t) pjmedia_master_port_destroy(pjmedia_master_port *m, 187 pj_bool_t destroy_ports); 188 189 190 191 PJ_END_DECL 192 193 /** 194 * @} 195 */ 196 197 198 #endif /* __PJMEDIA_MASTER_PORT_H__ */ 199 200