spandsp 0.0.6
|
00001 /* 00002 * SpanDSP - a series of DSP components for telephony 00003 * 00004 * sig_tone.h - Signalling tone processing for the 2280Hz, 2400Hz, 2600Hz 00005 * and similar signalling tone used in older protocols. 00006 * 00007 * Written by Steve Underwood <steveu@coppice.org> 00008 * 00009 * Copyright (C) 2004 Steve Underwood 00010 * 00011 * All rights reserved. 00012 * 00013 * This program is free software; you can redistribute it and/or modify 00014 * it under the terms of the GNU Lesser General Public License version 2.1, 00015 * as published by the Free Software Foundation. 00016 * 00017 * This program is distributed in the hope that it will be useful, 00018 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00019 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00020 * GNU Lesser General Public License for more details. 00021 * 00022 * You should have received a copy of the GNU Lesser General Public 00023 * License along with this program; if not, write to the Free Software 00024 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. 00025 * 00026 * $Id: sig_tone.h,v 1.20 2009/09/04 14:38:46 steveu Exp $ 00027 */ 00028 00029 /*! \file */ 00030 00031 /*! \page sig_tone_page The signaling tone processor 00032 \section sig_tone_sec_1 What does it do? 00033 The signaling tone processor handles the 2280Hz, 2400Hz and 2600Hz tones, used 00034 in many analogue signaling procotols, and digital ones derived from them. 00035 00036 \section sig_tone_sec_2 How does it work? 00037 Most single and two voice frequency signalling systems share many features, as these 00038 features have developed in similar ways over time, to address the limitations of 00039 early tone signalling systems. 00040 00041 The usual practice is to start the generation of tone at a high energy level, so a 00042 strong signal is available at the receiver, for crisp tone detection. If the tone 00043 remains on for a significant period, the energy level is reduced, to minimise crosstalk. 00044 During the signalling transitions, only the tone is sent through the channel, and the media 00045 signal is suppressed. This means the signalling receiver has a very clean signal to work with, 00046 allowing for crisp detection of the signalling tone. However, when the signalling tone is on 00047 for extended periods, there may be supervisory information in the media signal, such as voice 00048 announcements. To allow these to pass through the system, the signalling tone is mixed with 00049 the media signal. It is the job of the signalling receiver to separate the signalling tone 00050 and the media. The necessary filtering may degrade the quality of the voice signal, but at 00051 least supervisory information may be heard. 00052 */ 00053 00054 #if !defined(_SPANDSP_SIG_TONE_H_) 00055 #define _SPANDSP_SIG_TONE_H_ 00056 00057 /* The optional tone sets */ 00058 enum 00059 { 00060 /*! European 2280Hz signaling tone. Tone 1 is 2280Hz. Tone 2 is not used. */ 00061 SIG_TONE_2280HZ = 1, 00062 /*! US 2600Hz signaling tone. Tone 1 is 2600Hz. Tone 2 is not used. */ 00063 SIG_TONE_2600HZ, 00064 /*! US 2400Hz + 2600Hz signaling tones. Tone 1 is 2600Hz. Tone 2 is 2400Hz. */ 00065 SIG_TONE_2400HZ_2600HZ 00066 }; 00067 00068 /* Mode control and report bits for transmit and receive */ 00069 enum 00070 { 00071 /*! Signaling tone 1 is present */ 00072 SIG_TONE_1_PRESENT = 0x001, 00073 /*! Signaling tone 1 has changed state (ignored when setting tx mode) */ 00074 SIG_TONE_1_CHANGE = 0x002, 00075 /*! Signaling tone 2 is present */ 00076 SIG_TONE_2_PRESENT = 0x004, 00077 /*! Signaling tone 2 has changed state (ignored when setting tx mode) */ 00078 SIG_TONE_2_CHANGE = 0x008, 00079 /*! The media signal is passing through. Tones might be added to it. */ 00080 SIG_TONE_TX_PASSTHROUGH = 0x010, 00081 /*! The media signal is passing through. Tones might be extracted from it, if detected. */ 00082 SIG_TONE_RX_PASSTHROUGH = 0x040, 00083 /*! Force filtering of the signaling tone, whether signaling is being detected or not. 00084 This is mostly useful for test purposes. */ 00085 SIG_TONE_RX_FILTER_TONE = 0x080, 00086 /*! Request an update of the transmit status, upon timeout of the previous status. */ 00087 SIG_TONE_TX_UPDATE_REQUEST = 0x100, 00088 /*! Request an update of the receiver status, upon timeout of the previous status. */ 00089 SIG_TONE_RX_UPDATE_REQUEST = 0x200 00090 }; 00091 00092 /*! 00093 Signaling tone descriptor. This defines the working state for a 00094 single instance of the transmit and receive sides of a signaling 00095 tone processor. 00096 */ 00097 typedef struct sig_tone_descriptor_s sig_tone_descriptor_t; 00098 00099 typedef struct sig_tone_tx_state_s sig_tone_tx_state_t; 00100 00101 typedef struct sig_tone_rx_state_s sig_tone_rx_state_t; 00102 00103 #if defined(__cplusplus) 00104 extern "C" 00105 { 00106 #endif 00107 00108 /*! Process a block of received audio samples. 00109 \brief Process a block of received audio samples. 00110 \param s The signaling tone context. 00111 \param amp The audio sample buffer. 00112 \param len The number of samples in the buffer. 00113 \return The number of samples unprocessed. */ 00114 SPAN_DECLARE(int) sig_tone_rx(sig_tone_rx_state_t *s, int16_t amp[], int len); 00115 00116 /*! Set the receive mode. 00117 \brief Set the receive mode. 00118 \param s The signaling tone context. 00119 \param mode The new mode for the receiver. 00120 \param duration The duration for this mode, before an update is requested. 00121 A duration of zero means forever. */ 00122 SPAN_DECLARE(void) sig_tone_rx_set_mode(sig_tone_rx_state_t *s, int mode, int duration); 00123 00124 /*! Initialise a signaling tone receiver context. 00125 \brief Initialise a signaling tone context. 00126 \param s The signaling tone context. 00127 \param tone_type The type of signaling tone. 00128 \param sig_update Callback function to handle signaling updates. 00129 \param user_data An opaque pointer. 00130 \return A pointer to the signalling tone context, or NULL if there was a problem. */ 00131 SPAN_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); 00132 00133 /*! Release a signaling tone receiver context. 00134 \brief Release a signaling tone receiver context. 00135 \param s The signaling tone context. 00136 \return 0 for OK */ 00137 SPAN_DECLARE(int) sig_tone_rx_release(sig_tone_rx_state_t *s); 00138 00139 /*! Free a signaling tone receiver context. 00140 \brief Free a signaling tone receiver context. 00141 \param s The signaling tone context. 00142 \return 0 for OK */ 00143 SPAN_DECLARE(int) sig_tone_rx_free(sig_tone_rx_state_t *s); 00144 00145 /*! Generate a block of signaling tone audio samples. 00146 \brief Generate a block of signaling tone audio samples. 00147 \param s The signaling tone context. 00148 \param amp The audio sample buffer. 00149 \param len The number of samples to be generated. 00150 \return The number of samples actually generated. */ 00151 SPAN_DECLARE(int) sig_tone_tx(sig_tone_tx_state_t *s, int16_t amp[], int len); 00152 00153 /*! Set the tone mode. 00154 \brief Set the tone mode. 00155 \param s The signaling tone context. 00156 \param mode The new mode for the transmitted tones. 00157 \param duration The duration for this mode, before an update is requested. 00158 A duration of zero means forever. */ 00159 SPAN_DECLARE(void) sig_tone_tx_set_mode(sig_tone_tx_state_t *s, int mode, int duration); 00160 00161 /*! Initialise a signaling tone transmitter context. 00162 \brief Initialise a signaling tone context. 00163 \param s The signaling tone context. 00164 \param tone_type The type of signaling tone. 00165 \param sig_update Callback function to handle signaling updates. 00166 \param user_data An opaque pointer. 00167 \return A pointer to the signalling tone context, or NULL if there was a problem. */ 00168 SPAN_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); 00169 00170 /*! Release a signaling tone transmitter context. 00171 \brief Release a signaling tone transmitter context. 00172 \param s The signaling tone context. 00173 \return 0 for OK */ 00174 SPAN_DECLARE(int) sig_tone_tx_release(sig_tone_tx_state_t *s); 00175 00176 /*! Free a signaling tone transmitter context. 00177 \brief Free a signaling tone transmitter context. 00178 \param s The signaling tone context. 00179 \return 0 for OK */ 00180 SPAN_DECLARE(int) sig_tone_tx_free(sig_tone_tx_state_t *s); 00181 00182 #if defined(__cplusplus) 00183 } 00184 #endif 00185 00186 #endif 00187 /*- End of file ------------------------------------------------------------*/