spandsp 0.0.6

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 
00026 /*! \file */
00027 
00028 #if !defined(_SPANDSP_T30_H_)
00029 #define _SPANDSP_T30_H_
00030 
00031 /*! \page t30_page T.30 FAX protocol handling
00032 
00033 \section t30_page_sec_1 What does it do?
00034 The T.30 protocol is the core protocol used for FAX transmission. This module
00035 implements most of its key featrues. It does not interface to the outside work.
00036 Seperate modules do that for T.38, analogue line, and other forms of FAX
00037 communication.
00038 
00039 Current features of this module include:
00040 
00041     - FAXing to and from multi-page TIFF/F files, whose images are one of the standard
00042       FAX sizes.
00043     - V.27ter, V.29 and V.17 modes (2400bps, to 14,400bps).
00044     - T.4 1D (MH), T.4 2D,(MR) and T.6 (MMR) compression.
00045     - Error correction mode (ECM).
00046     - All standard horizonal resolutions (R8, R16, 300dpi, 600dpi, 800dpi, 1200dpi).
00047     - All standard vertical resolutions (standard, fine, superfine, 300dpi, 600dpi, 800dpi, 1200dpi).
00048     - All standard page widths (A4, B4, A3).
00049     - All standard page lengths (A4, B4, North American letter, North American legal, continuous).
00050     - Monitoring and sending identifier strings (CSI, TSI, and CIG).
00051     - Monitoring and sending sub-address strings (SUB).
00052     - Monitoring and sending polling sub-addresses (SEP).
00053     - Monitoring and sending polled sub-addresses (PSA).
00054     - Monitoring and sending sender identifications (SID).
00055     - Monitoring and sending passwords (PWD).
00056     - Monitoring of non-standard facility frames (NSF, NSC, and NSS).
00057     - Sending custom non-standard facility frames (NSF, NSC, and NSS).
00058     - Analogue modem and T.38 operation.
00059 
00060 \section t30_page_sec_2 How does it work?
00061 
00062 Some of the following is paraphrased from some notes found a while ago on the Internet.
00063 I cannot remember exactly where they came from, but they are useful.
00064 
00065 \subsection t30_page_sec_2a The answer (CED) tone
00066 
00067 The T.30 standard says an answering fax device must send CED (a 2100Hz tone) for
00068 approximately 3 seconds before sending the first handshake message. Some machines
00069 send an 1100Hz or 1850Hz tone, and some send no tone at all. In fact, this answer
00070 tone is so unpredictable, it cannot really be used. It should, however, always be
00071 generated according to the specification.
00072 
00073 \subsection t30_page_sec_2b Common Timing Deviations
00074 
00075 The T.30 spec. specifies a number of time-outs. For example, after dialing a number,
00076 a calling fax system should listen for a response for 35 seconds before giving up.
00077 These time-out periods are as follows: 
00078 
00079     - T1 - 35+-5s: the maximum time for which two fax system will attempt to identify each other
00080     - T2 - 6+-1s:  a time-out used to start the sequence for changing transmit parameters
00081     - T3 - 10+-5s: a time-out used in handling operator interrupts
00082     - T5 - 60+-5s: a time-out used in error correction mode
00083 
00084 These time-outs are sometimes misinterpreted. In addition, they are routinely
00085 ignored, sometimes with good reason. For example, after placing a call, the
00086 calling fax system is supposed to wait for 35 seconds before giving up. If the
00087 answering unit does not answer on the first ring or if a voice answering machine
00088 is connected to the line, or if there are many delays through the network,
00089 the delay before answer can be much longer than 35 seconds. 
00090 
00091 Fax units that support error correction mode (ECM) can respond to a post-image
00092 handshake message with a receiver not ready (RNR) message. The calling unit then
00093 queries the receiving fax unit with a receiver ready (RR) message. If the
00094 answering unit is still busy (printing for example), it will repeat the RNR
00095 message. According to the T.30 standard, this sequence (RR/RNR RR/RNR) can be
00096 repeated for up to the end of T5 (60+-5s). However, many fax systems
00097 ignore the time-out and will continue the sequence indefinitely, unless the user
00098 manually overrides. 
00099 
00100 All the time-outs are subject to alteration, and sometimes misuse. Good T.30
00101 implementations must do the right thing, and tolerate others doing the wrong thing.
00102 
00103 \subsection t30_page_sec_2c Variations in the inter-carrier gap
00104 
00105 T.30 specifies 75+-20ms of silence between signals using different modulation
00106 schemes. Examples are between the end of a DCS signal and the start of a TCF signal,
00107 and between the end of an image and the start of a post-image signal. Many fax systems
00108 violate this requirement, especially for the silent period between DCS and TCF.
00109 This may be stretched to well over 100ms. If this period is too long, it can interfere with
00110 handshake signal error recovery, should a packet be corrupted on the line. Systems
00111 should ensure they stay within the prescribed T.30 limits, and be tolerant of others
00112 being out of spec.. 
00113 
00114 \subsection t30_page_sec_2d Other timing variations
00115 
00116 Testing is required to determine the ability of a fax system to handle
00117 variations in the duration of pauses between unacknowledged handshake message
00118 repetitions, and also in the pauses between the receipt of a handshake command and
00119 the start of a response to that command. In order to reduce the total
00120 transmission time, many fax systems start sending a response message before the
00121 end of the command has been received. 
00122 
00123 \subsection t30_page_sec_2e Other deviations from the T.30 standard
00124 
00125 There are many other commonly encountered variations between machines, including:
00126 
00127     - frame sequence deviations
00128     - preamble and flag sequence variations
00129     - improper EOM usage
00130     - unusual data rate fallback sequences
00131     - common training pattern detection algorithms
00132     - image transmission deviations
00133     - use of the talker echo protect tone
00134     - image padding and short lines
00135     - RTP/RTN handshake message usage
00136     - long duration lines
00137     - nonstandard disconnect sequences
00138     - DCN usage
00139 */
00140 
00141 /*! The maximum length of a DIS, DTC or DCS frame */
00142 #define T30_MAX_DIS_DTC_DCS_LEN     22
00143 /*! The maximum length of the body of an ident string */
00144 #define T30_MAX_IDENT_LEN           20
00145 /*! The maximum length of the user string to insert in page headers */
00146 #define T30_MAX_PAGE_HEADER_INFO    50
00147 
00148 typedef struct t30_state_s t30_state_t;
00149 
00150 /*!
00151     T.30 phase B callback handler. This handler can be used to process addition
00152     information available in some FAX calls, such as passwords. The callback handler
00153     can access whatever additional information might have been received, using
00154     t30_get_received_info().
00155     \brief T.30 phase B callback handler.
00156     \param s The T.30 context.
00157     \param user_data An opaque pointer.
00158     \param result The phase B event code.
00159     \return The new status. Normally, T30_ERR_OK is returned.
00160 */
00161 typedef int (t30_phase_b_handler_t)(t30_state_t *s, void *user_data, int result);
00162 
00163 /*!
00164     T.30 phase D callback handler.
00165     \brief T.30 phase D callback handler.
00166     \param s The T.30 context.
00167     \param user_data An opaque pointer.
00168     \param result The phase D event code.
00169     \return The new status. Normally, T30_ERR_OK is returned.
00170 */
00171 typedef int (t30_phase_d_handler_t)(t30_state_t *s, void *user_data, int result);
00172 
00173 /*!
00174     T.30 phase E callback handler.
00175     \brief T.30 phase E callback handler.
00176     \param s The T.30 context.
00177     \param user_data An opaque pointer.
00178     \param completion_code The phase E completion code.
00179 */
00180 typedef void (t30_phase_e_handler_t)(t30_state_t *s, void *user_data, int completion_code);
00181 
00182 /*!
00183     T.30 real time frame handler.
00184     \brief T.30 real time frame handler.
00185     \param s The T.30 context.
00186     \param user_data An opaque pointer.
00187     \param direction TRUE for incoming, FALSE for outgoing.
00188     \param msg The HDLC message.
00189     \param len The length of the message.
00190 */
00191 typedef void (t30_real_time_frame_handler_t)(t30_state_t *s,
00192                                              void *user_data,
00193                                              int direction,
00194                                              const uint8_t msg[],
00195                                              int len);
00196 
00197 /*!
00198     T.30 document handler.
00199     \brief T.30 document handler.
00200     \param s The T.30 context.
00201     \param user_data An opaque pointer.
00202     \param result The document event code.
00203 */
00204 typedef int (t30_document_handler_t)(t30_state_t *s, void *user_data, int status);
00205 
00206 /*!
00207     T.30 set a receive or transmit type handler.
00208     \brief T.30 set a receive or transmit type handler.
00209     \param user_data An opaque pointer.
00210     \param type The modem, tone or silence to be sent or received.
00211     \param bit_rate The bit rate of the modem to be sent or received.
00212     \param short_train TRUE if the short training sequence should be used (where one exists).
00213     \param use_hdlc FALSE for bit stream, TRUE for HDLC framing.
00214 */
00215 typedef void (t30_set_handler_t)(void *user_data, int type, int bit_rate, int short_train, int use_hdlc);
00216 
00217 /*!
00218     T.30 send HDLC handler.
00219     \brief T.30 send HDLC handler.
00220     \param user_data An opaque pointer.
00221     \param msg The HDLC message.
00222     \param len The length of the message.
00223 */
00224 typedef void (t30_send_hdlc_handler_t)(void *user_data, const uint8_t msg[], int len);
00225 
00226 /*!
00227     T.30 protocol completion codes, at phase E.
00228 */
00229 enum
00230 {
00231     T30_ERR_OK = 0,             /*! OK */
00232 
00233     /* Link problems */
00234     T30_ERR_CEDTONE,            /*! The CED tone exceeded 5s */
00235     T30_ERR_T0_EXPIRED,         /*! Timed out waiting for initial communication */
00236     T30_ERR_T1_EXPIRED,         /*! Timed out waiting for the first message */
00237     T30_ERR_T3_EXPIRED,         /*! Timed out waiting for procedural interrupt */
00238     T30_ERR_HDLC_CARRIER,       /*! The HDLC carrier did not stop in a timely manner */
00239     T30_ERR_CANNOT_TRAIN,       /*! Failed to train with any of the compatible modems */
00240     T30_ERR_OPER_INT_FAIL,      /*! Operator intervention failed */
00241     T30_ERR_INCOMPATIBLE,       /*! Far end is not compatible */
00242     T30_ERR_RX_INCAPABLE,       /*! Far end is not able to receive */
00243     T30_ERR_TX_INCAPABLE,       /*! Far end is not able to transmit */
00244     T30_ERR_NORESSUPPORT,       /*! Far end cannot receive at the resolution of the image */
00245     T30_ERR_NOSIZESUPPORT,      /*! Far end cannot receive at the size of image */
00246     T30_ERR_UNEXPECTED,         /*! Unexpected message received */
00247 
00248     /* Phase E status values returned to a transmitter */
00249     T30_ERR_TX_BADDCS,          /*! Received bad response to DCS or training */
00250     T30_ERR_TX_BADPG,           /*! Received a DCN from remote after sending a page */
00251     T30_ERR_TX_ECMPHD,          /*! Invalid ECM response received from receiver */
00252     T30_ERR_TX_GOTDCN,          /*! Received a DCN while waiting for a DIS */
00253     T30_ERR_TX_INVALRSP,        /*! Invalid response after sending a page */
00254     T30_ERR_TX_NODIS,           /*! Received other than DIS while waiting for DIS */
00255     T30_ERR_TX_PHBDEAD,         /*! Received no response to DCS, training or TCF */
00256     T30_ERR_TX_PHDDEAD,         /*! No response after sending a page */
00257     T30_ERR_TX_T5EXP,           /*! Timed out waiting for receiver ready (ECM mode) */
00258 
00259     /* Phase E status values returned to a receiver */
00260     T30_ERR_RX_ECMPHD,          /*! Invalid ECM response received from transmitter */
00261     T30_ERR_RX_GOTDCS,          /*! DCS received while waiting for DTC */
00262     T30_ERR_RX_INVALCMD,        /*! Unexpected command after page received */
00263     T30_ERR_RX_NOCARRIER,       /*! Carrier lost during fax receive */
00264     T30_ERR_RX_NOEOL,           /*! Timed out while waiting for EOL (end Of line) */
00265     T30_ERR_RX_NOFAX,           /*! Timed out while waiting for first line */
00266     T30_ERR_RX_T2EXPDCN,        /*! Timer T2 expired while waiting for DCN */
00267     T30_ERR_RX_T2EXPD,          /*! Timer T2 expired while waiting for phase D */
00268     T30_ERR_RX_T2EXPFAX,        /*! Timer T2 expired while waiting for fax page */
00269     T30_ERR_RX_T2EXPMPS,        /*! Timer T2 expired while waiting for next fax page */
00270     T30_ERR_RX_T2EXPRR,         /*! Timer T2 expired while waiting for RR command */
00271     T30_ERR_RX_T2EXP,           /*! Timer T2 expired while waiting for NSS, DCS or MCF */
00272     T30_ERR_RX_DCNWHY,          /*! Unexpected DCN while waiting for DCS or DIS */
00273     T30_ERR_RX_DCNDATA,         /*! Unexpected DCN while waiting for image data */
00274     T30_ERR_RX_DCNFAX,          /*! Unexpected DCN while waiting for EOM, EOP or MPS */
00275     T30_ERR_RX_DCNPHD,          /*! Unexpected DCN after EOM or MPS sequence */
00276     T30_ERR_RX_DCNRRD,          /*! Unexpected DCN after RR/RNR sequence */
00277     T30_ERR_RX_DCNNORTN,        /*! Unexpected DCN after requested retransmission */
00278 
00279     /* TIFF file problems */
00280     T30_ERR_FILEERROR,          /*! TIFF/F file cannot be opened */
00281     T30_ERR_NOPAGE,             /*! TIFF/F page not found */
00282     T30_ERR_BADTIFF,            /*! TIFF/F format is not compatible */
00283     T30_ERR_BADPAGE,            /*! TIFF/F page number tag missing */
00284     T30_ERR_BADTAG,             /*! Incorrect values for TIFF/F tags */
00285     T30_ERR_BADTIFFHDR,         /*! Bad TIFF/F header - incorrect values in fields */
00286     T30_ERR_NOMEM,              /*! Cannot allocate memory for more pages */
00287     
00288     /* General problems */
00289     T30_ERR_RETRYDCN,           /*! Disconnected after permitted retries */
00290     T30_ERR_CALLDROPPED,        /*! The call dropped prematurely */
00291     
00292     /* Feature negotiation issues */
00293     T30_ERR_NOPOLL,             /*! Poll not accepted */
00294     T30_ERR_IDENT_UNACCEPTABLE, /*! Far end's ident is not acceptable */
00295     T30_ERR_SUB_UNACCEPTABLE,   /*! Far end's sub-address is not acceptable */
00296     T30_ERR_SEP_UNACCEPTABLE,   /*! Far end's selective polling address is not acceptable */
00297     T30_ERR_PSA_UNACCEPTABLE,   /*! Far end's polled sub-address is not acceptable */
00298     T30_ERR_SID_UNACCEPTABLE,   /*! Far end's sender identification is not acceptable */
00299     T30_ERR_PWD_UNACCEPTABLE,   /*! Far end's password is not acceptable */
00300     T30_ERR_TSA_UNACCEPTABLE,   /*! Far end's transmitting subscriber internet address is not acceptable */
00301     T30_ERR_IRA_UNACCEPTABLE,   /*! Far end's internet routing address is not acceptable */
00302     T30_ERR_CIA_UNACCEPTABLE,   /*! Far end's calling subscriber internet address is not acceptable */
00303     T30_ERR_ISP_UNACCEPTABLE,   /*! Far end's internet selective polling address is not acceptable */
00304     T30_ERR_CSA_UNACCEPTABLE    /*! Far end's called subscriber internet address is not acceptable */
00305 };
00306 
00307 /*!
00308     I/O modes for the T.30 protocol.
00309     These are allocated such that the lower 4 bits represents the variant of the modem - e.g. the
00310     particular bit rate selected.
00311 */
00312 enum
00313 {
00314     T30_MODEM_NONE = 0,
00315     T30_MODEM_PAUSE,
00316     T30_MODEM_CED,
00317     T30_MODEM_CNG,
00318     T30_MODEM_V21,
00319     T30_MODEM_V27TER,
00320     T30_MODEM_V29,
00321     T30_MODEM_V17,
00322     T30_MODEM_V34HDX,
00323     T30_MODEM_DONE
00324 };
00325 
00326 enum
00327 {
00328     T30_FRONT_END_SEND_STEP_COMPLETE = 0,
00329     /*! The current receive has completed. This is only needed to report an
00330         unexpected end of the receive operation, as might happen with T.38
00331         dying. */
00332     T30_FRONT_END_RECEIVE_COMPLETE,
00333     T30_FRONT_END_SIGNAL_PRESENT,
00334     T30_FRONT_END_SIGNAL_ABSENT,
00335     T30_FRONT_END_CED_PRESENT,
00336     T30_FRONT_END_CNG_PRESENT
00337 };
00338 
00339 enum
00340 {
00341     /*! Support the V.27ter modem (2400, and 4800bps) for image transfer. */
00342     T30_SUPPORT_V27TER = 0x01,
00343     /*! Support the V.29 modem (9600, and 7200bps) for image transfer. */
00344     T30_SUPPORT_V29 = 0x02,
00345     /*! Support the V.17 modem (14400, 12000, 9600 and 7200bps) for image transfer. */
00346     T30_SUPPORT_V17 = 0x04,
00347     /*! Support the V.34 modem (up to 33,600bps) for image transfer. */
00348     T30_SUPPORT_V34HDX = 0x08,
00349     /*! Support the Internet aware FAX mode (no bit rate limit) for image transfer. */
00350     T30_SUPPORT_IAF = 0x10
00351 };
00352 
00353 enum
00354 {
00355     /*! No compression */
00356     T30_SUPPORT_NO_COMPRESSION = 0x01,
00357     /*! T.1 1D compression */
00358     T30_SUPPORT_T4_1D_COMPRESSION = 0x02,
00359     /*! T.4 2D compression */
00360     T30_SUPPORT_T4_2D_COMPRESSION = 0x04,
00361     /*! T.6 2D compression */
00362     T30_SUPPORT_T6_COMPRESSION = 0x08,
00363     /*! T.85 monochrome JBIG compression, with fixed L0 */
00364     T30_SUPPORT_T85_COMPRESSION = 0x10,
00365     /*! T.85 monochrome JBIG compression, with variable L0 */
00366     T30_SUPPORT_T85_L0_COMPRESSION = 0x20,
00367     /*! T.43 colour JBIG compression */
00368     T30_SUPPORT_T43_COMPRESSION = 0x40,
00369     /*! T.45 run length colour compression */
00370     T30_SUPPORT_T45_COMPRESSION = 0x80,
00371     /*! T.81 + T.30 Annex E colour JPEG compression */
00372     T30_SUPPORT_T81_COMPRESSION = 0x100,
00373     /*! T.81 + T.30 Annex K colour sYCC-JPEG compression */
00374     T30_SUPPORT_SYCC_T81_COMPRESSION = 0x200,
00375     /*! T.88 monochrome JBIG2 compression */
00376     T30_SUPPORT_T88_COMPRESSION = 0x400
00377 };
00378 
00379 enum
00380 {
00381     /*! Support standard FAX Y-resolution 98/100dpi */
00382     T30_SUPPORT_STANDARD_RESOLUTION = 0x01,
00383     /*! Support fine FAX Y-resolution 196/200dpi */
00384     T30_SUPPORT_FINE_RESOLUTION = 0x02,
00385     /*! Support super-fine FAX Y-resolution 392/400dpi */
00386     T30_SUPPORT_SUPERFINE_RESOLUTION = 0x04,
00387 
00388     /*! Support half FAX X-resolution 100/102dpi */
00389     T30_SUPPORT_R4_RESOLUTION = 0x10000,
00390     /*! Support standard FAX X-resolution 200/204dpi */
00391     T30_SUPPORT_R8_RESOLUTION = 0x20000,
00392     /*! Support double FAX X-resolution 400dpi */
00393     T30_SUPPORT_R16_RESOLUTION = 0x40000,
00394 
00395     /*! Support 300dpi x 300 dpi */
00396     T30_SUPPORT_300_300_RESOLUTION = 0x100000,
00397     /*! Support 400dpi x 400 dpi */
00398     T30_SUPPORT_400_400_RESOLUTION = 0x200000,
00399     /*! Support 600dpi x 600 dpi */
00400     T30_SUPPORT_600_600_RESOLUTION = 0x400000,
00401     /*! Support 1200dpi x 1200 dpi */
00402     T30_SUPPORT_1200_1200_RESOLUTION = 0x800000,
00403     /*! Support 300dpi x 600 dpi */
00404     T30_SUPPORT_300_600_RESOLUTION = 0x1000000,
00405     /*! Support 400dpi x 800 dpi */
00406     T30_SUPPORT_400_800_RESOLUTION = 0x2000000,
00407     /*! Support 600dpi x 1200 dpi */
00408     T30_SUPPORT_600_1200_RESOLUTION = 0x4000000
00409 };
00410 
00411 enum
00412 {
00413     T30_SUPPORT_215MM_WIDTH = 0x01,
00414     T30_SUPPORT_255MM_WIDTH = 0x02,
00415     T30_SUPPORT_303MM_WIDTH = 0x04,
00416 
00417     T30_SUPPORT_UNLIMITED_LENGTH = 0x10000,
00418     T30_SUPPORT_A4_LENGTH = 0x20000,
00419     T30_SUPPORT_B4_LENGTH = 0x40000,
00420     T30_SUPPORT_US_LETTER_LENGTH = 0x80000,
00421     T30_SUPPORT_US_LEGAL_LENGTH = 0x100000
00422 };
00423 
00424 enum
00425 {
00426     /*! Enable support of identification, through the SID and/or PWD frames. */
00427     T30_SUPPORT_IDENTIFICATION = 0x01,
00428     /*! Enable support of selective polling, through the SEP frame. */
00429     T30_SUPPORT_SELECTIVE_POLLING = 0x02,
00430     /*! Enable support of polling sub-addressing, through the PSA frame. */
00431     T30_SUPPORT_POLLED_SUB_ADDRESSING = 0x04,
00432     /*! Enable support of multiple selective polling, through repeated used of the SEP and PSA frames. */
00433     T30_SUPPORT_MULTIPLE_SELECTIVE_POLLING = 0x08,
00434     /*! Enable support of sub-addressing, through the SUB frame. */
00435     T30_SUPPORT_SUB_ADDRESSING = 0x10,
00436     /*! Enable support of transmitting subscriber internet address, through the TSA frame. */
00437     T30_SUPPORT_TRANSMITTING_SUBSCRIBER_INTERNET_ADDRESS = 0x20,
00438     /*! Enable support of internet routing address, through the IRA frame. */
00439     T30_SUPPORT_INTERNET_ROUTING_ADDRESS = 0x40,
00440     /*! Enable support of calling subscriber internet address, through the CIA frame. */
00441     T30_SUPPORT_CALLING_SUBSCRIBER_INTERNET_ADDRESS = 0x80,
00442     /*! Enable support of internet selective polling address, through the ISP frame. */
00443     T30_SUPPORT_INTERNET_SELECTIVE_POLLING_ADDRESS = 0x100,
00444     /*! Enable support of called subscriber internet address, through the CSA frame. */
00445     T30_SUPPORT_CALLED_SUBSCRIBER_INTERNET_ADDRESS = 0x200,
00446     /*! Enable support of the field not valid (FNV) frame. */
00447     T30_SUPPORT_FIELD_NOT_VALID = 0x400,
00448     /*! Enable support of the command repeat (CRP) frame. */
00449     T30_SUPPORT_COMMAND_REPEAT = 0x800
00450 };
00451 
00452 enum
00453 {
00454     T30_IAF_MODE_T37 = 0x01,
00455     T30_IAF_MODE_T38 = 0x02,
00456     T30_IAF_MODE_FLOW_CONTROL = 0x04,
00457     /*! Continuous flow mode means data is sent as fast as possible, usually across
00458         the Internet, where speed is not constrained by a PSTN modem. */
00459     T30_IAF_MODE_CONTINUOUS_FLOW = 0x08,
00460     /*! No TCF means TCF is not exchanged. The end points must sort out usable speed
00461         issues locally. */
00462     T30_IAF_MODE_NO_TCF = 0x10,
00463     /*! No fill bits means do not insert fill bits, even if the T.30 messages request
00464         them. */
00465     T30_IAF_MODE_NO_FILL_BITS = 0x20,
00466     /*! No indicators means do not send indicator messages when using T.38. */
00467     T30_IAF_MODE_NO_INDICATORS = 0x40,
00468     /*! Use relaxed timers for T.38. This is appropriate when using TCP/TPKT for T.38,
00469         as there is no point in anything but a long backstop timeout in such a mode. */
00470     T30_IAF_MODE_RELAXED_TIMERS = 0x80
00471 };
00472 
00473 typedef struct
00474 {
00475     /*! \brief The identifier string (CSI, TSI, CIG). */
00476     char ident[T30_MAX_IDENT_LEN + 1];
00477     /*! \brief The sub-address string (SUB). */
00478     char sub_address[T30_MAX_IDENT_LEN + 1];
00479     /*! \brief The selective polling sub-address (SEP). */
00480     char selective_polling_address[T30_MAX_IDENT_LEN + 1];
00481     /*! \brief The polled sub-address (PSA). */
00482     char polled_sub_address[T30_MAX_IDENT_LEN + 1];
00483     /*! \brief The sender identification (SID). */
00484     char sender_ident[T30_MAX_IDENT_LEN + 1];
00485     /*! \brief The password (PWD). */
00486     char password[T30_MAX_IDENT_LEN + 1];
00487     /*! \brief Non-standard facilities (NSF). */
00488     uint8_t *nsf;
00489     size_t nsf_len;
00490     /*! \brief Non-standard facilities command (NSC). */
00491     uint8_t *nsc;
00492     size_t nsc_len;
00493     /*! \brief Non-standard facilities set-up (NSS). */
00494     uint8_t *nss;
00495     size_t nss_len;
00496     /*! \brief Transmitting subscriber internet address (TSA). */
00497     int tsa_type;
00498     char *tsa;
00499     size_t tsa_len;
00500     /*! \brief Internet routing address (IRA). */
00501     int ira_type;
00502     char *ira;
00503     size_t ira_len;
00504     /*! \brief Calling subscriber internet address (CIA). */
00505     int cia_type;
00506     char *cia;
00507     size_t cia_len;
00508     /*! \brief Internet selective polling address (ISP). */
00509     int isp_type;
00510     char *isp;
00511     size_t isp_len;
00512     /*! \brief Called subscriber internet address (CSA). */
00513     int csa_type;
00514     char *csa;
00515     size_t csa_len;
00516 } t30_exchanged_info_t;
00517 
00518 typedef struct
00519 {
00520     /*! \brief The current bit rate for image transfer. */
00521     int bit_rate;
00522     /*! \brief TRUE if error correcting mode is used. */
00523     int error_correcting_mode;
00524     /*! \brief The number of pages sent so far. */
00525     int pages_tx;
00526     /*! \brief The number of pages received so far. */
00527     int pages_rx;
00528     /*! \brief The number of pages in the file (<0 if not known). */
00529     int pages_in_file;
00530     /*! \brief The horizontal column-to-column resolution of the most recent page, in pixels per metre */
00531     int x_resolution;
00532     /*! \brief The vertical row-to-row resolution of the most recent page, in pixels per metre */
00533     int y_resolution;
00534     /*! \brief The number of horizontal pixels in the most recent page. */
00535     int width;
00536     /*! \brief The number of vertical pixels in the most recent page. */
00537     int length;
00538     /*! \brief The size of the image, in bytes */
00539     int image_size;
00540     /*! \brief The type of compression used between the FAX machines */
00541     int encoding;
00542     /*! \brief The number of bad pixel rows in the most recent page. */
00543     int bad_rows;
00544     /*! \brief The largest number of bad pixel rows in a block in the most recent page. */
00545     int longest_bad_row_run;
00546     /*! \brief The number of HDLC frame retries, if error correcting mode is used. */
00547     int error_correcting_mode_retries;
00548     /*! \brief Current status. */
00549     int current_status;
00550 #if 0
00551     /*! \brief The number of RTP events in this call. */
00552     int rtp_events;
00553     /*! \brief The number of RTN events in this call. */
00554     int rtn_events;
00555 #endif
00556 } t30_stats_t;
00557 
00558 #if defined(__cplusplus)
00559 extern "C"
00560 {
00561 #endif
00562 
00563 /*! Initialise a T.30 context.
00564     \brief Initialise a T.30 context.
00565     \param s The T.30 context.
00566     \param calling_party TRUE if the context is for a calling party. FALSE if the
00567            context is for an answering party.
00568     \param set_rx_type_handler
00569     \param set_rx_type_user_data
00570     \param set_tx_type_handler
00571     \param set_tx_type_user_data
00572     \param send_hdlc_handler
00573     \param send_hdlc_user_data
00574     \return A pointer to the context, or NULL if there was a problem. */
00575 SPAN_DECLARE(t30_state_t *) t30_init(t30_state_t *s,
00576                                      int calling_party,
00577                                      t30_set_handler_t *set_rx_type_handler,
00578                                      void *set_rx_type_user_data,
00579                                      t30_set_handler_t *set_tx_type_handler,
00580                                      void *set_tx_type_user_data,
00581                                      t30_send_hdlc_handler_t *send_hdlc_handler,
00582                                      void *send_hdlc_user_data);
00583 
00584 /*! Release a T.30 context.
00585     \brief Release a T.30 context.
00586     \param s The T.30 context.
00587     \return 0 for OK, else -1. */
00588 SPAN_DECLARE(int) t30_release(t30_state_t *s);
00589 
00590 /*! Free a T.30 context.
00591     \brief Free a T.30 context.
00592     \param s The T.30 context.
00593     \return 0 for OK, else -1. */
00594 SPAN_DECLARE(int) t30_free(t30_state_t *s);
00595 
00596 /*! Restart a T.30 context.
00597     \brief Restart a T.30 context.
00598     \param s The T.30 context.
00599     \return 0 for OK, else -1. */
00600 SPAN_DECLARE(int) t30_restart(t30_state_t *s);
00601 
00602 /*! Check if a T.30 call is still active. This may be used to regularly poll
00603     if the job has finished.
00604     \brief Check if a T.30 call is still active.
00605     \param s The T.30 context.
00606     \return TRUE for call still active, or FALSE for call completed. */
00607 SPAN_DECLARE(int) t30_call_active(t30_state_t *s);
00608 
00609 /*! Cleanup a T.30 context if the call terminates.
00610     \brief Cleanup a T.30 context if the call terminates.
00611     \param s The T.30 context. */
00612 SPAN_DECLARE(void) t30_terminate(t30_state_t *s);
00613 
00614 /*! Inform the T.30 engine of a status change in the front end (end of tx, rx signal change, etc.).
00615     \brief Inform the T.30 engine of a status change in the front end (end of tx, rx signal change, etc.).
00616     \param user_data The T.30 context.
00617     \param status The type of status change which occured. */
00618 SPAN_DECLARE(void) t30_front_end_status(void *user_data, int status);
00619 
00620 /*! Get a bit of received non-ECM image data.
00621     \brief Get a bit of received non-ECM image data.
00622     \param user_data An opaque pointer, which must point to the T.30 context.
00623     \return The next bit to transmit. */
00624 SPAN_DECLARE_NONSTD(int) t30_non_ecm_get_bit(void *user_data);
00625 
00626 /*! Get a byte of received non-ECM image data.
00627     \brief Get a byte of received non-ECM image data.
00628     \param user_data An opaque pointer, which must point to the T.30 context.
00629     \return The next byte to transmit. */
00630 SPAN_DECLARE(int) t30_non_ecm_get_byte(void *user_data);
00631 
00632 /*! Get a chunk of received non-ECM image data.
00633     \brief Get a bit of received non-ECM image data.
00634     \param user_data An opaque pointer, which must point to the T.30 context.
00635     \param buf The buffer to contain the data.
00636     \param max_len The maximum length of the chunk.
00637     \return The actual length of the chunk. */
00638 SPAN_DECLARE(int) t30_non_ecm_get_chunk(void *user_data, uint8_t buf[], int max_len);
00639 
00640 /*! Process a bit of received non-ECM image data.
00641     \brief Process a bit of received non-ECM image data
00642     \param user_data An opaque pointer, which must point to the T.30 context.
00643     \param bit The received bit. */
00644 SPAN_DECLARE_NONSTD(void) t30_non_ecm_put_bit(void *user_data, int bit);
00645 
00646 /*! Process a byte of received non-ECM image data.
00647     \brief Process a byte of received non-ECM image data
00648     \param user_data An opaque pointer, which must point to the T.30 context.
00649     \param byte The received byte. */
00650 SPAN_DECLARE(void) t30_non_ecm_put_byte(void *user_data, int byte);
00651 
00652 /*! Process a chunk of received non-ECM image data.
00653     \brief Process a chunk of received non-ECM image data
00654     \param user_data An opaque pointer, which must point to the T.30 context.
00655     \param buf The buffer containing the received data.
00656     \param len The length of the data in buf. */
00657 SPAN_DECLARE(void) t30_non_ecm_put_chunk(void *user_data, const uint8_t buf[], int len);
00658 
00659 /*! Process a received HDLC frame.
00660     \brief Process a received HDLC frame.
00661     \param user_data The T.30 context.
00662     \param msg The HDLC message.
00663     \param len The length of the message, in octets.
00664     \param ok TRUE if the frame was received without error. */
00665 SPAN_DECLARE_NONSTD(void) t30_hdlc_accept(void *user_data, const uint8_t msg[], int len, int ok);
00666 
00667 /*! Report the passage of time to the T.30 engine.
00668     \brief Report the passage of time to the T.30 engine.
00669     \param s The T.30 context.
00670     \param samples The time change in 1/8000th second steps. */
00671 SPAN_DECLARE(void) t30_timer_update(t30_state_t *s, int samples);
00672 
00673 /*! Get the current transfer statistics for the file being sent or received.
00674     \brief Get the current transfer statistics.
00675     \param s The T.30 context.
00676     \param t A pointer to a buffer for the statistics. */
00677 SPAN_DECLARE(void) t30_get_transfer_statistics(t30_state_t *s, t30_stats_t *t);
00678 
00679 /*! Request a local interrupt of FAX exchange.
00680     \brief Request a local interrupt of FAX exchange.
00681     \param s The T.30 context.
00682     \param state TRUE to enable interrupt request, else FALSE. */
00683 SPAN_DECLARE(void) t30_local_interrupt_request(t30_state_t *s, int state);
00684 
00685 /*! Allow remote interrupts of FAX exchange.
00686     \brief Allow remote interrupts of FAX exchange.
00687     \param s The T.30 context.
00688     \param state TRUE to allow interruptd, else FALSE. */
00689 SPAN_DECLARE(void) t30_remote_interrupts_allowed(t30_state_t *s, int state);
00690 
00691 #if defined(__cplusplus)
00692 }
00693 #endif
00694 
00695 #endif
00696 /*- End of file ------------------------------------------------------------*/