spandsp 0.0.6
|
00001 /* 00002 * SpanDSP - a series of DSP components for telephony 00003 * 00004 * modem_connect_tones.c - Generation and detection of tones 00005 * associated with modems calling and 00006 * answering calls. 00007 * 00008 * Written by Steve Underwood <steveu@coppice.org> 00009 * 00010 * Copyright (C) 2006 Steve Underwood 00011 * 00012 * All rights reserved. 00013 * 00014 * This program is free software; you can redistribute it and/or modify 00015 * it under the terms of the GNU Lesser General Public License version 2.1, 00016 * as published by the Free Software Foundation. 00017 * 00018 * This program is distributed in the hope that it will be useful, 00019 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00020 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00021 * GNU Lesser General Public License for more details. 00022 * 00023 * You should have received a copy of the GNU Lesser General Public 00024 * License along with this program; if not, write to the Free Software 00025 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. 00026 * 00027 * $Id: modem_connect_tones.h,v 1.24 2009/06/02 16:03:56 steveu Exp $ 00028 */ 00029 00030 /*! \file */ 00031 00032 #if !defined(_SPANDSP_MODEM_CONNECT_TONES_H_) 00033 #define _SPANDSP_MODEM_CONNECT_TONES_H_ 00034 00035 /*! \page modem_connect_tones_page Modem connect tone detection 00036 00037 \section modem_connect_tones_page_sec_1 What does it do? 00038 Some telephony terminal equipment, such as modems, require a channel which is as 00039 clear as possible. They use their own echo cancellation. If the network is also 00040 performing echo cancellation the two cancellors can end up squabbling about the 00041 nature of the channel, with bad results. A special tone is defined which should 00042 cause the network to disable any echo cancellation processes. This is the echo 00043 canceller disable tone. 00044 00045 The tone detector's design assumes the channel is free of any DC component. 00046 00047 \section modem_connect_tones_page_sec_2 How does it work? 00048 A sharp notch filter is implemented as a single bi-quad section. The presence of 00049 the 2100Hz disable tone is detected by comparing the notched filtered energy 00050 with the unfiltered energy. If the notch filtered energy is much lower than the 00051 unfiltered energy, then a large proportion of the energy must be at the notch 00052 frequency. This type of detector may seem less intuitive than using a narrow 00053 bandpass filter to isolate the energy at the notch freqency. However, a sharp 00054 bandpass implemented as an IIR filter rings badly. The reciprocal notch filter 00055 is very well behaved for our purpose. 00056 */ 00057 00058 enum 00059 { 00060 /*! \brief This is reported when a tone stops. */ 00061 MODEM_CONNECT_TONES_NONE = 0, 00062 /*! \brief CNG tone is a pure 1100Hz tone, in 0.5s bursts, with 3s silences in between. The 00063 bursts repeat for as long as is required. */ 00064 MODEM_CONNECT_TONES_FAX_CNG = 1, 00065 /*! \brief ANS tone is a pure continuous 2100Hz+-15Hz tone for 3.3s+-0.7s. */ 00066 MODEM_CONNECT_TONES_ANS = 2, 00067 /*! \brief ANS with phase reversals tone is a 2100Hz+-15Hz tone for 3.3s+-0.7s, with a 180 degree 00068 phase jump every 450ms+-25ms. */ 00069 MODEM_CONNECT_TONES_ANS_PR = 3, 00070 /*! \brief The ANSam tone is a version of ANS with 20% of 15Hz+-0.1Hz AM modulation, as per V.8 */ 00071 MODEM_CONNECT_TONES_ANSAM = 4, 00072 /*! \brief The ANSam with phase reversals tone is a version of ANS_PR with 20% of 15Hz+-0.1Hz AM 00073 modulation, as per V.8 */ 00074 MODEM_CONNECT_TONES_ANSAM_PR = 5, 00075 /*! \brief FAX preamble in a string of V.21 HDLC flag octets. */ 00076 MODEM_CONNECT_TONES_FAX_PREAMBLE = 6, 00077 /*! \brief CED tone is the same as ANS tone. FAX preamble in a string of V.21 HDLC flag octets. 00078 This is only valid as a tone type to receive. It is never reported as a detected tone 00079 type. The report will either be for FAX preamble or CED/ANS tone. */ 00080 MODEM_CONNECT_TONES_FAX_CED_OR_PREAMBLE = 7 00081 }; 00082 00083 /*! \brief FAX CED tone is the same as ANS tone. */ 00084 #define MODEM_CONNECT_TONES_FAX_CED MODEM_CONNECT_TONES_ANS 00085 00086 /*! 00087 Modem connect tones generator descriptor. This defines the state 00088 of a single working instance of the tone generator. 00089 */ 00090 typedef struct modem_connect_tones_tx_state_s modem_connect_tones_tx_state_t; 00091 00092 /*! 00093 Modem connect tones receiver descriptor. This defines the state 00094 of a single working instance of the tone detector. 00095 */ 00096 typedef struct modem_connect_tones_rx_state_s modem_connect_tones_rx_state_t; 00097 00098 #if defined(__cplusplus) 00099 extern "C" 00100 { 00101 #endif 00102 00103 /*! \brief Initialise an instance of the modem connect tones generator. 00104 \param s The context. 00105 */ 00106 SPAN_DECLARE(modem_connect_tones_tx_state_t *) modem_connect_tones_tx_init(modem_connect_tones_tx_state_t *s, 00107 int tone_type); 00108 00109 /*! \brief Release an instance of the modem connect tones generator. 00110 \param s The context. 00111 \return 0 for OK, else -1. 00112 */ 00113 SPAN_DECLARE(int) modem_connect_tones_tx_release(modem_connect_tones_tx_state_t *s); 00114 00115 /*! \brief Free an instance of the modem connect tones generator. 00116 \param s The context. 00117 \return 0 for OK, else -1. 00118 */ 00119 SPAN_DECLARE(int) modem_connect_tones_tx_free(modem_connect_tones_tx_state_t *s); 00120 00121 /*! \brief Generate a block of modem connect tones samples. 00122 \param s The context. 00123 \param amp An array of signal samples. 00124 \param len The number of samples to generate. 00125 \return The number of samples generated. 00126 */ 00127 SPAN_DECLARE_NONSTD(int) modem_connect_tones_tx(modem_connect_tones_tx_state_t *s, 00128 int16_t amp[], 00129 int len); 00130 00131 /*! \brief Process a block of samples through an instance of the modem connect 00132 tones detector. 00133 \param s The context. 00134 \param amp An array of signal samples. 00135 \param len The number of samples in the array. 00136 \return The number of unprocessed samples. 00137 */ 00138 SPAN_DECLARE_NONSTD(int) modem_connect_tones_rx(modem_connect_tones_rx_state_t *s, 00139 const int16_t amp[], 00140 int len); 00141 00142 /*! \brief Test if a modem_connect tone has been detected. 00143 \param s The context. 00144 \return TRUE if tone is detected, else FALSE. 00145 */ 00146 SPAN_DECLARE(int) modem_connect_tones_rx_get(modem_connect_tones_rx_state_t *s); 00147 00148 /*! \brief Initialise an instance of the modem connect tones detector. 00149 \param s The context. 00150 \param tone_type The type of connect tone being tested for. 00151 \param tone_callback An optional callback routine, used to report tones 00152 \param user_data An opaque pointer passed to the callback routine, 00153 \return A pointer to the context. 00154 */ 00155 SPAN_DECLARE(modem_connect_tones_rx_state_t *) modem_connect_tones_rx_init(modem_connect_tones_rx_state_t *s, 00156 int tone_type, 00157 tone_report_func_t tone_callback, 00158 void *user_data); 00159 00160 /*! \brief Release an instance of the modem connect tones detector. 00161 \param s The context. 00162 \return 0 for OK, else -1. */ 00163 SPAN_DECLARE(int) modem_connect_tones_rx_release(modem_connect_tones_rx_state_t *s); 00164 00165 /*! \brief Free an instance of the modem connect tones detector. 00166 \param s The context. 00167 \return 0 for OK, else -1. */ 00168 SPAN_DECLARE(int) modem_connect_tones_rx_free(modem_connect_tones_rx_state_t *s); 00169 00170 SPAN_DECLARE(const char *) modem_connect_tone_to_str(int tone); 00171 00172 #if defined(__cplusplus) 00173 } 00174 #endif 00175 00176 #endif 00177 /*- End of file ------------------------------------------------------------*/