/* $Id$ */ /* * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com) * Copyright (C) 2003-2008 Benny Prijono * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ #ifndef __PJMEDIA_MASTER_PORT_H__ #define __PJMEDIA_MASTER_PORT_H__ /** * @file master_port.h * @brief Master port. */ #include /** * @defgroup PJMEDIA_MASTER_PORT Master Port * @ingroup PJMEDIA_PORT_CLOCK * @brief 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 @ref PJMEDIA_CLOCK, which * provides the essensial timing for the master port. The @ref PJMEDIA_CLOCK * 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 @ref PJMEDIA_PORT_CLOCK to the * media ports interconnection. * */ PJ_BEGIN_DECL /** * Opaque declaration for master port. */ typedef struct pjmedia_master_port pjmedia_master_port; /** * Create a master port. * * @param pool Pool to allocate master port from. * @param u_port Upstream port. * @param d_port Downstream port. * @param options Options flags, from bitmask combinations from * pjmedia_clock_options. * @param p_m Pointer to receive the master port instance. * * @return PJ_SUCCESS on success. */ PJ_DECL(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); /** * Start the media flow. * * @param m The master port. * * @return PJ_SUCCESS on success. */ PJ_DECL(pj_status_t) pjmedia_master_port_start(pjmedia_master_port *m); /** * Stop the media flow. * * @param m The master port. * * @return PJ_SUCCESS on success. */ PJ_DECL(pj_status_t) pjmedia_master_port_stop(pjmedia_master_port *m); /** * 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. * * @param m The master port. * @param wait If non-zero, then the function will block until * a clock tick elapsed and callback has been called. * @param ts Optional argument to receive the current * timestamp. * * @return Non-zero if clock tick has elapsed, or FALSE if * the function returns before a clock tick has * elapsed. */ PJ_DECL(pj_bool_t) pjmedia_master_port_wait(pjmedia_master_port *m, pj_bool_t wait, pj_timestamp *ts); /** * 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). * * @param m The master port. * @param port Port to be used for upstream port. * * @return PJ_SUCCESS on success. */ PJ_DECL(pj_status_t) pjmedia_master_port_set_uport(pjmedia_master_port *m, pjmedia_port *port); /** * Get the upstream port. * * @param m The master port. * * @return The upstream port. */ PJ_DECL(pjmedia_port*) pjmedia_master_port_get_uport(pjmedia_master_port*m); /** * 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). * * @param m The master port. * @param port Port to be used for downstream port. * * @return PJ_SUCCESS on success. */ PJ_DECL(pj_status_t) pjmedia_master_port_set_dport(pjmedia_master_port *m, pjmedia_port *port); /** * Get the downstream port. * * @param m The master port. * * @return The downstream port. */ PJ_DECL(pjmedia_port*) pjmedia_master_port_get_dport(pjmedia_master_port*m); /** * Destroy the master port, and optionally destroy the upstream and * downstream ports. * * @param m The master port. * @param destroy_ports If non-zero, the function will destroy both * upstream and downstream ports too. * * @return PJ_SUCCESS on success. */ PJ_DECL(pj_status_t) pjmedia_master_port_destroy(pjmedia_master_port *m, pj_bool_t destroy_ports); PJ_END_DECL /** * @} */ #endif /* __PJMEDIA_MASTER_PORT_H__ */