spandsp 0.0.6

sig_tone.h
Go to the documentation of this file.
1/*
2 * SpanDSP - a series of DSP components for telephony
3 *
4 * sig_tone.h - Signalling tone processing for the 2280Hz, 2400Hz, 2600Hz
5 * and similar signalling tones used in older protocols.
6 *
7 * Written by Steve Underwood <steveu@coppice.org>
8 *
9 * Copyright (C) 2004 Steve Underwood
10 *
11 * All rights reserved.
12 *
13 * This program is free software; you can redistribute it and/or modify
14 * it under the terms of the GNU Lesser General Public License version 2.1,
15 * as published by the Free Software Foundation.
16 *
17 * This program is distributed in the hope that it will be useful,
18 * but WITHOUT ANY WARRANTY; without even the implied warranty of
19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 * GNU Lesser General Public License for more details.
21 *
22 * You should have received a copy of the GNU Lesser General Public
23 * License along with this program; if not, write to the Free Software
24 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
25 */
26
27/*! \file */
28
29/*! \page sig_tone_page The 2280/2400/2600Hz signalling tone processor
30\section sig_tone_sec_1 What does it do?
31 The signalling tone processor handles the 2280Hz, 2400Hz and 2600Hz tones, used
32 in many analogue signalling procotols, and digital ones derived from them.
33
34\section sig_tone_sec_2 How does it work?
35 Most single and two voice frequency signalling systems share many features, as these
36 features have developed in similar ways over time, to address the limitations of
37 early tone signalling systems.
38
39 The usual practice is to start the generation of tone at a high energy level, so a
40 strong signal is available at the receiver, for crisp tone detection. If the tone
41 remains on for a significant period, the energy level is reduced, to minimise crosstalk.
42 During the signalling transitions, only the tone is sent through the channel, and the media
43 signal is suppressed. This means the signalling receiver has a very clean signal to work with,
44 allowing for crisp detection of the signalling tone. However, when the signalling tone is on
45 for extended periods, there may be supervisory information in the media signal, such as voice
46 announcements. To allow these to pass through the system, the signalling tone is mixed with
47 the media signal. It is the job of the signalling receiver to separate the signalling tone
48 and the media. The necessary filtering may degrade the quality of the voice signal, but at
49 least supervisory information may be heard.
50*/
51
52#if !defined(_SPANDSP_SIG_TONE_H_)
53#define _SPANDSP_SIG_TONE_H_
54
55/* The optional tone sets */
56 enum
57{
58 /*! European 2280Hz signalling tone. Tone 1 is 2280Hz. Tone 2 is not used. */
59 SIG_TONE_2280HZ = 1,
60 /*! US 2600Hz signalling tone. Tone 1 is 2600Hz. Tone 2 is not used. */
61 SIG_TONE_2600HZ,
62 /*! US 2400Hz + 2600Hz signalling tones. Tone 1 is 2600Hz. Tone 2 is 2400Hz. */
63 SIG_TONE_2400HZ_2600HZ
64};
65
66/* Mode control and report bits for transmit and receive */
67 enum
68{
69 /*! Signalling tone 1 is present */
70 SIG_TONE_1_PRESENT = 0x001,
71 /*! Signalling tone 1 has changed state (ignored when setting tx mode) */
72 SIG_TONE_1_CHANGE = 0x002,
73 /*! Signalling tone 2 is present */
74 SIG_TONE_2_PRESENT = 0x004,
75 /*! Signalling tone 2 has changed state (ignored when setting tx mode) */
76 SIG_TONE_2_CHANGE = 0x008,
77 /*! The media signal is passing through. Tones might be added to it. */
78 SIG_TONE_TX_PASSTHROUGH = 0x010,
79 /*! The media signal is passing through. Tones might be extracted from it, if detected. */
80 SIG_TONE_RX_PASSTHROUGH = 0x040,
81 /*! Force filtering of the signalling tone, whether signalling is being detected or not.
82 This is mostly useful for test purposes. */
83 SIG_TONE_RX_FILTER_TONE = 0x080,
84 /*! Request an update of the transmit status, upon timeout of the previous status. */
85 SIG_TONE_TX_UPDATE_REQUEST = 0x100,
86 /*! Request an update of the receiver status, upon timeout of the previous status. */
87 SIG_TONE_RX_UPDATE_REQUEST = 0x200
88};
89
90 typedef struct sig_tone_tx_state_s sig_tone_tx_state_t;
91
92 typedef struct sig_tone_rx_state_s sig_tone_rx_state_t;
93
94#if defined(__cplusplus)
95 extern "C"
96{
97#endif
98
99/*! Process a block of received audio samples.
100 \brief Process a block of received audio samples.
101 \param s The signalling tone context.
102 \param amp The audio sample buffer.
103 \param len The number of samples in the buffer.
104 \return The number of samples unprocessed. */
105SPAN_DECLARE(int) sig_tone_rx(sig_tone_rx_state_t *s, int16_t amp[], int len);
106
107/*! Set the receive mode.
108 \brief Set the receive mode.
109 \param s The signalling tone context.
110 \param mode The new mode for the receiver.
111 \param duration The duration for this mode, before an update is requested.
112 A duration of zero means forever. */
113SPAN_DECLARE(void) sig_tone_rx_set_mode(sig_tone_rx_state_t *s, int mode, int duration);
114
115/*! Initialise a signalling tone receiver context.
116 \brief Initialise a signalling tone context.
117 \param s The signalling tone context.
118 \param tone_type The type of signalling tone.
119 \param sig_update Callback function to handle signalling updates.
120 \param user_data An opaque pointer.
121 \return A pointer to the signalling tone context, or NULL if there was a problem. */
122SPAN_DECLARE(sig_tone_rx_state_t *) sig_tone_rx_init(sig_tone_rx_state_t *s, int tone_type, tone_report_func_t sig_update, void *user_data);
123
124/*! Release a signalling tone receiver context.
125 \brief Release a signalling tone receiver context.
126 \param s The signalling tone context.
127 \return 0 for OK */
128SPAN_DECLARE(int) sig_tone_rx_release(sig_tone_rx_state_t *s);
129
130/*! Free a signalling tone receiver context.
131 \brief Free a signalling tone receiver context.
132 \param s The signalling tone context.
133 \return 0 for OK */
134SPAN_DECLARE(int) sig_tone_rx_free(sig_tone_rx_state_t *s);
135
136/*! Generate a block of signalling tone audio samples.
137 \brief Generate a block of signalling tone audio samples.
138 \param s The signalling tone context.
139 \param amp The audio sample buffer.
140 \param len The number of samples to be generated.
141 \return The number of samples actually generated. */
142SPAN_DECLARE(int) sig_tone_tx(sig_tone_tx_state_t *s, int16_t amp[], int len);
143
144/*! Set the tone mode.
145 \brief Set the tone mode.
146 \param s The signalling tone context.
147 \param mode The new mode for the transmitted tones.
148 \param duration The duration for this mode, before an update is requested.
149 A duration of zero means forever. */
150SPAN_DECLARE(void) sig_tone_tx_set_mode(sig_tone_tx_state_t *s, int mode, int duration);
151
152/*! Initialise a signalling tone transmitter context.
153 \brief Initialise a signalling tone context.
154 \param s The signalling tone context.
155 \param tone_type The type of signalling tone.
156 \param sig_update Callback function to handle signalling updates.
157 \param user_data An opaque pointer.
158 \return A pointer to the signalling tone context, or NULL if there was a problem. */
159SPAN_DECLARE(sig_tone_tx_state_t *) sig_tone_tx_init(sig_tone_tx_state_t *s, int tone_type, tone_report_func_t sig_update, void *user_data);
160
161/*! Release a signalling tone transmitter context.
162 \brief Release a signalling tone transmitter context.
163 \param s The signalling tone context.
164 \return 0 for OK */
165SPAN_DECLARE(int) sig_tone_tx_release(sig_tone_tx_state_t *s);
166
167/*! Free a signalling tone transmitter context.
168 \brief Free a signalling tone transmitter context.
169 \param s The signalling tone context.
170 \return 0 for OK */
171SPAN_DECLARE(int) sig_tone_tx_free(sig_tone_tx_state_t *s);
172
173#if defined(__cplusplus)
174}
175#endif
176
177#endif
178/*- End of file ------------------------------------------------------------*/
sig_tone_rx_release
int sig_tone_rx_release(sig_tone_rx_state_t *s)
Release a signalling tone receiver context.
Definition sig_tone.c:680
sig_tone_rx_free
int sig_tone_rx_free(sig_tone_rx_state_t *s)
Free a signalling tone receiver context.
Definition sig_tone.c:686
sig_tone_tx_set_mode
void sig_tone_tx_set_mode(sig_tone_tx_state_t *s, int mode, int duration)
Set the tone mode.
Definition sig_tone.c:299
sig_tone_rx_set_mode
void sig_tone_rx_set_mode(sig_tone_rx_state_t *s, int mode, int duration)
Set the receive mode.
Definition sig_tone.c:626
sig_tone_tx_release
int sig_tone_tx_release(sig_tone_tx_state_t *s)
Release a signalling tone transmitter context.
Definition sig_tone.c:352
sig_tone_tx_init
sig_tone_tx_state_t * sig_tone_tx_init(sig_tone_tx_state_t *s, int tone_type, tone_report_func_t sig_update, void *user_data)
Initialise a signalling tone context.
Definition sig_tone.c:319
sig_tone_rx
int sig_tone_rx(sig_tone_rx_state_t *s, int16_t amp[], int len)
Process a block of received audio samples.
Definition sig_tone.c:368
sig_tone_tx
int sig_tone_tx(sig_tone_tx_state_t *s, int16_t amp[], int len)
Generate a block of signalling tone audio samples.
Definition sig_tone.c:222
sig_tone_rx_init
sig_tone_rx_state_t * sig_tone_rx_init(sig_tone_rx_state_t *s, int tone_type, tone_report_func_t sig_update, void *user_data)
Initialise a signalling tone context.
Definition sig_tone.c:632
sig_tone_tx_free
int sig_tone_tx_free(sig_tone_tx_state_t *s)
Free a signalling tone transmitter context.
Definition sig_tone.c:358
SIG_TONE_1_PRESENT
@ SIG_TONE_1_PRESENT
Definition sig_tone.h:70
SIG_TONE_RX_UPDATE_REQUEST
@ SIG_TONE_RX_UPDATE_REQUEST
Definition sig_tone.h:87
SIG_TONE_1_CHANGE
@ SIG_TONE_1_CHANGE
Definition sig_tone.h:72
SIG_TONE_2_CHANGE
@ SIG_TONE_2_CHANGE
Definition sig_tone.h:76
SIG_TONE_TX_PASSTHROUGH
@ SIG_TONE_TX_PASSTHROUGH
Definition sig_tone.h:78
SIG_TONE_TX_UPDATE_REQUEST
@ SIG_TONE_TX_UPDATE_REQUEST
Definition sig_tone.h:85
SIG_TONE_RX_FILTER_TONE
@ SIG_TONE_RX_FILTER_TONE
Definition sig_tone.h:83
SIG_TONE_2_PRESENT
@ SIG_TONE_2_PRESENT
Definition sig_tone.h:74
SIG_TONE_RX_PASSTHROUGH
@ SIG_TONE_RX_PASSTHROUGH
Definition sig_tone.h:80
SIG_TONE_2280HZ
@ SIG_TONE_2280HZ
Definition sig_tone.h:59
SIG_TONE_2400HZ_2600HZ
@ SIG_TONE_2400HZ_2600HZ
Definition sig_tone.h:63
SIG_TONE_2600HZ
@ SIG_TONE_2600HZ
Definition sig_tone.h:61
sig_tone_rx_state_s
Definition private/sig_tone.h:157
sig_tone_rx_state_s::user_data
void * user_data
A user specified opaque pointer passed to the callback function.
Definition private/sig_tone.h:161
sig_tone_rx_state_s::sig_update
tone_report_func_t sig_update
The callback function used to handle signalling changes.
Definition private/sig_tone.h:159
sig_tone_tx_state_s
Definition private/sig_tone.h:126