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.19 2009/04/12 14:18:02 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 typedef int (*sig_tone_func_t)(void *user_data, int what); 00058 00059 /* The optional tone sets */ 00060 enum 00061 { 00062 /*! European 2280Hz signaling tone */ 00063 SIG_TONE_2280HZ = 1, 00064 /*! US 2600Hz signaling tone */ 00065 SIG_TONE_2600HZ, 00066 /*! US 2400Hz + 2600Hz signaling tones */ 00067 SIG_TONE_2400HZ_2600HZ 00068 }; 00069 00070 enum 00071 { 00072 /*! Signaling tone 1 is present */ 00073 SIG_TONE_1_PRESENT = 0x001, 00074 SIG_TONE_1_CHANGE = 0x002, 00075 /*! Signaling tone 2 is present */ 00076 SIG_TONE_2_PRESENT = 0x004, 00077 SIG_TONE_2_CHANGE = 0x008, 00078 /*! The media signal is passing through. Tones might be added to it. */ 00079 SIG_TONE_TX_PASSTHROUGH = 0x010, 00080 /*! The media signal is passing through. Tones might be extracted from it, if detected. */ 00081 SIG_TONE_RX_PASSTHROUGH = 0x020, 00082 SIG_TONE_UPDATE_REQUEST = 0x100 00083 }; 00084 00085 /*! 00086 Signaling tone descriptor. This defines the working state for a 00087 single instance of the transmit and receive sides of a signaling 00088 tone processor. 00089 */ 00090 typedef struct sig_tone_descriptor_s sig_tone_descriptor_t; 00091 00092 typedef struct sig_tone_tx_state_s sig_tone_tx_state_t; 00093 00094 typedef struct sig_tone_rx_state_s sig_tone_rx_state_t; 00095 00096 #if defined(__cplusplus) 00097 extern "C" 00098 { 00099 #endif 00100 00101 /*! Process a block of received audio samples. 00102 \brief Process a block of received audio samples. 00103 \param s The signaling tone context. 00104 \param amp The audio sample buffer. 00105 \param len The number of samples in the buffer. 00106 \return The number of samples unprocessed. */ 00107 SPAN_DECLARE(int) sig_tone_rx(sig_tone_rx_state_t *s, int16_t amp[], int len); 00108 00109 /*! Initialise a signaling tone receiver context. 00110 \brief Initialise a signaling tone context. 00111 \param s The signaling tone context. 00112 \param tone_type The type of signaling tone. 00113 \param sig_update Callback function to handle signaling updates. 00114 \param user_data An opaque pointer. 00115 \return A pointer to the signalling tone context, or NULL if there was a problem. */ 00116 SPAN_DECLARE(sig_tone_rx_state_t *) sig_tone_rx_init(sig_tone_rx_state_t *s, int tone_type, sig_tone_func_t sig_update, void *user_data); 00117 00118 /*! Release a signaling tone receiver context. 00119 \brief Release a signaling tone receiver context. 00120 \param s The signaling tone context. 00121 \return 0 for OK */ 00122 SPAN_DECLARE(int) sig_tone_rx_release(sig_tone_rx_state_t *s); 00123 00124 /*! Free a signaling tone receiver context. 00125 \brief Free a signaling tone receiver context. 00126 \param s The signaling tone context. 00127 \return 0 for OK */ 00128 SPAN_DECLARE(int) sig_tone_rx_free(sig_tone_rx_state_t *s); 00129 00130 /*! Generate a block of signaling tone audio samples. 00131 \brief Generate a block of signaling tone audio samples. 00132 \param s The signaling tone context. 00133 \param amp The audio sample buffer. 00134 \param len The number of samples to be generated. 00135 \return The number of samples actually generated. */ 00136 SPAN_DECLARE(int) sig_tone_tx(sig_tone_tx_state_t *s, int16_t amp[], int len); 00137 00138 /*! Set the tone mode. 00139 \brief Set the tone mode. 00140 \param s The signaling tone context. 00141 \param mode The new mode for the transmitted tones. */ 00142 SPAN_DECLARE(void) sig_tone_tx_set_mode(sig_tone_tx_state_t *s, int mode); 00143 00144 /*! Initialise a signaling tone transmitter context. 00145 \brief Initialise a signaling tone context. 00146 \param s The signaling tone context. 00147 \param tone_type The type of signaling tone. 00148 \param sig_update Callback function to handle signaling updates. 00149 \param user_data An opaque pointer. 00150 \return A pointer to the signalling tone context, or NULL if there was a problem. */ 00151 SPAN_DECLARE(sig_tone_tx_state_t *) sig_tone_tx_init(sig_tone_tx_state_t *s, int tone_type, sig_tone_func_t sig_update, void *user_data); 00152 00153 /*! Release a signaling tone transmitter context. 00154 \brief Release a signaling tone transmitter context. 00155 \param s The signaling tone context. 00156 \return 0 for OK */ 00157 SPAN_DECLARE(int) sig_tone_tx_release(sig_tone_tx_state_t *s); 00158 00159 /*! Free a signaling tone transmitter context. 00160 \brief Free a signaling tone transmitter context. 00161 \param s The signaling tone context. 00162 \return 0 for OK */ 00163 SPAN_DECLARE(int) sig_tone_tx_free(sig_tone_tx_state_t *s); 00164 00165 #if defined(__cplusplus) 00166 } 00167 #endif 00168 00169 #endif 00170 /*- End of file ------------------------------------------------------------*/