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 as published by
00014  * the Free Software Foundation; either version 2 of the License, or
00015  * (at your option) any later version.
00016  *
00017  * This program is distributed in the hope that it will be useful,
00018  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00019  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00020  * GNU General Public License for more details.
00021  *
00022  * You should have received a copy of the GNU General Public License
00023  * along with this program; if not, write to the Free Software
00024  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
00025  *
00026  * $Id: t30.h,v 1.16 2004/11/21 13:55:05 steveu Exp $
00027  */
00028 
00029 /*! \file */
00030 
00031 #if !defined(_T30_H_)
00032 #define _T30_H_
00033 
00034 /*! \page t30_page T.30 FAX protocol handling
00035 
00036 \section t30_page_sec_1 What does it do?
00037 The T.30 protocol is the core protocol used for FAX transmission.
00038 
00039 \section t30_page_sec_2 How does it work?
00040 
00041 Some of the following is paraphrased from some notes found a while ago on the Internet.
00042 I cannot remember exactly where they came from, but they are useful.
00043 
00044 The answer (CED) tone
00045 
00046 The T.30 standard says an answering fax device must send CED (a 2100Hz tone) for
00047 approximately 3 seconds before sending the first handshake message. Some machines
00048 send an 1100Hz or 1850Hz tone, and some send no tone at all. In fact, this answer
00049 tone is so unpredictable, it cannot really be used. It should, however, always be
00050 generated according to the specification.
00051 
00052 Common Timing Deviations
00053 
00054 The T.30 spec. specifies a number of time-outs. For example, after dialing a number,
00055 a calling fax system should listen for a response for 35 seconds before giving up.
00056 These time-out periods are as follows: 
00057 
00058     * T1 - 35 ± 5s: the maximum time for which two fax system will attempt to identify each other
00059     * T2 - 6 ± 1s:  a time-out used to start the sequence for changing transmit parameters
00060     * T3 - 10 ± 5s: a time-out used in handling operator interrupts
00061     * T5 - 60 ± 5s: a time-out used in error correction mode
00062 
00063 These time-outs are sometimes misinterpreted. In addition, they are routinely
00064 ignored, sometimes with good reason. For example, after placing a call, the
00065 calling fax system is supposed to wait for 35 seconds before giving up. If the
00066 answering unit does not answer on the first ring or if a voice answering machine
00067 is connected to the line, or if there are many delays through the network,
00068 the delay before answer can be much longer than 35 seconds. 
00069 
00070 Fax units that support error correction mode (ECM) can respond to a post-image
00071 handshake message with a receiver not ready (RNR) message. The calling unit then
00072 queries the receiving fax unit with a receiver ready (RR) message. If the
00073 answering unit is still busy (printing for example), it will repeat the RNR
00074 message. According to the T.30 standard, this sequence (RR/RNR RR/RNR) can be
00075 repeated for up to the end of T5 (60 ± 5 seconds). However, many fax systems
00076 ignore the time-out and will continue the sequence indefinitely, unless the user
00077 manually overrides. 
00078 
00079 All the time-outs are subject to alteration, and sometimes misuse. Good T.30
00080 implementations must do the right thing, and tolerate others doing the wrong thing.
00081  
00082 Variations in the inter-carrier gap
00083 
00084 T.30 specifies 75 ± 20ms of silence between signals using different modulation
00085 schemes. Examples are between the end of a DCS signal and the start of a TCF signal,
00086 and between the end of an image and the start of a post-image signal. Many fax systems
00087 violate this requirement, especially for the silent period between DCS and TCF.
00088 This may be stretched to well over 100ms. If this period is too long, it can interfere with
00089 handshake signal error recovery, should a packet be corrupted on the line. Systems
00090 should ensure they stay within the prescribed T.30 limits, and be tolerant of others
00091 being out of spec.. 
00092 
00093 Other timing variations
00094 
00095 Testing is required to determine the ability of a fax system to handle
00096 variations in the duration of pauses between unacknowledged handshake message
00097 repetitions, and also in the pauses between the receipt of a handshake command and
00098 the start of a response to that command. In order to reduce the total
00099 transmission time, many fax systems start sending a response message before the
00100 end of the command has been received. 
00101 
00102 Other deviations from the T.30 standard
00103 
00104 There are many other commonly encountered variations between machines, including:
00105 
00106     * frame sequence deviations
00107     * preamble and flag sequence variations
00108     * improper EOM usage
00109     * unusual data rate fallback sequences
00110     * common training pattern detection algorithms
00111     * image transmission deviations
00112     * use of the talker echo protect tone
00113     * image padding and short lines
00114     * RTP/RTN handshake message usage
00115     * long duration lines
00116     * nonstandard disconnect sequences
00117     * DCN usage
00118 */
00119 
00120 #define MAXFRAME            252
00121 
00122 typedef struct t30_state_s t30_state_t;
00123 
00124 /*!
00125     T.30 phase B callback handler.
00126     \brief T.30 phase B callback handler.
00127     \param s The T.30 context.
00128     \param user_data An opaque pointer.
00129     \param result The phase B event code.
00130 */
00131 typedef void (t30_phase_b_handler_t)(t30_state_t *s, void *user_data, int result);
00132 
00133 /*!
00134     T.30 phase D callback handler.
00135     \brief T.30 phase D callback handler.
00136     \param s The T.30 context.
00137     \param user_data An opaque pointer.
00138     \param result The phase D event code.
00139 */
00140 typedef void (t30_phase_d_handler_t)(t30_state_t *s, void *user_data, int result);
00141 
00142 /*!
00143     T.30 phase E callback handler.
00144     \brief T.30 phase E callback handler.
00145     \param s The T.30 context.
00146     \param user_data An opaque pointer.
00147     \param completion_code The phase E completion_code.
00148 */
00149 typedef void (t30_phase_e_handler_t)(t30_state_t *s, void *user_data, int completion_code);
00150 
00151 typedef void (t30_flush_handler_t)(t30_state_t *s,  void *user_data, int which);
00152 
00153 /*!
00154     T.30 protocol completion codes, at phase E.
00155 */
00156 enum
00157 {
00158     T30_ERR_OK = 0,         /* OK */
00159 
00160     /* External problems */
00161     T30_ERR_CEDTONE,        /* The CED tone exceeded 5s */
00162     T30_ERR_T0EXPIRED,      /* Timed out waiting for initial communication */
00163     T30_ERR_T1EXPIRED,      /* Timed out waiting for the first message */
00164     T30_ERR_T3EXPIRED,      /* Timed out waiting for procedural interrupt */
00165     T30_ERR_HDLCCARR,       /* The HDLC carrier did not stop in a timely manner */
00166     T30_ERR_CANNOTTRAIN,    /* Failed to train with any of the compatible modems */
00167     T30_ERR_OPERINTFAIL,    /* Operator intervention failed */
00168     T30_ERR_INCOMPATIBLE,   /* Far end is not compatible */
00169     T30_ERR_NOTRXCAPABLE,   /* Far end is not receive capable */
00170     T30_ERR_NOTTXCAPABLE,   /* Far end is not transmit capable */
00171     T30_ERR_UNEXPECTED,     /* Unexpected message received */
00172     T30_ERR_NORESSUPPORT,   /* Far end cannot receive at the resolution of the image */
00173     T30_ERR_NOSIZESUPPORT,  /* Far end cannot receive at the size of image */
00174 
00175     /* Internal problems */
00176     T30_ERR_FILEERROR,      /* TIFF/F file cannot be opened */
00177     T30_ERR_NOPAGE,         /* TIFF/F page not found */
00178     T30_ERR_BADTIFF,        /* TIFF/F format is not compatible */
00179     T30_ERR_UNSUPPORTED,    /* Unsupported feature */
00180 
00181     /* Phase E status values returned to a transmitter */
00182     T30_ERR_BADDCSTX,       /* Received bad response to DCS or training */
00183     T30_ERR_BADPGTX,        /* Received a DCN from remote after sending a page */
00184     T30_ERR_ECMPHDTX,       /* Invalid ECM response received from receiver */
00185     T30_ERR_ECMRNRTX,       /* Timer T5 expired, receiver not ready */
00186     T30_ERR_GOTDCNTX,       /* Received a DCN while waiting for a DIS */
00187     T30_ERR_INVALRSPTX,     /* Invalid response after sending a page */
00188     T30_ERR_NODISTX,        /* Received other than DIS while waiting for DIS */
00189     T30_ERR_NXTCMDTX,       /* Timed out waiting for next send_page command from driver */
00190     T30_ERR_PHBDEADTX,      /* Received no response to DCS, training or TCF */
00191     T30_ERR_PHDDEADTX,      /* No response after sending a page */
00192 
00193     /* Phase E status values returned to a receiver */
00194     T30_ERR_ECMPHDRX,       /* Invalid ECM response received from transmitter */
00195     T30_ERR_GOTDCSRX,       /* DCS received while waiting for DTC */
00196     T30_ERR_INVALCMDRX,     /* Unexpected command after page received */
00197     T30_ERR_NOCARRIERRX,    /* Carrier lost during fax receive */
00198     T30_ERR_NOEOLRX,        /* Timed out while waiting for EOL (end Of line) */
00199     T30_ERR_NOFAXRX,        /* Timed out while waiting for first line */
00200     T30_ERR_NXTCMDRX,       /* Timed out waiting for next receive page command */
00201     T30_ERR_T2EXPDCNRX,     /* Timer T2 expired while waiting for DCN */
00202     T30_ERR_T2EXPDRX,       /* Timer T2 expired while waiting for phase D */
00203     T30_ERR_T2EXPFAXRX,     /* Timer T2 expired while waiting for fax page */
00204     T30_ERR_T2EXPMPSRX,     /* Timer T2 expired while waiting for next fax page */
00205     T30_ERR_T2EXPRRRX,      /* Timer T2 expired while waiting for RR command */
00206     T30_ERR_T2EXPRX,        /* Timer T2 expired while waiting for NSS, DCS or MCF */
00207     T30_ERR_DCNWHYRX,       /* Unexpected DCN while waiting for DCS or DIS */
00208     T30_ERR_DCNDATARX,      /* Unexpected DCN while waiting for image data */
00209     T30_ERR_DCNFAXRX,       /* Unexpected DCN while waiting for EOM, EOP or MPS */
00210     T30_ERR_DCNPHDRX,       /* Unexpected DCN after EOM or MPS sequence */
00211     T30_ERR_DCNRRDRX,       /* Unexpected DCN after RR/RNR sequence */
00212     T30_ERR_DCNNORTNRX,     /* Unexpected DCN after requested retransmission */
00213 
00214     T30_ERR_BADPAGE,        /* TIFF/F page number tag missing */
00215     T30_ERR_BADTAG,         /* Incorrect values for TIFF/F tags */
00216     T30_ERR_BADTIFFHDR,     /* Bad TIFF/F header - incorrect values in fields */
00217     T30_ERR_BADPARM,        /* Invalid value for fax parameter */
00218     T30_ERR_BADSTATE,       /* Invalid initial state value specified */
00219     T30_ERR_CMDDATA,        /* Last command contained invalid data */
00220     T30_ERR_DISCONNECT,     /* Fax call disconnected by the other station */
00221     T30_ERR_INVALARG,       /* Illegal argument to function */
00222     T30_ERR_INVALFUNC,      /* Illegal call to function */
00223     T30_ERR_NODATA,         /* Data requested is not available (NSF, DIS, DCS) */
00224     T30_ERR_NOMEM,          /* Cannot allocate memory for more pages */
00225     T30_ERR_NOPOLL,         /* Poll not accepted */
00226     T30_ERR_NOSTATE,        /* Initial state value not set */
00227     T30_ERR_RETRYDCN,       /* Disconnected after permitted retries */
00228 };
00229 
00230 /*!
00231     I/O modes for the T.30 protocol.
00232 */
00233 enum
00234 {
00235     T30_MODEM_NONE = 0,
00236     T30_MODEM_PAUSE,
00237     T30_MODEM_CED,
00238     T30_MODEM_CNG,
00239     T30_MODEM_V21,
00240     T30_MODEM_V27TER_2400,
00241     T30_MODEM_V27TER_4800,
00242     T30_MODEM_V29_7200,
00243     T30_MODEM_V29_9600,
00244     T30_MODEM_V17_7200,
00245     T30_MODEM_V17_9600,
00246     T30_MODEM_V17_12000,
00247     T30_MODEM_V17_14400,
00248     T30_MODEM_DONE
00249 };
00250 
00251 /*!
00252     T.30 FAX channel descriptor. This defines the state of a single working
00253     instance of a T.30 FAX channel.
00254 */
00255 struct t30_state_s
00256 {
00257     /* This must be kept the first thing in the structure, so it can be pointed
00258        to reliably as the structures change over time. */
00259     t4_state_t t4;
00260 
00261     /*! \brief TRUE is behaving as the calling party */
00262     int calling_party;
00263 
00264     /*! \brief The local identifier string. */
00265     char local_ident[21];
00266     /*! \brief The identifier string supplied by the remote FAX machine. */
00267     char far_ident[21];
00268     /*! \brief The sub-address string supplied by the remote FAX machine. */
00269     char sub_address[21];
00270     /*! \brief A password to be associated with the T.30 context. */
00271     char password[21];
00272     /*! \brief The vendor of the remote machine, if known, else NULL. */
00273     const char *vendor;
00274     /*! \brief The model of the remote machine, if known, else NULL. */
00275     const char *model;
00276 
00277     /*! \brief A pointer to a callback routine to be called when phase B events
00278         occur. */
00279     t30_phase_b_handler_t *phase_b_handler;
00280     /*! \brief An opaque pointer supplied in event B callbacks. */
00281     void *phase_b_user_data;
00282     /*! \brief A pointer to a callback routine to be called when phase D events
00283         occur. */
00284     t30_phase_d_handler_t *phase_d_handler;
00285     /*! \brief An opaque pointer supplied in event D callbacks. */
00286     void *phase_d_user_data;
00287     /*! \brief A pointer to a callback routine to be called when phase E events
00288         occur. */
00289     t30_phase_e_handler_t *phase_e_handler;
00290     /*! \brief An opaque pointer supplied in event E callbacks. */
00291     void *phase_e_user_data;
00292     t30_flush_handler_t *t30_flush_handler;
00293     void *t30_flush_user_data;
00294 
00295     int options;
00296     int phase;
00297     int next_phase;
00298     int state;
00299     int mode;
00300     int msgendtime;
00301     int samplecount;
00302     
00303     uint8_t dtc_frame[22];
00304     int dtc_len;
00305     uint8_t dcs_frame[22];
00306     int dcs_len;
00307     uint8_t dis_frame[22];
00308     int dis_len;
00309 
00310     /*! \brief A flag to indicate a message is in progress. */
00311     int in_message;
00312     /*! \brief A tone generator context used to generate supervisory tones during
00313                FAX handling. */
00314     tone_gen_state_t tone_gen;
00315     /*! \brief An HDLC context used when receiving HDLC over V.21 messages. */
00316     hdlc_rx_state_t hdlcrx;
00317     /*! \brief An HDLC context used when transmitting HDLC over V.21 messages. */
00318     hdlc_tx_state_t hdlctx;
00319     /*! \brief A V.21 FSK modem context used when transmitting HDLC over V.21
00320                messages. */
00321     fsk_tx_state_t v21tx;
00322     /*! \brief A V.21 FSK modem context used when receiving HDLC over V.21
00323                messages. */
00324     fsk_rx_state_t v21rx;
00325 #if defined(ENABLE_V17)
00326     /*! \brief A V.17 modem context used when sending FAXes at 7200bps, 9600bps
00327                12000bps or 14400bps*/
00328     v17_tx_state_t v17tx;
00329     /*! \brief A V.29 modem context used when receiving FAXes at 7200bps, 9600bps
00330                12000bps or 14400bps*/
00331     v17_rx_state_t v17rx;
00332 #endif
00333     /*! \brief A V.27ter modem context used when sending FAXes at 2400bps or
00334                4800bps */
00335     v27ter_tx_state_t v27ter_tx;
00336     /*! \brief A V.27ter modem context used when receiving FAXes at 2400bps or
00337                4800bps */
00338     v27ter_rx_state_t v27ter_rx;
00339     /*! \brief A V.29 modem context used when sending FAXes at 7200bps or
00340                9600bps */
00341     v29_tx_state_t v29tx;
00342     /*! \brief A V.29 modem context used when receiving FAXes at 7200bps or
00343                9600bps */
00344     v29_rx_state_t v29rx;
00345     /*! \brief A counter for audio samples when inserting times silences according
00346                to the ITU specifications. */
00347     int silent_samples;
00348 
00349     /*! \brief TRUE is the short training sequence should be used. */
00350     int short_train;
00351 
00352     /*! \brief A count of the number of bits in the trainability test. */
00353     int training_test_bits;
00354     int training_current_zeros;
00355     int training_most_zeros;
00356 
00357     /*! \brief The current bit rate for the fast message transfer modem. */
00358     int bit_rate;
00359     /*! \brief The current modem type for the fast message transfer modem. */
00360     int modem_type;
00361     /*! \brief TRUE is a carrier is presnt. Otherwise FALSE. */
00362     int rx_signal_present;
00363 
00364     /* timer_t0 is the answer timeout when calling another FAX machine.
00365        Placing calls is handled outside the FAX processing. */
00366     /*! \brief Remote terminal identification timeout (in audio samples) */
00367     int timer_t0_t1;
00368     /*! \brief HDLC timer (in audio samples) */
00369     int timer_t2;
00370     /*! \brief Procedural interrupt timeout (in audio samples) */
00371     int timer_t3;
00372     /*! \brief Response timer (in audio samples) */
00373     int timer_t4;
00374     /* timer_t5 is only used with error correction */
00375     /*! \brief Signal on timer (in audio samples) */
00376     int timer_sig_on;
00377 
00378     int far_end_detected;
00379 
00380     int line_encoding;
00381     int min_row_bits;
00382     int resolution;
00383     int image_width;
00384     char rx_file[256];
00385     char tx_file[256];
00386     int current_status;
00387     /*! \brief Error and flow logging control */
00388     logging_state_t logging;
00389 };
00390 
00391 typedef struct
00392 {
00393     /*! \brief The current bit rate for image transfer. */
00394     int bit_rate;
00395     /*! \brief The number of pages transferred so far. */
00396     int pages_transferred;
00397     /*! \brief The number of horizontal pixels in the most recent page. */
00398     int columns;
00399     /*! \brief The number of vertical pixels in the most recent page. */
00400     int rows;
00401     /*! \brief The number of bad pixel rows in the most recent page. */
00402     int bad_rows;
00403     /*! \brief The largest number of bad pixel rows in a block in the most recent page. */
00404     int longest_bad_row_run;
00405     /*! \brief The horizontal resolution of the page in pixels per metre */
00406     int column_resolution;
00407     /*! \brief The vertical resolution of the page in pixels per metre */
00408     int row_resolution;
00409     /*! \brief The type of compression used between the FAX machines */
00410     int encoding;
00411     /*! \brief The size of the image, in bytes */
00412     int image_size;
00413 } t30_stats_t;
00414     
00415 #ifdef __cplusplus
00416 extern "C" {
00417 #endif
00418 
00419 /*! Return a text name for a T.30 frame type.
00420     \brief Return a text name for a T.30 frame type.
00421     \param x The frametype octet.
00422     \return A pointer to the text name for the frame type. If the frame type is
00423             not value, the string "???" is returned. */
00424 char *t30_frametype(uint8_t x);
00425 
00426 /*! Decode a DIS, DTC or DCS frame, and log the contents.
00427     \brief Decode a DIS, DTC or DCS frame, and log the contents.
00428     \param s The T.30 context.
00429     \param dis A pointer to the frame to be decoded.
00430     \param len The length of the frame. */
00431 void t30_decode_dis_dtc_dcs(t30_state_t *s, const uint8_t *dis, int len);
00432 
00433 /*! Initialise a T.30 context.
00434     \brief Initialise a T.30 context.
00435     \param s The T.30 context.
00436     \param calling_party TRUE if the context is for a calling party. FALSE if the
00437            context is for an answering party.
00438     \param user_data An opaque pointer which is associated with the T.30 context,
00439            and supplied in callbacks.
00440     \return 0 for OK, else -1. */
00441 int fax_init(t30_state_t *s, int calling_party, void *user_data);
00442 
00443 /*! Release a T.30 context.
00444     \brief Release a T.30 context.
00445     \param s The T.30 context. */
00446 void fax_release(t30_state_t *s);
00447 
00448 /*! Set the sub-address associated with a T.30 context.
00449     \brief Set the sub-address associated with a T.30 context.
00450     \param s The T.30 context.
00451     \param sub_address A pointer to the sub-address.
00452     \return 0 for OK, else -1. */
00453 int t30_set_sub_address(t30_state_t *s, const char *sub_address);
00454 
00455 /*! Set the header information associated with a T.30 context.
00456     \brief Set the header information associated with a T.30 context.
00457     \param s The T.30 context.
00458     \param info A pointer to the information string.
00459     \return 0 for OK, else -1. */
00460 int t30_set_header_info(t30_state_t *s, const char *info);
00461 
00462 /*! Set the local identifier associated with a T.30 context.
00463     \brief Set the local identifier associated with a T.30 context.
00464     \param s The T.30 context.
00465     \param id A pointer to the identifier.
00466     \return 0 for OK, else -1. */
00467 int t30_set_local_ident(t30_state_t *s, const char *id);
00468 
00469 /*! Get the sub-address associated with a T.30 context.
00470     \brief Get the sub-address associated with a T.30 context.
00471     \param s The T.30 context.
00472     \param sub_address A pointer to a buffer for the sub-address.  The buffer
00473            should be at least 21 bytes long.
00474     \return the length of the string. */
00475 int t30_get_sub_address(t30_state_t *s, char *sub_address);
00476 
00477 /*! Get the header information associated with a T.30 context.
00478     \brief Get the header information associated with a T.30 context.
00479     \param s The T.30 context.
00480     \param sub_address A pointer to a buffer for the header information.  The buffer
00481            should be at least 51 bytes long.
00482     \return the length of the string. */
00483 int t30_get_header_info(t30_state_t *s, char *info);
00484 
00485 /*! Get the local FAX machine identifier associated with a T.30 context.
00486     \brief Get the local identifier associated with a T.30 context.
00487     \param s The T.30 context.
00488     \param id A pointer to a buffer for the identifier. The buffer should
00489            be at least 21 bytes long.
00490     \return the length of the string. */
00491 int t30_get_local_ident(t30_state_t *s, char *id);
00492 
00493 /*! Get the remote FAX machine identifier associated with a T.30 context.
00494     \brief Get the remote identifier associated with a T.30 context.
00495     \param s The T.30 context.
00496     \param id A pointer to a buffer for the identifier. The buffer should
00497            be at least 21 bytes long.
00498     \return the length of the string. */
00499 int t30_get_far_ident(t30_state_t *s, char *id);
00500 
00501 /*! Get the current transfer statistics for the file being sent or received.
00502     \brief Get the current transfer statistics.
00503     \param s The T.30 context.
00504     \param t A pointer to a buffer for the statistics. */
00505 void t30_get_transfer_statistics(t30_state_t *s, t30_stats_t *t);
00506 
00507 /*! Set a callback function for T.30 phase B handling.
00508     \brief Set a callback function for T.30 phase B handling.
00509     \param s The T.30 context.
00510     \param handler The callback function
00511     \param user_data An opaque pointer passed to the callback function. */
00512 void t30_set_phase_b_handler(t30_state_t *s, t30_phase_b_handler_t *handler, void *user_data);
00513 
00514 /*! Set a callback function for T.30 phase D handling.
00515     \brief Set a callback function for T.30 phase D handling.
00516     \param s The T.30 context.
00517     \param handler The callback function
00518     \param user_data An opaque pointer passed to the callback function. */
00519 void t30_set_phase_d_handler(t30_state_t *s, t30_phase_d_handler_t *handler, void *user_data);
00520 
00521 /*! Set a callback function for T.30 phase E handling.
00522     \brief Set a callback function for T.30 phase E handling.
00523     \param s The T.30 context.
00524     \param handler The callback function
00525     \param user_data An opaque pointer passed to the callback function. */
00526 void t30_set_phase_e_handler(t30_state_t *s, t30_phase_e_handler_t *handler, void *user_data);
00527 
00528 void fax_set_flush_handler(t30_state_t *s, t30_flush_handler_t *handler, void *user_data);
00529 
00530 /*! Specify the file name of the next TIFF file to be received by a T.30
00531     context.
00532     \brief Set next receive file name.
00533     \param s The T.30 context.
00534     \param file The file name
00535     \param stop_page The maximum page to receive. -1 for no restriction. */
00536 void t30_set_rx_file(t30_state_t *s, const char *file, int stop_page);
00537 
00538 /*! Specify the file name of the next TIFF file to be transmitted by a T.30
00539     context.
00540     \brief Set next transmit file name.
00541     \param s The T.30 context.
00542     \param file The file name
00543     \param start_page The first page to send. -1 for no restriction.
00544     \param stop_page The last page to send. -1 for no restriction. */
00545 void t30_set_tx_file(t30_state_t *s, const char *file, int start_page, int stop_page);
00546 
00547 /*! Request a local interrupt of FAX exchange.
00548     \brief Request a local interrupt of FAX exchange.
00549     \param s The T.30 context.
00550     \param state TRUE to enable interrupt request, else FALSE. */
00551 void t30_local_interrupt_request(t30_state_t *s, int state);
00552 
00553 /*! Convert a phase E completion code to a short text description.
00554     \brief Convert a phase E completion code to a short text description.
00555     \param err The error code.
00556     \return A pointer to the description. */
00557 char *t30_completion_code_to_str(int err);
00558 
00559 /*! Apply FAX receive processing to a block of audio samples.
00560     \brief Apply FAX receive processing to a block of audio samples.
00561     \param s The T.30 context.
00562     \param buf The audio sample buffer.
00563     \param len The number of samples in the buffer.
00564     \return The number of samples unprocessed. This should only be non-zero if
00565             the software has reached the end of the FAX call. */
00566 int fax_rx(t30_state_t *s, int16_t *buf, int len);
00567 
00568 /*! Apply FAX transmit processing to generate a block of audio samples.
00569     \brief Apply FAX transmit processing to generate a block of audio samples.
00570     \param s The T.30 context.
00571     \param buf The audio sample buffer.
00572     \param max_len The number of samples to be generated.
00573     \return The number of samples actually generated. This will be zero when
00574             there is nothing to send. */
00575 int fax_tx(t30_state_t *s, int16_t *buf, int max_len);
00576 
00577 #ifdef __cplusplus
00578 }
00579 #endif
00580 
00581 #endif
00582 /*- End of file ------------------------------------------------------------*/

Generated on Fri Nov 10 09:40:24 2006 for libspandsp by  doxygen 1.5.1