t38_gateway.h

Go to the documentation of this file.
00001 /*
00002  * SpanDSP - a series of DSP components for telephony
00003  *
00004  * t38_gateway.h - An implementation of T.38, less the packet exchange part
00005  *
00006  * Written by Steve Underwood <steveu@coppice.org>
00007  *
00008  * Copyright (C) 2005 Steve Underwood
00009  *
00010  * All rights reserved.
00011  *
00012  * This program is free software; you can redistribute it and/or modify
00013  * it under the terms of the GNU General Public License version 2, as
00014  * published by the Free Software Foundation.
00015  *
00016  * This program is distributed in the hope that it will be useful,
00017  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00018  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00019  * GNU General Public License for more details.
00020  *
00021  * You should have received a copy of the GNU General Public License
00022  * along with this program; if not, write to the Free Software
00023  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
00024  *
00025  * $Id: t38_gateway.h,v 1.24 2007/04/05 19:20:50 steveu Exp $
00026  */
00027 
00028 /*! \file */
00029 
00030 #if !defined(_SPANDSP_T38_GATEWAY_H_)
00031 #define _SPANDSP_T38_GATEWAY_H_
00032 
00033 /*! \page t38_gateway_page T.38 real time FAX over IP PSTN gateway
00034 \section t38_gateway_page_sec_1 What does it do?
00035 
00036 The T.38 gateway facility provides a robust interface between T.38 IP packet streams and
00037 and 8k samples/second audio streams. It provides the buffering and flow control features needed
00038 to maximum the tolerance of jitter and packet loss on the IP network.
00039 
00040 \section t38_gateway_page_sec_2 How does it work?
00041 */
00042 
00043 #define T38_RX_BUF_LEN          2048
00044 #define T38_NON_ECM_TX_BUF_LEN  16384
00045 #define T38_TX_HDLC_BUFS        256
00046 /* Make sure the HDLC frame buffers are big enough for ECM frames. */
00047 #define T38_MAX_HDLC_LEN        260
00048 
00049 typedef struct
00050 {
00051     t38_core_state_t t38;
00052     
00053     int ecm_allowed;
00054 
00055     /*! \brief HDLC message buffers. */
00056     uint8_t hdlc_buf[T38_TX_HDLC_BUFS][T38_MAX_HDLC_LEN];
00057     /*! \brief HDLC message lengths. */
00058     int hdlc_len[T38_TX_HDLC_BUFS];
00059     /*! \brief HDLC message status flags. */
00060     int hdlc_flags[T38_TX_HDLC_BUFS];
00061     /*! \brief HDLC buffer contents. */
00062     int hdlc_contents[T38_TX_HDLC_BUFS];
00063     /*! \brief HDLC buffer number for input. */
00064     int hdlc_in;
00065     /*! \brief HDLC buffer number for output. */
00066     int hdlc_out;
00067 
00068     /*! \brief Progressively calculated CRC for HDLC messaging received from a modem. */
00069     uint16_t crc;
00070 
00071     /*! \brief non-ECM and HDLC modem receive data buffer */
00072     uint8_t rx_data[T38_RX_BUF_LEN];
00073     int rx_data_ptr;
00074 
00075     /*! \brief non-ECM modem transmit data buffer */
00076     uint8_t non_ecm_tx_data[T38_NON_ECM_TX_BUF_LEN];
00077     int non_ecm_tx_in_ptr;
00078     int non_ecm_tx_out_ptr;
00079 
00080     /*! \brief The location of the most recent EOL marker in the non-ECM data buffer */
00081     int non_ecm_tx_latest_eol_ptr;
00082     unsigned int bit_stream;
00083     /*! \brief The non-ECM flow control fill octet (0xFF before the first data, and 0x00
00084                once data has started). */
00085     uint8_t non_ecm_flow_control_fill_octet;
00086     /*! \brief TRUE if we are in the initial all ones part of non-ECM transmission. */
00087     int non_ecm_at_initial_all_ones;
00088     /*! \brief TRUE is the end of non-ECM data indication has been received. */
00089     int non_ecm_data_finished;
00090     /*! \brief The current octet being sent as non-ECM data. */
00091     int current_non_ecm_octet;
00092     /*! \brief The current bit number in the current non-ECM octet. */
00093     int non_ecm_bit_no;
00094     /*! \brief A count of the number of non-ECM fill octets generated for flow control control
00095                purposes. */
00096     int non_ecm_flow_control_fill_octets;
00097 
00098     /*! \brief the current class of field being received - i.e. none, non-ECM or HDLC */
00099     int current_rx_field_class;
00100     /*! \brief The T.38 indicator currently in use */
00101     int in_progress_rx_indicator;
00102 
00103     /*! \brief The current T.38 data type being sent. */
00104     int current_tx_data_type;
00105 
00106     /*! \brief TRUE if we are in error correcting (ECM) mode */
00107     int ecm_mode;
00108     /*! \brief The current bit rate for the fast modem. */
00109     int fast_bit_rate;
00110     /*! \brief The current fast modem type. */
00111     int fast_modem;
00112     /*! \brief TRUE if between DCS and TCF */
00113     int tcf_in_progress;
00114     /*! \brief Use talker echo protection when transmitting. */
00115     int use_tep;    
00116     /*! \brief TRUE if a carrier is present. Otherwise FALSE. */
00117     int rx_signal_present;
00118     /*! \brief TRUE if a modem has trained correctly. */
00119     int rx_trained;
00120 
00121     /*! \brief A tone generator context used to generate supervisory tones during
00122                FAX handling. */
00123     tone_gen_state_t tone_gen;
00124     /*! \brief An HDLC context used when receiving HDLC messages. */
00125     hdlc_rx_state_t hdlcrx;
00126 
00127     /*! \brief HDLC data used when transmitting HDLC messages. */
00128     hdlc_tx_state_t hdlctx;
00129 
00130     /*! \brief A V.21 FSK modem context used when transmitting HDLC over V.21
00131                messages. */
00132     fsk_tx_state_t v21tx;
00133     /*! \brief A V.21 FSK modem context used when receiving HDLC over V.21
00134                messages. */
00135     fsk_rx_state_t v21rx;
00136 
00137 #if defined(ENABLE_V17)
00138     /*! \brief A V.17 modem context used when sending FAXes at 7200bps, 9600bps
00139                12000bps or 14400bps*/
00140     v17_tx_state_t v17tx;
00141     /*! \brief A V.29 modem context used when receiving FAXes at 7200bps, 9600bps
00142                12000bps or 14400bps*/
00143     v17_rx_state_t v17rx;
00144 #endif
00145 
00146     /*! \brief A V.29 modem context used when sending FAXes at 7200bps or
00147                9600bps */
00148     v29_tx_state_t v29tx;
00149     /*! \brief A V.29 modem context used when receiving FAXes at 7200bps or
00150                9600bps */
00151     v29_rx_state_t v29rx;
00152 
00153     /*! \brief A V.27ter modem context used when sending FAXes at 2400bps or
00154                4800bps */
00155     v27ter_tx_state_t v27ter_tx;
00156     /*! \brief A V.27ter modem context used when receiving FAXes at 2400bps or
00157                4800bps */
00158     v27ter_rx_state_t v27ter_rx;
00159 
00160     /*! \brief */
00161     dc_restore_state_t dc_restore;
00162 
00163     /*! \brief Used to insert timed silences. */
00164     silence_gen_state_t silence_gen;
00165 
00166     /*! \brief The current receive signal handler */
00167     span_rx_handler_t *rx_handler;
00168     void *rx_user_data;
00169 
00170     /*! \brief The current transmit signal handler */
00171     span_tx_handler_t *tx_handler;
00172     void *tx_user_data;
00173     /*! \brief The transmit signal handler to be used when the current one has finished sending. */
00174     span_tx_handler_t *next_tx_handler;
00175     void *next_tx_user_data;
00176 
00177     /*! \brief The number of octets to send in each image packet (non-ECM or ECM) at the current
00178                rate and the current specified packet interval. */
00179     int octets_per_data_packet;
00180 
00181     /*! \brief The type of fast receive modem currently active, which may be T38_NONE */
00182     int fast_rx_active;
00183     /*! \brief The number of samples until the next timeout event */
00184     int samples_to_timeout;
00185     /*! \brief TRUE is short training is to be used for the fast modem */
00186     int short_train;
00187 
00188     /*! \brief TRUE if we need to corrupt the HDLC frame in progress, so the receiver cannot
00189                interpret it. */
00190     int corrupt_the_frame;
00191     
00192     int current_rx_type;
00193     int current_tx_type;
00194 
00195     logging_state_t logging;
00196 } t38_gateway_state_t;
00197 
00198 #ifdef __cplusplus
00199 extern "C"
00200 {
00201 #endif
00202 
00203 /*! \brief Initialise a gateway mode T.38 context.
00204     \param s The T.38 context.
00205     \param tx_packet_handler A callback routine to encapsulate and transmit T.38 packets.
00206     \param tx_packet_user_data An opaque pointer passed to the tx_packet_handler routine.
00207     \return A pointer to the termination mode T.38 context, or NULL if there was a problem. */
00208 t38_gateway_state_t *t38_gateway_init(t38_gateway_state_t *s,
00209                                       t38_tx_packet_handler_t *tx_packet_handler,
00210                                       void *tx_packet_user_data);
00211 
00212 /*! Process a block of received FAX audio samples.
00213     \brief Process a block of received FAX audio samples.
00214     \param s The T.38 context.
00215     \param amp The audio sample buffer.
00216     \param len The number of samples in the buffer.
00217     \return The number of samples unprocessed. */
00218 int t38_gateway_rx(t38_gateway_state_t *s, int16_t amp[], int len);
00219 
00220 /*! Generate a block of FAX audio samples.
00221     \brief Generate a block of FAX audio samples.
00222     \param s The T.38 context.
00223     \param amp The audio sample buffer.
00224     \param max_len The number of samples to be generated.
00225     \return The number of samples actually generated.
00226 */
00227 int t38_gateway_tx(t38_gateway_state_t *s, int16_t amp[], int max_len);
00228 
00229 /*! Control whether error correcting mode (ECM) is allowed.
00230     \brief Control whether error correcting mode (ECM) is allowed.
00231     \param s The T.38 context.
00232     \param ecm_allowed TRUE is ECM is to be allowed.
00233 */
00234 void t38_gateway_ecm_control(t38_gateway_state_t *s, int ecm_allowed);
00235 
00236 #ifdef __cplusplus
00237 }
00238 #endif
00239 
00240 #endif
00241 /*- End of file ------------------------------------------------------------*/

Generated on Fri Apr 13 13:18:37 2007 for libspandsp by  doxygen 1.5.2