/* $Id: tonegen.h 974 2007-02-19 01:13:53Z bennylp $ *//*  * Copyright (C) 2003-2007 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_TONEGEN_PORT_H__#define __PJMEDIA_TONEGEN_PORT_H__/** * @file tonegen.h * @brief Tone (sine, MF, DTMF) generator media port. */#include <pjmedia/port.h>/** * @defgroup PJMEDIA_MF_DTMF_TONE_GENERATOR Tone (sine, MF, DTMF) Generator * @ingroup PJMEDIA_PORT * @brief Tone (sine, MF, DTMF) Generator * @{ * This page describes tone generator media port. A tone generator can be * used to generate a single frequency sine wave or dual frequency tones * such as DTMF. * * The tone generator media port provides two functions to generate tones. * The function #pjmedia_tonegen_play() can be used to generate arbitrary * single or dual frequency tone, and #pjmedia_tonegen_play_digits() is * used to play digits such as DTMF. Each tone specified in the playback * function has individual on and off signal duration that must be * specified by application. * * In order to play digits such as DTMF, the tone generator is equipped * with digit map, which contain information about the frequencies of * the digits. The default digit map is DTMF (0-9,a-d,*,#), but application * may specifiy different digit map to the tone generator by calling * #pjmedia_tonegen_set_digit_map() function. */PJ_BEGIN_DECL/** * This structure describes individual MF digits to be played * with #pjmedia_tonegen_play(). */typedef struct pjmedia_tone_desc{    short   freq1;	    /**< First frequency.			    */    short   freq2;	    /**< Optional second frequency.		    */    short   on_msec;	    /**< Playback ON duration, in miliseconds.	    */    short   off_msec;	    /**< Playback OFF duration, ini miliseconds.    */    short   volume;	    /**< Volume (1-16383), or 0 for default.	    */} pjmedia_tone_desc;/** * This structure describes individual MF digits to be played * with #pjmedia_tonegen_play_digits(). */typedef struct pjmedia_tone_digit{    char    digit;	    /**< The ASCI identification for the digit.	    */    short   on_msec;	    /**< Playback ON duration, in miliseconds.	    */    short   off_msec;	    /**< Playback OFF duration, ini miliseconds.    */    short   volume;	    /**< Volume (1-16383), or 0 for default.	    */} pjmedia_tone_digit;/** * This structure describes the digit map which is used by the tone generator * to produce tones from an ASCII digits. * Digit map used by a particular tone generator can be retrieved/set with * #pjmedia_tonegen_get_digit_map() and #pjmedia_tonegen_set_digit_map(). */typedef struct pjmedia_tone_digit_map{    unsigned count;	    /**< Number of digits in the map.		*/    struct {	char    digit;	    /**< The ASCI identification for the digit.	*/	short   freq1;	    /**< First frequency.			*/	short   freq2;	    /**< Optional second frequency.		*/    } digits[16];	    /**< Array of digits in the digit map.	*/} pjmedia_tone_digit_map;/** * Tone generator options. */enum{    /**     * Play the tones in loop, restarting playing the first tone after     * the last tone has been played.     */    PJMEDIA_TONEGEN_LOOP    = 1};/** * Create an instance of tone generator with the specified parameters. * When the tone generator is first created, it will be loaded with the * default digit map. * * @param pool		    Pool to allocate memory for the port structure. * @param clock_rate	    Sampling rate. * @param channel_count	    Number of channels. Currently only mono and stereo *			    are supported. * @param samples_per_frame Number of samples per frame. * @param bits_per_sample   Number of bits per sample. This version of PJMEDIA *			    only supports 16bit per sample. * @param options	    Option flags. Application may specify  *			    PJMEDIA_TONEGEN_LOOP to play the tone in a loop. * @param p_port	    Pointer to receive the port instance. * * @return		    PJ_SUCCESS on success, or the appropriate *			    error code. */PJ_DECL(pj_status_t) pjmedia_tonegen_create(pj_pool_t *pool,					    unsigned clock_rate,					    unsigned channel_count,					    unsigned samples_per_frame,					    unsigned bits_per_sample,					    unsigned options,					    pjmedia_port **p_port);/** * Create an instance of tone generator with the specified parameters. * When the tone generator is first created, it will be loaded with the * default digit map. * * @param pool		    Pool to allocate memory for the port structure. * @param name		    Optional name for the tone generator. * @param clock_rate	    Sampling rate. * @param channel_count	    Number of channels. Currently only mono and stereo *			    are supported. * @param samples_per_frame Number of samples per frame. * @param bits_per_sample   Number of bits per sample. This version of PJMEDIA *			    only supports 16bit per sample. * @param options	    Option flags. Application may specify  *			    PJMEDIA_TONEGEN_LOOP to play the tone in a loop. * @param p_port	    Pointer to receive the port instance. * * @return		    PJ_SUCCESS on success, or the appropriate *			    error code. */PJ_DECL(pj_status_t) pjmedia_tonegen_create2(pj_pool_t *pool,					     const pj_str_t *name,					     unsigned clock_rate,					     unsigned channel_count,					     unsigned samples_per_frame,					     unsigned bits_per_sample,					     unsigned options,					     pjmedia_port **p_port);/** * Check if the tone generator is still busy producing some tones. * * @param tonegen	    The tone generator instance. * * @return		    Non-zero if busy. */PJ_DECL(pj_bool_t) pjmedia_tonegen_is_busy(pjmedia_port *tonegen);/** * Instruct the tone generator to stop current processing. * * @param tonegen	    The tone generator instance. * * @return		    PJ_SUCCESS on success. */PJ_DECL(pj_status_t) pjmedia_tonegen_stop(pjmedia_port *tonegen);/** * Instruct the tone generator to play single or dual frequency tones  * with the specified duration. The new tones will be appended to currently * playing tones, unless #pjmedia_tonegen_stop() is called before calling * this function. The playback will begin as soon as  the first get_frame() * is called to the generator. * * @param tonegen	    The tone generator instance. * @param count		    The number of tones in the array. * @param tones		    Array of tones to be played. * @param options	    Option flags. Application may specify  *			    PJMEDIA_TONEGEN_LOOP to play the tone in a loop. * * @return		    PJ_SUCCESS on success, or PJ_ETOOMANY if *			    there are too many digits in the queue. */PJ_DECL(pj_status_t) pjmedia_tonegen_play(pjmedia_port *tonegen,					  unsigned count,					  const pjmedia_tone_desc tones[],					  unsigned options);/** * Instruct the tone generator to play multiple MF digits with each of * the digits having individual ON/OFF duration. Each of the digit in the * digit array must have the corresponding descriptor in the digit map. * The new tones will be appended to currently playing tones, unless  * #pjmedia_tonegen_stop() is called before calling this function.  * The playback will begin as soon as the first get_frame() is called  * to the generator. * * @param tonegen	    The tone generator instance. * @param count		    Number of digits in the array. * @param digits	    Array of MF digits. * @param options	    Option flags. Application may specify  *			    PJMEDIA_TONEGEN_LOOP to play the tone in a loop. * * @return		    PJ_SUCCESS on success, or PJ_ETOOMANY if *			    there are too many digits in the queue, or *			    PJMEDIA_RTP_EINDTMF if invalid digit is *			    specified. */PJ_DECL(pj_status_t) pjmedia_tonegen_play_digits(pjmedia_port *tonegen,						 unsigned count,						 const pjmedia_tone_digit digits[],						 unsigned options);/** * Get the digit-map currently used by this tone generator. * * @param tonegen	    The tone generator instance. * @param m		    On output, it will be filled with the pointer to *			    the digitmap currently used by the tone generator. * * @return		    PJ_SUCCESS on success. */PJ_DECL(pj_status_t) pjmedia_tonegen_get_digit_map(pjmedia_port *tonegen,						   const pjmedia_tone_digit_map **m);/** * Set digit map to be used by the tone generator. * * @param tonegen	    The tone generator instance. * @param m		    Digitmap to be used by the tone generator. * * @return		    PJ_SUCCESS on success. */PJ_DECL(pj_status_t) pjmedia_tonegen_set_digit_map(pjmedia_port *tonegen,						   pjmedia_tone_digit_map *m);PJ_END_DECL/** * @} */#endif	/* __PJMEDIA_TONEGEN_PORT_H__ */