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