spandsp  0.0.6
t30.h
Go to the documentation of this file.
1 /*
2  * SpanDSP - a series of DSP components for telephony
3  *
4  * t30.h - definitions for T.30 fax processing
5  *
6  * Written by Steve Underwood <steveu@coppice.org>
7  *
8  * Copyright (C) 2003 Steve Underwood
9  *
10  * All rights reserved.
11  *
12  * This program is free software; you can redistribute it and/or modify
13  * it under the terms of the GNU Lesser General Public License version 2.1,
14  * as published by the Free Software Foundation.
15  *
16  * This program is distributed in the hope that it will be useful,
17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19  * GNU Lesser General Public License for more details.
20  *
21  * You should have received a copy of the GNU Lesser General Public
22  * License along with this program; if not, write to the Free Software
23  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
24  */
25 
26 /*! \file */
27 
28 #if !defined(_SPANDSP_T30_H_)
29 #define _SPANDSP_T30_H_
30 
31 /*! \page t30_page T.30 FAX protocol handling
32 
33 \section t30_page_sec_1 What does it do?
34 The T.30 protocol is the core protocol used for FAX transmission. This module
35 implements most of its key features. It does not interface to the outside world.
36 Seperate modules do that for T.38, analogue line, and other forms of FAX
37 communication.
38 
39 Current features of this module include:
40 
41  - FAXing to and from multi-page TIFF/F files, whose images are one of the standard
42  FAX sizes.
43  - V.27ter, V.29 and V.17 modes (2400bps, to 14,400bps).
44  - T.4 1D (MH), T.4 2D,(MR) and T.6 (MMR) compression.
45  - Error correction mode (ECM).
46  - All standard horizonal resolutions (R8, R16, 300dpi, 600dpi, 800dpi, 1200dpi).
47  - All standard vertical resolutions (standard, fine, superfine, 300dpi, 600dpi, 800dpi, 1200dpi).
48  - All standard page widths (A4, B4, A3).
49  - All standard page lengths (A4, B4, North American letter, North American legal, continuous).
50  - Monitoring and sending identifier strings (CSI, TSI, and CIG).
51  - Monitoring and sending sub-address strings (SUB).
52  - Monitoring and sending polling sub-addresses (SEP).
53  - Monitoring and sending polled sub-addresses (PSA).
54  - Monitoring and sending sender identifications (SID).
55  - Monitoring and sending passwords (PWD).
56  - Monitoring of non-standard facility frames (NSF, NSC, and NSS).
57  - Sending custom non-standard facility frames (NSF, NSC, and NSS).
58  - Analogue modem and T.38 operation.
59 
60 \section t30_page_sec_2 How does it work?
61 
62 Some of the following is paraphrased from some notes found a while ago on the Internet.
63 I cannot remember exactly where they came from, but they are useful.
64 
65 \subsection t30_page_sec_2a The answer (CED) tone
66 
67 The T.30 standard says an answering fax device must send CED (a 2100Hz tone) for
68 approximately 3 seconds before sending the first handshake message. Some machines
69 send an 1100Hz or 1850Hz tone, and some send no tone at all. In fact, this answer
70 tone is so unpredictable, it cannot really be used. It should, however, always be
71 generated according to the specification.
72 
73 \subsection t30_page_sec_2b Common Timing Deviations
74 
75 The T.30 spec. specifies a number of time-outs. For example, after dialing a number,
76 a calling fax system should listen for a response for 35 seconds before giving up.
77 These time-out periods are as follows:
78 
79  - T1 - 35+-5s: the maximum time for which two fax system will attempt to identify each other
80  - T2 - 6+-1s: a time-out used to start the sequence for changing transmit parameters
81  - T3 - 10+-5s: a time-out used in handling operator interrupts
82  - T5 - 60+-5s: a time-out used in error correction mode
83 
84 These time-outs are sometimes misinterpreted. In addition, they are routinely
85 ignored, sometimes with good reason. For example, after placing a call, the
86 calling fax system is supposed to wait for 35 seconds before giving up. If the
87 answering unit does not answer on the first ring or if a voice answering machine
88 is connected to the line, or if there are many delays through the network,
89 the delay before answer can be much longer than 35 seconds.
90 
91 Fax units that support error correction mode (ECM) can respond to a post-image
92 handshake message with a receiver not ready (RNR) message. The calling unit then
93 queries the receiving fax unit with a receiver ready (RR) message. If the
94 answering unit is still busy (printing for example), it will repeat the RNR
95 message. According to the T.30 standard, this sequence (RR/RNR RR/RNR) can be
96 repeated for up to the end of T5 (60+-5s). However, many fax systems
97 ignore the time-out and will continue the sequence indefinitely, unless the user
98 manually overrides.
99 
100 All the time-outs are subject to alteration, and sometimes misuse. Good T.30
101 implementations must do the right thing, and tolerate others doing the wrong thing.
102 
103 \subsection t30_page_sec_2c Variations in the inter-carrier gap
104 
105 T.30 specifies 75+-20ms of silence between signals using different modulation
106 schemes. Examples are between the end of a DCS signal and the start of a TCF signal,
107 and between the end of an image and the start of a post-image signal. Many fax systems
108 violate this requirement, especially for the silent period between DCS and TCF.
109 This may be stretched to well over 100ms. If this period is too long, it can interfere with
110 handshake signal error recovery, should a packet be corrupted on the line. Systems
111 should ensure they stay within the prescribed T.30 limits, and be tolerant of others
112 being out of spec..
113 
114 \subsection t30_page_sec_2d Other timing variations
115 
116 Testing is required to determine the ability of a fax system to handle
117 variations in the duration of pauses between unacknowledged handshake message
118 repetitions, and also in the pauses between the receipt of a handshake command and
119 the start of a response to that command. In order to reduce the total
120 transmission time, many fax systems start sending a response message before the
121 end of the command has been received.
122 
123 \subsection t30_page_sec_2e Other deviations from the T.30 standard
124 
125 There are many other commonly encountered variations between machines, including:
126 
127  - frame sequence deviations
128  - preamble and flag sequence variations
129  - improper EOM usage
130  - unusual data rate fallback sequences
131  - common training pattern detection algorithms
132  - image transmission deviations
133  - use of the talker echo protect tone
134  - image padding and short lines
135  - RTP/RTN handshake message usage
136  - long duration lines
137  - nonstandard disconnect sequences
138  - DCN usage
139 */
140 
141 /*! The maximum length of a DIS, DTC or DCS frame */
142 #define T30_MAX_DIS_DTC_DCS_LEN 22
143 /*! The maximum length of the body of an ident string */
144 #define T30_MAX_IDENT_LEN 20
145 /*! The maximum length of the user string to insert in page headers */
146 #define T30_MAX_PAGE_HEADER_INFO 50
147 
148 typedef struct t30_state_s t30_state_t;
149 
150 /*!
151  T.30 phase B callback handler. This handler can be used to process addition
152  information available in some FAX calls, such as passwords. The callback handler
153  can access whatever additional information might have been received, using
154  t30_get_received_info().
155  \brief T.30 phase B callback handler.
156  \param s The T.30 context.
157  \param user_data An opaque pointer.
158  \param result The phase B event code.
159  \return The new status. Normally, T30_ERR_OK is returned.
160 */
161 typedef int (t30_phase_b_handler_t)(t30_state_t *s, void *user_data, int result);
162 
163 /*!
164  T.30 phase D callback handler.
165  \brief T.30 phase D callback handler.
166  \param s The T.30 context.
167  \param user_data An opaque pointer.
168  \param result The phase D event code.
169  \return The new status. Normally, T30_ERR_OK is returned.
170 */
171 typedef int (t30_phase_d_handler_t)(t30_state_t *s, void *user_data, int result);
172 
173 /*!
174  T.30 phase E callback handler.
175  \brief T.30 phase E callback handler.
176  \param s The T.30 context.
177  \param user_data An opaque pointer.
178  \param completion_code The phase E completion code.
179 */
180 typedef void (t30_phase_e_handler_t)(t30_state_t *s, void *user_data, int completion_code);
181 
182 /*!
183  T.30 real time frame handler.
184  \brief T.30 real time frame handler.
185  \param s The T.30 context.
186  \param user_data An opaque pointer.
187  \param incoming True for incoming, false for outgoing.
188  \param msg The HDLC message.
189  \param len The length of the message.
190 */
192  void *user_data,
193  int incoming,
194  const uint8_t msg[],
195  int len);
196 
197 /*!
198  T.30 document handler.
199  \brief T.30 document handler.
200  \param s The T.30 context.
201  \param user_data An opaque pointer.
202  \param result The document event code.
203 */
204 typedef int (t30_document_handler_t)(t30_state_t *s, void *user_data, int status);
205 
206 /*!
207  T.30 set a receive or transmit type handler.
208  \brief T.30 set a receive or transmit type handler.
209  \param user_data An opaque pointer.
210  \param type The modem, tone or silence to be sent or received.
211  \param bit_rate The bit rate of the modem to be sent or received.
212  \param short_train True if the short training sequence should be used (where one exists).
213  \param use_hdlc False for bit stream, True for HDLC framing.
214 */
215 typedef void (t30_set_handler_t)(void *user_data, int type, int bit_rate, int short_train, int use_hdlc);
216 
217 /*!
218  T.30 send HDLC handler.
219  \brief T.30 send HDLC handler.
220  \param user_data An opaque pointer.
221  \param msg The HDLC message.
222  \param len The length of the message.
223 */
224 typedef void (t30_send_hdlc_handler_t)(void *user_data, const uint8_t msg[], int len);
225 
226 #if 0
227 /*!
228  T.30 send document handler.
229  \brief T.30 send document handler.
230  \param user_data An opaque pointer.
231  \param msg The document chunk.
232  \param len The length of the chunk.
233  \return The actual length of the chunk.
234 */
235 typedef int (t30_document_get_handler_t)(void *user_data, uint8_t msg[], int len);
236 
237 /*!
238  T.30 deliver document handler.
239  \brief T.30 deliver handler.
240  \param user_data An opaque pointer.
241  \param msg The document chunk.
242  \param len The length of the chunk.
243  \return The delivery status.
244 */
245 typedef int (t30_document_put_handler_t)(void *user_data, const uint8_t msg[], int len);
246 #endif
247 
248 /*!
249  T.30 protocol completion codes, at phase E.
250 */
251 enum
252 {
253  T30_ERR_OK = 0, /*! OK */
254 
255  /* Link problems */
256  T30_ERR_CEDTONE, /*! The CED tone exceeded 5s */
257  T30_ERR_T0_EXPIRED, /*! Timed out waiting for initial communication */
258  T30_ERR_T1_EXPIRED, /*! Timed out waiting for the first message */
259  T30_ERR_T3_EXPIRED, /*! Timed out waiting for procedural interrupt */
260  T30_ERR_HDLC_CARRIER, /*! The HDLC carrier did not stop in a timely manner */
261  T30_ERR_CANNOT_TRAIN, /*! Failed to train with any of the compatible modems */
262  T30_ERR_OPER_INT_FAIL, /*! Operator intervention failed */
263  T30_ERR_INCOMPATIBLE, /*! Far end is not compatible */
264  T30_ERR_RX_INCAPABLE, /*! Far end is not able to receive */
265  T30_ERR_TX_INCAPABLE, /*! Far end is not able to transmit */
266  T30_ERR_NORESSUPPORT, /*! Far end cannot receive at the resolution of the image */
267  T30_ERR_NOSIZESUPPORT, /*! Far end cannot receive at the size of image */
268  T30_ERR_UNEXPECTED, /*! Unexpected message received */
269 
270  /* Phase E status values returned to a transmitter */
271  T30_ERR_TX_BADDCS, /*! Received bad response to DCS or training */
272  T30_ERR_TX_BADPG, /*! Received a DCN from remote after sending a page */
273  T30_ERR_TX_ECMPHD, /*! Invalid ECM response received from receiver */
274  T30_ERR_TX_GOTDCN, /*! Received a DCN while waiting for a DIS */
275  T30_ERR_TX_INVALRSP, /*! Invalid response after sending a page */
276  T30_ERR_TX_NODIS, /*! Received other than DIS while waiting for DIS */
277  T30_ERR_TX_PHBDEAD, /*! Received no response to DCS, training or TCF */
278  T30_ERR_TX_PHDDEAD, /*! No response after sending a page */
279  T30_ERR_TX_T5EXP, /*! Timed out waiting for receiver ready (ECM mode) */
280 
281  /* Phase E status values returned to a receiver */
282  T30_ERR_RX_ECMPHD, /*! Invalid ECM response received from transmitter */
283  T30_ERR_RX_GOTDCS, /*! DCS received while waiting for DTC */
284  T30_ERR_RX_INVALCMD, /*! Unexpected command after page received */
285  T30_ERR_RX_NOCARRIER, /*! Carrier lost during fax receive */
286  T30_ERR_RX_NOEOL, /*! Timed out while waiting for EOL (end of line) */
287  T30_ERR_RX_NOFAX, /*! Timed out while waiting for first line */
288  T30_ERR_RX_T2EXPDCN, /*! Timer T2 expired while waiting for DCN */
289  T30_ERR_RX_T2EXPD, /*! Timer T2 expired while waiting for phase D */
290  T30_ERR_RX_T2EXPFAX, /*! Timer T2 expired while waiting for fax page */
291  T30_ERR_RX_T2EXPMPS, /*! Timer T2 expired while waiting for next fax page */
292  T30_ERR_RX_T2EXPRR, /*! Timer T2 expired while waiting for RR command */
293  T30_ERR_RX_T2EXP, /*! Timer T2 expired while waiting for NSS, DCS or MCF */
294  T30_ERR_RX_DCNWHY, /*! Unexpected DCN while waiting for DCS or DIS */
295  T30_ERR_RX_DCNDATA, /*! Unexpected DCN while waiting for image data */
296  T30_ERR_RX_DCNFAX, /*! Unexpected DCN while waiting for EOM, EOP or MPS */
297  T30_ERR_RX_DCNPHD, /*! Unexpected DCN after EOM or MPS sequence */
298  T30_ERR_RX_DCNRRD, /*! Unexpected DCN after RR/RNR sequence */
299  T30_ERR_RX_DCNNORTN, /*! Unexpected DCN after requested retransmission */
300 
301  /* TIFF file problems */
302  T30_ERR_FILEERROR, /*! TIFF/F file cannot be opened */
303  T30_ERR_NOPAGE, /*! TIFF/F page not found */
304  T30_ERR_BADTIFF, /*! TIFF/F format is not compatible */
305  T30_ERR_BADPAGE, /*! TIFF/F page number tag missing */
306  T30_ERR_BADTAG, /*! Incorrect values for TIFF/F tags */
307  T30_ERR_BADTIFFHDR, /*! Bad TIFF/F header - incorrect values in fields */
308  T30_ERR_NOMEM, /*! Cannot allocate memory for more pages */
309 
310  /* General problems */
311  T30_ERR_RETRYDCN, /*! Disconnected after permitted retries */
312  T30_ERR_CALLDROPPED, /*! The call dropped prematurely */
313 
314  /* Feature negotiation issues */
315  T30_ERR_NOPOLL, /*! Poll not accepted */
316  T30_ERR_IDENT_UNACCEPTABLE, /*! Far end's ident is not acceptable */
317  T30_ERR_SUB_UNACCEPTABLE, /*! Far end's sub-address is not acceptable */
318  T30_ERR_SEP_UNACCEPTABLE, /*! Far end's selective polling address is not acceptable */
319  T30_ERR_PSA_UNACCEPTABLE, /*! Far end's polled sub-address is not acceptable */
320  T30_ERR_SID_UNACCEPTABLE, /*! Far end's sender identification is not acceptable */
321  T30_ERR_PWD_UNACCEPTABLE, /*! Far end's password is not acceptable */
322  T30_ERR_TSA_UNACCEPTABLE, /*! Far end's transmitting subscriber internet address is not acceptable */
323  T30_ERR_IRA_UNACCEPTABLE, /*! Far end's internet routing address is not acceptable */
324  T30_ERR_CIA_UNACCEPTABLE, /*! Far end's calling subscriber internet address is not acceptable */
325  T30_ERR_ISP_UNACCEPTABLE, /*! Far end's internet selective polling address is not acceptable */
326  T30_ERR_CSA_UNACCEPTABLE /*! Far end's called subscriber internet address is not acceptable */
327 };
328 
329 /*!
330  I/O modes for the T.30 protocol.
331  These are allocated such that the lower 4 bits represents the variant of the modem - e.g. the
332  particular bit rate selected.
333 */
334 enum
335 {
336  T30_MODEM_NONE = 0,
337  T30_MODEM_PAUSE,
338  T30_MODEM_CED,
339  T30_MODEM_CNG,
340  T30_MODEM_V21,
341  T30_MODEM_V27TER,
342  T30_MODEM_V29,
343  T30_MODEM_V17,
344  T30_MODEM_V34HDX,
345  T30_MODEM_DONE
346 };
347 
348 enum
349 {
350  T30_FRONT_END_SEND_STEP_COMPLETE = 0,
351  /*! The current receive has completed. This is only needed to report an
352  unexpected end of the receive operation, as might happen with T.38
353  dying. */
355  T30_FRONT_END_SIGNAL_PRESENT,
356  T30_FRONT_END_SIGNAL_ABSENT,
357  T30_FRONT_END_CED_PRESENT,
358  T30_FRONT_END_CNG_PRESENT
359 };
360 
361 enum
362 {
363  /*! Support the V.27ter modem (2400, and 4800bps) for image transfer. */
365  /*! Support the V.29 modem (9600, and 7200bps) for image transfer. */
367  /*! Support the V.17 modem (14400, 12000, 9600 and 7200bps) for image transfer. */
369  /*! Support the V.34 modem (up to 33,600bps) for image transfer. */
371  /*! Support the Internet aware FAX mode (no bit rate limit) for image transfer. */
373 };
374 
375 enum
376 {
377  /*! No compression */
379  /*! T.1 1D compression */
381  /*! T.4 2D compression */
383  /*! T.6 2D compression */
385  /*! T.85 monochrome JBIG compression, with fixed L0 */
387  /*! T.85 monochrome JBIG compression, with variable L0 */
389  /*! T.43 colour JBIG compression */
391  /*! T.45 run length colour compression */
393  /*! T.81 + T.30 Annex E colour JPEG compression */
395  /*! T.81 + T.30 Annex K colour sYCC-JPEG compression */
397  /*! T.88 monochrome JBIG2 compression */
399 };
400 
401 enum
402 {
403  /*! Support standard FAX Y-resolution 98/100dpi */
405  /*! Support fine FAX Y-resolution 196/200dpi */
407  /*! Support super-fine FAX Y-resolution 392/400dpi */
409 
410  /*! Support half FAX X-resolution 100/102dpi */
412  /*! Support standard FAX X-resolution 200/204dpi */
414  /*! Support double FAX X-resolution 400dpi */
416 
417  /*! Support 300dpi x 300 dpi */
419  /*! Support 400dpi x 400 dpi */
421  /*! Support 600dpi x 600 dpi */
423  /*! Support 1200dpi x 1200 dpi */
425  /*! Support 300dpi x 600 dpi */
427  /*! Support 400dpi x 800 dpi */
429  /*! Support 600dpi x 1200 dpi */
431 };
432 
433 enum
434 {
435  T30_SUPPORT_215MM_WIDTH = 0x01,
436  T30_SUPPORT_255MM_WIDTH = 0x02,
437  T30_SUPPORT_303MM_WIDTH = 0x04,
438 
439  T30_SUPPORT_UNLIMITED_LENGTH = 0x10000,
440  T30_SUPPORT_A4_LENGTH = 0x20000,
441  T30_SUPPORT_B4_LENGTH = 0x40000,
442  T30_SUPPORT_US_LETTER_LENGTH = 0x80000,
443  T30_SUPPORT_US_LEGAL_LENGTH = 0x100000
444 };
445 
446 enum
447 {
448  /*! Enable support of identification, through the SID and/or PWD frames. */
450  /*! Enable support of selective polling, through the SEP frame. */
452  /*! Enable support of polling sub-addressing, through the PSA frame. */
454  /*! Enable support of multiple selective polling, through repeated used of the SEP and PSA frames. */
456  /*! Enable support of sub-addressing, through the SUB frame. */
458  /*! Enable support of transmitting subscriber internet address, through the TSA frame. */
460  /*! Enable support of internet routing address, through the IRA frame. */
462  /*! Enable support of calling subscriber internet address, through the CIA frame. */
464  /*! Enable support of internet selective polling address, through the ISP frame. */
466  /*! Enable support of called subscriber internet address, through the CSA frame. */
468  /*! Enable support of the field not valid (FNV) frame. */
470  /*! Enable support of the command repeat (CRP) frame. */
472 };
473 
474 enum
475 {
476  T30_IAF_MODE_T37 = 0x01,
477  T30_IAF_MODE_T38 = 0x02,
478  T30_IAF_MODE_FLOW_CONTROL = 0x04,
479  /*! Continuous flow mode means data is sent as fast as possible, usually across
480  the Internet, where speed is not constrained by a PSTN modem. */
482  /*! No TCF means TCF is not exchanged. The end points must sort out usable speed
483  issues locally. */
485  /*! No fill bits means do not insert fill bits, even if the T.30 messages request
486  them. */
488  /*! No indicators means do not send indicator messages when using T.38. */
490  /*! Use relaxed timers for T.38. This is appropriate when using TCP/TPKT for T.38,
491  as there is no point in anything but a long backstop timeout in such a mode. */
493 };
494 
495 typedef struct
496 {
497  /*! \brief The identifier string (CSI, TSI, CIG). */
498  char ident[T30_MAX_IDENT_LEN + 1];
499  /*! \brief The sub-address string (SUB). */
500  char sub_address[T30_MAX_IDENT_LEN + 1];
501  /*! \brief The selective polling sub-address (SEP). */
502  char selective_polling_address[T30_MAX_IDENT_LEN + 1];
503  /*! \brief The polled sub-address (PSA). */
504  char polled_sub_address[T30_MAX_IDENT_LEN + 1];
505  /*! \brief The sender identification (SID). */
506  char sender_ident[T30_MAX_IDENT_LEN + 1];
507  /*! \brief The password (PWD). */
508  char password[T30_MAX_IDENT_LEN + 1];
509  /*! \brief Non-standard facilities (NSF). */
510  uint8_t *nsf;
511  size_t nsf_len;
512  /*! \brief Non-standard facilities command (NSC). */
513  uint8_t *nsc;
514  size_t nsc_len;
515  /*! \brief Non-standard facilities set-up (NSS). */
516  uint8_t *nss;
517  size_t nss_len;
518  /*! \brief Transmitting subscriber internet address (TSA). */
519  int tsa_type;
520  char *tsa;
521  size_t tsa_len;
522  /*! \brief Internet routing address (IRA). */
523  int ira_type;
524  char *ira;
525  size_t ira_len;
526  /*! \brief Calling subscriber internet address (CIA). */
527  int cia_type;
528  char *cia;
529  size_t cia_len;
530  /*! \brief Internet selective polling address (ISP). */
531  int isp_type;
532  char *isp;
533  size_t isp_len;
534  /*! \brief Called subscriber internet address (CSA). */
535  int csa_type;
536  char *csa;
537  size_t csa_len;
539 
540 typedef struct
541 {
542  /*! \brief The current bit rate for image transfer. */
543  int bit_rate;
544  /*! \brief True if error correcting mode is used. */
546  /*! \brief The number of pages sent so far. */
547  int pages_tx;
548  /*! \brief The number of pages received so far. */
549  int pages_rx;
550  /*! \brief The number of pages in the file (<0 if not known). */
552  /*! \brief The horizontal column-to-column resolution of the most recent exchanged page, in pixels per metre */
554  /*! \brief The vertical row-to-row resolution of the most recent exchanged page, in pixels per metre */
556  /*! \brief The number of horizontal pixels in the most recent exchanged page. */
557  int width;
558  /*! \brief The number of vertical pixels in the most recent exchanged page. */
559  int length;
560  /*! \brief The size of the image, in bytes */
562  /*! \brief The type of compression used between the FAX machines */
563  int encoding;
564  /*! \brief The number of bad pixel rows in the most recent page. */
565  int bad_rows;
566  /*! \brief The largest number of bad pixel rows in a block in the most recent page. */
568  /*! \brief The number of HDLC frame retries, if error correcting mode is used. */
570  /*! \brief Current status. */
572 #if 0
573  /*! \brief The number of RTP events in this call. */
574  int rtp_events;
575  /*! \brief The number of RTN events in this call. */
576  int rtn_events;
577 #endif
578 } t30_stats_t;
579 
580 #if defined(__cplusplus)
581 extern "C"
582 {
583 #endif
584 
585 /*! Initialise a T.30 context.
586  \brief Initialise a T.30 context.
587  \param s The T.30 context.
588  \param calling_party True if the context is for a calling party. False if the
589  context is for an answering party.
590  \param set_rx_type_handler
591  \param set_rx_type_user_data
592  \param set_tx_type_handler
593  \param set_tx_type_user_data
594  \param send_hdlc_handler
595  \param send_hdlc_user_data
596  \return A pointer to the context, or NULL if there was a problem. */
597 SPAN_DECLARE(t30_state_t *) t30_init(t30_state_t *s,
598  int calling_party,
600  void *set_rx_type_user_data,
602  void *set_tx_type_user_data,
604  void *send_hdlc_user_data);
605 
606 /*! Release a T.30 context.
607  \brief Release a T.30 context.
608  \param s The T.30 context.
609  \return 0 for OK, else -1. */
610 SPAN_DECLARE(int) t30_release(t30_state_t *s);
611 
612 /*! Free a T.30 context.
613  \brief Free a T.30 context.
614  \param s The T.30 context.
615  \return 0 for OK, else -1. */
616 SPAN_DECLARE(int) t30_free(t30_state_t *s);
617 
618 /*! Restart a T.30 context.
619  \brief Restart a T.30 context.
620  \param s The T.30 context.
621  \return 0 for OK, else -1. */
622 SPAN_DECLARE(int) t30_restart(t30_state_t *s);
623 
624 /*! Check if a T.30 call is still active. This may be used to regularly poll
625  if the job has finished.
626  \brief Check if a T.30 call is still active.
627  \param s The T.30 context.
628  \return True for call still active, or false for call completed. */
629 SPAN_DECLARE(int) t30_call_active(t30_state_t *s);
630 
631 /*! Cleanup a T.30 context if the call terminates.
632  \brief Cleanup a T.30 context if the call terminates.
633  \param s The T.30 context. */
634 SPAN_DECLARE(void) t30_terminate(t30_state_t *s);
635 
636 /*! Inform the T.30 engine of a status change in the front end (end of tx, rx signal change, etc.).
637  \brief Inform the T.30 engine of a status change in the front end (end of tx, rx signal change, etc.).
638  \param user_data The T.30 context.
639  \param status The type of status change which occured. */
640 SPAN_DECLARE(void) t30_front_end_status(void *user_data, int status);
641 
642 /*! Get a bit of received non-ECM image data.
643  \brief Get a bit of received non-ECM image data.
644  \param user_data An opaque pointer, which must point to the T.30 context.
645  \return The next bit to transmit. */
646 SPAN_DECLARE_NONSTD(int) t30_non_ecm_get_bit(void *user_data);
647 
648 /*! Get a byte of received non-ECM image data.
649  \brief Get a byte of received non-ECM image data.
650  \param user_data An opaque pointer, which must point to the T.30 context.
651  \return The next byte to transmit. */
652 SPAN_DECLARE(int) t30_non_ecm_get_byte(void *user_data);
653 
654 /*! Get a chunk of received non-ECM image data.
655  \brief Get a bit of received non-ECM image data.
656  \param user_data An opaque pointer, which must point to the T.30 context.
657  \param buf The buffer to contain the data.
658  \param max_len The maximum length of the chunk.
659  \return The actual length of the chunk. */
660 SPAN_DECLARE(int) t30_non_ecm_get_chunk(void *user_data, uint8_t buf[], int max_len);
661 
662 /*! Process a bit of received non-ECM image data.
663  \brief Process a bit of received non-ECM image data
664  \param user_data An opaque pointer, which must point to the T.30 context.
665  \param bit The received bit. */
666 SPAN_DECLARE_NONSTD(void) t30_non_ecm_put_bit(void *user_data, int bit);
667 
668 /*! Process a byte of received non-ECM image data.
669  \brief Process a byte of received non-ECM image data
670  \param user_data An opaque pointer, which must point to the T.30 context.
671  \param byte The received byte. */
672 SPAN_DECLARE(void) t30_non_ecm_put_byte(void *user_data, int byte);
673 
674 /*! Process a chunk of received non-ECM image data.
675  \brief Process a chunk of received non-ECM image data
676  \param user_data An opaque pointer, which must point to the T.30 context.
677  \param buf The buffer containing the received data.
678  \param len The length of the data in buf. */
679 SPAN_DECLARE(void) t30_non_ecm_put_chunk(void *user_data, const uint8_t buf[], int len);
680 
681 /*! Process a received HDLC frame.
682  \brief Process a received HDLC frame.
683  \param user_data The T.30 context.
684  \param msg The HDLC message.
685  \param len The length of the message, in octets.
686  \param ok True if the frame was received without error. */
687 SPAN_DECLARE_NONSTD(void) t30_hdlc_accept(void *user_data, const uint8_t msg[], int len, int ok);
688 
689 /*! Report the passage of time to the T.30 engine.
690  \brief Report the passage of time to the T.30 engine.
691  \param s The T.30 context.
692  \param samples The time change in 1/8000th second steps. */
693 SPAN_DECLARE(void) t30_timer_update(t30_state_t *s, int samples);
694 
695 /*! Get the current transfer statistics for the file being sent or received.
696  \brief Get the current transfer statistics.
697  \param s The T.30 context.
698  \param t A pointer to a buffer for the statistics. */
699 SPAN_DECLARE(void) t30_get_transfer_statistics(t30_state_t *s, t30_stats_t *t);
700 
701 /*! Request a local interrupt of FAX exchange.
702  \brief Request a local interrupt of FAX exchange.
703  \param s The T.30 context.
704  \param state True to enable interrupt request, else false. */
705 SPAN_DECLARE(void) t30_local_interrupt_request(t30_state_t *s, int state);
706 
707 /*! Allow remote interrupts of FAX exchange.
708  \brief Allow remote interrupts of FAX exchange.
709  \param s The T.30 context.
710  \param state True to allow interruptd, else false. */
711 SPAN_DECLARE(void) t30_remote_interrupts_allowed(t30_state_t *s, int state);
712 
713 #if defined(__cplusplus)
714 }
715 #endif
716 
717 #endif
718 /*- End of file ------------------------------------------------------------*/
Definition: t30.h:275
Definition: t30.h:274
Definition: t30.h:267
Definition: t30.h:296
Definition: t30.h:299
Definition: t30.h:388
Definition: t30.h:272
Definition: t30.h:481
Definition: t30.h:292
Definition: t30.h:370
int pages_rx
The number of pages received so far.
Definition: t30.h:549
Definition: t30.h:265
Definition: t30.h:315
Definition: t30.h:293
Definition: t30.h:492
Definition: t30.h:469
#define T30_MAX_IDENT_LEN
Definition: t30.h:144
int t30_non_ecm_get_chunk(void *user_data, uint8_t buf[], int max_len)
Get a bit of received non-ECM image data.
Definition: t30.c:6208
Definition: t30.h:451
void * send_hdlc_user_data
An opaque pointer passed to the transmitted HDLC frame handler.
Definition: private/t30.h:134
int cia_type
Calling subscriber internet address (CIA).
Definition: t30.h:527
Definition: t30.h:386
Definition: t30.h:271
int image_size
The size of the image, in bytes.
Definition: t30.h:561
int calling_party
True if behaving as the calling party.
Definition: private/t30.h:47
Definition: t30.h:398
int tsa_type
Transmitting subscriber internet address (TSA).
Definition: t30.h:519
Definition: private/t30.h:35
int bit_rate
The current bit rate for image transfer.
Definition: t30.h:543
Definition: t30.h:306
uint8_t * nsc
Non-standard facilities command (NSC).
Definition: t30.h:513
Definition: t30.h:390
int x_resolution
The horizontal column-to-column resolution of the most recent exchanged page, in pixels per metre...
Definition: t30.h:553
Definition: t30.h:428
Definition: t30.h:308
int rtp_events
The number of RTP events.
Definition: private/t30.h:311
Definition: t30.h:422
int csa_type
Called subscriber internet address (CSA).
Definition: t30.h:535
int encoding
The type of compression used between the FAX machines.
Definition: t30.h:563
Definition: t30.h:382
t30_state_t * t30_init(t30_state_t *s, int calling_party, t30_set_handler_t *set_rx_type_handler, void *set_rx_type_user_data, t30_set_handler_t *set_tx_type_handler, void *set_tx_type_user_data, t30_send_hdlc_handler_t *send_hdlc_handler, void *send_hdlc_user_data)
Initialise a T.30 context.
Definition: t30.c:6989
Definition: t30.h:262
int isp_type
Internet selective polling address (ISP).
Definition: t30.h:531
void t30_front_end_status(void *user_data, int status)
Inform the T.30 engine of a status change in the front end (end of tx, rx signal change, etc.).
Definition: t30.c:6456
Definition: t30.h:291
Definition: t30.h:257
Definition: t30.h:487
int short_train
True if the short training sequence should be used.
Definition: private/t30.h:177
Definition: t30.h:273
void t30_non_ecm_put_chunk(void *user_data, const uint8_t buf[], int len)
Process a chunk of received non-ECM image data.
Definition: t30.c:6089
Definition: t30.h:263
Definition: t30.h:413
int t30_non_ecm_get_byte(void *user_data)
Get a byte of received non-ECM image data.
Definition: t30.c:6171
int t30_restart(t30_state_t *s)
Restart a T.30 context.
Definition: t30.c:6947
int ira_type
Internet routing address (IRA).
Definition: t30.h:523
SPAN_DECLARE_NONSTD(void) async_rx_put_bit(void *user_data
Accept a bit from a received serial bit stream.
t30_set_handler_t * set_tx_type_handler
The handler for changes to the transmit mode.
Definition: private/t30.h:127
Definition: t30.h:259
Definition: t30.h:311
Definition: t30.h:489
Definition: t30.h:415
Definition: t30.h:304
Definition: t30.h:289
void t30_timer_update(t30_state_t *s, int samples)
Report the passage of time to the T.30 engine.
Definition: t30.c:6772
int rtn_events
The number of RTN events.
Definition: private/t30.h:313
Definition: t30.h:285
Definition: t30.h:323
int t30_call_active(t30_state_t *s)
Check if a T.30 call is still active.
Definition: t30.c:7053
Definition: t30.h:268
Definition: t30.h:320
void( t30_send_hdlc_handler_t)(void *user_data, const uint8_t msg[], int len)
T.30 send HDLC handler.
Definition: t30.h:224
Definition: t30.h:295
int t30_release(t30_state_t *s)
Release a T.30 context.
Definition: t30.c:7036
int longest_bad_row_run
The largest number of bad pixel rows in a block in the most recent page.
Definition: t30.h:567
Definition: t30.h:286
Definition: t30.h:372
Definition: t30.h:288
Definition: t30.h:325
Definition: t30.h:366
Definition: t30.h:278
void * set_rx_type_user_data
An opaque pointer passed to the handler for changes to the receive mode.
Definition: private/t30.h:125
int( t30_phase_b_handler_t)(t30_state_t *s, void *user_data, int result)
T.30 phase B callback handler.
Definition: t30.h:161
Definition: t30.h:264
Definition: t30.h:430
Definition: t30.h:418
Definition: t30.h:297
uint8_t * nsf
Non-standard facilities (NSF).
Definition: t30.h:510
Definition: t30.h:298
Definition: t30.h:484
Definition: t30.h:322
int current_status
Current status.
Definition: t30.h:571
void( t30_set_handler_t)(void *user_data, int type, int bit_rate, int short_train, int use_hdlc)
T.30 set a receive or transmit type handler.
Definition: t30.h:215
Definition: t30.h:420
Definition: t30.h:321
Definition: t30.h:317
Definition: t30.h:471
void t30_remote_interrupts_allowed(t30_state_t *s, int state)
Allow remote interrupts of FAX exchange.
Definition: t30.c:6941
Definition: t30.h:260
Definition: t30.h:312
Definition: t30.h:307
Definition: t30.h:284
int pages_in_file
The number of pages in the file (&lt;0 if not known).
Definition: t30.h:551
Definition: t30.h:394
void( t30_phase_e_handler_t)(t30_state_t *s, void *user_data, int completion_code)
T.30 phase E callback handler.
Definition: t30.h:180
Definition: t30.h:319
Definition: t30.h:302
void * set_tx_type_user_data
An opaque pointer passed to the handler for changes to the transmit mode.
Definition: private/t30.h:129
Definition: t30.h:378
int( t30_phase_d_handler_t)(t30_state_t *s, void *user_data, int result)
T.30 phase D callback handler.
Definition: t30.h:171
Definition: t30.h:261
Definition: t30.h:258
void t30_non_ecm_put_byte(void *user_data, int byte)
Process a byte of received non-ECM image data.
Definition: t30.c:6043
void t30_get_transfer_statistics(t30_state_t *s, t30_stats_t *t)
Get the current transfer statistics.
Definition: t30.c:6887
int( t30_document_handler_t)(t30_state_t *s, void *user_data, int status)
T.30 document handler.
Definition: t30.h:204
Definition: t30.h:294
Definition: t30.h:404
void t30_local_interrupt_request(t30_state_t *s, int state)
Request a local interrupt of FAX exchange.
Definition: t30.c:6928
Definition: t30.h:368
int t30_free(t30_state_t *s)
Free a T.30 context.
Definition: t30.c:7045
Definition: t30.h:316
Definition: t30.h:426
Definition: t30.h:380
Definition: t30.h:277
Definition: t30.h:279
Definition: t30.h:449
Definition: t30.h:392
Definition: t30.h:266
Definition: t30.h:276
Definition: t30.h:364
Definition: t30.h:324
t30_send_hdlc_handler_t * send_hdlc_handler
The transmitted HDLC frame handler.
Definition: private/t30.h:132
Definition: t30.h:287
t30_set_handler_t * set_rx_type_handler
The handler for changes to the receive mode.
Definition: private/t30.h:123
Definition: t30.h:384
int length
The number of vertical pixels in the most recent exchanged page.
Definition: t30.h:559
void t30_terminate(t30_state_t *s)
Cleanup a T.30 context if the call terminates.
Definition: t30.c:6851
Definition: t30.h:303
Definition: t30.h:406
Definition: t30.h:318
Definition: t30.h:256
Definition: t30.h:305
int error_correcting_mode
True if error correcting mode is used.
Definition: t30.h:545
Definition: t30.h:283
int error_correcting_mode_retries
The number of HDLC frame retries, if error correcting mode is used.
Definition: t30.h:569
Definition: t30.h:282
int width
The number of horizontal pixels in the most recent exchanged page.
Definition: t30.h:557
Definition: t30.h:411
Definition: t30.h:290
int y_resolution
The vertical row-to-row resolution of the most recent exchanged page, in pixels per metre...
Definition: t30.h:555
Definition: t30.h:326
Definition: t30.h:457
Definition: t30.h:495
uint8_t * nss
Non-standard facilities set-up (NSS).
Definition: t30.h:516
Definition: t30.h:354
Definition: t30.h:540
void( t30_real_time_frame_handler_t)(t30_state_t *s, void *user_data, int incoming, const uint8_t msg[], int len)
T.30 real time frame handler.
Definition: t30.h:191
int state
The current state of the T.30 state machine.
Definition: private/t30.h:157
int bad_rows
The number of bad pixel rows in the most recent page.
Definition: t30.h:565
int pages_tx
The number of pages sent so far.
Definition: t30.h:547