super_tone_rx.h

00001 /*
00002  * SpanDSP - a series of DSP components for telephony
00003  *
00004  * super_tone_rx.h - Flexible telephony supervisory tone detection.
00005  *
00006  * Written by Steve Underwood <steveu@coppice.org>
00007  *
00008  * Copyright (C) 2003 Steve Underwood
00009  *
00010  * All rights reserved.
00011  *
00012  * This program is free software; you can redistribute it and/or modify
00013  * it under the terms of the GNU Lesser General Public License version 2.1,
00014  * as published by the Free Software Foundation.
00015  *
00016  * This program is distributed in the hope that it will be useful,
00017  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00018  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00019  * GNU Lesser General Public License for more details.
00020  *
00021  * You should have received a copy of the GNU Lesser General Public
00022  * License along with this program; if not, write to the Free Software
00023  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
00024  */
00025 
00026 #if !defined(_SPANDSP_SUPER_TONE_RX_H_)
00027 #define _SPANDSP_SUPER_TONE_RX_H_
00028 
00029 /*! \page super_tone_rx_page Supervisory tone detection
00030 
00031 \section super_tone_rx_page_sec_1 What does it do?
00032 
00033 The supervisory tone detector may be configured to detect most of the world's
00034 telephone supervisory tones - things like ringback, busy, number unobtainable,
00035 and so on.
00036 
00037 \section super_tone_rx_page_sec_2 How does it work?
00038 
00039 The supervisory tone detector is passed a series of data structures describing
00040 the tone patterns - the frequencies and cadencing - of the tones to be searched
00041 for. It constructs one or more Goertzel filters to monitor the required tones.
00042 If tones are close in frequency a single Goertzel set to the centre of the
00043 frequency range will be used. This optimises the efficiency of the detector. The
00044 Goertzel filters are applied without applying any special window functional
00045 (i.e. they use a rectangular window), so they have a sinc like response.
00046 However, for most tone patterns their rejection qualities are adequate. 
00047 
00048 The detector aims to meet the need of the standard call progress tones, to
00049 ITU-T E.180/Q.35 (busy, dial, ringback, reorder). Also, the extended tones,
00050 to ITU-T E.180, Supplement 2 and EIA/TIA-464-A (recall dial tone, special
00051 ringback tone, intercept tone, call waiting tone, busy verification tone,
00052 executive override tone, confirmation tone).
00053 */
00054 
00055 /*! Tone detection indication callback routine */
00056 typedef void (*tone_report_func_t)(void *user_data, int code, int level, int delay);
00057 
00058 typedef struct super_tone_rx_segment_s super_tone_rx_segment_t;
00059 
00060 typedef struct super_tone_rx_descriptor_s super_tone_rx_descriptor_t;
00061 
00062 typedef struct super_tone_rx_state_s super_tone_rx_state_t;
00063 
00064 #if defined(__cplusplus)
00065 extern "C"
00066 {
00067 #endif
00068 
00069 /*! Create a new supervisory tone detector descriptor.
00070     \param desc The supervisory tone set desciptor. If NULL, the routine will allocate space for a
00071                 descriptor.
00072     \return The supervisory tone set descriptor.
00073 */
00074 SPAN_DECLARE(super_tone_rx_descriptor_t *) super_tone_rx_make_descriptor(super_tone_rx_descriptor_t *desc);
00075 
00076 /*! Free a supervisory tone detector descriptor.
00077     \param desc The supervisory tone set desciptor.
00078     \return 0 for OK, -1 for fail.
00079 */
00080 SPAN_DECLARE(int) super_tone_rx_free_descriptor(super_tone_rx_descriptor_t *desc);
00081 
00082 /*! Add a new tone pattern to a supervisory tone detector set.
00083     \param desc The supervisory tone set descriptor.
00084     \return The new tone ID. */
00085 SPAN_DECLARE(int) super_tone_rx_add_tone(super_tone_rx_descriptor_t *desc);
00086 
00087 /*! Add a new tone pattern element to a tone pattern in a supervisory tone detector.
00088     \param desc The supervisory tone set desciptor.
00089     \param tone The tone ID within the descriptor.
00090     \param f1 Frequency 1 (-1 for a silent period).
00091     \param f2 Frequency 2 (-1 for a silent period, or only one frequency).
00092     \param min The minimum duration, in ms.
00093     \param max The maximum duration, in ms.
00094     \return The new number of elements in the tone description.
00095 */
00096 SPAN_DECLARE(int) super_tone_rx_add_element(super_tone_rx_descriptor_t *desc,
00097                                             int tone,
00098                                             int f1,
00099                                             int f2,
00100                                             int min,
00101                                             int max);
00102 
00103 /*! Initialise a supervisory tone detector.
00104     \param s The supervisory tone detector context.
00105     \param desc The tone descriptor.
00106     \param callback The callback routine called to report the valid detection or termination of
00107            one of the monitored tones.
00108     \param user_data An opaque pointer passed when calling the callback routine.
00109     \return The supervisory tone detector context.
00110 */
00111 SPAN_DECLARE(super_tone_rx_state_t *) super_tone_rx_init(super_tone_rx_state_t *s,
00112                                                          super_tone_rx_descriptor_t *desc,
00113                                                          tone_report_func_t callback,
00114                                                          void *user_data);
00115 
00116 /*! Release a supervisory tone detector.
00117     \param s The supervisory tone context.
00118     \return 0 for OK, -1 for fail.
00119 */
00120 SPAN_DECLARE(int) super_tone_rx_release(super_tone_rx_state_t *s);
00121 
00122 /*! Free a supervisory tone detector.
00123     \param s The supervisory tone context.
00124     \return 0 for OK, -1 for fail.
00125 */
00126 SPAN_DECLARE(int) super_tone_rx_free(super_tone_rx_state_t *s);
00127 
00128 /*! Define a callback routine to be called each time a tone pattern element is complete. This is
00129     mostly used when analysing a tone.
00130     \param s The supervisory tone context.
00131     \param callback The callback routine.
00132 */
00133 SPAN_DECLARE(void) super_tone_rx_segment_callback(super_tone_rx_state_t *s,
00134                                                   void (*callback)(void *data, int f1, int f2, int duration));
00135 
00136 /*! Apply supervisory tone detection processing to a block of audio samples.
00137     \brief Apply supervisory tone detection processing to a block of audio samples.
00138     \param super The supervisory tone context.
00139     \param amp The audio sample buffer.
00140     \param samples The number of samples in the buffer.
00141     \return The number of samples processed.
00142 */
00143 SPAN_DECLARE(int) super_tone_rx(super_tone_rx_state_t *super, const int16_t amp[], int samples);
00144 
00145 #if defined(__cplusplus)
00146 }
00147 #endif
00148 
00149 #endif
00150 /*- End of file ------------------------------------------------------------*/

Generated on Fri Apr 15 16:14:38 2011 for spandsp by  doxygen 1.4.7