Mercurial > hg > audiostuff

comparison spandsp-0.0.6pre17/src/spandsp/modem_connect_tones.h @ 4:26cd8f1ef0b1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
import spandsp-0.0.6pre17
author Peter Meerwald <pmeerw@cosy.sbg.ac.at>
date Fri, 25 Jun 2010 15:50:58 +0200
parents
children
comparison
equal deleted inserted replaced
3:c6c5a16ce2f2 4:26cd8f1ef0b1
1 /*
2 * SpanDSP - a series of DSP components for telephony
3 *
4 * modem_connect_tones.c - Generation and detection of tones
5 * associated with modems calling and
6 * answering calls.
7 *
8 * Written by Steve Underwood <steveu@coppice.org>
9 *
10 * Copyright (C) 2006 Steve Underwood
11 *
12 * All rights reserved.
13 *
14 * This program is free software; you can redistribute it and/or modify
15 * it under the terms of the GNU Lesser General Public License version 2.1,
16 * as published by the Free Software Foundation.
17 *
18 * This program is distributed in the hope that it will be useful,
19 * but WITHOUT ANY WARRANTY; without even the implied warranty of
20 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 * GNU Lesser General Public License for more details.
22 *
23 * You should have received a copy of the GNU Lesser General Public
24 * License along with this program; if not, write to the Free Software
25 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
26 *
27 * $Id: modem_connect_tones.h,v 1.24 2009/06/02 16:03:56 steveu Exp $
28 */
29
30 /*! \file */
31
32 #if !defined(_SPANDSP_MODEM_CONNECT_TONES_H_)
33 #define _SPANDSP_MODEM_CONNECT_TONES_H_
34
35 /*! \page modem_connect_tones_page Modem connect tone detection
36
37 \section modem_connect_tones_page_sec_1 What does it do?
38 Some telephony terminal equipment, such as modems, require a channel which is as
39 clear as possible. They use their own echo cancellation. If the network is also
40 performing echo cancellation the two cancellors can end up squabbling about the
41 nature of the channel, with bad results. A special tone is defined which should
42 cause the network to disable any echo cancellation processes. This is the echo
43 canceller disable tone.
44
45 The tone detector's design assumes the channel is free of any DC component.
46
47 \section modem_connect_tones_page_sec_2 How does it work?
48 A sharp notch filter is implemented as a single bi-quad section. The presence of
49 the 2100Hz disable tone is detected by comparing the notched filtered energy
50 with the unfiltered energy. If the notch filtered energy is much lower than the
51 unfiltered energy, then a large proportion of the energy must be at the notch
52 frequency. This type of detector may seem less intuitive than using a narrow
53 bandpass filter to isolate the energy at the notch freqency. However, a sharp
54 bandpass implemented as an IIR filter rings badly. The reciprocal notch filter
55 is very well behaved for our purpose.
56 */
57
58 enum
59 {
60 /*! \brief This is reported when a tone stops. */
61 MODEM_CONNECT_TONES_NONE = 0,
62 /*! \brief CNG tone is a pure 1100Hz tone, in 0.5s bursts, with 3s silences in between. The
63 bursts repeat for as long as is required. */
64 MODEM_CONNECT_TONES_FAX_CNG = 1,
65 /*! \brief ANS tone is a pure continuous 2100Hz+-15Hz tone for 3.3s+-0.7s. */
66 MODEM_CONNECT_TONES_ANS = 2,
67 /*! \brief ANS with phase reversals tone is a 2100Hz+-15Hz tone for 3.3s+-0.7s, with a 180 degree
68 phase jump every 450ms+-25ms. */
69 MODEM_CONNECT_TONES_ANS_PR = 3,
70 /*! \brief The ANSam tone is a version of ANS with 20% of 15Hz+-0.1Hz AM modulation, as per V.8 */
71 MODEM_CONNECT_TONES_ANSAM = 4,
72 /*! \brief The ANSam with phase reversals tone is a version of ANS_PR with 20% of 15Hz+-0.1Hz AM
73 modulation, as per V.8 */
74 MODEM_CONNECT_TONES_ANSAM_PR = 5,
75 /*! \brief FAX preamble in a string of V.21 HDLC flag octets. */
76 MODEM_CONNECT_TONES_FAX_PREAMBLE = 6,
77 /*! \brief CED tone is the same as ANS tone. FAX preamble in a string of V.21 HDLC flag octets.
78 This is only valid as a tone type to receive. It is never reported as a detected tone
79 type. The report will either be for FAX preamble or CED/ANS tone. */
80 MODEM_CONNECT_TONES_FAX_CED_OR_PREAMBLE = 7
81 };
82
83 /*! \brief FAX CED tone is the same as ANS tone. */
84 #define MODEM_CONNECT_TONES_FAX_CED MODEM_CONNECT_TONES_ANS
85
86 /*!
87 Modem connect tones generator descriptor. This defines the state
88 of a single working instance of the tone generator.
89 */
90 typedef struct modem_connect_tones_tx_state_s modem_connect_tones_tx_state_t;
91
92 /*!
93 Modem connect tones receiver descriptor. This defines the state
94 of a single working instance of the tone detector.
95 */
96 typedef struct modem_connect_tones_rx_state_s modem_connect_tones_rx_state_t;
97
98 #if defined(__cplusplus)
99 extern "C"
100 {
101 #endif
102
103 /*! \brief Initialise an instance of the modem connect tones generator.
104 \param s The context.
105 */
106 SPAN_DECLARE(modem_connect_tones_tx_state_t *) modem_connect_tones_tx_init(modem_connect_tones_tx_state_t *s,
107 int tone_type);
108
109 /*! \brief Release an instance of the modem connect tones generator.
110 \param s The context.
111 \return 0 for OK, else -1.
112 */
113 SPAN_DECLARE(int) modem_connect_tones_tx_release(modem_connect_tones_tx_state_t *s);
114
115 /*! \brief Free an instance of the modem connect tones generator.
116 \param s The context.
117 \return 0 for OK, else -1.
118 */
119 SPAN_DECLARE(int) modem_connect_tones_tx_free(modem_connect_tones_tx_state_t *s);
120
121 /*! \brief Generate a block of modem connect tones samples.
122 \param s The context.
123 \param amp An array of signal samples.
124 \param len The number of samples to generate.
125 \return The number of samples generated.
126 */
127 SPAN_DECLARE_NONSTD(int) modem_connect_tones_tx(modem_connect_tones_tx_state_t *s,
128 int16_t amp[],
129 int len);
130
131 /*! \brief Process a block of samples through an instance of the modem connect
132 tones detector.
133 \param s The context.
134 \param amp An array of signal samples.
135 \param len The number of samples in the array.
136 \return The number of unprocessed samples.
137 */
138 SPAN_DECLARE_NONSTD(int) modem_connect_tones_rx(modem_connect_tones_rx_state_t *s,
139 const int16_t amp[],
140 int len);
141
142 /*! \brief Test if a modem_connect tone has been detected.
143 \param s The context.
144 \return TRUE if tone is detected, else FALSE.
145 */
146 SPAN_DECLARE(int) modem_connect_tones_rx_get(modem_connect_tones_rx_state_t *s);
147
148 /*! \brief Initialise an instance of the modem connect tones detector.
149 \param s The context.
150 \param tone_type The type of connect tone being tested for.
151 \param tone_callback An optional callback routine, used to report tones
152 \param user_data An opaque pointer passed to the callback routine,
153 \return A pointer to the context.
154 */
155 SPAN_DECLARE(modem_connect_tones_rx_state_t *) modem_connect_tones_rx_init(modem_connect_tones_rx_state_t *s,
156 int tone_type,
157 tone_report_func_t tone_callback,
158 void *user_data);
159
160 /*! \brief Release an instance of the modem connect tones detector.
161 \param s The context.
162 \return 0 for OK, else -1. */
163 SPAN_DECLARE(int) modem_connect_tones_rx_release(modem_connect_tones_rx_state_t *s);
164
165 /*! \brief Free an instance of the modem connect tones detector.
166 \param s The context.
167 \return 0 for OK, else -1. */
168 SPAN_DECLARE(int) modem_connect_tones_rx_free(modem_connect_tones_rx_state_t *s);
169
170 SPAN_DECLARE(const char *) modem_connect_tone_to_str(int tone);
171
172 #if defined(__cplusplus)
173 }
174 #endif
175
176 #endif
177 /*- End of file ------------------------------------------------------------*/

Repositories maintained by Peter Meerwald, pmeerw@pmeerw.net.