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 tones 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 00027 /*! \file */ 00028 00029 /*! \page sig_tone_page The 2280/2400/2600Hz signalling tone processor 00030 \section sig_tone_sec_1 What does it do? 00031 The signalling tone processor handles the 2280Hz, 2400Hz and 2600Hz tones, used 00032 in many analogue signalling procotols, and digital ones derived from them. 00033 00034 \section sig_tone_sec_2 How does it work? 00035 Most single and two voice frequency signalling systems share many features, as these 00036 features have developed in similar ways over time, to address the limitations of 00037 early tone signalling systems. 00038 00039 The usual practice is to start the generation of tone at a high energy level, so a 00040 strong signal is available at the receiver, for crisp tone detection. If the tone 00041 remains on for a significant period, the energy level is reduced, to minimise crosstalk. 00042 During the signalling transitions, only the tone is sent through the channel, and the media 00043 signal is suppressed. This means the signalling receiver has a very clean signal to work with, 00044 allowing for crisp detection of the signalling tone. However, when the signalling tone is on 00045 for extended periods, there may be supervisory information in the media signal, such as voice 00046 announcements. To allow these to pass through the system, the signalling tone is mixed with 00047 the media signal. It is the job of the signalling receiver to separate the signalling tone 00048 and the media. The necessary filtering may degrade the quality of the voice signal, but at 00049 least supervisory information may be heard. 00050 */ 00051 00052 #if !defined(_SPANDSP_SIG_TONE_H_) 00053 #define _SPANDSP_SIG_TONE_H_ 00054 00055 /* The optional tone sets */ 00056 enum 00057 { 00058 /*! European 2280Hz signalling tone. Tone 1 is 2280Hz. Tone 2 is not used. */ 00059 SIG_TONE_2280HZ = 1, 00060 /*! US 2600Hz signalling tone. Tone 1 is 2600Hz. Tone 2 is not used. */ 00061 SIG_TONE_2600HZ, 00062 /*! US 2400Hz + 2600Hz signalling tones. Tone 1 is 2600Hz. Tone 2 is 2400Hz. */ 00063 SIG_TONE_2400HZ_2600HZ 00064 }; 00065 00066 /* Mode control and report bits for transmit and receive */ 00067 enum 00068 { 00069 /*! Signalling tone 1 is present */ 00070 SIG_TONE_1_PRESENT = 0x001, 00071 /*! Signalling tone 1 has changed state (ignored when setting tx mode) */ 00072 SIG_TONE_1_CHANGE = 0x002, 00073 /*! Signalling tone 2 is present */ 00074 SIG_TONE_2_PRESENT = 0x004, 00075 /*! Signalling tone 2 has changed state (ignored when setting tx mode) */ 00076 SIG_TONE_2_CHANGE = 0x008, 00077 /*! The media signal is passing through. Tones might be added to it. */ 00078 SIG_TONE_TX_PASSTHROUGH = 0x010, 00079 /*! The media signal is passing through. Tones might be extracted from it, if detected. */ 00080 SIG_TONE_RX_PASSTHROUGH = 0x040, 00081 /*! Force filtering of the signalling tone, whether signalling is being detected or not. 00082 This is mostly useful for test purposes. */ 00083 SIG_TONE_RX_FILTER_TONE = 0x080, 00084 /*! Request an update of the transmit status, upon timeout of the previous status. */ 00085 SIG_TONE_TX_UPDATE_REQUEST = 0x100, 00086 /*! Request an update of the receiver status, upon timeout of the previous status. */ 00087 SIG_TONE_RX_UPDATE_REQUEST = 0x200 00088 }; 00089 00090 typedef struct sig_tone_tx_state_s sig_tone_tx_state_t; 00091 00092 typedef struct sig_tone_rx_state_s sig_tone_rx_state_t; 00093 00094 #if defined(__cplusplus) 00095 extern "C" 00096 { 00097 #endif 00098 00099 /*! Process a block of received audio samples. 00100 \brief Process a block of received audio samples. 00101 \param s The signalling tone context. 00102 \param amp The audio sample buffer. 00103 \param len The number of samples in the buffer. 00104 \return The number of samples unprocessed. */ 00105 SPAN_DECLARE(int) sig_tone_rx(sig_tone_rx_state_t *s, int16_t amp[], int len); 00106 00107 /*! Set the receive mode. 00108 \brief Set the receive mode. 00109 \param s The signalling tone context. 00110 \param mode The new mode for the receiver. 00111 \param duration The duration for this mode, before an update is requested. 00112 A duration of zero means forever. */ 00113 SPAN_DECLARE(void) sig_tone_rx_set_mode(sig_tone_rx_state_t *s, int mode, int duration); 00114 00115 /*! Initialise a signalling tone receiver context. 00116 \brief Initialise a signalling tone context. 00117 \param s The signalling tone context. 00118 \param tone_type The type of signalling tone. 00119 \param sig_update Callback function to handle signalling updates. 00120 \param user_data An opaque pointer. 00121 \return A pointer to the signalling tone context, or NULL if there was a problem. */ 00122 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); 00123 00124 /*! Release a signalling tone receiver context. 00125 \brief Release a signalling tone receiver context. 00126 \param s The signalling tone context. 00127 \return 0 for OK */ 00128 SPAN_DECLARE(int) sig_tone_rx_release(sig_tone_rx_state_t *s); 00129 00130 /*! Free a signalling tone receiver context. 00131 \brief Free a signalling tone receiver context. 00132 \param s The signalling tone context. 00133 \return 0 for OK */ 00134 SPAN_DECLARE(int) sig_tone_rx_free(sig_tone_rx_state_t *s); 00135 00136 /*! Generate a block of signalling tone audio samples. 00137 \brief Generate a block of signalling tone audio samples. 00138 \param s The signalling tone context. 00139 \param amp The audio sample buffer. 00140 \param len The number of samples to be generated. 00141 \return The number of samples actually generated. */ 00142 SPAN_DECLARE(int) sig_tone_tx(sig_tone_tx_state_t *s, int16_t amp[], int len); 00143 00144 /*! Set the tone mode. 00145 \brief Set the tone mode. 00146 \param s The signalling tone context. 00147 \param mode The new mode for the transmitted tones. 00148 \param duration The duration for this mode, before an update is requested. 00149 A duration of zero means forever. */ 00150 SPAN_DECLARE(void) sig_tone_tx_set_mode(sig_tone_tx_state_t *s, int mode, int duration); 00151 00152 /*! Initialise a signalling tone transmitter context. 00153 \brief Initialise a signalling tone context. 00154 \param s The signalling tone context. 00155 \param tone_type The type of signalling tone. 00156 \param sig_update Callback function to handle signalling updates. 00157 \param user_data An opaque pointer. 00158 \return A pointer to the signalling tone context, or NULL if there was a problem. */ 00159 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); 00160 00161 /*! Release a signalling tone transmitter context. 00162 \brief Release a signalling tone transmitter context. 00163 \param s The signalling tone context. 00164 \return 0 for OK */ 00165 SPAN_DECLARE(int) sig_tone_tx_release(sig_tone_tx_state_t *s); 00166 00167 /*! Free a signalling tone transmitter context. 00168 \brief Free a signalling tone transmitter context. 00169 \param s The signalling tone context. 00170 \return 0 for OK */ 00171 SPAN_DECLARE(int) sig_tone_tx_free(sig_tone_tx_state_t *s); 00172 00173 #if defined(__cplusplus) 00174 } 00175 #endif 00176 00177 #endif 00178 /*- End of file ------------------------------------------------------------*/