/* * SpanDSP - a series of DSP components for telephony * * t30.h - definitions for T.30 fax processing * * Written by Steve Underwood <steveu@coppice.org> * * Copyright (C) 2003 Steve Underwood * * All rights reserved. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License version 2, as * published by the Free Software Foundation. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program; if not, write to the Free Software * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. * * $Id: t30.h,v 1.77 2007/08/02 13:55:48 steveu Exp $ *//*! \file */#if !defined(_SPANDSP_T30_H_)#define _SPANDSP_T30_H_/*! \page t30_page T.30 FAX protocol handling\section t30_page_sec_1 What does it do?The T.30 protocol is the core protocol used for FAX transmission. This moduleimplements most of its key featrues. It does not interface to the outside work.Seperate modules do that for T.38, analogue line, and other forms of FAXcommunication.Current features of this module include:    - FAXing to and from multi-page TIFF/F files, whose images are one of the standard      FAX sizes.    - T.4 1D (MH), T.4 2D,(MR) and T.6 (MMR) compression.    - Error correction (ECM)    - All standard resolutions and page sizes\section t30_page_sec_2 How does it work?Some of the following is paraphrased from some notes found a while ago on the Internet.I cannot remember exactly where they came from, but they are useful.The answer (CED) toneThe T.30 standard says an answering fax device must send CED (a 2100Hz tone) forapproximately 3 seconds before sending the first handshake message. Some machinessend an 1100Hz or 1850Hz tone, and some send no tone at all. In fact, this answertone is so unpredictable, it cannot really be used. It should, however, always begenerated according to the specification.Common Timing DeviationsThe T.30 spec. specifies a number of time-outs. For example, after dialing a number,a calling fax system should listen for a response for 35 seconds before giving up.These time-out periods are as follows:     * T1 - 35+-5s: the maximum time for which two fax system will attempt to identify each other    * T2 - 6+-1s:  a time-out used to start the sequence for changing transmit parameters    * T3 - 10+-5s: a time-out used in handling operator interrupts    * T5 - 60+-5s: a time-out used in error correction modeThese time-outs are sometimes misinterpreted. In addition, they are routinelyignored, sometimes with good reason. For example, after placing a call, thecalling fax system is supposed to wait for 35 seconds before giving up. If theanswering unit does not answer on the first ring or if a voice answering machineis connected to the line, or if there are many delays through the network,the delay before answer can be much longer than 35 seconds. Fax units that support error correction mode (ECM) can respond to a post-imagehandshake message with a receiver not ready (RNR) message. The calling unit thenqueries the receiving fax unit with a receiver ready (RR) message. If theanswering unit is still busy (printing for example), it will repeat the RNRmessage. According to the T.30 standard, this sequence (RR/RNR RR/RNR) can berepeated for up to the end of T5 (60+-5s). However, many fax systemsignore the time-out and will continue the sequence indefinitely, unless the usermanually overrides. All the time-outs are subject to alteration, and sometimes misuse. Good T.30implementations must do the right thing, and tolerate others doing the wrong thing. Variations in the inter-carrier gapT.30 specifies 75+-20ms of silence between signals using different modulationschemes. Examples are between the end of a DCS signal and the start of a TCF signal,and between the end of an image and the start of a post-image signal. Many fax systemsviolate this requirement, especially for the silent period between DCS and TCF.This may be stretched to well over 100ms. If this period is too long, it can interfere withhandshake signal error recovery, should a packet be corrupted on the line. Systemsshould ensure they stay within the prescribed T.30 limits, and be tolerant of othersbeing out of spec.. Other timing variationsTesting is required to determine the ability of a fax system to handlevariations in the duration of pauses between unacknowledged handshake messagerepetitions, and also in the pauses between the receipt of a handshake command andthe start of a response to that command. In order to reduce the totaltransmission time, many fax systems start sending a response message before theend of the command has been received. Other deviations from the T.30 standardThere are many other commonly encountered variations between machines, including:    * frame sequence deviations    * preamble and flag sequence variations    * improper EOM usage    * unusual data rate fallback sequences    * common training pattern detection algorithms    * image transmission deviations    * use of the talker echo protect tone    * image padding and short lines    * RTP/RTN handshake message usage    * long duration lines    * nonstandard disconnect sequences    * DCN usage*/#define T30_MAX_DIS_DTC_DCS_LEN     22#define T30_MAX_IDENT_LEN           21#define T30_MAX_LOCAL_NSF_LEN       100typedef struct t30_state_s t30_state_t;/*!    T.30 phase B callback handler.    \brief T.30 phase B callback handler.    \param s The T.30 context.    \param user_data An opaque pointer.    \param result The phase B event code.*/typedef void (t30_phase_b_handler_t)(t30_state_t *s, void *user_data, int result);/*!    T.30 phase D callback handler.    \brief T.30 phase D callback handler.    \param s The T.30 context.    \param user_data An opaque pointer.    \param result The phase D event code.*/typedef void (t30_phase_d_handler_t)(t30_state_t *s, void *user_data, int result);/*!    T.30 phase E callback handler.    \brief T.30 phase E callback handler.    \param s The T.30 context.    \param user_data An opaque pointer.    \param completion_code The phase E completion code.*/typedef void (t30_phase_e_handler_t)(t30_state_t *s, void *user_data, int completion_code);/*!    T.30 document handler.    \brief T.30 document handler.    \param s The T.30 context.    \param user_data An opaque pointer.    \param result The document event code.*/typedef int (t30_document_handler_t)(t30_state_t *s, void *user_data, int status);/*!    T.30 set a receive or transmit type handler.    \brief T.30 set a receive or transmit type handler.    \param user_data An opaque pointer.    \param type The modem, tone or silence to be sent or received.    \param short_train TRUE if the short training sequence should be used (where one exists).    \param use_hdlc FALSE for bit stream, TRUE for HDLC framing.*/typedef void (t30_set_handler_t)(void *user_data, int type, int short_train, int use_hdlc);/*!    T.30 send HDLC handler.    \brief T.30 send HDLC handler.    \param user_data An opaque pointer.    \param msg The HDLC message.    \param len The length of the message.*/typedef void (t30_send_hdlc_handler_t)(void *user_data, const uint8_t *msg, int len);/*!    T.30 protocol completion codes, at phase E.*/enum{    T30_ERR_OK = 0,         /*! OK */    /* Link problems */    T30_ERR_CEDTONE,        /*! The CED tone exceeded 5s */    T30_ERR_T0_EXPIRED,     /*! Timed out waiting for initial communication */    T30_ERR_T1_EXPIRED,     /*! Timed out waiting for the first message */    T30_ERR_T3_EXPIRED,     /*! Timed out waiting for procedural interrupt */    T30_ERR_HDLC_CARRIER,   /*! The HDLC carrier did not stop in a timely manner */    T30_ERR_CANNOT_TRAIN,   /*! Failed to train with any of the compatible modems */    T30_ERR_OPERINTFAIL,    /*! Operator intervention failed */    T30_ERR_INCOMPATIBLE,   /*! Far end is not compatible */    T30_ERR_RX_INCAPABLE,   /*! Far end is not able to receive */    T30_ERR_TX_INCAPABLE,   /*! Far end is not able to transmit */    T30_ERR_NORESSUPPORT,   /*! Far end cannot receive at the resolution of the image */    T30_ERR_NOSIZESUPPORT,  /*! Far end cannot receive at the size of image */    T30_ERR_UNEXPECTED,     /*! Unexpected message received */    /* TIFF file problems */    T30_ERR_FILEERROR,      /*! TIFF/F file cannot be opened */    T30_ERR_NOPAGE,         /*! TIFF/F page not found */    T30_ERR_BADTIFF,        /*! TIFF/F format is not compatible */    /* Phase E status values returned to a transmitter */    T30_ERR_BADDCSTX,       /*! Received bad response to DCS or training */    T30_ERR_BADPGTX,        /*! Received a DCN from remote after sending a page */    T30_ERR_ECMPHDTX,       /*! Invalid ECM response received from receiver */    T30_ERR_T5_EXPIRED,     /*! Timed out waiting for receiver ready (ECM mode) */    T30_ERR_GOTDCNTX,       /*! Received a DCN while waiting for a DIS */    T30_ERR_INVALRSPTX,     /*! Invalid response after sending a page */    T30_ERR_NODISTX,        /*! Received other than DIS while waiting for DIS */    T30_ERR_PHBDEADTX,      /*! Received no response to DCS, training or TCF */    T30_ERR_PHDDEADTX,      /*! No response after sending a page */    /* Phase E status values returned to a receiver */    T30_ERR_ECMPHDRX,       /*! Invalid ECM response received from transmitter */    T30_ERR_GOTDCSRX,       /*! DCS received while waiting for DTC */    T30_ERR_INVALCMDRX,     /*! Unexpected command after page received */    T30_ERR_NOCARRIERRX,    /*! Carrier lost during fax receive */    T30_ERR_NOEOLRX,        /*! Timed out while waiting for EOL (end Of line) */    T30_ERR_NOFAXRX,        /*! Timed out while waiting for first line */    T30_ERR_T2EXPDCNRX,     /*! Timer T2 expired while waiting for DCN */    T30_ERR_T2EXPDRX,       /*! Timer T2 expired while waiting for phase D */    T30_ERR_T2EXPFAXRX,     /*! Timer T2 expired while waiting for fax page */    T30_ERR_T2EXPMPSRX,     /*! Timer T2 expired while waiting for next fax page */    T30_ERR_T2EXPRRRX,      /*! Timer T2 expired while waiting for RR command */    T30_ERR_T2EXPRX,        /*! Timer T2 expired while waiting for NSS, DCS or MCF */    T30_ERR_DCNWHYRX,       /*! Unexpected DCN while waiting for DCS or DIS */    T30_ERR_DCNDATARX,      /*! Unexpected DCN while waiting for image data */    T30_ERR_DCNFAXRX,       /*! Unexpected DCN while waiting for EOM, EOP or MPS */    T30_ERR_DCNPHDRX,       /*! Unexpected DCN after EOM or MPS sequence */    T30_ERR_DCNRRDRX,       /*! Unexpected DCN after RR/RNR sequence */    T30_ERR_DCNNORTNRX,     /*! Unexpected DCN after requested retransmission */    T30_ERR_BADPAGE,        /*! TIFF/F page number tag missing */    T30_ERR_BADTAG,         /*! Incorrect values for TIFF/F tags */    T30_ERR_BADTIFFHDR,     /*! Bad TIFF/F header - incorrect values in fields */    T30_ERR_NODATA,         /*! Data requested is not available (NSF, DIS, DCS) */    T30_ERR_NOMEM,          /*! Cannot allocate memory for more pages */    T30_ERR_NOPOLL,         /*! Poll not accepted */    T30_ERR_RETRYDCN,       /*! Disconnected after permitted retries */    T30_ERR_CALLDROPPED     /*! The call dropped prematurely */};/*!    I/O modes for the T.30 protocol.*/enum{    T30_MODEM_NONE = 0,    T30_MODEM_PAUSE,    T30_MODEM_CED,    T30_MODEM_CNG,    T30_MODEM_V21,    T30_MODEM_V27TER_2400,    T30_MODEM_V27TER_4800,    T30_MODEM_V29_7200,    T30_MODEM_V29_9600,    T30_MODEM_V17_7200,    T30_MODEM_V17_9600,    T30_MODEM_V17_12000,    T30_MODEM_V17_14400,    T30_MODEM_DONE};enum{    T30_FRONT_END_SEND_STEP_COMPLETE = 0,    T30_FRONT_END_SEND_COMPLETE,    /*! The current receive has completed. This is only needed to report an        unexpected end of the receive operation, as might happen with T.38        dying. */    T30_FRONT_END_RECEIVE_COMPLETE,    T30_FRONT_END_SIGNAL_PRESENT,    T30_FRONT_END_SIGNAL_ABSENT};enum{    T30_SUPPORT_V27TER = 0x01,    T30_SUPPORT_V29 = 0x02,    T30_SUPPORT_V17 = 0x04,    T30_SUPPORT_V34 = 0x08,    T30_SUPPORT_IAF = 0x10,