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 - A T.38, less the packet exchange part
00005  *
00006  * Written by Steve Underwood <steveu@coppice.org>
00007  *
00008  * Copyright (C) 2005, 2006, 2007 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.41 2008/03/05 13:38:24 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 /*!
00050     T.38 gateway state.
00051 */
00052 typedef struct
00053 {
00054     /*! Core T.38 support */
00055     t38_core_state_t t38;
00056 
00057     /*! \brief TRUE if ECM FAX mode is allowed through the gateway. */
00058     int ecm_allowed;
00059     /*! \brief Use talker echo protection when transmitting. */
00060     int use_tep;    
00061 
00062     /*! \brief If TRUE, transmit silence when there is nothing else to transmit. If FALSE return only
00063                the actual generated audio. Note that this only affects untimed silences. Timed silences
00064                (e.g. the 75ms silence between V.21 and a high speed modem) will alway be transmitted as
00065                silent audio. */
00066     int transmit_on_idle;
00067 
00068     /*! \brief A bit mask of the currently supported modem types. */
00069     int supported_modems;
00070     
00071     int suppress_nsx;
00072 
00073     /*! \brief The number of pages for which a confirm (MCF) message was returned. */
00074     int pages_confirmed;
00075     /*! \brief HDLC message buffers. */
00076     uint8_t hdlc_buf[T38_TX_HDLC_BUFS][T38_MAX_HDLC_LEN];
00077     /*! \brief HDLC message lengths. */
00078     int hdlc_len[T38_TX_HDLC_BUFS];
00079     /*! \brief HDLC message status flags. */
00080     int hdlc_flags[T38_TX_HDLC_BUFS];
00081     /*! \brief HDLC buffer contents. */
00082     int hdlc_contents[T38_TX_HDLC_BUFS];
00083     /*! \brief HDLC buffer number for input. */
00084     int hdlc_in;
00085     /*! \brief HDLC buffer number for output. */
00086     int hdlc_out;
00087 
00088     /*! \brief Progressively calculated CRC for HDLC messaging received from a modem. */
00089     uint16_t crc;
00090 
00091     /*! \brief non-ECM and HDLC modem receive data buffer */
00092     uint8_t rx_data[T38_RX_BUF_LEN];
00093     int rx_data_ptr;
00094 
00095     /*! \brief non-ECM modem transmit data buffer */
00096     uint8_t non_ecm_tx_data[T38_NON_ECM_TX_BUF_LEN];
00097     int non_ecm_tx_in_ptr;
00098     int non_ecm_tx_out_ptr;
00099 
00100     /*! \brief The location of the most recent EOL marker in the non-ECM data buffer */
00101     int non_ecm_tx_latest_eol_ptr;
00102     unsigned int non_ecm_bit_stream;
00103     /*! \brief The non-ECM flow control fill octet (0xFF before the first data, and 0x00
00104                once data has started). */
00105     uint8_t non_ecm_flow_control_fill_octet;
00106     /*! \brief TRUE if we are in the initial all ones part of non-ECM transmission. */
00107     int non_ecm_at_initial_all_ones;
00108     /*! \brief TRUE is the end of non-ECM data indication has been received. */
00109     int non_ecm_data_finished;
00110     /*! \brief The current octet being sent as non-ECM data. */
00111     unsigned int non_ecm_rx_bit_stream;
00112     unsigned int non_ecm_tx_octet;
00113     /*! \brief The current bit number in the current non-ECM octet. */
00114     int non_ecm_bit_no;
00115     int non_ecm_in_octets;
00116     int non_ecm_out_octets;
00117     int non_ecm_in_rows;
00118     int non_ecm_out_rows;
00119     /*! \brief A count of the number of non-ECM fill octets generated for flow control control
00120                purposes. */
00121     int non_ecm_flow_control_fill_octets;
00122 
00123     /*! \brief the current class of field being received - i.e. none, non-ECM or HDLC */
00124     int current_rx_field_class;
00125     /*! \brief The T.38 indicator currently in use */
00126     int in_progress_rx_indicator;
00127 
00128     /*! \brief The current T.38 data type being sent. */
00129     int current_tx_data_type;
00130 
00131     /*! \brief TRUE if we are in error correcting (ECM) mode */
00132     int ecm_mode;
00133     /*! \brief The current bit rate for the fast modem. */
00134     int fast_bit_rate;
00135     /*! \brief The current fast modem type. */
00136     int fast_modem;
00137     /*! \brief TRUE if between DCS and TCF, and we want the fast image modem to
00138                start in the T.38 data at a predictable time from the end of the
00139                V.21 signal. */
00140     int tcf_mode_predictable_modem_start;
00141     /*! \brief TRUE if a carrier is present. Otherwise FALSE. */
00142     int rx_signal_present;
00143     /*! \brief TRUE if a modem has trained correctly. */
00144     int rx_trained;
00145 
00146     /*! \brief A tone generator context used to generate supervisory tones during
00147                FAX handling. */
00148     tone_gen_state_t tone_gen;
00149     /*! \brief An HDLC context used when receiving HDLC messages. */
00150     hdlc_rx_state_t hdlcrx;
00151 
00152     /*! \brief HDLC data used when transmitting HDLC messages. */
00153     hdlc_tx_state_t hdlctx;
00154 
00155     /*! \brief A V.21 FSK modem context used when transmitting HDLC over V.21
00156                messages. */
00157     fsk_tx_state_t v21_tx;
00158     /*! \brief A V.21 FSK modem context used when receiving HDLC over V.21
00159                messages. */
00160     fsk_rx_state_t v21_rx;
00161 
00162     /*! \brief A V.17 modem context used when sending FAXes at 7200bps, 9600bps
00163                12000bps or 14400bps*/
00164     v17_tx_state_t v17_tx;
00165     /*! \brief A V.29 modem context used when receiving FAXes at 7200bps, 9600bps
00166                12000bps or 14400bps*/
00167     v17_rx_state_t v17_rx;
00168 
00169     /*! \brief A V.29 modem context used when sending FAXes at 7200bps or
00170                9600bps */
00171     v29_tx_state_t v29_tx;
00172     /*! \brief A V.29 modem context used when receiving FAXes at 7200bps or
00173                9600bps */
00174     v29_rx_state_t v29_rx;
00175 
00176     /*! \brief A V.27ter modem context used when sending FAXes at 2400bps or
00177                4800bps */
00178     v27ter_tx_state_t v27ter_tx;
00179     /*! \brief A V.27ter modem context used when receiving FAXes at 2400bps or
00180                4800bps */
00181     v27ter_rx_state_t v27ter_rx;
00182 
00183     /*! \brief */
00184     dc_restore_state_t dc_restore;
00185 
00186     /*! \brief Used to insert timed silences. */
00187     silence_gen_state_t silence_gen;
00188 
00189     /*! \brief The immediately active receive signal handler, which may hop between
00190                rx_handler and dummy_rx(). */
00191     span_rx_handler_t *immediate_rx_handler;
00192     /*! \brief The current receive signal handler */
00193     span_rx_handler_t *rx_handler;
00194     /*! \brief An opaque pointer, passed to rx_handler. */
00195     void *rx_user_data;
00196 
00197     /*! \brief The current transmit signal handler */
00198     span_tx_handler_t *tx_handler;
00199     /*! \brief An opaque pointer, passed to tx_handler. */
00200     void *tx_user_data;
00201     /*! \brief The transmit signal handler to be used when the current one has finished sending. */
00202     span_tx_handler_t *next_tx_handler;
00203     /*! \brief An opaque pointer, passed to next_tx_handler. */
00204     void *next_tx_user_data;
00205 
00206     /*! \brief The number of octets to send in each image packet (non-ECM or ECM) at the current
00207                rate and the current specified packet interval. */
00208     int octets_per_data_packet;
00209 
00210     /*! \brief The type of fast receive modem currently active, which may be T38_NONE */
00211     int fast_rx_active;
00212     /*! \brief The number of samples until the next timeout event */
00213     int samples_to_timeout;
00214     /*! \brief TRUE if in image data mode (as opposed to TCF mode). */
00215     int image_data_mode;
00216     /*! \brief TRUE if in image data modem is to use short training. */
00217     int short_train;
00218 
00219     /*! \brief TRUE if we need to corrupt the HDLC frame in progress, so the receiver cannot
00220                interpret it. */
00221     int corrupt_the_frame_to_t38;
00222     /*! \brief TRUE if we need to corrupt the HDLC frame in progress, so the receiver cannot
00223                interpret it. */
00224     int corrupt_the_frame_from_t38;
00225 
00226     /*! \brief The currently select receiver type */
00227     int current_rx_type;
00228     /*! \brief The currently select transmitter type */
00229     int current_tx_type;
00230 
00231     /*! \brief Audio logging file handles */
00232     int fax_audio_rx_log;
00233     int fax_audio_tx_log;
00234     /*! \brief Error and flow logging control */
00235     logging_state_t logging;
00236 } t38_gateway_state_t;
00237 
00238 typedef struct
00239 {
00240     /*! \brief The current bit rate for image transfer. */
00241     int bit_rate;
00242     /*! \brief TRUE if error correcting mode is used. */
00243     int error_correcting_mode;
00244     /*! \brief The number of pages transferred so far. */
00245     int pages_transferred;
00246 } t38_stats_t;
00247 
00248 #if defined(__cplusplus)
00249 extern "C"
00250 {
00251 #endif
00252 
00253 /*! \brief Initialise a gateway mode T.38 context.
00254     \param s The T.38 context.
00255     \param tx_packet_handler A callback routine to encapsulate and transmit T.38 packets.
00256     \param tx_packet_user_data An opaque pointer passed to the tx_packet_handler routine.
00257     \return A pointer to the termination mode T.38 context, or NULL if there was a problem. */
00258 t38_gateway_state_t *t38_gateway_init(t38_gateway_state_t *s,
00259                                       t38_tx_packet_handler_t *tx_packet_handler,
00260                                       void *tx_packet_user_data);
00261 
00262 /*! Free a gateway mode T.38 context.
00263     \brief Free a T.38 context.
00264     \param s The T.38 context.
00265     \return 0 for OK, else -1. */
00266 int t38_gateway_free(t38_gateway_state_t *s);
00267 
00268 /*! Process a block of received FAX audio samples.
00269     \brief Process a block of received FAX audio samples.
00270     \param s The T.38 context.
00271     \param amp The audio sample buffer.
00272     \param len The number of samples in the buffer.
00273     \return The number of samples unprocessed. */
00274 int t38_gateway_rx(t38_gateway_state_t *s, int16_t amp[], int len);
00275 
00276 /*! Generate a block of FAX audio samples.
00277     \brief Generate a block of FAX audio samples.
00278     \param s The T.38 context.
00279     \param amp The audio sample buffer.
00280     \param max_len The number of samples to be generated.
00281     \return The number of samples actually generated.
00282 */
00283 int t38_gateway_tx(t38_gateway_state_t *s, int16_t amp[], int max_len);
00284 
00285 /*! Control whether error correcting mode (ECM) is allowed.
00286     \brief Control whether error correcting mode (ECM) is allowed.
00287     \param s The T.38 context.
00288     \param ecm_allowed TRUE is ECM is to be allowed.
00289 */
00290 void t38_gateway_set_ecm_capability(t38_gateway_state_t *s, int ecm_allowed);
00291 
00292 /*! Select whether silent audio will be sent when transmit is idle.
00293     \brief Select whether silent audio will be sent when transmit is idle.
00294     \param s The T.38 context.
00295     \param transmit_on_idle TRUE if silent audio should be output when the FAX transmitter is
00296            idle. FALSE to transmit zero length audio when the FAX transmitter is idle. The default
00297            behaviour is FALSE.
00298 */
00299 void t38_gateway_set_transmit_on_idle(t38_gateway_state_t *s, int transmit_on_idle);
00300 
00301 /*! Specify which modem types are supported by a T.30 context.
00302     \brief Specify supported modems.
00303     \param s The T.38 context.
00304     \param supported_modems Bit field list of the supported modems.
00305 */
00306 void t38_gateway_set_supported_modems(t38_gateway_state_t *s, int supported_modems);
00307 
00308 /*! Select whether NSC, NSF, and NSS should be suppressed. It selected, the contents of
00309     these messages are forced to zero for all octets beyond the message type. This makes
00310     them look like manufacturer specific messages, from a manufacturer which does not exist.
00311     \brief Select whether NSC, NSF, and NSS should be suppressed.
00312     \param s The T.38 context.
00313     \param suppress_nsx TRUE if NSC, NSF, and NSS should be suppressed.
00314 */
00315 void t38_gateway_set_nsx_suppression(t38_gateway_state_t *s, int suppress_nsx);
00316 
00317 /*! Select whether talker echo protection tone will be sent for the image modems.
00318     \brief Select whether TEP will be sent for the image modems.
00319     \param s The T.38 context.
00320     \param use_tep TRUE if TEP should be sent.
00321 */
00322 void t38_gateway_set_tep_mode(t38_gateway_state_t *s, int use_tep);
00323 
00324 /*! Get the current transfer statistics for the current T.38 session.
00325     \brief Get the current transfer statistics.
00326     \param s The T.38 context.
00327     \param t A pointer to a buffer for the statistics. */
00328 void t38_gateway_get_transfer_statistics(t38_gateway_state_t *s, t38_stats_t *t);
00329 
00330 #if defined(__cplusplus)
00331 }
00332 #endif
00333 
00334 #endif
00335 /*- End of file ------------------------------------------------------------*/

Generated on Wed Apr 16 02:37:05 2008 for libspandsp by  doxygen 1.5.1