sig_tone.h

Go to the documentation of this file.
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 ------------------------------------------------------------*/

Generated on 29 Jul 2015 for spandsp by  doxygen 1.6.1