Mercurial > hg > audiostuff

comparison spandsp-0.0.3/spandsp-0.0.3/src/spandsp/t30.h @ 5:f762bf195c4b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
import spandsp-0.0.3
author Peter Meerwald <pmeerw@cosy.sbg.ac.at>
date Fri, 25 Jun 2010 16:00:21 +0200
parents
children
comparison
equal deleted inserted replaced
4:26cd8f1ef0b1 5:f762bf195c4b
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 ------------------------------------------------------------*/

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