|
5
|
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 General Public License version 2, as
|
|
|
14 * 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 General Public License for more details.
|
|
|
20 *
|
|
|
21 * You should have received a copy of the GNU General Public License
|
|
|
22 * along with this program; if not, write to the Free Software
|
|
|
23 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
|
|
|
24 *
|
|
|
25 * $Id: t30.h,v 1.61 2006/11/01 12:58:21 steveu Exp $
|
|
|
26 */
|
|
|
27
|
|
|
28 /*! \file */
|
|
|
29
|
|
|
30 #if !defined(_T30_H_)
|
|
|
31 #define _T30_H_
|
|
|
32
|
|
|
33 /*! \page t30_page T.30 FAX protocol handling
|
|
|
34
|
|
|
35 \section t30_page_sec_1 What does it do?
|
|
|
36 The T.30 protocol is the core protocol used for FAX transmission. This module
|
|
|
37 implements most of its key featrues. It does not interface to the outside work.
|
|
|
38 Seperate modules do that for T.38, analogue line, and other forms of FAX
|
|
|
39 communication.
|
|
|
40
|
|
|
41 Current features of this module include:
|
|
|
42
|
|
|
43 - FAXing to and from multi-page TIFF/F files, whose images are one of the standard
|
|
|
44 FAX sizes.
|
|
|
45 - T.4 1D (MH), T.4 2D,(MR) and T.6 (MMR) compression.
|
|
|
46 - Error correction (ECM)
|
|
|
47 - All standard resolutions and page sizes
|
|
|
48
|
|
|
49 \section t30_page_sec_2 How does it work?
|
|
|
50
|
|
|
51 Some of the following is paraphrased from some notes found a while ago on the Internet.
|
|
|
52 I cannot remember exactly where they came from, but they are useful.
|
|
|
53
|
|
|
54 The answer (CED) tone
|
|
|
55
|
|
|
56 The T.30 standard says an answering fax device must send CED (a 2100Hz tone) for
|
|
|
57 approximately 3 seconds before sending the first handshake message. Some machines
|
|
|
58 send an 1100Hz or 1850Hz tone, and some send no tone at all. In fact, this answer
|
|
|
59 tone is so unpredictable, it cannot really be used. It should, however, always be
|
|
|
60 generated according to the specification.
|
|
|
61
|
|
|
62 Common Timing Deviations
|
|
|
63
|
|
|
64 The T.30 spec. specifies a number of time-outs. For example, after dialing a number,
|
|
|
65 a calling fax system should listen for a response for 35 seconds before giving up.
|
|
|
66 These time-out periods are as follows:
|
|
|
67
|
|
|
68 * T1 - 35+-5s: the maximum time for which two fax system will attempt to identify each other
|
|
|
69 * T2 - 6+-1s: a time-out used to start the sequence for changing transmit parameters
|
|
|
70 * T3 - 10+-5s: a time-out used in handling operator interrupts
|
|
|
71 * T5 - 60+-5s: a time-out used in error correction mode
|
|
|
72
|
|
|
73 These time-outs are sometimes misinterpreted. In addition, they are routinely
|
|
|
74 ignored, sometimes with good reason. For example, after placing a call, the
|
|
|
75 calling fax system is supposed to wait for 35 seconds before giving up. If the
|
|
|
76 answering unit does not answer on the first ring or if a voice answering machine
|
|
|
77 is connected to the line, or if there are many delays through the network,
|
|
|
78 the delay before answer can be much longer than 35 seconds.
|
|
|
79
|
|
|
80 Fax units that support error correction mode (ECM) can respond to a post-image
|
|
|
81 handshake message with a receiver not ready (RNR) message. The calling unit then
|
|
|
82 queries the receiving fax unit with a receiver ready (RR) message. If the
|
|
|
83 answering unit is still busy (printing for example), it will repeat the RNR
|
|
|
84 message. According to the T.30 standard, this sequence (RR/RNR RR/RNR) can be
|
|
|
85 repeated for up to the end of T5 (60+-5s). However, many fax systems
|
|
|
86 ignore the time-out and will continue the sequence indefinitely, unless the user
|
|
|
87 manually overrides.
|
|
|
88
|
|
|
89 All the time-outs are subject to alteration, and sometimes misuse. Good T.30
|
|
|
90 implementations must do the right thing, and tolerate others doing the wrong thing.
|
|
|
91
|
|
|
92 Variations in the inter-carrier gap
|
|
|
93
|
|
|
94 T.30 specifies 75+-20ms of silence between signals using different modulation
|
|
|
95 schemes. Examples are between the end of a DCS signal and the start of a TCF signal,
|
|
|
96 and between the end of an image and the start of a post-image signal. Many fax systems
|
|
|
97 violate this requirement, especially for the silent period between DCS and TCF.
|
|
|
98 This may be stretched to well over 100ms. If this period is too long, it can interfere with
|
|
|
99 handshake signal error recovery, should a packet be corrupted on the line. Systems
|
|
|
100 should ensure they stay within the prescribed T.30 limits, and be tolerant of others
|
|
|
101 being out of spec..
|
|
|
102
|
|
|
103 Other timing variations
|
|
|
104
|
|
|
105 Testing is required to determine the ability of a fax system to handle
|
|
|
106 variations in the duration of pauses between unacknowledged handshake message
|
|
|
107 repetitions, and also in the pauses between the receipt of a handshake command and
|
|
|
108 the start of a response to that command. In order to reduce the total
|
|
|
109 transmission time, many fax systems start sending a response message before the
|
|
|
110 end of the command has been received.
|
|
|
111
|
|
|
112 Other deviations from the T.30 standard
|
|
|
113
|
|
|
114 There are many other commonly encountered variations between machines, including:
|
|
|
115
|
|
|
116 * frame sequence deviations
|
|
|
117 * preamble and flag sequence variations
|
|
|
118 * improper EOM usage
|
|
|
119 * unusual data rate fallback sequences
|
|
|
120 * common training pattern detection algorithms
|
|
|
121 * image transmission deviations
|
|
|
122 * use of the talker echo protect tone
|
|
|
123 * image padding and short lines
|
|
|
124 * RTP/RTN handshake message usage
|
|
|
125 * long duration lines
|
|
|
126 * nonstandard disconnect sequences
|
|
|
127 * DCN usage
|
|
|
128 */
|
|
|
129
|
|
|
130 #define T30_MAX_DIS_DTC_DCS_LEN 22
|
|
|
131 #define T30_MAX_IDENT_LEN 21
|
|
|
132
|
|
|
133 typedef struct t30_state_s t30_state_t;
|
|
|
134
|
|
|
135 /*!
|
|
|
136 T.30 phase B callback handler.
|
|
|
137 \brief T.30 phase B callback handler.
|
|
|
138 \param s The T.30 context.
|
|
|
139 \param user_data An opaque pointer.
|
|
|
140 \param result The phase B event code.
|
|
|
141 */
|
|
|
142 typedef void (t30_phase_b_handler_t)(t30_state_t *s, void *user_data, int result);
|
|
|
143
|
|
|
144 /*!
|
|
|
145 T.30 phase D callback handler.
|
|
|
146 \brief T.30 phase D callback handler.
|
|
|
147 \param s The T.30 context.
|
|
|
148 \param user_data An opaque pointer.
|
|
|
149 \param result The phase D event code.
|
|
|
150 */
|
|
|
151 typedef void (t30_phase_d_handler_t)(t30_state_t *s, void *user_data, int result);
|
|
|
152
|
|
|
153 /*!
|
|
|
154 T.30 phase E callback handler.
|
|
|
155 \brief T.30 phase E callback handler.
|
|
|
156 \param s The T.30 context.
|
|
|
157 \param user_data An opaque pointer.
|
|
|
158 \param completion_code The phase E completion code.
|
|
|
159 */
|
|
|
160 typedef void (t30_phase_e_handler_t)(t30_state_t *s, void *user_data, int completion_code);
|
|
|
161
|
|
|
162 /*!
|
|
|
163 T.30 document handler.
|
|
|
164 \brief T.30 document handler.
|
|
|
165 \param s The T.30 context.
|
|
|
166 \param user_data An opaque pointer.
|
|
|
167 \param result The document event code.
|
|
|
168 */
|
|
|
169 typedef int (t30_document_handler_t)(t30_state_t *s, void *user_data, int status);
|
|
|
170
|
|
|
171 /*!
|
|
|
172 T.30 set a receive or transmit type handler.
|
|
|
173 \brief T.30 set a receive or transmit type handler.
|
|
|
174 \param user_data An opaque pointer.
|
|
|
175 \param type The modem, tone or silence to be sent or received.
|
|
|
176 \param short_train TRUE if the short training sequence should be used (where one exists).
|
|
|
177 \param use_hdlc FALSE for bit stream, TRUE for HDLC framing.
|
|
|
178 */
|
|
|
179 typedef void (t30_set_handler_t)(void *user_data, int type, int short_train, int use_hdlc);
|
|
|
180
|
|
|
181 /*!
|
|
|
182 T.30 send HDLC handler.
|
|
|
183 \brief T.30 send HDLC handler.
|
|
|
184 \param user_data An opaque pointer.
|
|
|
185 \param msg The HDLC message.
|
|
|
186 \param len The length of the message.
|
|
|
187 */
|
|
|
188 typedef void (t30_send_hdlc_handler_t)(void *user_data, const uint8_t *msg, int len);
|
|
|
189
|
|
|
190 /*!
|
|
|
191 T.30 protocol completion codes, at phase E.
|
|
|
192 */
|
|
|
193 enum
|
|
|
194 {
|
|
|
195 T30_ERR_OK = 0, /* OK */
|
|
|
196
|
|
|
197 /* External problems */
|
|
|
198 T30_ERR_CEDTONE, /* The CED tone exceeded 5s */
|
|
|
199 T30_ERR_T0EXPIRED, /* Timed out waiting for initial communication */
|
|
|
200 T30_ERR_T1EXPIRED, /* Timed out waiting for the first message */
|
|
|
201 T30_ERR_T3EXPIRED, /* Timed out waiting for procedural interrupt */
|
|
|
202 T30_ERR_HDLCCARR, /* The HDLC carrier did not stop in a timely manner */
|
|
|
203 T30_ERR_CANNOTTRAIN, /* Failed to train with any of the compatible modems */
|
|
|
204 T30_ERR_OPERINTFAIL, /* Operator intervention failed */
|
|
|
205 T30_ERR_INCOMPATIBLE, /* Far end is not compatible */
|
|
|
206 T30_ERR_NOTRXCAPABLE, /* Far end is not receive capable */
|
|
|
207 T30_ERR_NOTTXCAPABLE, /* Far end is not transmit capable */
|
|
|
208 T30_ERR_UNEXPECTED, /* Unexpected message received */
|
|
|
209 T30_ERR_NORESSUPPORT, /* Far end cannot receive at the resolution of the image */
|
|
|
210 T30_ERR_NOSIZESUPPORT, /* Far end cannot receive at the size of image */
|
|
|
211
|
|
|
212 /* Internal problems */
|
|
|
213 T30_ERR_FILEERROR, /* TIFF/F file cannot be opened */
|
|
|
214 T30_ERR_NOPAGE, /* TIFF/F page not found */
|
|
|
215 T30_ERR_BADTIFF, /* TIFF/F format is not compatible */
|
|
|
216 T30_ERR_UNSUPPORTED, /* Unsupported feature */
|
|
|
217
|
|
|
218 /* Phase E status values returned to a transmitter */
|
|
|
219 T30_ERR_BADDCSTX, /* Received bad response to DCS or training */
|
|
|
220 T30_ERR_BADPGTX, /* Received a DCN from remote after sending a page */
|
|
|
221 T30_ERR_ECMPHDTX, /* Invalid ECM response received from receiver */
|
|
|
222 T30_ERR_ECMRNRTX, /* Timer T5 expired, receiver not ready */
|
|
|
223 T30_ERR_GOTDCNTX, /* Received a DCN while waiting for a DIS */
|
|
|
224 T30_ERR_INVALRSPTX, /* Invalid response after sending a page */
|
|
|
225 T30_ERR_NODISTX, /* Received other than DIS while waiting for DIS */
|
|
|
226 T30_ERR_NXTCMDTX, /* Timed out waiting for next send_page command from driver */
|
|
|
227 T30_ERR_PHBDEADTX, /* Received no response to DCS, training or TCF */
|
|
|
228 T30_ERR_PHDDEADTX, /* No response after sending a page */
|
|
|
229
|
|
|
230 /* Phase E status values returned to a receiver */
|
|
|
231 T30_ERR_ECMPHDRX, /* Invalid ECM response received from transmitter */
|
|
|
232 T30_ERR_GOTDCSRX, /* DCS received while waiting for DTC */
|
|
|
233 T30_ERR_INVALCMDRX, /* Unexpected command after page received */
|
|
|
234 T30_ERR_NOCARRIERRX, /* Carrier lost during fax receive */
|
|
|
235 T30_ERR_NOEOLRX, /* Timed out while waiting for EOL (end Of line) */
|
|
|
236 T30_ERR_NOFAXRX, /* Timed out while waiting for first line */
|
|
|
237 T30_ERR_NXTCMDRX, /* Timed out waiting for next receive page command */
|
|
|
238 T30_ERR_T2EXPDCNRX, /* Timer T2 expired while waiting for DCN */
|
|
|
239 T30_ERR_T2EXPDRX, /* Timer T2 expired while waiting for phase D */
|
|
|
240 T30_ERR_T2EXPFAXRX, /* Timer T2 expired while waiting for fax page */
|
|
|
241 T30_ERR_T2EXPMPSRX, /* Timer T2 expired while waiting for next fax page */
|
|
|
242 T30_ERR_T2EXPRRRX, /* Timer T2 expired while waiting for RR command */
|
|
|
243 T30_ERR_T2EXPRX, /* Timer T2 expired while waiting for NSS, DCS or MCF */
|
|
|
244 T30_ERR_DCNWHYRX, /* Unexpected DCN while waiting for DCS or DIS */
|
|
|
245 T30_ERR_DCNDATARX, /* Unexpected DCN while waiting for image data */
|
|
|
246 T30_ERR_DCNFAXRX, /* Unexpected DCN while waiting for EOM, EOP or MPS */
|
|
|
247 T30_ERR_DCNPHDRX, /* Unexpected DCN after EOM or MPS sequence */
|
|
|
248 T30_ERR_DCNRRDRX, /* Unexpected DCN after RR/RNR sequence */
|
|
|
249 T30_ERR_DCNNORTNRX, /* Unexpected DCN after requested retransmission */
|
|
|
250
|
|
|
251 T30_ERR_BADPAGE, /* TIFF/F page number tag missing */
|
|
|
252 T30_ERR_BADTAG, /* Incorrect values for TIFF/F tags */
|
|
|
253 T30_ERR_BADTIFFHDR, /* Bad TIFF/F header - incorrect values in fields */
|
|
|
254 T30_ERR_BADPARM, /* Invalid value for fax parameter */
|
|
|
255 T30_ERR_BADSTATE, /* Invalid initial state value specified */
|
|
|
256 T30_ERR_CMDDATA, /* Last command contained invalid data */
|
|
|
257 T30_ERR_DISCONNECT, /* Fax call disconnected by the other station */
|
|
|
258 T30_ERR_INVALARG, /* Illegal argument to function */
|
|
|
259 T30_ERR_INVALFUNC, /* Illegal call to function */
|
|
|
260 T30_ERR_NODATA, /* Data requested is not available (NSF, DIS, DCS) */
|
|
|
261 T30_ERR_NOMEM, /* Cannot allocate memory for more pages */
|
|
|
262 T30_ERR_NOPOLL, /* Poll not accepted */
|
|
|
263 T30_ERR_NOSTATE, /* Initial state value not set */
|
|
|
264 T30_ERR_RETRYDCN, /* Disconnected after permitted retries */
|
|
|
265 T30_ERR_CALLDROPPED /* The call dropped prematurely */
|
|
|
266 };
|
|
|
267
|
|
|
268 /*!
|
|
|
269 I/O modes for the T.30 protocol.
|
|
|
270 */
|
|
|
271 enum
|
|
|
272 {
|
|
|
273 T30_MODEM_NONE = 0,
|
|
|
274 T30_MODEM_PAUSE,
|
|
|
275 T30_MODEM_CED,
|
|
|
276 T30_MODEM_CNG,
|
|
|
277 T30_MODEM_V21,
|
|
|
278 T30_MODEM_V27TER_2400,
|
|
|
279 T30_MODEM_V27TER_4800,
|
|
|
280 T30_MODEM_V29_7200,
|
|
|
281 T30_MODEM_V29_9600,
|
|
|
282 T30_MODEM_V17_7200,
|
|
|
283 T30_MODEM_V17_9600,
|
|
|
284 T30_MODEM_V17_12000,
|
|
|
285 T30_MODEM_V17_14400,
|
|
|
286 T30_MODEM_DONE
|
|
|
287 };
|
|
|
288
|
|
|
289 enum
|
|
|
290 {
|
|
|
291 T30_SUPPORT_V27TER = 0x01,
|
|
|
292 T30_SUPPORT_V29 = 0x02,
|
|
|
293 T30_SUPPORT_V17 = 0x04,
|
|
|
294 T30_SUPPORT_V34 = 0x08,
|
|
|
295 T30_SUPPORT_IAF = 0x10,
|
|
|
296 };
|
|
|
297
|
|
|
298 enum
|
|
|
299 {
|
|
|
300 T30_SUPPORT_NO_COMPRESSION = 0x01,
|
|
|
301 T30_SUPPORT_T4_1D_COMPRESSION = 0x02,
|
|
|
302 T30_SUPPORT_T4_2D_COMPRESSION = 0x04,
|
|
|
303 T30_SUPPORT_T6_COMPRESSION = 0x08,
|
|
|
304 T30_SUPPORT_T85_COMPRESSION = 0x10, /* Monochrome JBIG */
|
|
|
305 T30_SUPPORT_T43_COMPRESSION = 0x20, /* Colour JBIG */
|
|
|
306 T30_SUPPORT_T45_COMPRESSION = 0x40 /* Run length colour compression */
|
|
|
307 };
|
|
|
308
|
|
|
309 enum
|
|
|
310 {
|
|
|
311 T30_SUPPORT_STANDARD_RESOLUTION = 0x01,
|
|
|
312 T30_SUPPORT_FINE_RESOLUTION = 0x02,
|
|
|
313 T30_SUPPORT_SUPERFINE_RESOLUTION = 0x04,
|
|
|
314
|
|
|
315 T30_SUPPORT_R4_RESOLUTION = 0x10000,
|
|
|
316 T30_SUPPORT_R8_RESOLUTION = 0x20000,
|
|
|
317 T30_SUPPORT_R16_RESOLUTION = 0x40000,
|
|
|
318
|
|
|
319 T30_SUPPORT_300_300_RESOLUTION = 0x100000,
|
|
|
320 T30_SUPPORT_400_400_RESOLUTION = 0x200000,
|
|
|
321 T30_SUPPORT_600_600_RESOLUTION = 0x400000,
|
|
|
322 T30_SUPPORT_1200_1200_RESOLUTION = 0x800000,
|
|
|
323 T30_SUPPORT_300_600_RESOLUTION = 0x1000000,
|
|
|
324 T30_SUPPORT_400_800_RESOLUTION = 0x2000000,
|
|
|
325 T30_SUPPORT_600_1200_RESOLUTION = 0x4000000
|
|
|
326 };
|
|
|
327
|
|
|
328 enum
|
|
|
329 {
|
|
|
330 T30_SUPPORT_215MM_WIDTH = 0x01,
|
|
|
331 T30_SUPPORT_255MM_WIDTH = 0x02,
|
|
|
332 T30_SUPPORT_303MM_WIDTH = 0x04,
|
|
|
333
|
|
|
334 T30_SUPPORT_UNLIMITED_LENGTH = 0x10000,
|
|
|
335 T30_SUPPORT_A4_LENGTH = 0x20000,
|
|
|
336 T30_SUPPORT_B4_LENGTH = 0x40000,
|
|
|
337 T30_SUPPORT_US_LETTER_LENGTH = 0x80000,
|
|
|
338 T30_SUPPORT_US_LEGAL_LENGTH = 0x100000
|
|
|
339 };
|
|
|
340
|
|
|
341 enum
|
|
|
342 {
|
|
|
343 T30_SUPPORT_SEP = 0x01,
|
|
|
344 T30_SUPPORT_PSA = 0x02
|
|
|
345 };
|
|
|
346
|
|
|
347 enum
|
|
|
348 {
|
|
|
349 T30_IAF_MODE_T37 = 0x01,
|
|
|
350 T30_IAF_MODE_T38 = 0x02,
|
|
|
351 T30_IAF_MODE_FLOW_CONTROL = 0x04,
|
|
|
352 /*! Continuous flow mode means data is sent as fast as possible, usually across
|
|
|
353 the Internet, where speed is not constrained by a PSTN modem. */
|
|
|
354 T30_IAF_MODE_CONTINUOUS_FLOW = 0x08,
|
|
|
355 /*! No TCF means TCF is not exchanged. The end points must sort out usable speed
|
|
|
356 issues locally. */
|
|
|
357 T30_IAF_MODE_NO_TCF = 0x10,
|
|
|
358 /*! No fill bits means do not insert fill bits, even if the T.30 messages request
|
|
|
359 them. */
|
|
|
360 T30_IAF_MODE_NO_FILL_BITS = 0x20
|
|
|
361 };
|
|
|
362
|
|
|
363 /*!
|
|
|
364 T.30 FAX channel descriptor. This defines the state of a single working
|
|
|
365 instance of a T.30 FAX channel.
|
|
|
366 */
|
|
|
367 struct t30_state_s
|
|
|
368 {
|
|
|
369 /* This must be kept the first thing in the structure, so it can be pointed
|
|
|
370 to reliably as the structures change over time. */
|
|
|
371 t4_state_t t4;
|
|
|
372
|
|
|
373 /*! \brief TRUE is behaving as the calling party */
|
|
|
374 int calling_party;
|
|
|
375
|
|
|
376 /*! \brief The local identifier string. */
|
|
|
377 char local_ident[T30_MAX_IDENT_LEN];
|
|
|
378 /*! \brief The identifier string supplied by the remote FAX machine. */
|
|
|
379 char far_ident[T30_MAX_IDENT_LEN];
|
|
|
380 /*! \brief The sub-address string to be sent to the remote FAX machine. */
|
|
|
381 char local_sub_address[T30_MAX_IDENT_LEN];
|
|
|
382 /*! \brief The sub-address string supplied by the remote FAX machine. */
|
|
|
383 char far_sub_address[T30_MAX_IDENT_LEN];
|
|
|
384 /*! \brief The selective polling sub-address supplied by the remote FAX machine. */
|
|
|
385 char sep_address[T30_MAX_IDENT_LEN];
|
|
|
386 /*! \brief The polled sub-address supplied by the remote FAX machine. */
|
|
|
387 char psa_address[T30_MAX_IDENT_LEN];
|
|
|
388 /*! \brief A password to be associated with the T.30 context. */
|
|
|
389 char local_password[T30_MAX_IDENT_LEN];
|
|
|
390 /*! \brief A password expected from the far end. */
|
|
|
391 char far_password[T30_MAX_IDENT_LEN];
|
|
|
392 /*! \brief The text which will be used in FAX page header. No text results
|
|
|
393 in no header line. */
|
|
|
394 char header_info[50 + 1];
|
|
|
395 /*! \brief The country of origin of the remote machine, if known, else NULL. */
|
|
|
396 const char *country;
|
|
|
397 /*! \brief The vendor of the remote machine, if known, else NULL. */
|
|
|
398 const char *vendor;
|
|
|
399 /*! \brief The model of the remote machine, if known, else NULL. */
|
|
|
400 const char *model;
|
|
|
401 uint8_t local_nsf[100];
|
|
|
402 int local_nsf_len;
|
|
|
403
|
|
|
404 /*! \brief A pointer to a callback routine to be called when phase B events
|
|
|
405 occur. */
|
|
|
406 t30_phase_b_handler_t *phase_b_handler;
|
|
|
407 /*! \brief An opaque pointer supplied in event B callbacks. */
|
|
|
408 void *phase_b_user_data;
|
|
|
409 /*! \brief A pointer to a callback routine to be called when phase D events
|
|
|
410 occur. */
|
|
|
411 t30_phase_d_handler_t *phase_d_handler;
|
|
|
412 /*! \brief An opaque pointer supplied in event D callbacks. */
|
|
|
413 void *phase_d_user_data;
|
|
|
414 /*! \brief A pointer to a callback routine to be called when phase E events
|
|
|
415 occur. */
|
|
|
416 t30_phase_e_handler_t *phase_e_handler;
|
|
|
417 /*! \brief An opaque pointer supplied in event E callbacks. */
|
|
|
418 void *phase_e_user_data;
|
|
|
419
|
|
|
420 /*! \brief A pointer to a callback routine to be called when document events
|
|
|
421 (e.g. end of transmitted document) occur. */
|
|
|
422 t30_document_handler_t *document_handler;
|
|
|
423 /*! \brief An opaque pointer supplied in document callbacks. */
|
|
|
424 void *document_user_data;
|
|
|
425
|
|
|
426 t30_set_handler_t *set_rx_type_handler;
|
|
|
427 void *set_rx_type_user_data;
|
|
|
428 t30_set_handler_t *set_tx_type_handler;
|
|
|
429 void *set_tx_type_user_data;
|
|
|
430
|
|
|
431 t30_send_hdlc_handler_t *send_hdlc_handler;
|
|
|
432 void *send_hdlc_user_data;
|
|
|
433
|
|
|
434 int phase;
|
|
|
435 int next_phase;
|
|
|
436 int state;
|
|
|
437 int step;
|
|
|
438
|
|
|
439 uint8_t dcs_frame[T30_MAX_DIS_DTC_DCS_LEN];
|
|
|
440 int dcs_len;
|
|
|
441 uint8_t dis_dtc_frame[T30_MAX_DIS_DTC_DCS_LEN];
|
|
|
442 int dis_dtc_len;
|
|
|
443 /*! \brief TRUE if a valid DIS has been received from the far end. */
|
|
|
444 int dis_received;
|
|
|
445 /*! \brief TRUE if a valid passwrod has been received from the far end. */
|
|
|
446 int far_password_ok;
|
|
|
447
|
|
|
448 /*! \brief A flag to indicate a message is in progress. */
|
|
|
449 int in_message;
|
|
|
450
|
|
|
451 /*! \brief TRUE if the short training sequence should be used. */
|
|
|
452 int short_train;
|
|
|
453
|
|
|
454 /*! \brief A count of the number of bits in the trainability test. */
|
|
|
455 int training_test_bits;
|
|
|
456 int training_current_zeros;
|
|
|
457 int training_most_zeros;
|
|
|
458
|
|
|
459 /*! \brief The current fallback step for the fast message transfer modem. */
|
|
|
460 int current_fallback;
|
|
|
461 /*! \brief TRUE if a carrier is present. Otherwise FALSE. */
|
|
|
462 int rx_signal_present;
|
|
|
463 /*! \brief TRUE if a modem has trained correctly. */
|
|
|
464 int rx_trained;
|
|
|
465 int current_rx_type;
|
|
|
466 int current_tx_type;
|
|
|
467
|
|
|
468 /*! \brief T0 is the answer timeout when calling another FAX machine.
|
|
|
469 Placing calls is handled outside the FAX processing, but this timeout keeps
|
|
|
470 running until V.21 modulation is sent or received.
|
|
|
471 T1 is the remote terminal identification timeout (in audio samples). */
|
|
|
472 int timer_t0_t1;
|
|
|
473 /*! \brief T2 is the HDLC command timeout.
|
|
|
474 T4 is the HDLC response timeout (in audio samples). */
|
|
|
475 int timer_t2_t4;
|
|
|
476 /*! \brief TRUE if the T2/T4 timer is actually timing T4 */
|
|
|
477 int timer_is_t4;
|
|
|
478 /*! \brief Procedural interrupt timeout (in audio samples). */
|
|
|
479 int timer_t3;
|
|
|
480 /*! \brief This is only used in error correcting mode. */
|
|
|
481 int timer_t5;
|
|
|
482 /*! \brief This is only used in full duplex (e.g. ISDN) modes. */
|
|
|
483 int timer_t6;
|
|
|
484 /*! \brief This is only used in full duplex (e.g. ISDN) modes. */
|
|
|
485 int timer_t7;
|
|
|
486 /*! \brief This is only used in full duplex (e.g. ISDN) modes. */
|
|
|
487 int timer_t8;
|
|
|
488
|
|
|
489 int far_end_detected;
|
|
|
490
|
|
|
491 int local_interrupt_pending;
|
|
|
492 int crp_enabled;
|
|
|
493 int line_encoding;
|
|
|
494 int min_row_bits;
|
|
|
495 int x_resolution;
|
|
|
496 int y_resolution;
|
|
|
497 int image_width;
|
|
|
498 int retries;
|
|
|
499 int error_correcting_mode;
|
|
|
500 int ppr_count;
|
|
|
501 int octets_per_ecm_frame;
|
|
|
502 uint8_t ecm_data[256][260];
|
|
|
503 int16_t ecm_len[256];
|
|
|
504 uint8_t ecm_frame_map[3 + 32];
|
|
|
505 int ecm_page;
|
|
|
506 int ecm_block;
|
|
|
507 int ecm_frames;
|
|
|
508 int ecm_current_frame;
|
|
|
509 int ecm_at_page_end;
|
|
|
510 int next_tx_step;
|
|
|
511 int next_rx_step;
|
|
|
512 char rx_file[256];
|
|
|
513 int rx_stop_page;
|
|
|
514 char tx_file[256];
|
|
|
515 int tx_start_page;
|
|
|
516 int tx_stop_page;
|
|
|
517 int current_status;
|
|
|
518 int iaf;
|
|
|
519 int supported_modems;
|
|
|
520 int supported_compressions;
|
|
|
521 int supported_resolutions;
|
|
|
522 int supported_image_sizes;
|
|
|
523 int supported_polling_features;
|
|
|
524 int ecm_allowed;
|
|
|
525 /*! \brief Error and flow logging control */
|
|
|
526 logging_state_t logging;
|
|
|
527 };
|
|
|
528
|
|
|
529 typedef struct
|
|
|
530 {
|
|
|
531 /*! \brief The current bit rate for image transfer. */
|
|
|
532 int bit_rate;
|
|
|
533 /*! \brief TRUE if error correcting mode is used. */
|
|
|
534 int error_correcting_mode;
|
|
|
535 /*! \brief The number of pages transferred so far. */
|
|
|
536 int pages_transferred;
|
|
|
537 /*! \brief The number of horizontal pixels in the most recent page. */
|
|
|
538 int width;
|
|
|
539 /*! \brief The number of vertical pixels in the most recent page. */
|
|
|
540 int length;
|
|
|
541 /*! \brief The number of bad pixel rows in the most recent page. */
|
|
|
542 int bad_rows;
|
|
|
543 /*! \brief The largest number of bad pixel rows in a block in the most recent page. */
|
|
|
544 int longest_bad_row_run;
|
|
|
545 /*! \brief The horizontal column-to-column resolution of the page in pixels per metre */
|
|
|
546 int x_resolution;
|
|
|
547 /*! \brief The vertical row-to-row resolution of the page in pixels per metre */
|
|
|
548 int y_resolution;
|
|
|
549 /*! \brief The type of compression used between the FAX machines */
|
|
|
550 int encoding;
|
|
|
551 /*! \brief The size of the image, in bytes */
|
|
|
552 int image_size;
|
|
|
553 /*! \brief Current status */
|
|
|
554 int current_status;
|
|
|
555 } t30_stats_t;
|
|
|
556
|
|
|
557 #ifdef __cplusplus
|
|
|
558 extern "C" {
|
|
|
559 #endif
|
|
|
560
|
|
|
561 /*! Initialise a T.30 context.
|
|
|
562 \brief Initialise a T.30 context.
|
|
|
563 \param s The T.30 context.
|
|
|
564 \param calling_party TRUE if the context is for a calling party. FALSE if the
|
|
|
565 context is for an answering party.
|
|
|
566 \return 0 for OK, else -1. */
|
|
|
567 int t30_init(t30_state_t *s,
|
|
|
568 int calling_party,
|
|
|
569 t30_set_handler_t *set_rx_type_handler,
|
|
|
570 void *set_rx_type_user_data,
|
|
|
571 t30_set_handler_t *set_tx_type_handler,
|
|
|
572 void *set_tx_type_user_data,
|
|
|
573 t30_send_hdlc_handler_t *send_hdlc_handler,
|
|
|
574 void *send_hdlc_user_data);
|
|
|
575
|
|
|
576 /*! Release a T.30 context.
|
|
|
577 \brief Release a T.30 context.
|
|
|
578 \param s The T.30 context. */
|
|
|
579 void t30_release(t30_state_t *s);
|
|
|
580
|
|
|
581 /*! Restart a T.30 context.
|
|
|
582 \brief Restart a T.30 context.
|
|
|
583 \param s The T.30 context.
|
|
|
584 \return 0 for OK, else -1. */
|
|
|
585 int t30_restart(t30_state_t *s);
|
|
|
586
|
|
|
587 /*! Create and initialise a T.30 context.
|
|
|
588 \brief Create and initialise a T.30 context.
|
|
|
589 \param calling_party TRUE if the context is for a calling party. FALSE if the
|
|
|
590 context is for an answering party.
|
|
|
591 \return A pointer to the FAX context, or NULL if one could not be created.
|
|
|
592 */
|
|
|
593 t30_state_t *t30_create(int calling_party,
|
|
|
594 t30_set_handler_t *set_rx_type_handler,
|
|
|
595 void *set_rx_type_user_data,
|
|
|
596 t30_set_handler_t *set_tx_type_handler,
|
|
|
597 void *set_tx_type_user_data,
|
|
|
598 t30_send_hdlc_handler_t *send_hdlc_handler,
|
|
|
599 void *send_hdlc_user_data);
|
|
|
600
|
|
|
601 /*! Free a T.30 context.
|
|
|
602 \brief Free a T.30 context.
|
|
|
603 \param s The T.30 context. */
|
|
|
604 void t30_free(t30_state_t *s);
|
|
|
605
|
|
|
606 /*! Cleanup a T.30 context if the call terminates.
|
|
|
607 \brief Cleanup a T.30 context if the call terminates.
|
|
|
608 \param s The T.30 context. */
|
|
|
609 void t30_terminate(t30_state_t *s);
|
|
|
610
|
|
|
611 /*! Return a text name for a T.30 frame type.
|
|
|
612 \brief Return a text name for a T.30 frame type.
|
|
|
613 \param x The frametype octet.
|
|
|
614 \return A pointer to the text name for the frame type. If the frame type is
|
|
|
615 not value, the string "???" is returned. */
|
|
|
616 const char *t30_frametype(uint8_t x);
|
|
|
617
|
|
|
618 /*! Decode a DIS, DTC or DCS frame, and log the contents.
|
|
|
619 \brief Decode a DIS, DTC or DCS frame, and log the contents.
|
|
|
620 \param s The T.30 context.
|
|
|
621 \param dis A pointer to the frame to be decoded.
|
|
|
622 \param len The length of the frame. */
|
|
|
623 void t30_decode_dis_dtc_dcs(t30_state_t *s, const uint8_t *dis, int len);
|
|
|
624
|
|
|
625 /*! Convert a phase E completion code to a short text description.
|
|
|
626 \brief Convert a phase E completion code to a short text description.
|
|
|
627 \param result The result code.
|
|
|
628 \return A pointer to the description. */
|
|
|
629 const char *t30_completion_code_to_str(int result);
|
|
|
630
|
|
|
631 /*! Set Internet aware FAX (IAF) mode.
|
|
|
632 \brief Set Internet aware FAX (IAF) mode.
|
|
|
633 \param s The T.30 context.
|
|
|
634 \param iaf TRUE for IAF, or FALSE for non-IAF. */
|
|
|
635 void t30_set_iaf_mode(t30_state_t *s, int iaf);
|
|
|
636
|
|
|
637 /*! Set the sub-address associated with a T.30 context.
|
|
|
638 \brief Set the sub-address associated with a T.30 context.
|
|
|
639 \param s The T.30 context.
|
|
|
640 \param sub_address A pointer to the sub-address.
|
|
|
641 \return 0 for OK, else -1. */
|
|
|
642 int t30_set_local_sub_address(t30_state_t *s, const char *sub_address);
|
|
|
643
|
|
|
644 /*! Set the header information associated with a T.30 context.
|
|
|
645 \brief Set the header information associated with a T.30 context.
|
|
|
646 \param s The T.30 context.
|
|
|
647 \param info A pointer to the information string.
|
|
|
648 \return 0 for OK, else -1. */
|
|
|
649 int t30_set_header_info(t30_state_t *s, const char *info);
|
|
|
650
|
|
|
651 /*! Set the local identifier associated with a T.30 context.
|
|
|
652 \brief Set the local identifier associated with a T.30 context.
|
|
|
653 \param s The T.30 context.
|
|
|
654 \param id A pointer to the identifier.
|
|
|
655 \return 0 for OK, else -1. */
|
|
|
656 int t30_set_local_ident(t30_state_t *s, const char *id);
|
|
|
657
|
|
|
658 int t30_set_local_nsf(t30_state_t *s, const uint8_t *nsf, int len);
|
|
|
659
|
|
|
660 /*! Get the sub-address associated with a T.30 context.
|
|
|
661 \brief Get the sub-address associated with a T.30 context.
|
|
|
662 \param s The T.30 context.
|
|
|
663 \param sub_address A pointer to a buffer for the sub-address. The buffer
|
|
|
664 should be at least 21 bytes long.
|
|
|
665 \return the length of the string. */
|
|
|
666 size_t t30_get_sub_address(t30_state_t *s, char *sub_address);
|
|
|
667
|
|
|
668 /*! Get the header information associated with a T.30 context.
|
|
|
669 \brief Get the header information associated with a T.30 context.
|
|
|
670 \param s The T.30 context.
|
|
|
671 \param sub_address A pointer to a buffer for the header information. The buffer
|
|
|
672 should be at least 51 bytes long.
|
|
|
673 \return the length of the string. */
|
|
|
674 size_t t30_get_header_info(t30_state_t *s, char *info);
|
|
|
675
|
|
|
676 /*! Get the local FAX machine identifier associated with a T.30 context.
|
|
|
677 \brief Get the local identifier associated with a T.30 context.
|
|
|
678 \param s The T.30 context.
|
|
|
679 \param id A pointer to a buffer for the identifier. The buffer should
|
|
|
680 be at least 21 bytes long.
|
|
|
681 \return the length of the string. */
|
|
|
682 size_t t30_get_local_ident(t30_state_t *s, char *id);
|
|
|
683
|
|
|
684 /*! Get the remote FAX machine identifier associated with a T.30 context.
|
|
|
685 \brief Get the remote identifier associated with a T.30 context.
|
|
|
686 \param s The T.30 context.
|
|
|
687 \param id A pointer to a buffer for the identifier. The buffer should
|
|
|
688 be at least 21 bytes long.
|
|
|
689 \return the length of the string. */
|
|
|
690 size_t t30_get_far_ident(t30_state_t *s, char *id);
|
|
|
691
|
|
|
692 /*! Get the country of origin of the remote FAX machine associated with a T.30 context.
|
|
|
693 \brief Get the country of origin of the remote FAX machine associated with a T.30 context.
|
|
|
694 \param s The T.30 context.
|
|
|
695 \return a pointer to the country name, or NULL if the country is not known. */
|
|
|
696 const char *t30_get_far_country(t30_state_t *s);
|
|
|
697
|
|
|
698 /*! Get the name of the vendor of the remote FAX machine associated with a T.30 context.
|
|
|
699 \brief Get the name of the vendor of the remote FAX machine associated with a T.30 context.
|
|
|
700 \param s The T.30 context.
|
|
|
701 \return a pointer to the vendor name, or NULL if the vendor is not known. */
|
|
|
702 const char *t30_get_far_vendor(t30_state_t *s);
|
|
|
703
|
|
|
704 /*! Get the name of the model of the remote FAX machine associated with a T.30 context.
|
|
|
705 \brief Get the name of the model of the remote FAX machine associated with a T.30 context.
|
|
|
706 \param s The T.30 context.
|
|
|
707 \return a pointer to the model name, or NULL if the model is not known. */
|
|
|
708 const char *t30_get_far_model(t30_state_t *s);
|
|
|
709
|
|
|
710 /*! Get the current transfer statistics for the file being sent or received.
|
|
|
711 \brief Get the current transfer statistics.
|
|
|
712 \param s The T.30 context.
|
|
|
713 \param t A pointer to a buffer for the statistics. */
|
|
|
714 void t30_get_transfer_statistics(t30_state_t *s, t30_stats_t *t);
|
|
|
715
|
|
|
716 /*! Set a callback function for T.30 phase B handling.
|
|
|
717 \brief Set a callback function for T.30 phase B handling.
|
|
|
718 \param s The T.30 context.
|
|
|
719 \param handler The callback function
|
|
|
720 \param user_data An opaque pointer passed to the callback function. */
|
|
|
721 void t30_set_phase_b_handler(t30_state_t *s, t30_phase_b_handler_t *handler, void *user_data);
|
|
|
722
|
|
|
723 /*! Set a callback function for T.30 phase D handling.
|
|
|
724 \brief Set a callback function for T.30 phase D handling.
|
|
|
725 \param s The T.30 context.
|
|
|
726 \param handler The callback function
|
|
|
727 \param user_data An opaque pointer passed to the callback function. */
|
|
|
728 void t30_set_phase_d_handler(t30_state_t *s, t30_phase_d_handler_t *handler, void *user_data);
|
|
|
729
|
|
|
730 /*! Set a callback function for T.30 phase E handling.
|
|
|
731 \brief Set a callback function for T.30 phase E handling.
|
|
|
732 \param s The T.30 context.
|
|
|
733 \param handler The callback function
|
|
|
734 \param user_data An opaque pointer passed to the callback function. */
|
|
|
735 void t30_set_phase_e_handler(t30_state_t *s, t30_phase_e_handler_t *handler, void *user_data);
|
|
|
736
|
|
|
737 /*! Set a callback function for T.30 end of document handling.
|
|
|
738 \brief Set a callback function for T.30 end of document handling.
|
|
|
739 \param s The T.30 context.
|
|
|
740 \param handler The callback function
|
|
|
741 \param user_data An opaque pointer passed to the callback function. */
|
|
|
742 void t30_set_document_handler(t30_state_t *s, t30_document_handler_t *handler, void *user_data);
|
|
|
743
|
|
|
744 /*! Specify the file name of the next TIFF file to be received by a T.30
|
|
|
745 context.
|
|
|
746 \brief Set next receive file name.
|
|
|
747 \param s The T.30 context.
|
|
|
748 \param file The file name
|
|
|
749 \param stop_page The maximum page to receive. -1 for no restriction. */
|
|
|
750 void t30_set_rx_file(t30_state_t *s, const char *file, int stop_page);
|
|
|
751
|
|
|
752 /*! Specify the file name of the next TIFF file to be transmitted by a T.30
|
|
|
753 context.
|
|
|
754 \brief Set next transmit file name.
|
|
|
755 \param s The T.30 context.
|
|
|
756 \param file The file name
|
|
|
757 \param start_page The first page to send. -1 for no restriction.
|
|
|
758 \param stop_page The last page to send. -1 for no restriction. */
|
|
|
759 void t30_set_tx_file(t30_state_t *s, const char *file, int start_page, int stop_page);
|
|
|
760
|
|
|
761 /*! Specify which modem types are supported by a T.30 context.
|
|
|
762 \brief Specify supported modems.
|
|
|
763 \param s The T.30 context.
|
|
|
764 \param supported_modems Bit field list of the supported modems. */
|
|
|
765 void t30_set_supported_modems(t30_state_t *s, int supported_modems);
|
|
|
766
|
|
|
767 /*! Specify which compression types are supported by a T.30 context.
|
|
|
768 \brief Specify supported compression types.
|
|
|
769 \param s The T.30 context.
|
|
|
770 \param supported_compressions Bit field list of the supported compression types. */
|
|
|
771 void t30_set_supported_compressions(t30_state_t *s, int supported_compressions);
|
|
|
772
|
|
|
773 /*! Specify which resolutions are supported by a T.30 context.
|
|
|
774 \brief Specify supported resolutions.
|
|
|
775 \param s The T.30 context.
|
|
|
776 \param supported_compressions Bit field list of the supported resolutions. */
|
|
|
777 void t30_set_supported_resolutions(t30_state_t *s, int supported_resolutions);
|
|
|
778
|
|
|
779 /*! Specify which images sizes are supported by a T.30 context.
|
|
|
780 \brief Specify supported image sizes.
|
|
|
781 \param s The T.30 context.
|
|
|
782 \param supported_image_sizes Bit field list of the supported widths and lengths. */
|
|
|
783 void t30_set_supported_image_sizes(t30_state_t *s, int supported_image_sizes);
|
|
|
784
|
|
|
785 /*! Specify if error correction mode (ECM) is allowed by a T.30 context.
|
|
|
786 \brief Select ECM capability.
|
|
|
787 \param s The T.30 context.
|
|
|
788 \param enabled TRUE for ECM capable, FALSE for not ECM capable. */
|
|
|
789 void t30_set_ecm_capability(t30_state_t *s, int enabled);
|
|
|
790
|
|
|
791 /*! Request a local interrupt of FAX exchange.
|
|
|
792 \brief Request a local interrupt of FAX exchange.
|
|
|
793 \param s The T.30 context.
|
|
|
794 \param state TRUE to enable interrupt request, else FALSE. */
|
|
|
795 void t30_local_interrupt_request(t30_state_t *s, int state);
|
|
|
796
|
|
|
797 /*! Inform the T.30 engine the current transmission has completed.
|
|
|
798 \brief Inform the T.30 engine the current transmission has completed.
|
|
|
799 \param s The T.30 context. */
|
|
|
800 void t30_send_complete(void *user_data);
|
|
|
801
|
|
|
802 /*! Inform the T.30 engine the current receive has completed. This is
|
|
|
803 only needed to report an unexpected end of the receive operation, as
|
|
|
804 might happen with T.38 dying.
|
|
|
805 \brief Inform the T.30 engine the current receive has completed.
|
|
|
806 \param s The T.30 context. */
|
|
|
807 void t30_receive_complete(void *user_data);
|
|
|
808
|
|
|
809 /*! Get a bit of received non-ECM image data.
|
|
|
810 \brief Get a bit of received non-ECM image data.
|
|
|
811 \param user_data An opaque pointer, which must point to the T.30 context.
|
|
|
812 \return bit The next bit to transmit. */
|
|
|
813 int t30_non_ecm_get_bit(void *user_data);
|
|
|
814
|
|
|
815 /*! Process a bit of received non-ECM image data.
|
|
|
816 \brief Process a bit of received non-ECM image data
|
|
|
817 \param user_data An opaque pointer, which must point to the T.30 context.
|
|
|
818 \param bit The received bit. */
|
|
|
819 void t30_non_ecm_put_bit(void *user_data, int bit);
|
|
|
820
|
|
|
821 /*! Process a byte of received non-ECM image data.
|
|
|
822 \brief Process a byte of received non-ECM image data
|
|
|
823 \param user_data An opaque pointer, which must point to the T.30 context.
|
|
|
824 \param byte The received byte. */
|
|
|
825 void t30_non_ecm_putbyte(void *user_data, int byte);
|
|
|
826
|
|
|
827 /*! Process a received HDLC frame.
|
|
|
828 \brief Process a received HDLC frame.
|
|
|
829 \param s The T.30 context.
|
|
|
830 \param ok TRUE if the frame was received without error.
|
|
|
831 \param msg The HDLC message.
|
|
|
832 \param int The length of the message, in octets. */
|
|
|
833 void t30_hdlc_accept(void *user_data, int ok, const uint8_t *msg, int len);
|
|
|
834
|
|
|
835 /*! Report the passage of time to the T.30 engine.
|
|
|
836 \brief Report the passage of time to the T.30 engine.
|
|
|
837 \param s The T.30 context.
|
|
|
838 \param samples The time change in 1/8000th second steps. */
|
|
|
839 void t30_timer_update(t30_state_t *s, int samples);
|
|
|
840
|
|
|
841 #ifdef __cplusplus
|
|
|
842 }
|
|
|
843 #endif
|
|
|
844
|
|
|
845 #endif
|
|
|
846 /*- End of file ------------------------------------------------------------*/
|
