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 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 ------------------------------------------------------------*/

Generated by  doxygen 1.6.2