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.110 2008/06/28 02:14:26 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 #define T30_MAX_DIS_DTC_DCS_LEN 22 144 #define T30_MAX_IDENT_LEN 20 145 #define T30_MAX_PAGE_HEADER_INFO 50 146 147 typedef struct t30_state_s t30_state_t; 148 149 /*! 150 T.30 phase B callback handler. This handler can be used to process addition 151 information available in some FAX calls, such as passwords. The callback handler 152 can access whatever additional information might have been received, using 153 t30_get_received_info(). 154 \brief T.30 phase B callback handler. 155 \param s The T.30 context. 156 \param user_data An opaque pointer. 157 \param result The phase B event code. 158 \return The new status. Normally, T30_ERR_OK is returned. 159 */ 160 typedef int (t30_phase_b_handler_t)(t30_state_t *s, void *user_data, int result); 161 162 /*! 163 T.30 phase D callback handler. 164 \brief T.30 phase D callback handler. 165 \param s The T.30 context. 166 \param user_data An opaque pointer. 167 \param result The phase D event code. 168 \return The new status. Normally, T30_ERR_OK is returned. 169 */ 170 typedef int (t30_phase_d_handler_t)(t30_state_t *s, void *user_data, int result); 171 172 /*! 173 T.30 phase E callback handler. 174 \brief T.30 phase E callback handler. 175 \param s The T.30 context. 176 \param user_data An opaque pointer. 177 \param completion_code The phase E completion code. 178 */ 179 typedef void (t30_phase_e_handler_t)(t30_state_t *s, void *user_data, int completion_code); 180 181 /*! 182 T.30 real time frame handler. 183 \brief T.30 real time frame handler. 184 \param s The T.30 context. 185 \param user_data An opaque pointer. 186 \param direction TRUE for incoming, FALSE for outgoing. 187 \param msg The HDLC message. 188 \param len The length of the message. 189 */ 190 typedef void (t30_real_time_frame_handler_t)(t30_state_t *s, 191 void *user_data, 192 int direction, 193 const uint8_t *msg, 194 int len); 195 196 /*! 197 T.30 document handler. 198 \brief T.30 document handler. 199 \param s The T.30 context. 200 \param user_data An opaque pointer. 201 \param result The document event code. 202 */ 203 typedef int (t30_document_handler_t)(t30_state_t *s, void *user_data, int status); 204 205 /*! 206 T.30 set a receive or transmit type handler. 207 \brief T.30 set a receive or transmit type handler. 208 \param user_data An opaque pointer. 209 \param type The modem, tone or silence to be sent or received. 210 \param short_train TRUE if the short training sequence should be used (where one exists). 211 \param use_hdlc FALSE for bit stream, TRUE for HDLC framing. 212 */ 213 typedef void (t30_set_handler_t)(void *user_data, int type, int short_train, int use_hdlc); 214 215 /*! 216 T.30 send HDLC handler. 217 \brief T.30 send HDLC handler. 218 \param user_data An opaque pointer. 219 \param msg The HDLC message. 220 \param len The length of the message. 221 */ 222 typedef void (t30_send_hdlc_handler_t)(void *user_data, const uint8_t *msg, int len); 223 224 /*! 225 T.30 protocol completion codes, at phase E. 226 */ 227 enum 228 { 229 T30_ERR_OK = 0, /*! OK */ 230 231 /* Link problems */ 232 T30_ERR_CEDTONE, /*! The CED tone exceeded 5s */ 233 T30_ERR_T0_EXPIRED, /*! Timed out waiting for initial communication */ 234 T30_ERR_T1_EXPIRED, /*! Timed out waiting for the first message */ 235 T30_ERR_T3_EXPIRED, /*! Timed out waiting for procedural interrupt */ 236 T30_ERR_HDLC_CARRIER, /*! The HDLC carrier did not stop in a timely manner */ 237 T30_ERR_CANNOT_TRAIN, /*! Failed to train with any of the compatible modems */ 238 T30_ERR_OPER_INT_FAIL, /*! Operator intervention failed */ 239 T30_ERR_INCOMPATIBLE, /*! Far end is not compatible */ 240 T30_ERR_RX_INCAPABLE, /*! Far end is not able to receive */ 241 T30_ERR_TX_INCAPABLE, /*! Far end is not able to transmit */ 242 T30_ERR_NORESSUPPORT, /*! Far end cannot receive at the resolution of the image */ 243 T30_ERR_NOSIZESUPPORT, /*! Far end cannot receive at the size of image */ 244 T30_ERR_UNEXPECTED, /*! Unexpected message received */ 245 246 /* Phase E status values returned to a transmitter */ 247 T30_ERR_TX_BADDCS, /*! Received bad response to DCS or training */ 248 T30_ERR_TX_BADPG, /*! Received a DCN from remote after sending a page */ 249 T30_ERR_TX_ECMPHD, /*! Invalid ECM response received from receiver */ 250 T30_ERR_TX_GOTDCN, /*! Received a DCN while waiting for a DIS */ 251 T30_ERR_TX_INVALRSP, /*! Invalid response after sending a page */ 252 T30_ERR_TX_NODIS, /*! Received other than DIS while waiting for DIS */ 253 T30_ERR_TX_PHBDEAD, /*! Received no response to DCS, training or TCF */ 254 T30_ERR_TX_PHDDEAD, /*! No response after sending a page */ 255 T30_ERR_TX_T5EXP, /*! Timed out waiting for receiver ready (ECM mode) */ 256 257 /* Phase E status values returned to a receiver */ 258 T30_ERR_RX_ECMPHD, /*! Invalid ECM response received from transmitter */ 259 T30_ERR_RX_GOTDCS, /*! DCS received while waiting for DTC */ 260 T30_ERR_RX_INVALCMD, /*! Unexpected command after page received */ 261 T30_ERR_RX_NOCARRIER, /*! Carrier lost during fax receive */ 262 T30_ERR_RX_NOEOL, /*! Timed out while waiting for EOL (end Of line) */ 263 T30_ERR_RX_NOFAX, /*! Timed out while waiting for first line */ 264 T30_ERR_RX_T2EXPDCN, /*! Timer T2 expired while waiting for DCN */ 265 T30_ERR_RX_T2EXPD, /*! Timer T2 expired while waiting for phase D */ 266 T30_ERR_RX_T2EXPFAX, /*! Timer T2 expired while waiting for fax page */ 267 T30_ERR_RX_T2EXPMPS, /*! Timer T2 expired while waiting for next fax page */ 268 T30_ERR_RX_T2EXPRR, /*! Timer T2 expired while waiting for RR command */ 269 T30_ERR_RX_T2EXP, /*! Timer T2 expired while waiting for NSS, DCS or MCF */ 270 T30_ERR_RX_DCNWHY, /*! Unexpected DCN while waiting for DCS or DIS */ 271 T30_ERR_RX_DCNDATA, /*! Unexpected DCN while waiting for image data */ 272 T30_ERR_RX_DCNFAX, /*! Unexpected DCN while waiting for EOM, EOP or MPS */ 273 T30_ERR_RX_DCNPHD, /*! Unexpected DCN after EOM or MPS sequence */ 274 T30_ERR_RX_DCNRRD, /*! Unexpected DCN after RR/RNR sequence */ 275 T30_ERR_RX_DCNNORTN, /*! Unexpected DCN after requested retransmission */ 276 277 /* TIFF file problems */ 278 T30_ERR_FILEERROR, /*! TIFF/F file cannot be opened */ 279 T30_ERR_NOPAGE, /*! TIFF/F page not found */ 280 T30_ERR_BADTIFF, /*! TIFF/F format is not compatible */ 281 T30_ERR_BADPAGE, /*! TIFF/F page number tag missing */ 282 T30_ERR_BADTAG, /*! Incorrect values for TIFF/F tags */ 283 T30_ERR_BADTIFFHDR, /*! Bad TIFF/F header - incorrect values in fields */ 284 T30_ERR_NOMEM, /*! Cannot allocate memory for more pages */ 285 286 /* General problems */ 287 T30_ERR_RETRYDCN, /*! Disconnected after permitted retries */ 288 T30_ERR_CALLDROPPED, /*! The call dropped prematurely */ 289 290 /* Feature negotiation issues */ 291 T30_ERR_NOPOLL, /*! Poll not accepted */ 292 T30_ERR_IDENT_UNACCEPTABLE, /*! Far end's ident is not acceptable */ 293 T30_ERR_SUB_UNACCEPTABLE, /*! Far end's sub-address is not acceptable */ 294 T30_ERR_SEP_UNACCEPTABLE, /*! Far end's selective polling address is not acceptable */ 295 T30_ERR_PSA_UNACCEPTABLE, /*! Far end's polled sub-address is not acceptable */ 296 T30_ERR_SID_UNACCEPTABLE, /*! Far end's sender identification is not acceptable */ 297 T30_ERR_PWD_UNACCEPTABLE, /*! Far end's password is not acceptable */ 298 T30_ERR_TSA_UNACCEPTABLE, /*! Far end's transmitting subscriber internet address is not acceptable */ 299 T30_ERR_IRA_UNACCEPTABLE, /*! Far end's internet routing address is not acceptable */ 300 T30_ERR_CIA_UNACCEPTABLE, /*! Far end's calling subscriber internet address is not acceptable */ 301 T30_ERR_ISP_UNACCEPTABLE, /*! Far end's internet selective polling address is not acceptable */ 302 T30_ERR_CSA_UNACCEPTABLE /*! Far end's called subscriber internet address is not acceptable */ 303 }; 304 305 /*! 306 I/O modes for the T.30 protocol. 307 */ 308 enum 309 { 310 T30_MODEM_NONE = 0, 311 T30_MODEM_PAUSE, 312 T30_MODEM_CED, 313 T30_MODEM_CNG, 314 T30_MODEM_V21, 315 T30_MODEM_V27TER_2400, 316 T30_MODEM_V27TER_4800, 317 T30_MODEM_V29_7200, 318 T30_MODEM_V29_9600, 319 T30_MODEM_V17_7200, 320 T30_MODEM_V17_9600, 321 T30_MODEM_V17_12000, 322 T30_MODEM_V17_14400, 323 T30_MODEM_DONE 324 }; 325 326 enum 327 { 328 T30_FRONT_END_SEND_STEP_COMPLETE = 0, 329 /*! The current receive has completed. This is only needed to report an 330 unexpected end of the receive operation, as might happen with T.38 331 dying. */ 332 T30_FRONT_END_RECEIVE_COMPLETE, 333 T30_FRONT_END_SIGNAL_PRESENT, 334 T30_FRONT_END_SIGNAL_ABSENT 335 }; 336 337 enum 338 { 339 T30_SUPPORT_V27TER = 0x01, 340 T30_SUPPORT_V29 = 0x02, 341 T30_SUPPORT_V17 = 0x04, 342 T30_SUPPORT_V34 = 0x08, 343 T30_SUPPORT_IAF = 0x10, 344 }; 345 346 enum 347 { 348 T30_SUPPORT_NO_COMPRESSION = 0x01, 349 T30_SUPPORT_T4_1D_COMPRESSION = 0x02, 350 T30_SUPPORT_T4_2D_COMPRESSION = 0x04, 351 T30_SUPPORT_T6_COMPRESSION = 0x08, 352 T30_SUPPORT_T85_COMPRESSION = 0x10, /* Monochrome JBIG */ 353 T30_SUPPORT_T43_COMPRESSION = 0x20, /* Colour JBIG */ 354 T30_SUPPORT_T45_COMPRESSION = 0x40 /* Run length colour compression */ 355 }; 356 357 enum 358 { 359 T30_SUPPORT_STANDARD_RESOLUTION = 0x01, 360 T30_SUPPORT_FINE_RESOLUTION = 0x02, 361 T30_SUPPORT_SUPERFINE_RESOLUTION = 0x04, 362 363 T30_SUPPORT_R4_RESOLUTION = 0x10000, 364 T30_SUPPORT_R8_RESOLUTION = 0x20000, 365 T30_SUPPORT_R16_RESOLUTION = 0x40000, 366 367 T30_SUPPORT_300_300_RESOLUTION = 0x100000, 368 T30_SUPPORT_400_400_RESOLUTION = 0x200000, 369 T30_SUPPORT_600_600_RESOLUTION = 0x400000, 370 T30_SUPPORT_1200_1200_RESOLUTION = 0x800000, 371 T30_SUPPORT_300_600_RESOLUTION = 0x1000000, 372 T30_SUPPORT_400_800_RESOLUTION = 0x2000000, 373 T30_SUPPORT_600_1200_RESOLUTION = 0x4000000 374 }; 375 376 enum 377 { 378 T30_SUPPORT_215MM_WIDTH = 0x01, 379 T30_SUPPORT_255MM_WIDTH = 0x02, 380 T30_SUPPORT_303MM_WIDTH = 0x04, 381 382 T30_SUPPORT_UNLIMITED_LENGTH = 0x10000, 383 T30_SUPPORT_A4_LENGTH = 0x20000, 384 T30_SUPPORT_B4_LENGTH = 0x40000, 385 T30_SUPPORT_US_LETTER_LENGTH = 0x80000, 386 T30_SUPPORT_US_LEGAL_LENGTH = 0x100000 387 }; 388 389 enum 390 { 391 /*! Enable support of identification, through the SID and/or PWD frames */ 392 T30_SUPPORT_IDENTIFICATION = 0x01, 393 /*! Enable support of selective polling, through the SEP frame */ 394 T30_SUPPORT_SELECTIVE_POLLING = 0x02, 395 /*! Enable support of polling sub-addressing, through the PSA frame */ 396 T30_SUPPORT_POLLED_SUB_ADDRESSING = 0x04, 397 /*! Enable support of multiple selective polling, through repeated used of the SEP and PSA frames */ 398 T30_SUPPORT_MULTIPLE_SELECTIVE_POLLING = 0x08, 399 /*! Enable support of sub-addressing, through the SUB frame */ 400 T30_SUPPORT_SUB_ADDRESSING = 0x10, 401 /*! Enable support of transmitting subscriber internet address, through the TSA frame */ 402 T30_SUPPORT_TRANSMITTING_SUBSCRIBER_INTERNET_ADDRESS = 0x20, 403 /*! Enable support of internet routing address, through the IRA frame */ 404 T30_SUPPORT_INTERNET_ROUTING_ADDRESS = 0x40, 405 /*! Enable support of calling subscriber internet address, through the CIA frame */ 406 T30_SUPPORT_CALLING_SUBSCRIBER_INTERNET_ADDRESS = 0x80, 407 /*! Enable support of internet selective polling address, through the ISP frame */ 408 T30_SUPPORT_INTERNET_SELECTIVE_POLLING_ADDRESS = 0x100, 409 /*! Enable support of called subscriber internet address, through the CSA frame */ 410 T30_SUPPORT_CALLED_SUBSCRIBER_INTERNET_ADDRESS = 0x200, 411 /*! Enable support of the field not valid (FNV) frame */ 412 T30_SUPPORT_FIELD_NOT_VALID = 0x400, 413 /*! Enable support of the command repeat (CRP) frame */ 414 T30_SUPPORT_COMMAND_REPEAT = 0x800 415 }; 416 417 enum 418 { 419 T30_IAF_MODE_T37 = 0x01, 420 T30_IAF_MODE_T38 = 0x02, 421 T30_IAF_MODE_FLOW_CONTROL = 0x04, 422 /*! Continuous flow mode means data is sent as fast as possible, usually across 423 the Internet, where speed is not constrained by a PSTN modem. */ 424 T30_IAF_MODE_CONTINUOUS_FLOW = 0x08, 425 /*! No TCF means TCF is not exchanged. The end points must sort out usable speed 426 issues locally. */ 427 T30_IAF_MODE_NO_TCF = 0x10, 428 /*! No fill bits means do not insert fill bits, even if the T.30 messages request 429 them. */ 430 T30_IAF_MODE_NO_FILL_BITS = 0x20, 431 /*! No indicators means do not send indicator messages when using T.38. */ 432 T30_IAF_MODE_NO_INDICATORS = 0x40 433 }; 434 435 typedef struct 436 { 437 /*! \brief The identifier string (CSI, TSI, CIG). */ 438 char ident[T30_MAX_IDENT_LEN + 1]; 439 /*! \brief The sub-address string (SUB). */ 440 char sub_address[T30_MAX_IDENT_LEN + 1]; 441 /*! \brief The selective polling sub-address (SEP). */ 442 char selective_polling_address[T30_MAX_IDENT_LEN + 1]; 443 /*! \brief The polled sub-address (PSA). */ 444 char polled_sub_address[T30_MAX_IDENT_LEN + 1]; 445 /*! \brief The sender identification (SID). */ 446 char sender_ident[T30_MAX_IDENT_LEN + 1]; 447 /*! \brief The password (PWD). */ 448 char password[T30_MAX_IDENT_LEN + 1]; 449 /*! \brief Non-standard facilities (NSF). */ 450 uint8_t *nsf; 451 size_t nsf_len; 452 /*! \brief Non-standard facilities command (NSC). */ 453 uint8_t *nsc; 454 size_t nsc_len; 455 /*! \brief Non-standard facilities set-up (NSS). */ 456 uint8_t *nss; 457 size_t nss_len; 458 /*! \brief Transmitting subscriber internet address (TSA). */ 459 int tsa_type; 460 char *tsa; 461 size_t tsa_len; 462 /*! \brief Internet routing address (IRA). */ 463 int ira_type; 464 char *ira; 465 size_t ira_len; 466 /*! \brief Calling subscriber internet address (CIA). */ 467 int cia_type; 468 char *cia; 469 size_t cia_len; 470 /*! \brief Internet selective polling address (ISP). */ 471 int isp_type; 472 char *isp; 473 size_t isp_len; 474 /*! \brief Called subscriber internet address (CSA). */ 475 int csa_type; 476 char *csa; 477 size_t csa_len; 478 } t30_exchanged_info_t; 479 480 /*! 481 T.30 FAX channel descriptor. This defines the state of a single working 482 instance of a T.30 FAX channel. 483 */ 484 struct t30_state_s 485 { 486 /* This must be kept the first thing in the structure, so it can be pointed 487 to reliably as the structures change over time. */ 488 /*! \brief T.4 context for reading or writing image data. */ 489 t4_state_t t4; 490 491 int operation_in_progress; 492 493 /*! \brief TRUE if behaving as the calling party */ 494 int calling_party; 495 496 /*! \brief The received DCS, formatted as an ASCII string, for inclusion 497 in the TIFF file. */ 498 char rx_dcs_string[T30_MAX_DIS_DTC_DCS_LEN*3 + 1]; 499 /*! \brief The text which will be used in FAX page header. No text results 500 in no header line. */ 501 char header_info[T30_MAX_PAGE_HEADER_INFO + 1]; 502 /*! \brief The information fields received. */ 503 t30_exchanged_info_t rx_info; 504 /*! \brief The information fields to be transmitted. */ 505 t30_exchanged_info_t tx_info; 506 /*! \brief The country of origin of the remote machine, if known, else NULL. */ 507 const char *country; 508 /*! \brief The vendor of the remote machine, if known, else NULL. */ 509 const char *vendor; 510 /*! \brief The model of the remote machine, if known, else NULL. */ 511 const char *model; 512 513 /*! \brief A pointer to a callback routine to be called when phase B events 514 occur. */ 515 t30_phase_b_handler_t *phase_b_handler; 516 /*! \brief An opaque pointer supplied in event B callbacks. */ 517 void *phase_b_user_data; 518 /*! \brief A pointer to a callback routine to be called when phase D events 519 occur. */ 520 t30_phase_d_handler_t *phase_d_handler; 521 /*! \brief An opaque pointer supplied in event D callbacks. */ 522 void *phase_d_user_data; 523 /*! \brief A pointer to a callback routine to be called when phase E events 524 occur. */ 525 t30_phase_e_handler_t *phase_e_handler; 526 /*! \brief An opaque pointer supplied in event E callbacks. */ 527 void *phase_e_user_data; 528 /*! \brief A pointer to a callback routine to be called when frames are 529 exchanged. */ 530 t30_real_time_frame_handler_t *real_time_frame_handler; 531 /*! \brief An opaque pointer supplied in real time frame callbacks. */ 532 void *real_time_frame_user_data; 533 534 /*! \brief A pointer to a callback routine to be called when document events 535 (e.g. end of transmitted document) occur. */ 536 t30_document_handler_t *document_handler; 537 /*! \brief An opaque pointer supplied in document callbacks. */ 538 void *document_user_data; 539 540 /*! \brief The handler for changes to the receive mode */ 541 t30_set_handler_t *set_rx_type_handler; 542 /*! \brief An opaque pointer passed to the handler for changes to the receive mode */ 543 void *set_rx_type_user_data; 544 /*! \brief The handler for changes to the transmit mode */ 545 t30_set_handler_t *set_tx_type_handler; 546 /*! \brief An opaque pointer passed to the handler for changes to the transmit mode */ 547 void *set_tx_type_user_data; 548 549 /*! \brief The transmitted HDLC frame handler. */ 550 t30_send_hdlc_handler_t *send_hdlc_handler; 551 /*! \brief An opaque pointer passed to the transmitted HDLC frame handler. */ 552 void *send_hdlc_user_data; 553 554 /*! \brief The DIS code for the minimum scan row time we require. This is usually 0ms, 555 but if we are trying to simulate another type of FAX machine, we may need a non-zero 556 value here. */ 557 uint8_t local_min_scan_time_code; 558 559 /*! \brief The current T.30 phase. */ 560 int phase; 561 /*! \brief The T.30 phase to change to when the current phase ends. */ 562 int next_phase; 563 /*! \brief The current state of the T.30 state machine. */ 564 int state; 565 /*! \brief The step in sending a sequence of HDLC frames. */ 566 int step; 567 568 /*! \brief The preparation buffer for the DCS message to be transmitted. */ 569 uint8_t dcs_frame[T30_MAX_DIS_DTC_DCS_LEN]; 570 /*! \brief The length of the DCS message to be transmitted. */ 571 int dcs_len; 572 /*! \brief The preparation buffer for DIS or DTC message to be transmitted. */ 573 uint8_t local_dis_dtc_frame[T30_MAX_DIS_DTC_DCS_LEN]; 574 /*! \brief The length of the DIS or DTC message to be transmitted. */ 575 int local_dis_dtc_len; 576 /*! \brief The last DIS or DTC message received form the far end. */ 577 uint8_t far_dis_dtc_frame[T30_MAX_DIS_DTC_DCS_LEN]; 578 /*! \brief The length of the last DIS or DTC message received form the far end. */ 579 int far_dis_dtc_len; 580 /*! \brief TRUE if a valid DIS has been received from the far end. */ 581 int dis_received; 582 583 /*! \brief A flag to indicate a message is in progress. */ 584 int in_message; 585 586 /*! \brief TRUE if the short training sequence should be used. */ 587 int short_train; 588 589 /*! \brief A count of the number of bits in the trainability test. */ 590 int training_test_bits; 591 /*! \brief The current count of consecutive zero bits, during the trainability test. */ 592 int training_current_zeros; 593 /*! \brief The maximum consecutive zero bits seen to date, during the trainability test. */ 594 int training_most_zeros; 595 596 /*! \brief The current fallback step for the fast message transfer modem. */ 597 int current_fallback; 598 /*! \brief The subset of supported modems allowed at the current time, allowing for negotiation. */ 599 int current_permitted_modems; 600 /*! \brief TRUE if a carrier is present. Otherwise FALSE. */ 601 int rx_signal_present; 602 /*! \brief TRUE if a modem has trained correctly. */ 603 int rx_trained; 604 int current_rx_type; 605 int current_tx_type; 606 607 /*! \brief T0 is the answer timeout when calling another FAX machine. 608 Placing calls is handled outside the FAX processing, but this timeout keeps 609 running until V.21 modulation is sent or received. 610 T1 is the remote terminal identification timeout (in audio samples). */ 611 int timer_t0_t1; 612 /*! \brief T2 is the HDLC command timeout. 613 T4 is the HDLC response timeout (in audio samples). */ 614 int timer_t2_t4; 615 /*! \brief TRUE if the T2/T4 timer is actually timing T4 */ 616 int timer_is_t4; 617 /*! \brief Procedural interrupt timeout (in audio samples). */ 618 int timer_t3; 619 /*! \brief This is only used in error correcting mode. */ 620 int timer_t5; 621 /*! \brief This is only used in full duplex (e.g. ISDN) modes. */ 622 int timer_t6; 623 /*! \brief This is only used in full duplex (e.g. ISDN) modes. */ 624 int timer_t7; 625 /*! \brief This is only used in full duplex (e.g. ISDN) modes. */ 626 int timer_t8; 627 628 /*! \brief TRUE once the far end FAX entity has been detected. */ 629 int far_end_detected; 630 631 /*! \brief TRUE if a local T.30 interrupt is pending. */ 632 int local_interrupt_pending; 633 /*! \brief The image coding being used on the line. */ 634 int line_encoding; 635 /*! \brief The image coding being used for output files. */ 636 int output_encoding; 637 /*! \brief The current DCS message minimum scan time code. */ 638 uint8_t min_scan_time_code; 639 /*! \brief The X direction resolution of the current image, in pixels per metre. */ 640 int x_resolution; 641 /*! \brief The Y direction resolution of the current image, in pixels per metre. */ 642 int y_resolution; 643 /*! \brief The width of the current image, in pixels. */ 644 t4_image_width_t image_width; 645 /*! \brief Current number of retries of the action in progress. */ 646 int retries; 647 /*! \brief TRUE if error correcting mode is used. */ 648 int error_correcting_mode; 649 /*! \brief The current count of consecutive T30_PPR messages. */ 650 int ppr_count; 651 /*! \brief The current count of consecutive T30_RNR messages. */ 652 int receiver_not_ready_count; 653 /*! \brief The number of octets to be used per ECM frame. */ 654 int octets_per_ecm_frame; 655 /*! \brief The ECM partial page buffer. */ 656 uint8_t ecm_data[256][260]; 657 /*! \brief The lengths of the frames in the ECM partial page buffer. */ 658 int16_t ecm_len[256]; 659 /*! \brief A bit map of the OK ECM frames, constructed as a PPR frame. */ 660 uint8_t ecm_frame_map[3 + 32]; 661 662 /*! \brief The current page number, in ECM mode */ 663 int ecm_page; 664 /*! \brief The current block number, in ECM mode */ 665 int ecm_block; 666 /*! \brief The number of frames in the current block number, in ECM mode */ 667 int ecm_frames; 668 /*! \brief The number of frames sent in the current burst of image transmission, in ECM mode */ 669 int ecm_frames_this_tx_burst; 670 /*! \brief The current ECM frame, during ECM transmission. */ 671 int ecm_current_tx_frame; 672 /*! \brief TRUE if we are at the end of an ECM page to se sent - i.e. there are no more 673 partial pages still to come. */ 674 int ecm_at_page_end; 675 int next_tx_step; 676 int next_rx_step; 677 /*! \brief Image file name for image reception. */ 678 char rx_file[256]; 679 /*! \brief The last page we are prepared accept for a received image file. -1 means no restriction. */ 680 int rx_stop_page; 681 /*! \brief Image file name to be sent. */ 682 char tx_file[256]; 683 /*! \brief The first page to be sent from the image file. -1 means no restriction. */ 684 int tx_start_page; 685 /*! \brief The last page to be sent from the image file. -1 means no restriction. */ 686 int tx_stop_page; 687 int current_status; 688 /*! \brief Internet Aware FAX mode bit mask. */ 689 int iaf; 690 /*! \brief A bit mask of the currently supported modem types. */ 691 int supported_modems; 692 /*! \brief A bit mask of the currently supported image compression modes. */ 693 int supported_compressions; 694 /*! \brief A bit mask of the currently supported image resolutions. */ 695 int supported_resolutions; 696 /*! \brief A bit mask of the currently supported image sizes. */ 697 int supported_image_sizes; 698 /*! \brief A bit mask of the currently supported T.30 special features. */ 699 int supported_t30_features; 700 /*! \brief TRUE is ECM mode handling is enabled. */ 701 int ecm_allowed; 702 703 /*! \brief the FCF2 field of the last PPS message we received. */ 704 int last_pps_fcf2; 705 /*! \brief The number of the first ECM frame which we do not currently received correctly. For 706 a partial page received correctly, this will be one greater than the number of frames it 707 contains. */ 708 int ecm_first_bad_frame; 709 /*! \brief A count of successfully received ECM frames, to assess progress as a basis for 710 deciding whether to continue error correction when PPRs keep repeating. */ 711 int ecm_progress; 712 713 /*! \brief Error and flow logging control */ 714 logging_state_t logging; 715 }; 716 717 typedef struct 718 { 719 /*! \brief The current bit rate for image transfer. */ 720 int bit_rate; 721 /*! \brief TRUE if error correcting mode is used. */ 722 int error_correcting_mode; 723 /*! \brief The number of pages transferred so far. */ 724 int pages_transferred; 725 /*! \brief The number of pages in the file (<0 if not known). */ 726 int pages_in_file; 727 /*! \brief The number of horizontal pixels in the most recent page. */ 728 int width; 729 /*! \brief The number of vertical pixels in the most recent page. */ 730 int length; 731 /*! \brief The number of bad pixel rows in the most recent page. */ 732 int bad_rows; 733 /*! \brief The largest number of bad pixel rows in a block in the most recent page. */ 734 int longest_bad_row_run; 735 /*! \brief The horizontal column-to-column resolution of the page in pixels per metre */ 736 int x_resolution; 737 /*! \brief The vertical row-to-row resolution of the page in pixels per metre */ 738 int y_resolution; 739 /*! \brief The type of compression used between the FAX machines */ 740 int encoding; 741 /*! \brief The size of the image, in bytes */ 742 int image_size; 743 /*! \brief Current status */ 744 int current_status; 745 } t30_stats_t; 746 747 #if defined(__cplusplus) 748 extern "C" 749 { 750 #endif 751 752 /*! Initialise a T.30 context. 753 \brief Initialise a T.30 context. 754 \param s The T.30 context. 755 \param calling_party TRUE if the context is for a calling party. FALSE if the 756 context is for an answering party. 757 \param set_rx_type_handler 758 \param set_rx_type_user_data 759 \param set_tx_type_handler 760 \param set_tx_type_user_data 761 \param send_hdlc_handler 762 \param send_hdlc_user_data 763 \return A pointer to the context, or NULL if there was a problem. */ 764 t30_state_t *t30_init(t30_state_t *s, 765 int calling_party, 766 t30_set_handler_t *set_rx_type_handler, 767 void *set_rx_type_user_data, 768 t30_set_handler_t *set_tx_type_handler, 769 void *set_tx_type_user_data, 770 t30_send_hdlc_handler_t *send_hdlc_handler, 771 void *send_hdlc_user_data); 772 773 /*! Release a T.30 context. 774 \brief Release a T.30 context. 775 \param s The T.30 context. 776 \return 0 for OK, else -1. */ 777 int t30_release(t30_state_t *s); 778 779 /*! Free a T.30 context. 780 \brief Free a T.30 context. 781 \param s The T.30 context. 782 \return 0 for OK, else -1. */ 783 int t30_free(t30_state_t *s); 784 785 /*! Restart a T.30 context. 786 \brief Restart a T.30 context. 787 \param s The T.30 context. 788 \return 0 for OK, else -1. */ 789 int t30_restart(t30_state_t *s); 790 791 /*! Cleanup a T.30 context if the call terminates. 792 \brief Cleanup a T.30 context if the call terminates. 793 \param s The T.30 context. */ 794 void t30_terminate(t30_state_t *s); 795 796 /*! Inform the T.30 engine of a status change in the front end (end of tx, rx signal change, etc.). 797 \brief Inform the T.30 engine of a status change in the front end (end of tx, rx signal change, etc.). 798 \param user_data The T.30 context. 799 \param status The type of status change which occured. */ 800 void t30_front_end_status(void *user_data, int status); 801 802 /*! Get a bit of received non-ECM image data. 803 \brief Get a bit of received non-ECM image data. 804 \param user_data An opaque pointer, which must point to the T.30 context. 805 \return The next bit to transmit. */ 806 int t30_non_ecm_get_bit(void *user_data); 807 808 /*! Get a byte of received non-ECM image data. 809 \brief Get a byte of received non-ECM image data. 810 \param user_data An opaque pointer, which must point to the T.30 context. 811 \return The next byte to transmit. */ 812 int t30_non_ecm_get_byte(void *user_data); 813 814 /*! Get a chunk of received non-ECM image data. 815 \brief Get a bit of received non-ECM image data. 816 \param user_data An opaque pointer, which must point to the T.30 context. 817 \param buf The buffer to contain the data. 818 \param max_len The maximum length of the chunk. 819 \return The actual length of the chunk. */ 820 int t30_non_ecm_get_chunk(void *user_data, uint8_t buf[], int max_len); 821 822 /*! Process a bit of received non-ECM image data. 823 \brief Process a bit of received non-ECM image data 824 \param user_data An opaque pointer, which must point to the T.30 context. 825 \param bit The received bit. */ 826 void t30_non_ecm_put_bit(void *user_data, int bit); 827 828 /*! Process a byte of received non-ECM image data. 829 \brief Process a byte of received non-ECM image data 830 \param user_data An opaque pointer, which must point to the T.30 context. 831 \param byte The received byte. */ 832 void t30_non_ecm_put_byte(void *user_data, int byte); 833 834 /*! Process a chunk of received non-ECM image data. 835 \brief Process a chunk of received non-ECM image data 836 \param user_data An opaque pointer, which must point to the T.30 context. 837 \param buf The buffer containing the received data. 838 \param len The length of the data in buf. */ 839 void t30_non_ecm_put_chunk(void *user_data, const uint8_t buf[], int len); 840 841 /*! Process a received HDLC frame. 842 \brief Process a received HDLC frame. 843 \param user_data The T.30 context. 844 \param msg The HDLC message. 845 \param len The length of the message, in octets. 846 \param ok TRUE if the frame was received without error. */ 847 void t30_hdlc_accept(void *user_data, const uint8_t *msg, int len, int ok); 848 849 /*! Report the passage of time to the T.30 engine. 850 \brief Report the passage of time to the T.30 engine. 851 \param s The T.30 context. 852 \param samples The time change in 1/8000th second steps. */ 853 void t30_timer_update(t30_state_t *s, int samples); 854 855 /*! Get the current transfer statistics for the file being sent or received. 856 \brief Get the current transfer statistics. 857 \param s The T.30 context. 858 \param t A pointer to a buffer for the statistics. */ 859 void t30_get_transfer_statistics(t30_state_t *s, t30_stats_t *t); 860 861 /*! Request a local interrupt of FAX exchange. 862 \brief Request a local interrupt of FAX exchange. 863 \param s The T.30 context. 864 \param state TRUE to enable interrupt request, else FALSE. */ 865 void t30_local_interrupt_request(t30_state_t *s, int state); 866 867 #if defined(__cplusplus) 868 } 869 #endif 870 871 #endif 872 /*- End of file ------------------------------------------------------------*/ 873