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 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: t30.h,v 1.85 2007/11/30 12:20:35 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           21
00132 #define T30_MAX_LOCAL_NSF_LEN       100
00133 
00134 typedef struct t30_state_s t30_state_t;
00135 
00136 /*!
00137     T.30 phase B callback handler.
00138     \brief T.30 phase B callback handler.
00139     \param s The T.30 context.
00140     \param user_data An opaque pointer.
00141     \param result The phase B event code.
00142 */
00143 typedef void (t30_phase_b_handler_t)(t30_state_t *s, void *user_data, int result);
00144 
00145 /*!
00146     T.30 phase D callback handler.
00147     \brief T.30 phase D callback handler.
00148     \param s The T.30 context.
00149     \param user_data An opaque pointer.
00150     \param result The phase D event code.
00151 */
00152 typedef void (t30_phase_d_handler_t)(t30_state_t *s, void *user_data, int result);
00153 
00154 /*!
00155     T.30 phase E callback handler.
00156     \brief T.30 phase E callback handler.
00157     \param s The T.30 context.
00158     \param user_data An opaque pointer.
00159     \param completion_code The phase E completion code.
00160 */
00161 typedef void (t30_phase_e_handler_t)(t30_state_t *s, void *user_data, int completion_code);
00162 
00163 /*!
00164     T.30 document handler.
00165     \brief T.30 document handler.
00166     \param s The T.30 context.
00167     \param user_data An opaque pointer.
00168     \param result The document event code.
00169 */
00170 typedef int (t30_document_handler_t)(t30_state_t *s, void *user_data, int status);
00171 
00172 /*!
00173     T.30 set a receive or transmit type handler.
00174     \brief T.30 set a receive or transmit type handler.
00175     \param user_data An opaque pointer.
00176     \param type The modem, tone or silence to be sent or received.
00177     \param short_train TRUE if the short training sequence should be used (where one exists).
00178     \param use_hdlc FALSE for bit stream, TRUE for HDLC framing.
00179 */
00180 typedef void (t30_set_handler_t)(void *user_data, int type, int short_train, int use_hdlc);
00181 
00182 /*!
00183     T.30 send HDLC handler.
00184     \brief T.30 send HDLC handler.
00185     \param user_data An opaque pointer.
00186     \param msg The HDLC message.
00187     \param len The length of the message.
00188 */
00189 typedef void (t30_send_hdlc_handler_t)(void *user_data, const uint8_t *msg, int len);
00190 
00191 /*!
00192     T.30 protocol completion codes, at phase E.
00193 */
00194 enum
00195 {
00196     T30_ERR_OK = 0,         /*! OK */
00197 
00198     /* Link problems */
00199     T30_ERR_CEDTONE,        /*! The CED tone exceeded 5s */
00200     T30_ERR_T0_EXPIRED,     /*! Timed out waiting for initial communication */
00201     T30_ERR_T1_EXPIRED,     /*! Timed out waiting for the first message */
00202     T30_ERR_T3_EXPIRED,     /*! Timed out waiting for procedural interrupt */
00203     T30_ERR_HDLC_CARRIER,   /*! The HDLC carrier did not stop in a timely manner */
00204     T30_ERR_CANNOT_TRAIN,   /*! Failed to train with any of the compatible modems */
00205     T30_ERR_OPERINTFAIL,    /*! Operator intervention failed */
00206     T30_ERR_INCOMPATIBLE,   /*! Far end is not compatible */
00207     T30_ERR_RX_INCAPABLE,   /*! Far end is not able to receive */
00208     T30_ERR_TX_INCAPABLE,   /*! Far end is not able to transmit */
00209     T30_ERR_NORESSUPPORT,   /*! Far end cannot receive at the resolution of the image */
00210     T30_ERR_NOSIZESUPPORT,  /*! Far end cannot receive at the size of image */
00211     T30_ERR_UNEXPECTED,     /*! Unexpected message received */
00212 
00213     /* TIFF file problems */
00214     T30_ERR_FILEERROR,      /*! TIFF/F file cannot be opened */
00215     T30_ERR_NOPAGE,         /*! TIFF/F page not found */
00216     T30_ERR_BADTIFF,        /*! TIFF/F format is not compatible */
00217 
00218     /* Phase E status values returned to a transmitter */
00219     T30_ERR_BADDCSTX,       /*! Received bad response to DCS or training */
00220     T30_ERR_BADPGTX,        /*! Received a DCN from remote after sending a page */
00221     T30_ERR_ECMPHDTX,       /*! Invalid ECM response received from receiver */
00222     T30_ERR_T5_EXPIRED,     /*! Timed out waiting for receiver ready (ECM mode) */
00223     T30_ERR_GOTDCNTX,       /*! Received a DCN while waiting for a DIS */
00224     T30_ERR_INVALRSPTX,     /*! Invalid response after sending a page */
00225     T30_ERR_NODISTX,        /*! Received other than DIS while waiting for DIS */
00226     T30_ERR_PHBDEADTX,      /*! Received no response to DCS, training or TCF */
00227     T30_ERR_PHDDEADTX,      /*! No response after sending a page */
00228 
00229     /* Phase E status values returned to a receiver */
00230     T30_ERR_ECMPHDRX,       /*! Invalid ECM response received from transmitter */
00231     T30_ERR_GOTDCSRX,       /*! DCS received while waiting for DTC */
00232     T30_ERR_INVALCMDRX,     /*! Unexpected command after page received */
00233     T30_ERR_NOCARRIERRX,    /*! Carrier lost during fax receive */
00234     T30_ERR_NOEOLRX,        /*! Timed out while waiting for EOL (end Of line) */
00235     T30_ERR_NOFAXRX,        /*! Timed out while waiting for first line */
00236     T30_ERR_T2EXPDCNRX,     /*! Timer T2 expired while waiting for DCN */
00237     T30_ERR_T2EXPDRX,       /*! Timer T2 expired while waiting for phase D */
00238     T30_ERR_T2EXPFAXRX,     /*! Timer T2 expired while waiting for fax page */
00239     T30_ERR_T2EXPMPSRX,     /*! Timer T2 expired while waiting for next fax page */
00240     T30_ERR_T2EXPRRRX,      /*! Timer T2 expired while waiting for RR command */
00241     T30_ERR_T2EXPRX,        /*! Timer T2 expired while waiting for NSS, DCS or MCF */
00242     T30_ERR_DCNWHYRX,       /*! Unexpected DCN while waiting for DCS or DIS */
00243     T30_ERR_DCNDATARX,      /*! Unexpected DCN while waiting for image data */
00244     T30_ERR_DCNFAXRX,       /*! Unexpected DCN while waiting for EOM, EOP or MPS */
00245     T30_ERR_DCNPHDRX,       /*! Unexpected DCN after EOM or MPS sequence */
00246     T30_ERR_DCNRRDRX,       /*! Unexpected DCN after RR/RNR sequence */
00247     T30_ERR_DCNNORTNRX,     /*! Unexpected DCN after requested retransmission */
00248 
00249     T30_ERR_BADPAGE,        /*! TIFF/F page number tag missing */
00250     T30_ERR_BADTAG,         /*! Incorrect values for TIFF/F tags */
00251     T30_ERR_BADTIFFHDR,     /*! Bad TIFF/F header - incorrect values in fields */
00252     T30_ERR_NODATA,         /*! Data requested is not available (NSF, DIS, DCS) */
00253     T30_ERR_NOMEM,          /*! Cannot allocate memory for more pages */
00254     T30_ERR_NOPOLL,         /*! Poll not accepted */
00255     T30_ERR_RETRYDCN,       /*! Disconnected after permitted retries */
00256     T30_ERR_CALLDROPPED     /*! The call dropped prematurely */
00257 };
00258 
00259 /*!
00260     I/O modes for the T.30 protocol.
00261 */
00262 enum
00263 {
00264     T30_MODEM_NONE = 0,
00265     T30_MODEM_PAUSE,
00266     T30_MODEM_CED,
00267     T30_MODEM_CNG,
00268     T30_MODEM_V21,
00269     T30_MODEM_V27TER_2400,
00270     T30_MODEM_V27TER_4800,
00271     T30_MODEM_V29_7200,
00272     T30_MODEM_V29_9600,
00273     T30_MODEM_V17_7200,
00274     T30_MODEM_V17_9600,
00275     T30_MODEM_V17_12000,
00276     T30_MODEM_V17_14400,
00277     T30_MODEM_DONE
00278 };
00279 
00280 enum
00281 {
00282     T30_FRONT_END_SEND_STEP_COMPLETE = 0,
00283     T30_FRONT_END_SEND_COMPLETE,
00284     /*! The current receive has completed. This is only needed to report an
00285         unexpected end of the receive operation, as might happen with T.38
00286         dying. */
00287     T30_FRONT_END_RECEIVE_COMPLETE,
00288     T30_FRONT_END_SIGNAL_PRESENT,
00289     T30_FRONT_END_SIGNAL_ABSENT
00290 };
00291 
00292 enum
00293 {
00294     T30_SUPPORT_V27TER = 0x01,
00295     T30_SUPPORT_V29 = 0x02,
00296     T30_SUPPORT_V17 = 0x04,
00297     T30_SUPPORT_V34 = 0x08,
00298     T30_SUPPORT_IAF = 0x10,
00299 };
00300 
00301 enum
00302 {
00303     T30_SUPPORT_NO_COMPRESSION = 0x01,
00304     T30_SUPPORT_T4_1D_COMPRESSION = 0x02,
00305     T30_SUPPORT_T4_2D_COMPRESSION = 0x04,
00306     T30_SUPPORT_T6_COMPRESSION = 0x08,
00307     T30_SUPPORT_T85_COMPRESSION = 0x10,     /* Monochrome JBIG */
00308     T30_SUPPORT_T43_COMPRESSION = 0x20,     /* Colour JBIG */
00309     T30_SUPPORT_T45_COMPRESSION = 0x40      /* Run length colour compression */
00310 };
00311 
00312 enum
00313 {
00314     T30_SUPPORT_STANDARD_RESOLUTION = 0x01,
00315     T30_SUPPORT_FINE_RESOLUTION = 0x02,
00316     T30_SUPPORT_SUPERFINE_RESOLUTION = 0x04,
00317 
00318     T30_SUPPORT_R4_RESOLUTION = 0x10000,
00319     T30_SUPPORT_R8_RESOLUTION = 0x20000,
00320     T30_SUPPORT_R16_RESOLUTION = 0x40000,
00321 
00322     T30_SUPPORT_300_300_RESOLUTION = 0x100000,
00323     T30_SUPPORT_400_400_RESOLUTION = 0x200000,
00324     T30_SUPPORT_600_600_RESOLUTION = 0x400000,
00325     T30_SUPPORT_1200_1200_RESOLUTION = 0x800000,
00326     T30_SUPPORT_300_600_RESOLUTION = 0x1000000,
00327     T30_SUPPORT_400_800_RESOLUTION = 0x2000000,
00328     T30_SUPPORT_600_1200_RESOLUTION = 0x4000000
00329 };
00330 
00331 enum
00332 {
00333     T30_SUPPORT_215MM_WIDTH = 0x01,
00334     T30_SUPPORT_255MM_WIDTH = 0x02,
00335     T30_SUPPORT_303MM_WIDTH = 0x04,
00336 
00337     T30_SUPPORT_UNLIMITED_LENGTH = 0x10000,
00338     T30_SUPPORT_A4_LENGTH = 0x20000,
00339     T30_SUPPORT_B4_LENGTH = 0x40000,
00340     T30_SUPPORT_US_LETTER_LENGTH = 0x80000,
00341     T30_SUPPORT_US_LEGAL_LENGTH = 0x100000
00342 };
00343 
00344 enum
00345 {
00346     T30_SUPPORT_SEP = 0x01,
00347     T30_SUPPORT_PSA = 0x02
00348 };
00349 
00350 enum
00351 {
00352     T30_IAF_MODE_T37 = 0x01,
00353     T30_IAF_MODE_T38 = 0x02,
00354     T30_IAF_MODE_FLOW_CONTROL = 0x04,
00355     /*! Continuous flow mode means data is sent as fast as possible, usually across
00356         the Internet, where speed is not constrained by a PSTN modem. */
00357     T30_IAF_MODE_CONTINUOUS_FLOW = 0x08,
00358     /*! No TCF means TCF is not exchanged. The end points must sort out usable speed
00359         issues locally. */
00360     T30_IAF_MODE_NO_TCF = 0x10,
00361     /*! No fill bits means do not insert fill bits, even if the T.30 messages request
00362         them. */
00363     T30_IAF_MODE_NO_FILL_BITS = 0x20,
00364     /*! No indicators means do not send indicator messages when using T.38. */
00365     T30_IAF_MODE_NO_INDICATORS = 0x40
00366 };
00367 
00368 /*!
00369     T.30 FAX channel descriptor. This defines the state of a single working
00370     instance of a T.30 FAX channel.
00371 */
00372 struct t30_state_s
00373 {
00374     /* This must be kept the first thing in the structure, so it can be pointed
00375        to reliably as the structures change over time. */
00376     t4_state_t t4;
00377 
00378     /*! \brief TRUE if behaving as the calling party */
00379     int calling_party;
00380     /*! \brief If >= 0 this is a minimum number of bits to force in non-ECM rows, regardless
00381         of the negotiated minimum row time. */
00382     int forced_min_non_ecm_row_bits;
00383     
00384     /*! \brief The received DCS, formatted as an ASCII string, for inclusion
00385                in the TIFF file. */
00386     char rx_dcs_string[T30_MAX_DIS_DTC_DCS_LEN*3 + 1];
00387     /*! \brief The local identifier string. */
00388     char local_ident[T30_MAX_IDENT_LEN];
00389     /*! \brief The identifier string supplied by the remote FAX machine. */
00390     char far_ident[T30_MAX_IDENT_LEN];
00391     /*! \brief The sub-address string to be sent to the remote FAX machine. */
00392     char local_sub_address[T30_MAX_IDENT_LEN];
00393     /*! \brief The sub-address string supplied by the remote FAX machine. */
00394     char far_sub_address[T30_MAX_IDENT_LEN];
00395     /*! \brief The selective polling sub-address supplied by the remote FAX machine. */
00396     char sep_address[T30_MAX_IDENT_LEN];
00397     /*! \brief The polled sub-address supplied by the remote FAX machine. */
00398     char psa_address[T30_MAX_IDENT_LEN];
00399     /*! \brief A password to be associated with the T.30 context. */
00400     char local_password[T30_MAX_IDENT_LEN];
00401     /*! \brief A password expected from the far end. */
00402     char far_password[T30_MAX_IDENT_LEN];
00403     /*! \brief The text which will be used in FAX page header. No text results
00404                in no header line. */
00405     char header_info[50 + 1];
00406     /*! \brief The country of origin of the remote machine, if known, else NULL. */
00407     const char *country;
00408     /*! \brief The vendor of the remote machine, if known, else NULL. */
00409     const char *vendor;
00410     /*! \brief The model of the remote machine, if known, else NULL. */
00411     const char *model;
00412     uint8_t local_nsf[T30_MAX_LOCAL_NSF_LEN];
00413     int local_nsf_len;
00414 
00415     /*! \brief A pointer to a callback routine to be called when phase B events
00416         occur. */
00417     t30_phase_b_handler_t *phase_b_handler;
00418     /*! \brief An opaque pointer supplied in event B callbacks. */
00419     void *phase_b_user_data;
00420     /*! \brief A pointer to a callback routine to be called when phase D events
00421         occur. */
00422     t30_phase_d_handler_t *phase_d_handler;
00423     /*! \brief An opaque pointer supplied in event D callbacks. */
00424     void *phase_d_user_data;
00425     /*! \brief A pointer to a callback routine to be called when phase E events
00426         occur. */
00427     t30_phase_e_handler_t *phase_e_handler;
00428     /*! \brief An opaque pointer supplied in event E callbacks. */
00429     void *phase_e_user_data;
00430 
00431     /*! \brief A pointer to a callback routine to be called when document events
00432         (e.g. end of transmitted document) occur. */
00433     t30_document_handler_t *document_handler;
00434     /*! \brief An opaque pointer supplied in document callbacks. */
00435     void *document_user_data;
00436 
00437     t30_set_handler_t *set_rx_type_handler;
00438     void *set_rx_type_user_data;
00439     t30_set_handler_t *set_tx_type_handler;
00440     void *set_tx_type_user_data;
00441 
00442     t30_send_hdlc_handler_t *send_hdlc_handler;
00443     void *send_hdlc_user_data;
00444    
00445     int phase;
00446     int next_phase;
00447     int state;
00448     int step;
00449 
00450     uint8_t dcs_frame[T30_MAX_DIS_DTC_DCS_LEN];
00451     int dcs_len;
00452     uint8_t dis_dtc_frame[T30_MAX_DIS_DTC_DCS_LEN];
00453     int dis_dtc_len;
00454     /*! \brief TRUE if a valid DIS has been received from the far end. */
00455     int dis_received;
00456     /*! \brief TRUE if a valid passwrod has been received from the far end. */
00457     int far_password_ok;
00458 
00459     /*! \brief A flag to indicate a message is in progress. */
00460     int in_message;
00461 
00462     /*! \brief TRUE if the short training sequence should be used. */
00463     int short_train;
00464 
00465     /*! \brief A count of the number of bits in the trainability test. */
00466     int training_test_bits;
00467     int training_current_zeros;
00468     int training_most_zeros;
00469 
00470     /*! \brief The current fallback step for the fast message transfer modem. */
00471     int current_fallback;
00472     /*! \brief The subset of supported modems allowed at the current time, allowing for negotiation. */
00473     int current_permitted_modems;
00474     /*! \brief TRUE if a carrier is present. Otherwise FALSE. */
00475     int rx_signal_present;
00476     /*! \brief TRUE if a modem has trained correctly. */
00477     int rx_trained;
00478     int current_rx_type;
00479     int current_tx_type;
00480 
00481     /*! \brief T0 is the answer timeout when calling another FAX machine.
00482         Placing calls is handled outside the FAX processing, but this timeout keeps
00483         running until V.21 modulation is sent or received.
00484         T1 is the remote terminal identification timeout (in audio samples). */
00485     int timer_t0_t1;
00486     /*! \brief T2 is the HDLC command timeout.
00487                T4 is the HDLC response timeout (in audio samples). */
00488     int timer_t2_t4;
00489     /*! \brief TRUE if the T2/T4 timer is actually timing T4 */
00490     int timer_is_t4;
00491     /*! \brief Procedural interrupt timeout (in audio samples). */
00492     int timer_t3;
00493     /*! \brief This is only used in error correcting mode. */
00494     int timer_t5;
00495     /*! \brief This is only used in full duplex (e.g. ISDN) modes. */
00496     int timer_t6;
00497     /*! \brief This is only used in full duplex (e.g. ISDN) modes. */
00498     int timer_t7;
00499     /*! \brief This is only used in full duplex (e.g. ISDN) modes. */
00500     int timer_t8;
00501 
00502     int far_end_detected;
00503 
00504     int local_interrupt_pending;
00505     int crp_enabled;
00506     int line_encoding;
00507     int output_encoding;
00508     uint8_t min_scan_time_code;
00509     int x_resolution;
00510     int y_resolution;
00511     t4_image_width_t image_width;
00512     int retries;
00513     /*! \brief TRUE if error correcting mode is used. */
00514     int error_correcting_mode;
00515     int ppr_count;
00516     int receiver_not_ready_count;
00517     int octets_per_ecm_frame;
00518     uint8_t ecm_data[256][260];
00519     int16_t ecm_len[256];
00520     uint8_t ecm_frame_map[3 + 32];
00521     
00522     /*! \brief The current page number in ECM mode */
00523     int ecm_page;
00524 
00525     /*! \brief The current block number in ECM mode */
00526     int ecm_block;
00527     
00528     /*! \brief The number of frames in the current block number in ECM mode */
00529     int ecm_frames;
00530 
00531     /*! \brief The number of frames in the current burst of image transmission in ECM mode */
00532     int ecm_frames_this_burst;
00533     int ecm_current_frame;
00534     int ecm_at_page_end;
00535     int next_tx_step;
00536     int next_rx_step;
00537     char rx_file[256];
00538     int rx_stop_page;
00539     char tx_file[256];
00540     int tx_start_page;
00541     int tx_stop_page;
00542     int current_status;
00543     int iaf;
00544     int supported_modems;
00545     int supported_compressions;
00546     int supported_resolutions;
00547     int supported_image_sizes;
00548     int supported_polling_features;
00549     int support_fnv;
00550     int ecm_allowed;
00551     
00552     int last_pps_fcf2;
00553     int ecm_first_bad_frame;
00554 
00555     /*! \brief Error and flow logging control */
00556     logging_state_t logging;
00557 };
00558 
00559 typedef struct
00560 {
00561     /*! \brief The current bit rate for image transfer. */
00562     int bit_rate;
00563     /*! \brief TRUE if error correcting mode is used. */
00564     int error_correcting_mode;
00565     /*! \brief The number of pages transferred so far. */
00566     int pages_transferred;
00567     /*! \brief The number of pages in the file (<0 if not known). */
00568     int pages_in_file;
00569     /*! \brief The number of horizontal pixels in the most recent page. */
00570     int width;
00571     /*! \brief The number of vertical pixels in the most recent page. */
00572     int length;
00573     /*! \brief The number of bad pixel rows in the most recent page. */
00574     int bad_rows;
00575     /*! \brief The largest number of bad pixel rows in a block in the most recent page. */
00576     int longest_bad_row_run;
00577     /*! \brief The horizontal column-to-column resolution of the page in pixels per metre */
00578     int x_resolution;
00579     /*! \brief The vertical row-to-row resolution of the page in pixels per metre */
00580     int y_resolution;
00581     /*! \brief The type of compression used between the FAX machines */
00582     int encoding;
00583     /*! \brief The size of the image, in bytes */
00584     int image_size;
00585     /*! \brief Current status */
00586     int current_status;
00587 } t30_stats_t;
00588 
00589 #if defined(__cplusplus)
00590 extern "C"
00591 {
00592 #endif
00593 
00594 /*! Initialise a T.30 context.
00595     \brief Initialise a T.30 context.
00596     \param s The T.30 context.
00597     \param calling_party TRUE if the context is for a calling party. FALSE if the
00598            context is for an answering party.
00599     \return A pointer to the context, or NULL if there was a problem. */
00600 t30_state_t *t30_init(t30_state_t *s,
00601                       int calling_party,
00602                       t30_set_handler_t *set_rx_type_handler,
00603                       void *set_rx_type_user_data,
00604                       t30_set_handler_t *set_tx_type_handler,
00605                       void *set_tx_type_user_data,
00606                       t30_send_hdlc_handler_t *send_hdlc_handler,
00607                       void *send_hdlc_user_data);
00608 
00609 /*! Release a T.30 context.
00610     \brief Release a T.30 context.
00611     \param s The T.30 context.
00612     \return 0 for OK, else -1. */
00613 int t30_release(t30_state_t *s);
00614 
00615 /*! Free a T.30 context.
00616     \brief Free a T.30 context.
00617     \param s The T.30 context.
00618     \return 0 for OK, else -1. */
00619 int t30_free(t30_state_t *s);
00620 
00621 /*! Restart a T.30 context.
00622     \brief Restart a T.30 context.
00623     \param s The T.30 context.
00624     \return 0 for OK, else -1. */
00625 int t30_restart(t30_state_t *s);
00626 
00627 /*! Cleanup a T.30 context if the call terminates.
00628     \brief Cleanup a T.30 context if the call terminates.
00629     \param s The T.30 context. */
00630 void t30_terminate(t30_state_t *s);
00631 
00632 /*! Return a text name for a T.30 frame type.
00633     \brief Return a text name for a T.30 frame type.
00634     \param x The frametype octet.
00635     \return A pointer to the text name for the frame type. If the frame type is
00636             not value, the string "???" is returned. */
00637 const char *t30_frametype(uint8_t x);
00638 
00639 /*! Decode a DIS, DTC or DCS frame, and log the contents.
00640     \brief Decode a DIS, DTC or DCS frame, and log the contents.
00641     \param s The T.30 context.
00642     \param dis A pointer to the frame to be decoded.
00643     \param len The length of the frame. */
00644 void t30_decode_dis_dtc_dcs(t30_state_t *s, const uint8_t *dis, int len);
00645 
00646 /*! Convert a phase E completion code to a short text description.
00647     \brief Convert a phase E completion code to a short text description.
00648     \param result The result code.
00649     \return A pointer to the description. */
00650 const char *t30_completion_code_to_str(int result);
00651 
00652 /*! Set Internet aware FAX (IAF) mode.
00653     \brief Set Internet aware FAX (IAF) mode.
00654     \param s The T.30 context.
00655     \param iaf TRUE for IAF, or FALSE for non-IAF. */
00656 void t30_set_iaf_mode(t30_state_t *s, int iaf);
00657 
00658 /*! Set the sub-address associated with a T.30 context.
00659     \brief Set the sub-address associated with a T.30 context.
00660     \param s The T.30 context.
00661     \param sub_address A pointer to the sub-address.
00662     \return 0 for OK, else -1. */
00663 int t30_set_local_sub_address(t30_state_t *s, const char *sub_address);
00664 
00665 /*! Set the header information associated with a T.30 context.
00666     \brief Set the header information associated with a T.30 context.
00667     \param s The T.30 context.
00668     \param info A pointer to the information string.
00669     \return 0 for OK, else -1. */
00670 int t30_set_header_info(t30_state_t *s, const char *info);
00671 
00672 /*! Set the local identifier associated with a T.30 context.
00673     \brief Set the local identifier associated with a T.30 context.
00674     \param s The T.30 context.
00675     \param id A pointer to the identifier.
00676     \return 0 for OK, else -1. */
00677 int t30_set_local_ident(t30_state_t *s, const char *id);
00678 
00679 int t30_set_local_nsf(t30_state_t *s, const uint8_t *nsf, int len);
00680 
00681 /*! Get the sub-address associated with a T.30 context.
00682     \brief Get the sub-address associated with a T.30 context.
00683     \param s The T.30 context.
00684     \param sub_address A pointer to a buffer for the sub-address.  The buffer
00685            should be at least 21 bytes long.
00686     \return the length of the string. */
00687 size_t t30_get_sub_address(t30_state_t *s, char *sub_address);
00688 
00689 /*! Get the header information associated with a T.30 context.
00690     \brief Get the header information associated with a T.30 context.
00691     \param s The T.30 context.
00692     \param sub_address A pointer to a buffer for the header information.  The buffer
00693            should be at least 51 bytes long.
00694     \return the length of the string. */
00695 size_t t30_get_header_info(t30_state_t *s, char *info);
00696 
00697 /*! Get the local FAX machine identifier associated with a T.30 context.
00698     \brief Get the local identifier associated with a T.30 context.
00699     \param s The T.30 context.
00700     \param id A pointer to a buffer for the identifier. The buffer should
00701            be at least 21 bytes long.
00702     \return the length of the string. */
00703 size_t t30_get_local_ident(t30_state_t *s, char *id);
00704 
00705 /*! Get the remote FAX machine identifier associated with a T.30 context.
00706     \brief Get the remote identifier associated with a T.30 context.
00707     \param s The T.30 context.
00708     \param id A pointer to a buffer for the identifier. The buffer should
00709            be at least 21 bytes long.
00710     \return the length of the string. */
00711 size_t t30_get_far_ident(t30_state_t *s, char *id);
00712 
00713 /*! Get the country of origin of the remote FAX machine associated with a T.30 context.
00714     \brief Get the country of origin of the remote FAX machine associated with a T.30 context.
00715     \param s The T.30 context.
00716     \return a pointer to the country name, or NULL if the country is not known. */
00717 const char *t30_get_far_country(t30_state_t *s);
00718 
00719 /*! Get the name of the vendor of the remote FAX machine associated with a T.30 context.
00720     \brief Get the name of the vendor of the remote FAX machine associated with a T.30 context.
00721     \param s The T.30 context.
00722     \return a pointer to the vendor name, or NULL if the vendor is not known. */
00723 const char *t30_get_far_vendor(t30_state_t *s);
00724 
00725 /*! Get the name of the model of the remote FAX machine associated with a T.30 context.
00726     \brief Get the name of the model of the remote FAX machine associated with a T.30 context.
00727     \param s The T.30 context.
00728     \return a pointer to the model name, or NULL if the model is not known. */
00729 const char *t30_get_far_model(t30_state_t *s);
00730 
00731 /*! Get the current transfer statistics for the file being sent or received.
00732     \brief Get the current transfer statistics.
00733     \param s The T.30 context.
00734     \param t A pointer to a buffer for the statistics. */
00735 void t30_get_transfer_statistics(t30_state_t *s, t30_stats_t *t);
00736 
00737 /*! Set a callback function for T.30 phase B handling.
00738     \brief Set a callback function for T.30 phase B handling.
00739     \param s The T.30 context.
00740     \param handler The callback function
00741     \param user_data An opaque pointer passed to the callback function. */
00742 void t30_set_phase_b_handler(t30_state_t *s, t30_phase_b_handler_t *handler, void *user_data);
00743 
00744 /*! Set a callback function for T.30 phase D handling.
00745     \brief Set a callback function for T.30 phase D handling.
00746     \param s The T.30 context.
00747     \param handler The callback function
00748     \param user_data An opaque pointer passed to the callback function. */
00749 void t30_set_phase_d_handler(t30_state_t *s, t30_phase_d_handler_t *handler, void *user_data);
00750 
00751 /*! Set a callback function for T.30 phase E handling.
00752     \brief Set a callback function for T.30 phase E handling.
00753     \param s The T.30 context.
00754     \param handler The callback function
00755     \param user_data An opaque pointer passed to the callback function. */
00756 void t30_set_phase_e_handler(t30_state_t *s, t30_phase_e_handler_t *handler, void *user_data);
00757 
00758 /*! Set a callback function for T.30 end of document handling.
00759     \brief Set a callback function for T.30 end of document handling.
00760     \param s The T.30 context.
00761     \param handler The callback function
00762     \param user_data An opaque pointer passed to the callback function. */
00763 void t30_set_document_handler(t30_state_t *s, t30_document_handler_t *handler, void *user_data);
00764 
00765 /*! Specify the file name of the next TIFF file to be received by a T.30
00766     context.
00767     \brief Set next receive file name.
00768     \param s The T.30 context.
00769     \param file The file name
00770     \param stop_page The maximum page to receive. -1 for no restriction. */
00771 void t30_set_rx_file(t30_state_t *s, const char *file, int stop_page);
00772 
00773 /*! Specify the file name of the next TIFF file to be transmitted by a T.30
00774     context.
00775     \brief Set next transmit file name.
00776     \param s The T.30 context.
00777     \param file The file name
00778     \param start_page The first page to send. -1 for no restriction.
00779     \param stop_page The last page to send. -1 for no restriction. */
00780 void t30_set_tx_file(t30_state_t *s, const char *file, int start_page, int stop_page);
00781 
00782 /*! Specify which modem types are supported by a T.30 context.
00783     \brief Specify supported modems.
00784     \param s The T.30 context.
00785     \param supported_modems Bit field list of the supported modems.
00786     \return 0 if OK, else -1. */
00787 int t30_set_supported_modems(t30_state_t *s, int supported_modems);
00788 
00789 /*! Specify a period of responding with receiver not ready.
00790     \brief Specify a period of responding with receiver not ready.
00791     \param s The T.30 context.
00792     \param count The number of times to report receiver not ready.
00793     \return 0 if OK, else -1. */
00794 int t30_set_receiver_not_ready(t30_state_t *s, int count);
00795 
00796 /*! Specify which compression types are supported by a T.30 context.
00797     \brief Specify supported compression types.
00798     \param s The T.30 context.
00799     \param supported_compressions Bit field list of the supported compression types.
00800     \return 0 if OK, else -1. */
00801 int t30_set_supported_compressions(t30_state_t *s, int supported_compressions);
00802 
00803 /*! Specify which resolutions are supported by a T.30 context.
00804     \brief Specify supported resolutions.
00805     \param s The T.30 context.
00806     \param supported_compressions Bit field list of the supported resolutions.
00807     \return 0 if OK, else -1. */
00808 int t30_set_supported_resolutions(t30_state_t *s, int supported_resolutions);
00809 
00810 /*! Specify which images sizes are supported by a T.30 context.
00811     \brief Specify supported image sizes.
00812     \param s The T.30 context.
00813     \param supported_image_sizes Bit field list of the supported widths and lengths.
00814     \return 0 if OK, else -1. */
00815 int t30_set_supported_image_sizes(t30_state_t *s, int supported_image_sizes);
00816 
00817 /*! Specify if error correction mode (ECM) is allowed by a T.30 context.
00818     \brief Select ECM capability.
00819     \param s The T.30 context.
00820     \param enabled TRUE for ECM capable, FALSE for not ECM capable.
00821     \return 0 if OK, else -1. */
00822 int t30_set_ecm_capability(t30_state_t *s, int enabled);
00823 
00824 /*! Specify a specific minimum number of bits per row for non-ECM image data
00825     generated by a T.30 context. This is useful for forcing no fill insertion
00826     for T.38.
00827     \brief Specify minimum bits per non-ECM row.
00828     \param s The T.30 context.
00829     \param bit -1 for no specified minimum, else the number of bits.
00830     \return 0 if OK, else -1. */
00831 int t30_set_min_non_ecm_row_bits(t30_state_t *s, int bits);
00832 
00833 /*! Specify the output encoding for TIFF files created during FAX reception.
00834     \brief Specify the output encoding for TIFF files created during FAX reception.
00835     \param s The T.30 context.
00836     \param encoding. The coding required. The options are T4_COMPRESSION_ITU_T4_1D,
00837            T4_COMPRESSION_ITU_T4_2D, T4_COMPRESSION_ITU_T6. T6 is usually the
00838            densest option, but support for it is broken in a number of software
00839            packages.
00840     \return 0 if OK, else -1. */
00841 int t30_set_rx_encoding(t30_state_t *s, int encoding);
00842 
00843 /*! Request a local interrupt of FAX exchange.
00844     \brief Request a local interrupt of FAX exchange.
00845     \param s The T.30 context.
00846     \param state TRUE to enable interrupt request, else FALSE. */
00847 void t30_local_interrupt_request(t30_state_t *s, int state);
00848 
00849 /*! Inform the T.30 engine of a status change in the front end (end of tx, rx signal change, etc.).
00850     \brief Inform the T.30 engine of a status change in the front end (end of tx, rx signal change, etc.).
00851     \param user_data The T.30 context.
00852     \param status The type of status change which occured. */
00853 void t30_front_end_status(void *user_data, int status);
00854 
00855 /*! Get a bit of received non-ECM image data.
00856     \brief Get a bit of received non-ECM image data.
00857     \param user_data An opaque pointer, which must point to the T.30 context.
00858     \return The next bit to transmit. */
00859 int t30_non_ecm_get_bit(void *user_data);
00860 
00861 /*! Get a byte of received non-ECM image data.
00862     \brief Get a byte of received non-ECM image data.
00863     \param user_data An opaque pointer, which must point to the T.30 context.
00864     \return The next byte to transmit. */
00865 int t30_non_ecm_get_byte(void *user_data);
00866 
00867 /*! Get a chunk of received non-ECM image data.
00868     \brief Get a bit of received non-ECM image data.
00869     \param user_data An opaque pointer, which must point to the T.30 context.
00870     \param buf The buffer to contain the data.
00871     \param max_len The maximum length of the chunk.
00872     \return The actual length of the chunk. */
00873 int t30_non_ecm_get_chunk(void *user_data, uint8_t buf[], int max_len);
00874 
00875 /*! Process a bit of received non-ECM image data.
00876     \brief Process a bit of received non-ECM image data
00877     \param user_data An opaque pointer, which must point to the T.30 context.
00878     \param bit The received bit. */
00879 void t30_non_ecm_put_bit(void *user_data, int bit);
00880 
00881 /*! Process a byte of received non-ECM image data.
00882     \brief Process a byte of received non-ECM image data
00883     \param user_data An opaque pointer, which must point to the T.30 context.
00884     \param byte The received byte. */
00885 void t30_non_ecm_put_byte(void *user_data, int byte);
00886 
00887 /*! Process a chunk of received non-ECM image data.
00888     \brief Process a chunk of received non-ECM image data
00889     \param user_data An opaque pointer, which must point to the T.30 context.
00890     \param buf The buffer containing the received data.
00891     \param len The length of the data in buf. */
00892 void t30_non_ecm_put_chunk(void *user_data, const uint8_t buf[], int len);
00893 
00894 /*! Process a received HDLC frame.
00895     \brief Process a received HDLC frame.
00896     \param s The T.30 context.
00897     \param msg The HDLC message.
00898     \param int The length of the message, in octets.
00899     \param ok TRUE if the frame was received without error. */
00900 void t30_hdlc_accept(void *user_data, const uint8_t *msg, int len, int ok);
00901 
00902 /*! Report the passage of time to the T.30 engine.
00903     \brief Report the passage of time to the T.30 engine.
00904     \param s The T.30 context.
00905     \param samples The time change in 1/8000th second steps. */
00906 void t30_timer_update(t30_state_t *s, int samples);
00907 
00908 #if defined(__cplusplus)
00909 }
00910 #endif
00911 
00912 #endif
00913 /*- End of file ------------------------------------------------------------*/

Generated on Tue Nov 4 12:36:28 2008 for libspandsp by  doxygen 1.4.7