spandsp  0.0.6
super_tone_rx.h
1 /*
2  * SpanDSP - a series of DSP components for telephony
3  *
4  * super_tone_rx.h - Flexible telephony supervisory tone detection.
5  *
6  * Written by Steve Underwood <steveu@coppice.org>
7  *
8  * Copyright (C) 2003 Steve Underwood
9  *
10  * All rights reserved.
11  *
12  * This program is free software; you can redistribute it and/or modify
13  * it under the terms of the GNU Lesser General Public License version 2.1,
14  * as published by the Free Software Foundation.
15  *
16  * This program is distributed in the hope that it will be useful,
17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19  * GNU Lesser General Public License for more details.
20  *
21  * You should have received a copy of the GNU Lesser General Public
22  * License along with this program; if not, write to the Free Software
23  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
24  */
25 
26 #if !defined(_SPANDSP_SUPER_TONE_RX_H_)
27 #define _SPANDSP_SUPER_TONE_RX_H_
28 
29 /*! \page super_tone_rx_page Supervisory tone detection
30 
31 \section super_tone_rx_page_sec_1 What does it do?
32 
33 The supervisory tone detector may be configured to detect most of the world's
34 telephone supervisory tones - things like ringback, busy, number unobtainable,
35 and so on.
36 
37 \section super_tone_rx_page_sec_2 How does it work?
38 
39 The supervisory tone detector is passed a series of data structures describing
40 the tone patterns - the frequencies and cadencing - of the tones to be searched
41 for. It constructs one or more Goertzel filters to monitor the required tones.
42 If tones are close in frequency a single Goertzel set to the centre of the
43 frequency range will be used. This optimises the efficiency of the detector. The
44 Goertzel filters are applied without applying any special window functional
45 (i.e. they use a rectangular window), so they have a sinc like response.
46 However, for most tone patterns their rejection qualities are adequate.
47 
48 The detector aims to meet the need of the standard call progress tones, to
49 ITU-T E.180/Q.35 (busy, dial, ringback, reorder). Also, the extended tones,
50 to ITU-T E.180, Supplement 2 and EIA/TIA-464-A (recall dial tone, special
51 ringback tone, intercept tone, call waiting tone, busy verification tone,
52 executive override tone, confirmation tone).
53 */
54 
55 /*! Tone detection indication callback routine */
56 typedef void (*tone_report_func_t)(void *user_data, int code, int level, int delay);
57 
58 typedef void (*tone_segment_func_t)(void *data, int f1, int f2, int duration);
59 
61 
63 
65 
66 #if defined(__cplusplus)
67 extern "C"
68 {
69 #endif
70 
71 /*! Create a new supervisory tone detector descriptor.
72  \param desc The supervisory tone set desciptor. If NULL, the routine will allocate space for a
73  descriptor.
74  \return The supervisory tone set descriptor.
75 */
77 
78 /*! Free a supervisory tone detector descriptor.
79  \param desc The supervisory tone set desciptor.
80  \return 0 for OK, -1 for fail.
81 */
83 
84 /*! Add a new tone pattern to a supervisory tone detector set.
85  \param desc The supervisory tone set descriptor.
86  \return The new tone ID. */
87 SPAN_DECLARE(int) super_tone_rx_add_tone(super_tone_rx_descriptor_t *desc);
88 
89 /*! Add a new tone pattern element to a tone pattern in a supervisory tone detector.
90  \param desc The supervisory tone set desciptor.
91  \param tone The tone ID within the descriptor.
92  \param f1 Frequency 1 (-1 for a silent period).
93  \param f2 Frequency 2 (-1 for a silent period, or only one frequency).
94  \param min The minimum duration, in ms.
95  \param max The maximum duration, in ms.
96  \return The new number of elements in the tone description.
97 */
99  int tone,
100  int f1,
101  int f2,
102  int min,
103  int max);
104 
105 /*! Initialise a supervisory tone detector.
106  \param s The supervisory tone detector context.
107  \param desc The tone descriptor.
108  \param callback The callback routine called to report the valid detection or termination of
109  one of the monitored tones.
110  \param user_data An opaque pointer passed when calling the callback routine.
111  \return The supervisory tone detector context.
112 */
115  tone_report_func_t callback,
116  void *user_data);
117 
118 /*! Release a supervisory tone detector.
119  \param s The supervisory tone context.
120  \return 0 for OK, -1 for fail.
121 */
122 SPAN_DECLARE(int) super_tone_rx_release(super_tone_rx_state_t *s);
123 
124 /*! Free a supervisory tone detector.
125  \param s The supervisory tone context.
126  \return 0 for OK, -1 for fail.
127 */
128 SPAN_DECLARE(int) super_tone_rx_free(super_tone_rx_state_t *s);
129 
130 /*! Define a callback routine to be called to report the valid detection or termination of
131  one of the monitored tones.
132  \param s The supervisory tone context.
133  \param callback The callback routine called to report the valid detection or termination of
134  one of the monitored tones.
135  \param user_data An opaque pointer passed when calling the callback routine.
136 */
138  tone_report_func_t callback,
139  void *user_data);
140 
141 /*! Define a callback routine to be called each time a tone pattern element is complete. This is
142  mostly used when analysing a tone.
143  \param s The supervisory tone context.
144  \param callback The callback routine.
145 */
147  tone_segment_func_t callback);
148 
149 /*! Apply supervisory tone detection processing to a block of audio samples.
150  \brief Apply supervisory tone detection processing to a block of audio samples.
151  \param super The supervisory tone context.
152  \param amp The audio sample buffer.
153  \param samples The number of samples in the buffer.
154  \return The number of samples processed.
155 */
156 SPAN_DECLARE(int) super_tone_rx(super_tone_rx_state_t *super, const int16_t amp[], int samples);
157 
158 /*! Allow for a missing block of samples to a supervisory tone detector.
159  \brief Allow for a missing block of samples to a supervisory tone detector.
160  \param super The supervisory tone context.
161  \param samples The number of samples to allow for.
162  \return The number of samples processed.
163 */
164 SPAN_DECLARE(int) super_tone_rx_fillin(super_tone_rx_state_t *s, int samples);
165 
166 #if defined(__cplusplus)
167 }
168 #endif
169 
170 #endif
171 /*- End of file ------------------------------------------------------------*/
super_tone_rx_descriptor_t * super_tone_rx_make_descriptor(super_tone_rx_descriptor_t *desc)
Definition: super_tone_rx.c:198
Definition: private/super_tone_rx.h:51
void super_tone_rx_segment_callback(super_tone_rx_state_t *s, tone_segment_func_t callback)
Definition: super_tone_rx.c:248
int super_tone_rx_fillin(super_tone_rx_state_t *s, int samples)
Allow for a missing block of samples to a supervisory tone detector.
Definition: super_tone_rx.c:485
int super_tone_rx_add_tone(super_tone_rx_descriptor_t *desc)
Definition: super_tone_rx.c:106
int super_tone_rx_release(super_tone_rx_state_t *s)
Definition: super_tone_rx.c:295
void super_tone_rx_tone_callback(super_tone_rx_state_t *s, tone_report_func_t callback, void *user_data)
Definition: super_tone_rx.c:239
int super_tone_rx(super_tone_rx_state_t *s, const int16_t amp[], int samples)
Apply supervisory tone detection processing to a block of audio samples.
Definition: super_tone_rx.c:445
Definition: private/super_tone_rx.h:31
super_tone_rx_state_t * super_tone_rx_init(super_tone_rx_state_t *s, super_tone_rx_descriptor_t *desc, tone_report_func_t callback, void *user_data)
Definition: super_tone_rx.c:255
int super_tone_rx_free(super_tone_rx_state_t *s)
Definition: super_tone_rx.c:301
Definition: private/super_tone_rx.h:40
int super_tone_rx_add_element(super_tone_rx_descriptor_t *desc, int tone, int f1, int f2, int min, int max)
Definition: super_tone_rx.c:120
int super_tone_rx_free_descriptor(super_tone_rx_descriptor_t *desc)
Definition: super_tone_rx.c:216