t30.h

Go to the documentation of this file.
00001 /*
00002  * SpanDSP - a series of DSP components for telephony
00003  *
00004  * t30.h - definitions for T.30 fax processing
00005  *
00006  * Written by Steve Underwood <steveu@coppice.org>
00007  *
00008  * Copyright (C) 2003 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 Lesser General Public License version 2.1,
00014  * as 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 Lesser General Public License for more details.
00020  *
00021  * You should have received a copy of the GNU Lesser General Public
00022  * License along with this program; if not, write to the Free Software
00023  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
00024  *
00025  * $Id: t30.h,v 1.106 2008/05/05 12:42:06 steveu Exp $
00026  */
00027 
00028 /*! \file */
00029 
00030 #if !defined(_SPANDSP_T30_H_)
00031 #define _SPANDSP_T30_H_
00032 
00033 /*! \page t30_page T.30 FAX protocol handling
00034 
00035 \section t30_page_sec_1 What does it do?
00036 The T.30 protocol is the core protocol used for FAX transmission. This module
00037 implements most of its key featrues. It does not interface to the outside work.
00038 Seperate modules do that for T.38, analogue line, and other forms of FAX
00039 communication.
00040 
00041 Current features of this module include:
00042 
00043     - FAXing to and from multi-page TIFF/F files, whose images are one of the standard
00044       FAX sizes.
00045     - T.4 1D (MH), T.4 2D,(MR) and T.6 (MMR) compression.
00046     - Error correction (ECM)
00047     - All standard resolutions and page sizes
00048 
00049 \section t30_page_sec_2 How does it work?
00050 
00051 Some of the following is paraphrased from some notes found a while ago on the Internet.
00052 I cannot remember exactly where they came from, but they are useful.
00053 
00054 The answer (CED) tone
00055 
00056 The T.30 standard says an answering fax device must send CED (a 2100Hz tone) for
00057 approximately 3 seconds before sending the first handshake message. Some machines
00058 send an 1100Hz or 1850Hz tone, and some send no tone at all. In fact, this answer
00059 tone is so unpredictable, it cannot really be used. It should, however, always be
00060 generated according to the specification.
00061 
00062 Common Timing Deviations
00063 
00064 The T.30 spec. specifies a number of time-outs. For example, after dialing a number,
00065 a calling fax system should listen for a response for 35 seconds before giving up.
00066 These time-out periods are as follows: 
00067 
00068     * T1 - 35+-5s: the maximum time for which two fax system will attempt to identify each other
00069     * T2 - 6+-1s:  a time-out used to start the sequence for changing transmit parameters
00070     * T3 - 10+-5s: a time-out used in handling operator interrupts
00071     * T5 - 60+-5s: a time-out used in error correction mode
00072 
00073 These time-outs are sometimes misinterpreted. In addition, they are routinely
00074 ignored, sometimes with good reason. For example, after placing a call, the
00075 calling fax system is supposed to wait for 35 seconds before giving up. If the
00076 answering unit does not answer on the first ring or if a voice answering machine
00077 is connected to the line, or if there are many delays through the network,
00078 the delay before answer can be much longer than 35 seconds. 
00079 
00080 Fax units that support error correction mode (ECM) can respond to a post-image
00081 handshake message with a receiver not ready (RNR) message. The calling unit then
00082 queries the receiving fax unit with a receiver ready (RR) message. If the
00083 answering unit is still busy (printing for example), it will repeat the RNR
00084 message. According to the T.30 standard, this sequence (RR/RNR RR/RNR) can be
00085 repeated for up to the end of T5 (60+-5s). However, many fax systems
00086 ignore the time-out and will continue the sequence indefinitely, unless the user
00087 manually overrides. 
00088 
00089 All the time-outs are subject to alteration, and sometimes misuse. Good T.30
00090 implementations must do the right thing, and tolerate others doing the wrong thing.
00091  
00092 Variations in the inter-carrier gap
00093 
00094 T.30 specifies 75+-20ms of silence between signals using different modulation
00095 schemes. Examples are between the end of a DCS signal and the start of a TCF signal,
00096 and between the end of an image and the start of a post-image signal. Many fax systems
00097 violate this requirement, especially for the silent period between DCS and TCF.
00098 This may be stretched to well over 100ms. If this period is too long, it can interfere with
00099 handshake signal error recovery, should a packet be corrupted on the line. Systems
00100 should ensure they stay within the prescribed T.30 limits, and be tolerant of others
00101 being out of spec.. 
00102 
00103 Other timing variations
00104 
00105 Testing is required to determine the ability of a fax system to handle
00106 variations in the duration of pauses between unacknowledged handshake message
00107 repetitions, and also in the pauses between the receipt of a handshake command and
00108 the start of a response to that command. In order to reduce the total
00109 transmission time, many fax systems start sending a response message before the
00110 end of the command has been received. 
00111 
00112 Other deviations from the T.30 standard
00113 
00114 There are many other commonly encountered variations between machines, including:
00115 
00116     * frame sequence deviations
00117     * preamble and flag sequence variations
00118     * improper EOM usage
00119     * unusual data rate fallback sequences
00120     * common training pattern detection algorithms
00121     * image transmission deviations
00122     * use of the talker echo protect tone
00123     * image padding and short lines
00124     * RTP/RTN handshake message usage
00125     * long duration lines
00126     * nonstandard disconnect sequences
00127     * DCN usage
00128 */
00129 
00130 #define T30_MAX_DIS_DTC_DCS_LEN     22
00131 #define T30_MAX_IDENT_LEN           20
00132 #define T30_MAX_PAGE_HEADER_INFO    50
00133 
00134 typedef struct t30_state_s t30_state_t;
00135 
00136 /*!
00137     T.30 phase B callback handler. This handler can be used to process addition
00138     information available in some FAX calls, such as passwords. The callback handler
00139     can access whatever additional information might have been received, using
00140     t30_get_received_info().
00141     \brief T.30 phase B callback handler.
00142     \param s The T.30 context.
00143     \param user_data An opaque pointer.
00144     \param result The phase B event code.
00145     \return The new status. Normally, T30_ERR_OK is returned.
00146 */
00147 typedef int (t30_phase_b_handler_t)(t30_state_t *s, void *user_data, int result);
00148 
00149 /*!
00150     T.30 phase D callback handler.
00151     \brief T.30 phase D callback handler.
00152     \param s The T.30 context.
00153     \param user_data An opaque pointer.
00154     \param result The phase D event code.
00155     \return The new status. Normally, T30_ERR_OK is returned.
00156 */
00157 typedef int (t30_phase_d_handler_t)(t30_state_t *s, void *user_data, int result);
00158 
00159 /*!
00160     T.30 phase E callback handler.
00161     \brief T.30 phase E callback handler.
00162     \param s The T.30 context.
00163     \param user_data An opaque pointer.
00164     \param completion_code The phase E completion code.
00165 */
00166 typedef void (t30_phase_e_handler_t)(t30_state_t *s, void *user_data, int completion_code);
00167 
00168 /*!
00169     T.30 document handler.
00170     \brief T.30 document handler.
00171     \param s The T.30 context.
00172     \param user_data An opaque pointer.
00173     \param result The document event code.
00174 */
00175 typedef int (t30_document_handler_t)(t30_state_t *s, void *user_data, int status);
00176 
00177 /*!
00178     T.30 set a receive or transmit type handler.
00179     \brief T.30 set a receive or transmit type handler.
00180     \param user_data An opaque pointer.
00181     \param type The modem, tone or silence to be sent or received.
00182     \param short_train TRUE if the short training sequence should be used (where one exists).
00183     \param use_hdlc FALSE for bit stream, TRUE for HDLC framing.
00184 */
00185 typedef void (t30_set_handler_t)(void *user_data, int type, int short_train, int use_hdlc);
00186 
00187 /*!
00188     T.30 send HDLC handler.
00189     \brief T.30 send HDLC handler.
00190     \param user_data An opaque pointer.
00191     \param msg The HDLC message.
00192     \param len The length of the message.
00193 */
00194 typedef void (t30_send_hdlc_handler_t)(void *user_data, const uint8_t *msg, int len);
00195 
00196 /*!
00197     T.30 protocol completion codes, at phase E.
00198 */
00199 enum
00200 {
00201     T30_ERR_OK = 0,             /*! OK */
00202 
00203     /* Link problems */
00204     T30_ERR_CEDTONE,            /*! The CED tone exceeded 5s */
00205     T30_ERR_T0_EXPIRED,         /*! Timed out waiting for initial communication */
00206     T30_ERR_T1_EXPIRED,         /*! Timed out waiting for the first message */
00207     T30_ERR_T3_EXPIRED,         /*! Timed out waiting for procedural interrupt */
00208     T30_ERR_HDLC_CARRIER,       /*! The HDLC carrier did not stop in a timely manner */
00209     T30_ERR_CANNOT_TRAIN,       /*! Failed to train with any of the compatible modems */
00210     T30_ERR_OPER_INT_FAIL,      /*! Operator intervention failed */
00211     T30_ERR_INCOMPATIBLE,       /*! Far end is not compatible */
00212     T30_ERR_RX_INCAPABLE,       /*! Far end is not able to receive */
00213     T30_ERR_TX_INCAPABLE,       /*! Far end is not able to transmit */
00214     T30_ERR_NORESSUPPORT,       /*! Far end cannot receive at the resolution of the image */
00215     T30_ERR_NOSIZESUPPORT,      /*! Far end cannot receive at the size of image */
00216     T30_ERR_UNEXPECTED,         /*! Unexpected message received */
00217 
00218     /* Phase E status values returned to a transmitter */
00219     T30_ERR_TX_BADDCS,          /*! Received bad response to DCS or training */
00220     T30_ERR_TX_BADPG,           /*! Received a DCN from remote after sending a page */
00221     T30_ERR_TX_ECMPHD,          /*! Invalid ECM response received from receiver */
00222     T30_ERR_TX_GOTDCN,          /*! Received a DCN while waiting for a DIS */
00223     T30_ERR_TX_INVALRSP,        /*! Invalid response after sending a page */
00224     T30_ERR_TX_NODIS,           /*! Received other than DIS while waiting for DIS */
00225     T30_ERR_TX_PHBDEAD,         /*! Received no response to DCS, training or TCF */
00226     T30_ERR_TX_PHDDEAD,         /*! No response after sending a page */
00227     T30_ERR_TX_T5EXP,           /*! Timed out waiting for receiver ready (ECM mode) */
00228 
00229     /* Phase E status values returned to a receiver */
00230     T30_ERR_RX_ECMPHD,          /*! Invalid ECM response received from transmitter */
00231     T30_ERR_RX_GOTDCS,          /*! DCS received while waiting for DTC */
00232     T30_ERR_RX_INVALCMD,        /*! Unexpected command after page received */
00233     T30_ERR_RX_NOCARRIER,       /*! Carrier lost during fax receive */
00234     T30_ERR_RX_NOEOL,           /*! Timed out while waiting for EOL (end Of line) */
00235     T30_ERR_RX_NOFAX,           /*! Timed out while waiting for first line */
00236     T30_ERR_RX_T2EXPDCN,        /*! Timer T2 expired while waiting for DCN */
00237     T30_ERR_RX_T2EXPD,          /*! Timer T2 expired while waiting for phase D */
00238     T30_ERR_RX_T2EXPFAX,        /*! Timer T2 expired while waiting for fax page */
00239     T30_ERR_RX_T2EXPMPS,        /*! Timer T2 expired while waiting for next fax page */
00240     T30_ERR_RX_T2EXPRR,         /*! Timer T2 expired while waiting for RR command */
00241     T30_ERR_RX_T2EXP,           /*! Timer T2 expired while waiting for NSS, DCS or MCF */
00242     T30_ERR_RX_DCNWHY,          /*! Unexpected DCN while waiting for DCS or DIS */
00243     T30_ERR_RX_DCNDATA,         /*! Unexpected DCN while waiting for image data */
00244     T30_ERR_RX_DCNFAX,          /*! Unexpected DCN while waiting for EOM, EOP or MPS */
00245     T30_ERR_RX_DCNPHD,          /*! Unexpected DCN after EOM or MPS sequence */
00246     T30_ERR_RX_DCNRRD,          /*! Unexpected DCN after RR/RNR sequence */
00247     T30_ERR_RX_DCNNORTN,        /*! Unexpected DCN after requested retransmission */
00248 
00249     /* TIFF file problems */
00250     T30_ERR_FILEERROR,          /*! TIFF/F file cannot be opened */
00251     T30_ERR_NOPAGE,             /*! TIFF/F page not found */
00252     T30_ERR_BADTIFF,            /*! TIFF/F format is not compatible */
00253     T30_ERR_BADPAGE,            /*! TIFF/F page number tag missing */
00254     T30_ERR_BADTAG,             /*! Incorrect values for TIFF/F tags */
00255     T30_ERR_BADTIFFHDR,         /*! Bad TIFF/F header - incorrect values in fields */
00256     T30_ERR_NOMEM,              /*! Cannot allocate memory for more pages */
00257     
00258     /* General problems */
00259     T30_ERR_RETRYDCN,           /*! Disconnected after permitted retries */
00260     T30_ERR_CALLDROPPED,        /*! The call dropped prematurely */
00261     
00262     /* Feature negotiation issues */
00263     T30_ERR_NOPOLL,             /*! Poll not accepted */
00264     T30_ERR_IDENT_UNACCEPTABLE, /*! Far end's ident is not acceptable */
00265     T30_ERR_SUB_UNACCEPTABLE,   /*! Far end's sub-address is not acceptable */
00266     T30_ERR_SEP_UNACCEPTABLE,   /*! Far end's selective polling address is not acceptable */
00267     T30_ERR_PSA_UNACCEPTABLE,   /*! Far end's polled sub-address is not acceptable */
00268     T30_ERR_SID_UNACCEPTABLE,   /*! Far end's sender identification is not acceptable */
00269     T30_ERR_PWD_UNACCEPTABLE,   /*! Far end's password is not acceptable */
00270     T30_ERR_TSA_UNACCEPTABLE,   /*! Far end's transmitting subscriber internet address is not acceptable */
00271     T30_ERR_IRA_UNACCEPTABLE,   /*! Far end's internet routing address is not acceptable */
00272     T30_ERR_CIA_UNACCEPTABLE,   /*! Far end's calling subscriber internet address is not acceptable */
00273     T30_ERR_ISP_UNACCEPTABLE,   /*! Far end's internet selective polling address is not acceptable */
00274     T30_ERR_CSA_UNACCEPTABLE    /*! Far end's called subscriber internet address is not acceptable */
00275 };
00276 
00277 /*!
00278     I/O modes for the T.30 protocol.
00279 */
00280 enum
00281 {
00282     T30_MODEM_NONE = 0,
00283     T30_MODEM_PAUSE,
00284     T30_MODEM_CED,
00285     T30_MODEM_CNG,
00286     T30_MODEM_V21,
00287     T30_MODEM_V27TER_2400,
00288     T30_MODEM_V27TER_4800,
00289     T30_MODEM_V29_7200,
00290     T30_MODEM_V29_9600,
00291     T30_MODEM_V17_7200,
00292     T30_MODEM_V17_9600,
00293     T30_MODEM_V17_12000,
00294     T30_MODEM_V17_14400,
00295     T30_MODEM_DONE
00296 };
00297 
00298 enum
00299 {
00300     T30_FRONT_END_SEND_STEP_COMPLETE = 0,
00301     /*! The current receive has completed. This is only needed to report an
00302         unexpected end of the receive operation, as might happen with T.38
00303         dying. */
00304     T30_FRONT_END_RECEIVE_COMPLETE,
00305     T30_FRONT_END_SIGNAL_PRESENT,
00306     T30_FRONT_END_SIGNAL_ABSENT
00307 };
00308 
00309 enum
00310 {
00311     T30_SUPPORT_V27TER = 0x01,
00312     T30_SUPPORT_V29 = 0x02,
00313     T30_SUPPORT_V17 = 0x04,
00314     T30_SUPPORT_V34 = 0x08,
00315     T30_SUPPORT_IAF = 0x10,
00316 };
00317 
00318 enum
00319 {
00320     T30_SUPPORT_NO_COMPRESSION = 0x01,
00321     T30_SUPPORT_T4_1D_COMPRESSION = 0x02,
00322     T30_SUPPORT_T4_2D_COMPRESSION = 0x04,
00323     T30_SUPPORT_T6_COMPRESSION = 0x08,
00324     T30_SUPPORT_T85_COMPRESSION = 0x10,     /* Monochrome JBIG */
00325     T30_SUPPORT_T43_COMPRESSION = 0x20,     /* Colour JBIG */
00326     T30_SUPPORT_T45_COMPRESSION = 0x40      /* Run length colour compression */
00327 };
00328 
00329 enum
00330 {
00331     T30_SUPPORT_STANDARD_RESOLUTION = 0x01,
00332     T30_SUPPORT_FINE_RESOLUTION = 0x02,
00333     T30_SUPPORT_SUPERFINE_RESOLUTION = 0x04,
00334 
00335     T30_SUPPORT_R4_RESOLUTION = 0x10000,
00336     T30_SUPPORT_R8_RESOLUTION = 0x20000,
00337     T30_SUPPORT_R16_RESOLUTION = 0x40000,
00338 
00339     T30_SUPPORT_300_300_RESOLUTION = 0x100000,
00340     T30_SUPPORT_400_400_RESOLUTION = 0x200000,
00341     T30_SUPPORT_600_600_RESOLUTION = 0x400000,
00342     T30_SUPPORT_1200_1200_RESOLUTION = 0x800000,
00343     T30_SUPPORT_300_600_RESOLUTION = 0x1000000,
00344     T30_SUPPORT_400_800_RESOLUTION = 0x2000000,
00345     T30_SUPPORT_600_1200_RESOLUTION = 0x4000000
00346 };
00347 
00348 enum
00349 {
00350     T30_SUPPORT_215MM_WIDTH = 0x01,
00351     T30_SUPPORT_255MM_WIDTH = 0x02,
00352     T30_SUPPORT_303MM_WIDTH = 0x04,
00353 
00354     T30_SUPPORT_UNLIMITED_LENGTH = 0x10000,
00355     T30_SUPPORT_A4_LENGTH = 0x20000,
00356     T30_SUPPORT_B4_LENGTH = 0x40000,
00357     T30_SUPPORT_US_LETTER_LENGTH = 0x80000,
00358     T30_SUPPORT_US_LEGAL_LENGTH = 0x100000
00359 };
00360 
00361 enum
00362 {
00363     /*! Enable support of identification, through the SID and/or PWD frames */
00364     T30_SUPPORT_IDENTIFICATION = 0x01,
00365     /*! Enable support of selective polling, through the SEP frame */
00366     T30_SUPPORT_SELECTIVE_POLLING = 0x02,
00367     /*! Enable support of polling sub-addressing, through the PSA frame */
00368     T30_SUPPORT_POLLED_SUB_ADDRESSING = 0x04,
00369     /*! Enable support of multiple selective polling, through repeated used of the SEP and PSA frames */
00370     T30_SUPPORT_MULTIPLE_SELECTIVE_POLLING = 0x08,
00371     /*! Enable support of sub-addressing, through the SUB frame */
00372     T30_SUPPORT_SUB_ADDRESSING = 0x10,
00373     /*! Enable support of transmitting subscriber internet address, through the TSA frame */
00374     T30_SUPPORT_TRANSMITTING_SUBSCRIBER_INTERNET_ADDRESS = 0x20,
00375     /*! Enable support of internet routing address, through the IRA frame */
00376     T30_SUPPORT_INTERNET_ROUTING_ADDRESS = 0x40,
00377     /*! Enable support of calling subscriber internet address, through the CIA frame */
00378     T30_SUPPORT_CALLING_SUBSCRIBER_INTERNET_ADDRESS = 0x80,
00379     /*! Enable support of internet selective polling address, through the ISP frame */
00380     T30_SUPPORT_INTERNET_SELECTIVE_POLLING_ADDRESS = 0x100,
00381     /*! Enable support of called subscriber internet address, through the CSA frame */
00382     T30_SUPPORT_CALLED_SUBSCRIBER_INTERNET_ADDRESS = 0x200,
00383     /*! Enable support of the field not valid (FNV) frame */
00384     T30_SUPPORT_FIELD_NOT_VALID = 0x400,
00385     /*! Enable support of the command repeat (CRP) frame */
00386     T30_SUPPORT_COMMAND_REPEAT = 0x800
00387 };
00388 
00389 enum
00390 {
00391     T30_IAF_MODE_T37 = 0x01,
00392     T30_IAF_MODE_T38 = 0x02,
00393     T30_IAF_MODE_FLOW_CONTROL = 0x04,
00394     /*! Continuous flow mode means data is sent as fast as possible, usually across
00395         the Internet, where speed is not constrained by a PSTN modem. */
00396     T30_IAF_MODE_CONTINUOUS_FLOW = 0x08,
00397     /*! No TCF means TCF is not exchanged. The end points must sort out usable speed
00398         issues locally. */
00399     T30_IAF_MODE_NO_TCF = 0x10,
00400     /*! No fill bits means do not insert fill bits, even if the T.30 messages request
00401         them. */
00402     T30_IAF_MODE_NO_FILL_BITS = 0x20,
00403     /*! No indicators means do not send indicator messages when using T.38. */
00404     T30_IAF_MODE_NO_INDICATORS = 0x40
00405 };
00406 
00407 typedef struct
00408 {
00409     /*! \brief The identifier string (CSI, TSI, CIG). */
00410     char ident[T30_MAX_IDENT_LEN + 1];
00411     /*! \brief The sub-address string (SUB). */
00412     char sub_address[T30_MAX_IDENT_LEN + 1];
00413     /*! \brief The selective polling sub-address (SEP). */
00414     char selective_polling_address[T30_MAX_IDENT_LEN + 1];
00415     /*! \brief The polled sub-address (PSA). */
00416     char polled_sub_address[T30_MAX_IDENT_LEN + 1];
00417     /*! \brief The sender identification (SID). */
00418     char sender_ident[T30_MAX_IDENT_LEN + 1];
00419     /*! \brief The password (PWD). */
00420     char password[T30_MAX_IDENT_LEN + 1];
00421     /*! \brief Non-standard facilities (NSF). */
00422     uint8_t *nsf;
00423     size_t nsf_len;
00424     /*! \brief Non-standard facilities command (NSC). */
00425     uint8_t *nsc;
00426     size_t nsc_len;
00427     /*! \brief Non-standard facilities set-up (NSS). */
00428     uint8_t *nss;
00429     size_t nss_len;
00430     /*! \brief Transmitting subscriber internet address (TSA). */
00431     int tsa_type;
00432     char *tsa;
00433     size_t tsa_len;
00434     /*! \brief Internet routing address (IRA). */
00435     int ira_type;
00436     char *ira;
00437     size_t ira_len;
00438     /*! \brief Calling subscriber internet address (CIA). */
00439     int cia_type;
00440     char *cia;
00441     size_t cia_len;
00442     /*! \brief Internet selective polling address (ISP). */
00443     int isp_type;
00444     char *isp;
00445     size_t isp_len;
00446     /*! \brief Called subscriber internet address (CSA). */
00447     int csa_type;
00448     char *csa;
00449     size_t csa_len;
00450 } t30_exchanged_info_t;
00451 
00452 /*!
00453     T.30 FAX channel descriptor. This defines the state of a single working
00454     instance of a T.30 FAX channel.
00455 */
00456 struct t30_state_s
00457 {
00458     /* This must be kept the first thing in the structure, so it can be pointed
00459        to reliably as the structures change over time. */
00460     /*! \brief T.4 context for reading or writing image data. */
00461     t4_state_t t4;
00462     
00463     int operation_in_progress;
00464 
00465     /*! \brief TRUE if behaving as the calling party */
00466     int calling_party;
00467     
00468     /*! \brief The received DCS, formatted as an ASCII string, for inclusion
00469                in the TIFF file. */
00470     char rx_dcs_string[T30_MAX_DIS_DTC_DCS_LEN*3 + 1];
00471     /*! \brief The text which will be used in FAX page header. No text results
00472                in no header line. */
00473     char header_info[T30_MAX_PAGE_HEADER_INFO + 1];
00474     /*! \brief The information fields received. */
00475     t30_exchanged_info_t rx_info;
00476     /*! \brief The information fields to be transmitted. */
00477     t30_exchanged_info_t tx_info;
00478     /*! \brief The country of origin of the remote machine, if known, else NULL. */
00479     const char *country;
00480     /*! \brief The vendor of the remote machine, if known, else NULL. */
00481     const char *vendor;
00482     /*! \brief The model of the remote machine, if known, else NULL. */
00483     const char *model;
00484 
00485     /*! \brief A pointer to a callback routine to be called when phase B events
00486         occur. */
00487     t30_phase_b_handler_t *phase_b_handler;
00488     /*! \brief An opaque pointer supplied in event B callbacks. */
00489     void *phase_b_user_data;
00490     /*! \brief A pointer to a callback routine to be called when phase D events
00491         occur. */
00492     t30_phase_d_handler_t *phase_d_handler;
00493     /*! \brief An opaque pointer supplied in event D callbacks. */
00494     void *phase_d_user_data;
00495     /*! \brief A pointer to a callback routine to be called when phase E events
00496         occur. */
00497     t30_phase_e_handler_t *phase_e_handler;
00498     /*! \brief An opaque pointer supplied in event E callbacks. */
00499     void *phase_e_user_data;
00500 
00501     /*! \brief A pointer to a callback routine to be called when document events
00502         (e.g. end of transmitted document) occur. */
00503     t30_document_handler_t *document_handler;
00504     /*! \brief An opaque pointer supplied in document callbacks. */
00505     void *document_user_data;
00506 
00507     /*! \brief The handler for changes to the receive mode */
00508     t30_set_handler_t *set_rx_type_handler;
00509     /*! \brief An opaque pointer passed to the handler for changes to the receive mode */
00510     void *set_rx_type_user_data;
00511     /*! \brief The handler for changes to the transmit mode */
00512     t30_set_handler_t *set_tx_type_handler;
00513     /*! \brief An opaque pointer passed to the handler for changes to the transmit mode */
00514     void *set_tx_type_user_data;
00515 
00516     /*! \brief The transmitted HDLC frame handler. */
00517     t30_send_hdlc_handler_t *send_hdlc_handler;
00518     /*! \brief An opaque pointer passed to the transmitted HDLC frame handler. */
00519     void *send_hdlc_user_data;
00520 
00521     /*! \brief The DIS code for the minimum scan row time we require. This is usually 0ms,
00522         but if we are trying to simulate another type of FAX machine, we may need a non-zero
00523         value here. */
00524     uint8_t local_min_scan_time_code;
00525 
00526     /*! \brief The current T.30 phase. */
00527     int phase;
00528     /*! \brief The T.30 phase to change to when the current phase ends. */
00529     int next_phase;
00530     /*! \brief The current state of the T.30 state machine. */
00531     int state;
00532     /*! \brief The step in sending a sequence of HDLC frames. */
00533     int step;
00534 
00535     /*! \brief The preparation buffer for the DCS message to be transmitted. */
00536     uint8_t dcs_frame[T30_MAX_DIS_DTC_DCS_LEN];
00537     /*! \brief The length of the DCS message to be transmitted. */
00538     int dcs_len;
00539     /*! \brief The preparation buffer for DIS or DTC message to be transmitted. */
00540     uint8_t local_dis_dtc_frame[T30_MAX_DIS_DTC_DCS_LEN];
00541     /*! \brief The length of the DIS or DTC message to be transmitted. */
00542     int local_dis_dtc_len;
00543     /*! \brief The last DIS or DTC message received form the far end. */
00544     uint8_t far_dis_dtc_frame[T30_MAX_DIS_DTC_DCS_LEN];
00545     /*! \brief The length of the last DIS or DTC message received form the far end. */
00546     int far_dis_dtc_len;
00547     /*! \brief TRUE if a valid DIS has been received from the far end. */
00548     int dis_received;
00549 
00550     /*! \brief A flag to indicate a message is in progress. */
00551     int in_message;
00552 
00553     /*! \brief TRUE if the short training sequence should be used. */
00554     int short_train;
00555 
00556     /*! \brief A count of the number of bits in the trainability test. */
00557     int training_test_bits;
00558     /*! \brief The current count of consecutive zero bits, during the trainability test. */
00559     int training_current_zeros;
00560     /*! \brief The maximum consecutive zero bits seen to date, during the trainability test. */
00561     int training_most_zeros;
00562 
00563     /*! \brief The current fallback step for the fast message transfer modem. */
00564     int current_fallback;
00565     /*! \brief The subset of supported modems allowed at the current time, allowing for negotiation. */
00566     int current_permitted_modems;
00567     /*! \brief TRUE if a carrier is present. Otherwise FALSE. */
00568     int rx_signal_present;
00569     /*! \brief TRUE if a modem has trained correctly. */
00570     int rx_trained;
00571     int current_rx_type;
00572     int current_tx_type;
00573 
00574     /*! \brief T0 is the answer timeout when calling another FAX machine.
00575         Placing calls is handled outside the FAX processing, but this timeout keeps
00576         running until V.21 modulation is sent or received.
00577         T1 is the remote terminal identification timeout (in audio samples). */
00578     int timer_t0_t1;
00579     /*! \brief T2 is the HDLC command timeout.
00580                T4 is the HDLC response timeout (in audio samples). */
00581     int timer_t2_t4;
00582     /*! \brief TRUE if the T2/T4 timer is actually timing T4 */
00583     int timer_is_t4;
00584     /*! \brief Procedural interrupt timeout (in audio samples). */
00585     int timer_t3;
00586     /*! \brief This is only used in error correcting mode. */
00587     int timer_t5;
00588     /*! \brief This is only used in full duplex (e.g. ISDN) modes. */
00589     int timer_t6;
00590     /*! \brief This is only used in full duplex (e.g. ISDN) modes. */
00591     int timer_t7;
00592     /*! \brief This is only used in full duplex (e.g. ISDN) modes. */
00593     int timer_t8;
00594 
00595     /*! \brief TRUE once the far end FAX entity has been detected. */
00596     int far_end_detected;
00597 
00598     /*! \brief TRUE if a local T.30 interrupt is pending. */
00599     int local_interrupt_pending;
00600     /*! \brief The image coding being used on the line. */
00601     int line_encoding;
00602     /*! \brief The image coding being used for output files. */
00603     int output_encoding;
00604     /*! \brief The current DCS message minimum scan time code. */
00605     uint8_t min_scan_time_code;
00606     /*! \brief The X direction resolution of the current image, in pixels per metre. */
00607     int x_resolution;
00608     /*! \brief The Y direction resolution of the current image, in pixels per metre. */
00609     int y_resolution;
00610     /*! \brief The width of the current image, in pixels. */
00611     t4_image_width_t image_width;
00612     /*! \brief Current number of retries of the action in progress. */
00613     int retries;
00614     /*! \brief TRUE if error correcting mode is used. */
00615     int error_correcting_mode;
00616     /*! \brief The current count of consecutive T30_PPR messages. */
00617     int ppr_count;
00618     /*! \brief The current count of consecutive T30_RNR messages. */
00619     int receiver_not_ready_count;
00620     /*! \brief The number of octets to be used per ECM frame. */
00621     int octets_per_ecm_frame;
00622     /*! \brief The ECM partial page buffer. */
00623     uint8_t ecm_data[256][260];
00624     /*! \brief The lengths of the frames in the ECM partial page buffer. */
00625     int16_t ecm_len[256];
00626     /*! \brief A bit map of the OK ECM frames, constructed as a PPR frame. */
00627     uint8_t ecm_frame_map[3 + 32];
00628     
00629     /*! \brief The current page number, in ECM mode */
00630     int ecm_page;
00631     /*! \brief The current block number, in ECM mode */
00632     int ecm_block;
00633     /*! \brief The number of frames in the current block number, in ECM mode */
00634     int ecm_frames;
00635     /*! \brief The number of frames sent in the current burst of image transmission, in ECM mode */
00636     int ecm_frames_this_tx_burst;
00637     /*! \brief The current ECM frame, during ECM transmission. */
00638     int ecm_current_tx_frame;
00639     /*! \brief TRUE if we are at the end of an ECM page to se sent - i.e. there are no more
00640         partial pages still to come. */
00641     int ecm_at_page_end;
00642     int next_tx_step;
00643     int next_rx_step;
00644     /*! \brief Image file name for image reception. */
00645     char rx_file[256];
00646     /*! \brief The last page we are prepared accept for a received image file. -1 means no restriction. */
00647     int rx_stop_page;
00648     /*! \brief Image file name to be sent. */
00649     char tx_file[256];
00650     /*! \brief The first page to be sent from the image file. -1 means no restriction. */
00651     int tx_start_page;
00652     /*! \brief The last page to be sent from the image file. -1 means no restriction. */
00653     int tx_stop_page;
00654     int current_status;
00655     /*! \brief Internet Aware FAX mode bit mask. */
00656     int iaf;
00657     /*! \brief A bit mask of the currently supported modem types. */
00658     int supported_modems;
00659     /*! \brief A bit mask of the currently supported image compression modes. */
00660     int supported_compressions;
00661     /*! \brief A bit mask of the currently supported image resolutions. */
00662     int supported_resolutions;
00663     /*! \brief A bit mask of the currently supported image sizes. */
00664     int supported_image_sizes;
00665     /*! \brief A bit mask of the currently supported T.30 special features. */
00666     int supported_t30_features;
00667     /*! \brief TRUE is ECM mode handling is enabled. */
00668     int ecm_allowed;
00669     
00670     /*! \brief the FCF2 field of the last PPS message we received. */
00671     int last_pps_fcf2;
00672     /*! \brief The number of the first ECM frame which we do not currently received correctly. For
00673         a partial page received correctly, this will be one greater than the number of frames it
00674         contains. */
00675     int ecm_first_bad_frame;
00676     /*! \brief A count of successfully received ECM frames, to assess progress as a basis for
00677         deciding whether to continue error correction when PPRs keep repeating. */
00678     int ecm_progress;
00679 
00680     /*! \brief Error and flow logging control */
00681     logging_state_t logging;
00682 };
00683 
00684 typedef struct
00685 {
00686     /*! \brief The current bit rate for image transfer. */
00687     int bit_rate;
00688     /*! \brief TRUE if error correcting mode is used. */
00689     int error_correcting_mode;
00690     /*! \brief The number of pages transferred so far. */
00691     int pages_transferred;
00692     /*! \brief The number of pages in the file (<0 if not known). */
00693     int pages_in_file;
00694     /*! \brief The number of horizontal pixels in the most recent page. */
00695     int width;
00696     /*! \brief The number of vertical pixels in the most recent page. */
00697     int length;
00698     /*! \brief The number of bad pixel rows in the most recent page. */
00699     int bad_rows;
00700     /*! \brief The largest number of bad pixel rows in a block in the most recent page. */
00701     int longest_bad_row_run;
00702     /*! \brief The horizontal column-to-column resolution of the page in pixels per metre */
00703     int x_resolution;
00704     /*! \brief The vertical row-to-row resolution of the page in pixels per metre */
00705     int y_resolution;
00706     /*! \brief The type of compression used between the FAX machines */
00707     int encoding;
00708     /*! \brief The size of the image, in bytes */
00709     int image_size;
00710     /*! \brief Current status */
00711     int current_status;
00712 } t30_stats_t;
00713 
00714 #if defined(__cplusplus)
00715 extern "C"
00716 {
00717 #endif
00718 
00719 /*! Initialise a T.30 context.
00720     \brief Initialise a T.30 context.
00721     \param s The T.30 context.
00722     \param calling_party TRUE if the context is for a calling party. FALSE if the
00723            context is for an answering party.
00724     \param set_rx_type_handler
00725     \param set_rx_type_user_data
00726     \param set_tx_type_handler
00727     \param set_tx_type_user_data
00728     \param send_hdlc_handler
00729     \param send_hdlc_user_data
00730     \return A pointer to the context, or NULL if there was a problem. */
00731 t30_state_t *t30_init(t30_state_t *s,
00732                       int calling_party,
00733                       t30_set_handler_t *set_rx_type_handler,
00734                       void *set_rx_type_user_data,
00735                       t30_set_handler_t *set_tx_type_handler,
00736                       void *set_tx_type_user_data,
00737                       t30_send_hdlc_handler_t *send_hdlc_handler,
00738                       void *send_hdlc_user_data);
00739 
00740 /*! Release a T.30 context.
00741     \brief Release a T.30 context.
00742     \param s The T.30 context.
00743     \return 0 for OK, else -1. */
00744 int t30_release(t30_state_t *s);
00745 
00746 /*! Free a T.30 context.
00747     \brief Free a T.30 context.
00748     \param s The T.30 context.
00749     \return 0 for OK, else -1. */
00750 int t30_free(t30_state_t *s);
00751 
00752 /*! Restart a T.30 context.
00753     \brief Restart a T.30 context.
00754     \param s The T.30 context.
00755     \return 0 for OK, else -1. */
00756 int t30_restart(t30_state_t *s);
00757 
00758 /*! Cleanup a T.30 context if the call terminates.
00759     \brief Cleanup a T.30 context if the call terminates.
00760     \param s The T.30 context. */
00761 void t30_terminate(t30_state_t *s);
00762 
00763 /*! Inform the T.30 engine of a status change in the front end (end of tx, rx signal change, etc.).
00764     \brief Inform the T.30 engine of a status change in the front end (end of tx, rx signal change, etc.).
00765     \param user_data The T.30 context.
00766     \param status The type of status change which occured. */
00767 void t30_front_end_status(void *user_data, int status);
00768 
00769 /*! Get a bit of received non-ECM image data.
00770     \brief Get a bit of received non-ECM image data.
00771     \param user_data An opaque pointer, which must point to the T.30 context.
00772     \return The next bit to transmit. */
00773 int t30_non_ecm_get_bit(void *user_data);
00774 
00775 /*! Get a byte of received non-ECM image data.
00776     \brief Get a byte of received non-ECM image data.
00777     \param user_data An opaque pointer, which must point to the T.30 context.
00778     \return The next byte to transmit. */
00779 int t30_non_ecm_get_byte(void *user_data);
00780 
00781 /*! Get a chunk of received non-ECM image data.
00782     \brief Get a bit of received non-ECM image data.
00783     \param user_data An opaque pointer, which must point to the T.30 context.
00784     \param buf The buffer to contain the data.
00785     \param max_len The maximum length of the chunk.
00786     \return The actual length of the chunk. */
00787 int t30_non_ecm_get_chunk(void *user_data, uint8_t buf[], int max_len);
00788 
00789 /*! Process a bit of received non-ECM image data.
00790     \brief Process a bit of received non-ECM image data
00791     \param user_data An opaque pointer, which must point to the T.30 context.
00792     \param bit The received bit. */
00793 void t30_non_ecm_put_bit(void *user_data, int bit);
00794 
00795 /*! Process a byte of received non-ECM image data.
00796     \brief Process a byte of received non-ECM image data
00797     \param user_data An opaque pointer, which must point to the T.30 context.
00798     \param byte The received byte. */
00799 void t30_non_ecm_put_byte(void *user_data, int byte);
00800 
00801 /*! Process a chunk of received non-ECM image data.
00802     \brief Process a chunk of received non-ECM image data
00803     \param user_data An opaque pointer, which must point to the T.30 context.
00804     \param buf The buffer containing the received data.
00805     \param len The length of the data in buf. */
00806 void t30_non_ecm_put_chunk(void *user_data, const uint8_t buf[], int len);
00807 
00808 /*! Process a received HDLC frame.
00809     \brief Process a received HDLC frame.
00810     \param user_data The T.30 context.
00811     \param msg The HDLC message.
00812     \param len The length of the message, in octets.
00813     \param ok TRUE if the frame was received without error. */
00814 void t30_hdlc_accept(void *user_data, const uint8_t *msg, int len, int ok);
00815 
00816 /*! Report the passage of time to the T.30 engine.
00817     \brief Report the passage of time to the T.30 engine.
00818     \param s The T.30 context.
00819     \param samples The time change in 1/8000th second steps. */
00820 void t30_timer_update(t30_state_t *s, int samples);
00821 
00822 /*! Get the current transfer statistics for the file being sent or received.
00823     \brief Get the current transfer statistics.
00824     \param s The T.30 context.
00825     \param t A pointer to a buffer for the statistics. */
00826 void t30_get_transfer_statistics(t30_state_t *s, t30_stats_t *t);
00827 
00828 /*! Request a local interrupt of FAX exchange.
00829     \brief Request a local interrupt of FAX exchange.
00830     \param s The T.30 context.
00831     \param state TRUE to enable interrupt request, else FALSE. */
00832 void t30_local_interrupt_request(t30_state_t *s, int state);
00833 
00834 #if defined(__cplusplus)
00835 }
00836 #endif
00837 
00838 #endif
00839 /*- End of file ------------------------------------------------------------*/

Generated on Mon Nov 21 19:45:44 2011 for libspandsp by  doxygen 1.5.3