diff options
Diffstat (limited to 'pjmedia/include/pjmedia/tonegen.h')
-rw-r--r-- | pjmedia/include/pjmedia/tonegen.h | 225 |
1 files changed, 225 insertions, 0 deletions
diff --git a/pjmedia/include/pjmedia/tonegen.h b/pjmedia/include/pjmedia/tonegen.h new file mode 100644 index 00000000..c1d47200 --- /dev/null +++ b/pjmedia/include/pjmedia/tonegen.h @@ -0,0 +1,225 @@ +/* $Id$ */ +/* + * Copyright (C) 2003-2006 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. */ +} 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. */ +} 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_load_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]; +} pjmedia_tone_digit_map; + + + +/** + * 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, must be zero for now. + * @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); + + +/** + * 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 Playback options, must be zero for now. + * + * @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 Playback options, must be zero for now. + * + * @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__ */ + |