modem_connect_tones.h

Go to the documentation of this file.
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.22 2009/02/10 13:06:47 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. This is only valid as a result of tone
00076                detection. It should not be specified as a tone type to transmit or receive. */
00077     MODEM_CONNECT_TONES_FAX_PREAMBLE = 6,
00078     /*! \brief CED tone is the same as ANS tone. FAX preamble in a string of V.21 HDLC flag octets.
00079                This is only valid as a tone type to receive. It is never reported as a detected tone
00080                type. The report will either be for FAX preamble or CED/ANS tone. */
00081     MODEM_CONNECT_TONES_FAX_CED_OR_PREAMBLE = 7
00082 };
00083 
00084 /*! \brief FAX CED tone is the same as ANS tone. */
00085 #define MODEM_CONNECT_TONES_FAX_CED MODEM_CONNECT_TONES_ANS
00086 
00087 /*!
00088     Modem connect tones generator descriptor. This defines the state
00089     of a single working instance of the tone generator.
00090 */
00091 typedef struct modem_connect_tones_tx_state_s modem_connect_tones_tx_state_t;
00092 
00093 /*!
00094     Modem connect tones receiver descriptor. This defines the state
00095     of a single working instance of the tone detector.
00096 */
00097 typedef struct modem_connect_tones_rx_state_s modem_connect_tones_rx_state_t;
00098 
00099 #if defined(__cplusplus)
00100 extern "C"
00101 {
00102 #endif
00103 
00104 /*! \brief Initialise an instance of the modem connect tones generator.
00105     \param s The context.
00106 */
00107 SPAN_DECLARE(modem_connect_tones_tx_state_t *) modem_connect_tones_tx_init(modem_connect_tones_tx_state_t *s,
00108                                                                            int tone_type);
00109 
00110 /*! \brief Release an instance of the modem connect tones generator.
00111     \param s The context.
00112     \return 0 for OK, else -1.
00113 */
00114 SPAN_DECLARE(int) modem_connect_tones_tx_release(modem_connect_tones_tx_state_t *s);
00115 
00116 /*! \brief Free an instance of the modem connect tones generator.
00117     \param s The context.
00118     \return 0 for OK, else -1.
00119 */
00120 SPAN_DECLARE(int) modem_connect_tones_tx_free(modem_connect_tones_tx_state_t *s);
00121 
00122 /*! \brief Generate a block of modem connect tones samples.
00123     \param s The context.
00124     \param amp An array of signal samples.
00125     \param len The number of samples to generate.
00126     \return The number of samples generated.
00127 */
00128 SPAN_DECLARE(int) modem_connect_tones_tx(modem_connect_tones_tx_state_t *s,
00129                                          int16_t amp[],
00130                                          int len);
00131 
00132 /*! \brief Process a block of samples through an instance of the modem connect
00133            tones detector.
00134     \param s The context.
00135     \param amp An array of signal samples.
00136     \param len The number of samples in the array.
00137     \return The number of unprocessed samples.
00138 */
00139 SPAN_DECLARE(int) modem_connect_tones_rx(modem_connect_tones_rx_state_t *s,
00140                                          const int16_t amp[],
00141                                          int len);
00142                              
00143 /*! \brief Test if a modem_connect tone has been detected.
00144     \param s The context.
00145     \return TRUE if tone is detected, else FALSE.
00146 */
00147 SPAN_DECLARE(int) modem_connect_tones_rx_get(modem_connect_tones_rx_state_t *s);
00148 
00149 /*! \brief Initialise an instance of the modem connect tones detector.
00150     \param s The context.
00151     \param tone_type The type of connect tone being tested for.
00152     \param tone_callback An optional callback routine, used to report tones
00153     \param user_data An opaque pointer passed to the callback routine,
00154     \return A pointer to the context.
00155 */
00156 SPAN_DECLARE(modem_connect_tones_rx_state_t *) modem_connect_tones_rx_init(modem_connect_tones_rx_state_t *s,
00157                                                                            int tone_type,
00158                                                                            tone_report_func_t tone_callback,
00159                                                                            void *user_data);
00160 
00161 /*! \brief Release an instance of the modem connect tones detector.
00162     \param s The context.
00163     \return 0 for OK, else -1. */
00164 SPAN_DECLARE(int) modem_connect_tones_rx_release(modem_connect_tones_rx_state_t *s);
00165 
00166 /*! \brief Free an instance of the modem connect tones detector.
00167     \param s The context.
00168     \return 0 for OK, else -1. */
00169 SPAN_DECLARE(int) modem_connect_tones_rx_free(modem_connect_tones_rx_state_t *s);
00170 
00171 SPAN_DECLARE(const char *) modem_connect_tone_to_str(int tone);
00172 
00173 #if defined(__cplusplus)
00174 }
00175 #endif
00176 
00177 #endif
00178 /*- End of file ------------------------------------------------------------*/

Generated on Tue Aug 4 03:36:01 2009 for spandsp by  doxygen 1.5.9