Mercurial > hg > audiostuff

comparison spandsp-0.0.6pre17/src/spandsp/t30.h @ 4:26cd8f1ef0b1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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 ------------------------------------------------------------*/

Repositories maintained by Peter Meerwald, pmeerw@pmeerw.net.