Added multi-purpose tone generator in PJMEDIA (tonegen.[hc])

git-svn-id: http://svn.pjsip.org/repos/pjproject/trunk@693 74dad513-b988-da41-8d7b-12977e46ad98

3 files changed, 234 insertions, 0 deletions

diff --git a/pjmedia/include/pjmedia.h b/pjmedia/include/pjmedia.h
index 233dc889..83fded59 100644
--- a/pjmedia/include/pjmedia.h
+++ b/pjmedia/include/pjmedia.h
@@ -50,6 +50,7 @@
 #include <pjmedia/sound.h>
 #include <pjmedia/sound_port.h>
 #include <pjmedia/splitcomb.h>
+#include <pjmedia/tonegen.h>
 #include <pjmedia/transport.h>
 #include <pjmedia/transport_udp.h>
 #include <pjmedia/wav_port.h>
diff --git a/pjmedia/include/pjmedia/config.h b/pjmedia/include/pjmedia/config.h
index 344ef2c2..7bd9f946 100644
--- a/pjmedia/include/pjmedia/config.h
+++ b/pjmedia/include/pjmedia/config.h
@@ -241,6 +241,14 @@
 #endif
 
 
+/**
+ * Maximum tones/digits that can be enqueued in the tone generator.
+ */
+#ifndef PJMEDIA_TONEGEN_MAX_DIGITS
+#   define PJMEDIA_TONEGEN_MAX_DIGITS		    32
+#endif
+
+
 
 /**
  * @}
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__ */
+