conference.h

一个开源的sip源代码

/* $Id: conference.h 1301 2007-05-25 06:13:55Z bennylp $ */
/* 
 * Copyright (C) 2003-2007 Benny Prijono <[e-mail]>
 *
 * 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_CONF_H__
#define __PJMEDIA_CONF_H__


/**
 * @file conference.h
 * @brief Conference bridge.
 */
#include <pjmedia/port.h>

/**
 * @defgroup PJMEDIA_CONF Conference Bridge
 * @ingroup PJMEDIA_PORT
 * @brief The implementation of conference bridge
 * @{
 *
 * This describes the conference bridge implementation in PJMEDIA. The
 * conference bridge provides powerful and very efficient mechanism to
 * route the audio flow and mix the audio signal when required.
 *
 * Some more information about the media flow when conference bridge is
 * used is described in http://www.pjsip.org/trac/wiki/media-flow .
 */

PJ_BEGIN_DECL


/**
 * Opaque type for conference bridge.
 */
typedef struct pjmedia_conf pjmedia_conf;

/**
 * Conference port info.
 */
typedef struct pjmedia_conf_port_info
{
    unsigned		slot;		    /**< Slot number.		    */
    pj_str_t		name;		    /**< Port name.		    */
    pjmedia_port_op	tx_setting;	    /**< Transmit settings.	    */
    pjmedia_port_op	rx_setting;	    /**< Receive settings.	    */
    unsigned		listener_cnt;	    /**< Number of listeners.	    */
    unsigned	       *listener_slots;	    /**< Array of listeners.	    */
    unsigned		clock_rate;	    /**< Clock rate of the port.    */
    unsigned		channel_count;	    /**< Number of channels.	    */
    unsigned		samples_per_frame;  /**< Samples per frame	    */
    unsigned		bits_per_sample;    /**< Bits per sample.	    */
    int			tx_adj_level;	    /**< Tx level adjustment.	    */
    int			rx_adj_level;	    /**< Rx level adjustment.	    */
} pjmedia_conf_port_info;


/**
 * Conference port options. The values here can be combined in bitmask to
 * be specified when the conference bridge is created.
 */
enum pjmedia_conf_option
{
    PJMEDIA_CONF_NO_MIC  = 1,	/**< Disable audio streams from the
				     microphone device.			    */
    PJMEDIA_CONF_NO_DEVICE = 2,	/**< Do not create sound device.	    */
    PJMEDIA_CONF_SMALL_FILTER=4,/**< Use small filter table when resampling */
    PJMEDIA_CONF_USE_LINEAR=8	/**< Use linear resampling instead of filter
				     based.				    */
};


/**
 * Create conference bridge with the specified parameters. The sampling rate,
 * samples per frame, and bits per sample will be used for the internal
 * operation of the bridge (e.g. when mixing audio frames). However, ports 
 * with different configuration may be connected to the bridge. In this case,
 * the bridge is able to perform sampling rate conversion, and buffering in 
 * case the samples per frame is different.
 *
 * For this version of PJMEDIA, only 16bits per sample is supported.
 *
 * For this version of PJMEDIA, the channel count of the ports MUST match
 * the channel count of the bridge.
 *
 * Under normal operation (i.e. when PJMEDIA_CONF_NO_DEVICE option is NOT
 * specified), the bridge internally create an instance of sound device
 * and connect the sound device to port zero of the bridge. 
 *
 * If PJMEDIA_CONF_NO_DEVICE options is specified, no sound device will
 * be created in the conference bridge. Application MUST acquire the port
 * interface of the bridge by calling #pjmedia_conf_get_master_port(), and
 * connect this port interface to a sound device port by calling
 * #pjmedia_snd_port_connect(), or to a master port (pjmedia_master_port)
 * if application doesn't want to instantiate any sound devices.
 *
 * The sound device or master port are crucial for the bridge's operation, 
 * because it provides the bridge with necessary clock to process the audio
 * frames periodically. Internally, the bridge runs when get_frame() to 
 * port zero is called.
 *
 * @param pool		    Pool to use to allocate the bridge and 
 *			    additional buffers for the sound device.
 * @param max_slots	    Maximum number of slots/ports to be created in
 *			    the bridge. Note that the bridge internally uses
 *			    one port for the sound device, so the actual 
 *			    maximum number of ports will be less one than
 *			    this value.
 * @param sampling_rate	    Set the sampling rate of the bridge. This value
 *			    is also used to set the sampling rate of the
 *			    sound device.
 * @param channel_count	    Number of channels in the PCM stream. Normally
 *			    the value will be 1 for mono, but application may
 *			    specify a value of 2 for stereo. Note that all
 *			    ports that will be connected to the bridge MUST 
 *			    have the same number of channels as the bridge.
 * @param samples_per_frame Set the number of samples per frame. This value
 *			    is also used to set the sound device.
 * @param bits_per_sample   Set the number of bits per sample. This value
 *			    is also used to set the sound device. Currently
 *			    only 16bit per sample is supported.
 * @param options	    Bitmask options to be set for the bridge. The
 *			    options are constructed from #pjmedia_conf_option
 *			    enumeration.
 * @param p_conf	    Pointer to receive the conference bridge instance.
 *
 * @return		    PJ_SUCCESS if conference bridge can be created.
 */
PJ_DECL(pj_status_t) pjmedia_conf_create( pj_pool_t *pool,
					  unsigned max_slots,
					  unsigned sampling_rate,
					  unsigned channel_count,
					  unsigned samples_per_frame,
					  unsigned bits_per_sample,
					  unsigned options,
					  pjmedia_conf **p_conf );


/**
 * Destroy conference bridge.
 *
 * @param conf		    The conference bridge.
 *
 * @return		    PJ_SUCCESS on success.
 */
PJ_DECL(pj_status_t) pjmedia_conf_destroy( pjmedia_conf *conf );


/**
 * Get the master port interface of the conference bridge. The master port
 * corresponds to the port zero of the bridge. This is only usefull when 
 * application wants to manage the sound device by itself, instead of 
 * allowing the bridge to automatically create a sound device implicitly.
 *
 * This function will only return a port interface if PJMEDIA_CONF_NO_DEVICE
 * option was specified when the bridge was created.
 *
 * Application can connect the port returned by this function to a 
 * sound device by calling #pjmedia_snd_port_connect().
 *
 * @param conf		    The conference bridge.
 *
 * @return		    The port interface of port zero of the bridge,
 *			    only when PJMEDIA_CONF_NO_DEVICE options was
 *			    specified when the bridge was created.
 */
PJ_DECL(pjmedia_port*) pjmedia_conf_get_master_port(pjmedia_conf *conf);


/**
 * Set master port name.
 *
 * @param conf		    The conference bridge.
 * @param name		    Name to be assigned.
 *
 * @return		    PJ_SUCCESS on success.
 */
PJ_DECL(pj_status_t) pjmedia_conf_set_port0_name(pjmedia_conf *conf,
						 const pj_str_t *name);


/**
 * Add media port to the conference bridge.
 *
 * By default, the new conference port will have both TX and RX enabled, 
 * but it is not connected to any other ports. Application SHOULD call 
 * #pjmedia_conf_connect_port() to  enable audio transmission and receipt 
 * to/from this port.
 *
 * Once the media port is connected to other port(s) in the bridge,
 * the bridge will continuosly call get_frame() and put_frame() to the
 * port, allowing media to flow to/from the port.
 *
 * @param conf		The conference bridge.
 * @param pool		Pool to allocate buffers for this port.
 * @param strm_port	Stream port interface.
 * @param name		Optional name for the port. If this value is NULL,
 *			the name will be taken from the name in the port 
 *			info.
 * @param p_slot	Pointer to receive the slot index of the port in
 *			the conference bridge.
 *
 * @return		PJ_SUCCESS on success.
 */
PJ_DECL(pj_status_t) pjmedia_conf_add_port( pjmedia_conf *conf,
					    pj_pool_t *pool,
					    pjmedia_port *strm_port,
					    const pj_str_t *name,
					    unsigned *p_slot );


/**
 * Create and add a passive media port to the conference bridge. Unlike
 * "normal" media port that is added with #pjmedia_conf_add_port(), media
 * port created with this function will not have its get_frame() and
 * put_frame() called by the bridge; instead, application MUST continuosly
 * call these functions to the port, to allow media to flow from/to the
 * port.
 *
 * Upon return of this function, application will be given two objects:
 * the slot number of the port in the bridge, and pointer to the media
 * port where application MUST start calling get_frame() and put_frame()
 * to the port.
 *
 * @param conf		    The conference bridge.
 * @param pool		    Pool to allocate buffers etc for this port.
 * @param name		    Name to be assigned to the port.
 * @param clock_rate	    Clock rate/sampling rate.
 * @param channel_count	    Number of channels.
 * @param samples_per_frame Number of samples per frame.
 * @param bits_per_sample   Number of bits per sample.
 * @param options	    Options (should be zero at the moment).
 * @param p_slot	    Pointer to receive the slot index of the port in
 *			    the conference bridge.