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 * $Id: super_tone_rx.h,v 1.21 2009/02/10 13:06:47 steveu Exp $ 00026 */ 00027 00028 #if !defined(_SPANDSP_SUPER_TONE_RX_H_) 00029 #define _SPANDSP_SUPER_TONE_RX_H_ 00030 00031 /*! \page super_tone_rx_page Supervisory tone detection 00032 00033 \section super_tone_rx_page_sec_1 What does it do? 00034 00035 The supervisory tone detector may be configured to detect most of the world's 00036 telephone supervisory tones - things like ringback, busy, number unobtainable, 00037 and so on. 00038 00039 \section super_tone_rx_page_sec_2 How does it work? 00040 00041 The supervisory tone detector is passed a series of data structures describing 00042 the tone patterns - the frequencies and cadencing - of the tones to be searched 00043 for. It constructs one or more Goertzel filters to monitor the required tones. 00044 If tones are close in frequency a single Goertzel set to the centre of the 00045 frequency range will be used. This optimises the efficiency of the detector. The 00046 Goertzel filters are applied without applying any special window functional 00047 (i.e. they use a rectangular window), so they have a sinc like response. 00048 However, for most tone patterns their rejection qualities are adequate. 00049 00050 The detector aims to meet the need of the standard call progress tones, to 00051 ITU-T E.180/Q.35 (busy, dial, ringback, reorder). Also, the extended tones, 00052 to ITU-T E.180, Supplement 2 and EIA/TIA-464-A (recall dial tone, special 00053 ringback tone, intercept tone, call waiting tone, busy verification tone, 00054 executive override tone, confirmation tone). 00055 */ 00056 00057 /*! Tone detection indication callback routine */ 00058 typedef void (*tone_report_func_t)(void *user_data, int code, int level, int delay); 00059 00060 typedef struct super_tone_rx_segment_s super_tone_rx_segment_t; 00061 00062 typedef struct super_tone_rx_descriptor_s super_tone_rx_descriptor_t; 00063 00064 typedef struct super_tone_rx_state_s super_tone_rx_state_t; 00065 00066 #if defined(__cplusplus) 00067 extern "C" 00068 { 00069 #endif 00070 00071 /*! Create a new supervisory tone detector descriptor. 00072 \param desc The supervisory tone set desciptor. If NULL, the routine will allocate space for a 00073 descriptor. 00074 \return The supervisory tone set descriptor. 00075 */ 00076 SPAN_DECLARE(super_tone_rx_descriptor_t *) super_tone_rx_make_descriptor(super_tone_rx_descriptor_t *desc); 00077 00078 /*! Free a supervisory tone detector descriptor. 00079 \param desc The supervisory tone set desciptor. 00080 \return 0 for OK, -1 for fail. 00081 */ 00082 SPAN_DECLARE(int) super_tone_rx_free_descriptor(super_tone_rx_descriptor_t *desc); 00083 00084 /*! Add a new tone pattern to a supervisory tone detector set. 00085 \param desc The supervisory tone set descriptor. 00086 \return The new tone ID. */ 00087 SPAN_DECLARE(int) super_tone_rx_add_tone(super_tone_rx_descriptor_t *desc); 00088 00089 /*! Add a new tone pattern element to a tone pattern in a supervisory tone detector. 00090 \param desc The supervisory tone set desciptor. 00091 \param tone The tone ID within the descriptor. 00092 \param f1 Frequency 1 (-1 for a silent period). 00093 \param f2 Frequency 2 (-1 for a silent period, or only one frequency). 00094 \param min The minimum duration, in ms. 00095 \param max The maximum duration, in ms. 00096 \return The new number of elements in the tone description. 00097 */ 00098 SPAN_DECLARE(int) super_tone_rx_add_element(super_tone_rx_descriptor_t *desc, 00099 int tone, 00100 int f1, 00101 int f2, 00102 int min, 00103 int max); 00104 00105 /*! Initialise a supervisory tone detector. 00106 \param s The supervisory tone detector context. 00107 \param desc The tone descriptor. 00108 \param callback The callback routine called to report the valid detection or termination of 00109 one of the monitored tones. 00110 \param user_data An opaque pointer passed when calling the callback routine. 00111 \return The supervisory tone detector context. 00112 */ 00113 SPAN_DECLARE(super_tone_rx_state_t *) super_tone_rx_init(super_tone_rx_state_t *s, 00114 super_tone_rx_descriptor_t *desc, 00115 tone_report_func_t callback, 00116 void *user_data); 00117 00118 /*! Release a supervisory tone detector. 00119 \param s The supervisory tone context. 00120 \return 0 for OK, -1 for fail. 00121 */ 00122 SPAN_DECLARE(int) super_tone_rx_release(super_tone_rx_state_t *s); 00123 00124 /*! Free a supervisory tone detector. 00125 \param s The supervisory tone context. 00126 \return 0 for OK, -1 for fail. 00127 */ 00128 SPAN_DECLARE(int) super_tone_rx_free(super_tone_rx_state_t *s); 00129 00130 /*! Define a callback routine to be called each time a tone pattern element is complete. This is 00131 mostly used when analysing a tone. 00132 \param s The supervisory tone context. 00133 \param callback The callback routine. 00134 */ 00135 SPAN_DECLARE(void) super_tone_rx_segment_callback(super_tone_rx_state_t *s, 00136 void (*callback)(void *data, int f1, int f2, int duration)); 00137 00138 /*! Apply supervisory tone detection processing to a block of audio samples. 00139 \brief Apply supervisory tone detection processing to a block of audio samples. 00140 \param super The supervisory tone context. 00141 \param amp The audio sample buffer. 00142 \param samples The number of samples in the buffer. 00143 \return The number of samples processed. 00144 */ 00145 SPAN_DECLARE(int) super_tone_rx(super_tone_rx_state_t *super, const int16_t amp[], int samples); 00146 00147 #if defined(__cplusplus) 00148 } 00149 #endif 00150 00151 #endif 00152 /*- End of file ------------------------------------------------------------*/