| /* $Id$ */ |
| /* |
| * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com) |
| * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org> |
| * |
| * 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 <pjmedia/port.h> |
| |
| /** |
| * @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 <b>tick</b> expires, a callback |
| * will be called, and the master port performs the following tasks: |
| * - it calls <b><tt>get_frame()</tt></b> from the downstream port, |
| * when give the frame to the upstream port by calling <b><tt>put_frame |
| * </tt></b> 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__ */ |
| |