spandsp  0.0.6
private/t30.h
Go to the documentation of this file.
1 /*
2  * SpanDSP - a series of DSP components for telephony
3  *
4  * private/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 
26 /*! \file */
27 
28 #if !defined(_SPANDSP_PRIVATE_T30_H_)
29 #define _SPANDSP_PRIVATE_T30_H_
30 
31 /*!
32  T.30 FAX channel descriptor. This defines the state of a single working
33  instance of a T.30 FAX channel.
34 */
36 {
37  /*! \brief T.4 context for reading or writing image data. */
38  union
39  {
40  t4_rx_state_t rx;
41  t4_tx_state_t tx;
42  } t4;
43  /*! \brief The type of FAX operation currently in progress */
45 
46  /*! \brief True if behaving as the calling party */
48 
49  /*! \brief Internet aware FAX mode bit mask. */
50  int iaf;
51  /*! \brief A bit mask of the currently supported modem types. */
53  /*! \brief A bit mask of the currently supported image compression modes. */
55  /*! \brief A bit mask of the currently supported image resolutions. */
57  /*! \brief A bit mask of the currently supported image sizes. */
59  /*! \brief A bit mask of the currently supported T.30 special features. */
61  /*! \brief True is ECM mode handling is enabled. */
63  /*! \brief True if we are capable of retransmitting pages */
65 
66  /*! \brief The received DCS, formatted as an ASCII string, for inclusion
67  in the TIFF file. */
69  /*! \brief The text which will be used in FAX page header. No text results
70  in no header line. */
72  /*! \brief True for FAX page headers to overlay (i.e. replace) the beginning of the
73  page image. False for FAX page headers to add to the overall length of
74  the page. */
76  /*! \brief Use private timezone if true */
78  /*! \brief Optional per instance time zone for the FAX page header timestamp. */
80 
81  /*! \brief True if remote T.30 procedural interrupts are allowed. */
83 
84  /*! \brief The information fields received. */
86  /*! \brief The information fields to be transmitted. */
88  /*! \brief The country of origin of the remote machine, if known, else NULL. */
89  const char *country;
90  /*! \brief The vendor of the remote machine, if known, else NULL. */
91  const char *vendor;
92  /*! \brief The model of the remote machine, if known, else NULL. */
93  const char *model;
94 
95  /*! \brief A pointer to a callback routine to be called when phase B events
96  occur. */
98  /*! \brief An opaque pointer supplied in event B callbacks. */
100  /*! \brief A pointer to a callback routine to be called when phase D events
101  occur. */
103  /*! \brief An opaque pointer supplied in event D callbacks. */
105  /*! \brief A pointer to a callback routine to be called when phase E events
106  occur. */
108  /*! \brief An opaque pointer supplied in event E callbacks. */
110  /*! \brief A pointer to a callback routine to be called when frames are
111  exchanged. */
113  /*! \brief An opaque pointer supplied in real time frame callbacks. */
115 
116  /*! \brief A pointer to a callback routine to be called when document events
117  (e.g. end of transmitted document) occur. */
119  /*! \brief An opaque pointer supplied in document callbacks. */
121 
122  /*! \brief The handler for changes to the receive mode */
124  /*! \brief An opaque pointer passed to the handler for changes to the receive mode */
126  /*! \brief The handler for changes to the transmit mode */
128  /*! \brief An opaque pointer passed to the handler for changes to the transmit mode */
130 
131  /*! \brief The transmitted HDLC frame handler. */
133  /*! \brief An opaque pointer passed to the transmitted HDLC frame handler. */
135 
136 #if 0
137  /*! \brief The document send handler. */
138  t30_document_get_handler_t *document_get_handler;
139  /*! \brief An opaque pointer passed to the document send handler. */
140  void *document_get_user_data;
141  /*! \brief The document delivery handler. */
142  t30_document_put_handler_t *document_put_handler;
143  /*! \brief An opaque pointer passed to the document delivery handler. */
144  void *document_put_user_data;
145 #endif
146 
147  /*! \brief The DIS code for the minimum scan row time we require. This is usually 0ms,
148  but if we are trying to simulate another type of FAX machine, we may need a non-zero
149  value here. */
151 
152  /*! \brief The current T.30 phase. */
153  int phase;
154  /*! \brief The T.30 phase to change to when the current phase ends. */
156  /*! \brief The current state of the T.30 state machine. */
157  int state;
158  /*! \brief The step in sending a sequence of HDLC frames. */
159  int step;
160 
161  /*! \brief The preparation buffer for the DCS message to be transmitted. */
163  /*! \brief The length of the DCS message to be transmitted. */
164  int dcs_len;
165  /*! \brief The preparation buffer for DIS or DTC message to be transmitted. */
167  /*! \brief The length of the DIS or DTC message to be transmitted. */
169  /*! \brief The last DIS or DTC message received form the far end. */
171  /*! \brief The length of the last DIS or DTC message received form the far end. */
173  /*! \brief True if a valid DIS has been received from the far end. */
175 
176  /*! \brief True if the short training sequence should be used. */
178 
179  /*! \brief True if an image carrier appears to have been received, even if it did not successfully
180  train. */
182 
183  /*! \brief A count of the number of bits in the trainability test. This counts down to zero when
184  sending TCF, and counts up when receiving it. */
186  /*! \brief The current count of consecutive received zero bits, during the trainability test. */
188  /*! \brief The maximum consecutive received zero bits seen to date, during the trainability test. */
190 
191  /*! \brief The current fallback step for the fast message transfer modem. */
193  /*! \brief The subset of supported modems allowed at the current time, allowing for negotiation. */
195  /*! \brief True if a carrier is present. Otherwise false. */
197  /*! \brief True if a modem has trained correctly. */
199  /*! \brief True if a valid HDLC frame has been received in the current reception period. */
201 
202  /*! \brief Current reception mode. */
204  /*! \brief Current transmission mode. */
206 
207  /*! \brief T0 is the answer timeout when calling another FAX machine.
208  Placing calls is handled outside the FAX processing, but this timeout keeps
209  running until V.21 modulation is sent or received.
210  T1 is the remote terminal identification timeout (in audio samples). */
212  /*! \brief T2, T2A and T2B are the HDLC command timeouts.
213  T4, T4A and T4B are the HDLC response timeouts (in audio samples). */
215  /*! \brief A value specifying which of the possible timers is currently running in timer_t2_t4 */
217  /*! \brief Procedural interrupt timeout (in audio samples). */
218  int timer_t3;
219  /*! \brief This is only used in error correcting mode. */
220  int timer_t5;
221  /*! \brief This is only used in full duplex (e.g. ISDN) modes. */
222  int timer_t6;
223  /*! \brief This is only used in full duplex (e.g. ISDN) modes. */
224  int timer_t7;
225  /*! \brief This is only used in full duplex (e.g. ISDN) modes. */
226  int timer_t8;
227 
228  /*! \brief True once the far end FAX entity has been detected. */
230 
231  /*! \brief True once the end of procedure condition has been detected. */
233 
234  /*! \brief True if a local T.30 interrupt is pending. */
236  /*! \brief The image coding being used on the line. */
238  /*! \brief The image coding being used for output files. */
240  /*! \brief The current DCS message minimum scan time code. */
242  /*! \brief The X direction resolution of the current image, in pixels per metre. */
244  /*! \brief The Y direction resolution of the current image, in pixels per metre. */
246  /*! \brief The width of the current image, in pixels. */
248  /*! \brief Current number of retries of the action in progress. */
249  int retries;
250  /*! \brief True if error correcting mode is used. */
252  /*! \brief The number of HDLC frame retries, if error correcting mode is used. */
254  /*! \brief The current count of consecutive T30_PPR messages. */
256  /*! \brief The current count of consecutive T30_RNR messages. */
258  /*! \brief The number of octets to be used per ECM frame. */
260  /*! \brief The ECM partial page buffer. */
261  uint8_t ecm_data[256][260];
262  /*! \brief The lengths of the frames in the ECM partial page buffer. */
263  int16_t ecm_len[256];
264  /*! \brief A bit map of the OK ECM frames, constructed as a PPR frame. */
265  uint8_t ecm_frame_map[3 + 32];
266 
267  /*! \brief The current page number for receiving, in ECM or non-ECM mode. This is reset at the start of a call. */
269  /*! \brief The current page number for sending, in ECM or non-ECM mode. This is reset at the start of a call. */
271  /*! \brief The current block number, in ECM mode */
273  /*! \brief The number of frames in the current block number, in ECM mode */
275  /*! \brief The number of frames sent in the current burst of image transmission, in ECM mode */
277  /*! \brief The current ECM frame, during ECM transmission. */
279  /*! \brief True if we are at the end of an ECM page to se sent - i.e. there are no more
280  partial pages still to come. */
282 
283  /*! \brief The last result for a received non-ECM page - T30_MPS, T30_RTP, or T30_RTN. */
285  /*! \brief The transmission step queued to follow the one in progress. */
287  /*! \brief The FCF for the next receive step. */
288  uint8_t next_rx_step;
289  /*! \brief Image file name for image reception. */
290  char rx_file[256];
291  /*! \brief The last page we are prepared accept for a received image file. -1 means no restriction. */
293  /*! \brief Image file name to be sent. */
294  char tx_file[256];
295  /*! \brief The first page to be sent from the image file. -1 means no restriction. */
297  /*! \brief The last page to be sent from the image file. -1 means no restriction. */
299  /*! \brief The current completion status. */
301 
302  /*! \brief the FCF2 field of the last PPS message we received. */
303  uint8_t last_pps_fcf2;
304  /*! \brief True if all frames of the current received ECM block are now OK */
306  /*! \brief A count of successfully received ECM frames, to assess progress as a basis for
307  deciding whether to continue error correction when PPRs keep repeating. */
309 
310  /*! \brief The number of RTP events */
312  /*! \brief The number of RTN events */
314 
315  /*! \brief Error and flow logging control */
317 };
318 
319 #endif
320 /*- End of file ------------------------------------------------------------*/
int far_dis_dtc_len
The length of the last DIS or DTC message received form the far end.
Definition: private/t30.h:172
int timer_t2_t4
T2, T2A and T2B are the HDLC command timeouts. T4, T4A and T4B are the HDLC response timeouts (in aud...
Definition: private/t30.h:214
uint8_t next_rx_step
The FCF for the next receive step.
Definition: private/t30.h:288
uint8_t dcs_frame[T30_MAX_DIS_DTC_DCS_LEN]
The preparation buffer for the DCS message to be transmitted.
Definition: private/t30.h:162
int remote_interrupts_allowed
True if remote T.30 procedural interrupts are allowed.
Definition: private/t30.h:82
int supported_compressions
A bit mask of the currently supported image compression modes.
Definition: private/t30.h:54
t30_document_handler_t * document_handler
A pointer to a callback routine to be called when document events (e.g. end of transmitted document) ...
Definition: private/t30.h:118
const char * model
The model of the remote machine, if known, else NULL.
Definition: private/t30.h:93
char tx_file[256]
Image file name to be sent.
Definition: private/t30.h:294
int output_encoding
The image coding being used for output files.
Definition: private/t30.h:239
void * send_hdlc_user_data
An opaque pointer passed to the transmitted HDLC frame handler.
Definition: private/t30.h:134
int timer_t0_t1
T0 is the answer timeout when calling another FAX machine. Placing calls is handled outside the FAX p...
Definition: private/t30.h:211
int current_fallback
The current fallback step for the fast message transfer modem.
Definition: private/t30.h:192
char header_info[T30_MAX_PAGE_HEADER_INFO+1]
The text which will be used in FAX page header. No text results in no header line.
Definition: private/t30.h:71
int calling_party
True if behaving as the calling party.
Definition: private/t30.h:47
int rx_stop_page
The last page we are prepared accept for a received image file. -1 means no restriction.
Definition: private/t30.h:292
int tx_page_number
The current page number for sending, in ECM or non-ECM mode. This is reset at the start of a call...
Definition: private/t30.h:270
Definition: private/t30.h:35
uint8_t min_scan_time_code
The current DCS message minimum scan time code.
Definition: private/t30.h:241
uint8_t ecm_data[256][260]
The ECM partial page buffer.
Definition: private/t30.h:261
void * real_time_frame_user_data
An opaque pointer supplied in real time frame callbacks.
Definition: private/t30.h:114
int ecm_frames
The number of frames in the current block number, in ECM mode.
Definition: private/t30.h:274
int next_tx_step
The transmission step queued to follow the one in progress.
Definition: private/t30.h:286
int16_t ecm_len[256]
The lengths of the frames in the ECM partial page buffer.
Definition: private/t30.h:263
t4_image_width_t image_width
The width of the current image, in pixels.
Definition: private/t30.h:247
int tx_stop_page
The last page to be sent from the image file. -1 means no restriction.
Definition: private/t30.h:298
int header_overlays_image
True for FAX page headers to overlay (i.e. replace) the beginning of the page image. False for FAX page headers to add to the overall length of the page.
Definition: private/t30.h:75
int supported_resolutions
A bit mask of the currently supported image resolutions.
Definition: private/t30.h:56
int rtp_events
The number of RTP events.
Definition: private/t30.h:311
uint8_t far_dis_dtc_frame[T30_MAX_DIS_DTC_DCS_LEN]
The last DIS or DTC message received form the far end.
Definition: private/t30.h:170
int timer_t7
This is only used in full duplex (e.g. ISDN) modes.
Definition: private/t30.h:224
t30_phase_e_handler_t * phase_e_handler
A pointer to a callback routine to be called when phase E events occur.
Definition: private/t30.h:107
int tcf_test_bits
A count of the number of bits in the trainability test. This counts down to zero when sending TCF...
Definition: private/t30.h:185
int ecm_block
The current block number, in ECM mode.
Definition: private/t30.h:272
int line_encoding
The image coding being used on the line.
Definition: private/t30.h:237
int short_train
True if the short training sequence should be used.
Definition: private/t30.h:177
int timer_t6
This is only used in full duplex (e.g. ISDN) modes.
Definition: private/t30.h:222
int local_dis_dtc_len
The length of the DIS or DTC message to be transmitted.
Definition: private/t30.h:168
char rx_dcs_string[T30_MAX_DIS_DTC_DCS_LEN *3+1]
The received DCS, formatted as an ASCII string, for inclusion in the TIFF file.
Definition: private/t30.h:68
int rx_ecm_block_ok
True if all frames of the current received ECM block are now OK.
Definition: private/t30.h:305
int local_interrupt_pending
True if a local T.30 interrupt is pending.
Definition: private/t30.h:235
t30_set_handler_t * set_tx_type_handler
The handler for changes to the transmit mode.
Definition: private/t30.h:127
int y_resolution
The Y direction resolution of the current image, in pixels per metre.
Definition: private/t30.h:245
int rx_trained
True if a modem has trained correctly.
Definition: private/t30.h:198
#define T30_MAX_DIS_DTC_DCS_LEN
Definition: t30.h:142
t30_real_time_frame_handler_t * real_time_frame_handler
A pointer to a callback routine to be called when frames are exchanged.
Definition: private/t30.h:112
int last_rx_page_result
The last result for a received non-ECM page - T30_MPS, T30_RTP, or T30_RTN.
Definition: private/t30.h:284
uint8_t local_dis_dtc_frame[T30_MAX_DIS_DTC_DCS_LEN]
The preparation buffer for DIS or DTC message to be transmitted.
Definition: private/t30.h:166
int rtn_events
The number of RTN events.
Definition: private/t30.h:313
t30_exchanged_info_t rx_info
The information fields received.
Definition: private/t30.h:85
union t30_state_s::@57 t4
T.4 context for reading or writing image data.
int current_status
The current completion status.
Definition: private/t30.h:300
logging_state_t logging
Error and flow logging control.
Definition: private/t30.h:316
int current_permitted_modems
The subset of supported modems allowed at the current time, allowing for negotiation.
Definition: private/t30.h:194
void( t30_send_hdlc_handler_t)(void *user_data, const uint8_t msg[], int len)
T.30 send HDLC handler.
Definition: t30.h:224
int current_rx_type
Current reception mode.
Definition: private/t30.h:203
int image_carrier_attempted
True if an image carrier appears to have been received, even if it did not successfully train...
Definition: private/t30.h:181
char rx_file[256]
Image file name for image reception.
Definition: private/t30.h:290
t30_phase_d_handler_t * phase_d_handler
A pointer to a callback routine to be called when phase D events occur.
Definition: private/t30.h:102
int octets_per_ecm_frame
The number of octets to be used per ECM frame.
Definition: private/t30.h:259
void * set_rx_type_user_data
An opaque pointer passed to the handler for changes to the receive mode.
Definition: private/t30.h:125
int error_correcting_mode_retries
The number of HDLC frame retries, if error correcting mode is used.
Definition: private/t30.h:253
int operation_in_progress
The type of FAX operation currently in progress.
Definition: private/t30.h:44
int supported_modems
A bit mask of the currently supported modem types.
Definition: private/t30.h:52
int current_tx_type
Current transmission mode.
Definition: private/t30.h:205
int( t30_phase_b_handler_t)(t30_state_t *s, void *user_data, int result)
T.30 phase B callback handler.
Definition: t30.h:161
int step
The step in sending a sequence of HDLC frames.
Definition: private/t30.h:159
int ppr_count
The current count of consecutive T30_PPR messages.
Definition: private/t30.h:255
int phase
The current T.30 phase.
Definition: private/t30.h:153
Definition: private/timezone.h:81
void( t30_set_handler_t)(void *user_data, int type, int bit_rate, int short_train, int use_hdlc)
T.30 set a receive or transmit type handler.
Definition: t30.h:215
void * phase_e_user_data
An opaque pointer supplied in event E callbacks.
Definition: private/t30.h:109
#define T30_MAX_PAGE_HEADER_INFO
Definition: t30.h:146
int rx_signal_present
True if a carrier is present. Otherwise false.
Definition: private/t30.h:196
void * phase_b_user_data
An opaque pointer supplied in event B callbacks.
Definition: private/t30.h:99
int far_end_detected
True once the far end FAX entity has been detected.
Definition: private/t30.h:229
t4_image_width_t
Definition: t4_rx.h:124
int retries
Current number of retries of the action in progress.
Definition: private/t30.h:249
int ecm_allowed
True is ECM mode handling is enabled.
Definition: private/t30.h:62
void( t30_phase_e_handler_t)(t30_state_t *s, void *user_data, int completion_code)
T.30 phase E callback handler.
Definition: t30.h:180
void * phase_d_user_data
An opaque pointer supplied in event D callbacks.
Definition: private/t30.h:104
int x_resolution
The X direction resolution of the current image, in pixels per metre.
Definition: private/t30.h:243
int next_phase
The T.30 phase to change to when the current phase ends.
Definition: private/t30.h:155
void * set_tx_type_user_data
An opaque pointer passed to the handler for changes to the transmit mode.
Definition: private/t30.h:129
int ecm_at_page_end
True if we are at the end of an ECM page to se sent - i.e. there are no more partial pages still to c...
Definition: private/t30.h:281
int( t30_phase_d_handler_t)(t30_state_t *s, void *user_data, int result)
T.30 phase D callback handler.
Definition: t30.h:171
int( t30_document_handler_t)(t30_state_t *s, void *user_data, int status)
T.30 document handler.
Definition: t30.h:204
Definition: private/logging.h:33
const char * country
The country of origin of the remote machine, if known, else NULL.
Definition: private/t30.h:89
int dcs_len
The length of the DCS message to be transmitted.
Definition: private/t30.h:164
int rx_page_number
The current page number for receiving, in ECM or non-ECM mode. This is reset at the start of a call...
Definition: private/t30.h:268
int timer_t5
This is only used in error correcting mode.
Definition: private/t30.h:220
uint8_t local_min_scan_time_code
The DIS code for the minimum scan row time we require. This is usually 0ms, but if we are trying to s...
Definition: private/t30.h:150
uint8_t ecm_frame_map[3+32]
A bit map of the OK ECM frames, constructed as a PPR frame.
Definition: private/t30.h:265
t30_send_hdlc_handler_t * send_hdlc_handler
The transmitted HDLC frame handler.
Definition: private/t30.h:132
int timer_t3
Procedural interrupt timeout (in audio samples).
Definition: private/t30.h:218
uint8_t last_pps_fcf2
the FCF2 field of the last PPS message we received.
Definition: private/t30.h:303
int timer_t2_t4_is
A value specifying which of the possible timers is currently running in timer_t2_t4.
Definition: private/t30.h:216
t30_phase_b_handler_t * phase_b_handler
A pointer to a callback routine to be called when phase B events occur.
Definition: private/t30.h:97
tz_t tz
Optional per instance time zone for the FAX page header timestamp.
Definition: private/t30.h:79
t30_set_handler_t * set_rx_type_handler
The handler for changes to the receive mode.
Definition: private/t30.h:123
int error_correcting_mode
True if error correcting mode is used.
Definition: private/t30.h:251
int use_own_tz
Use private timezone if true.
Definition: private/t30.h:77
int end_of_procedure_detected
True once the end of procedure condition has been detected.
Definition: private/t30.h:232
int supported_t30_features
A bit mask of the currently supported T.30 special features.
Definition: private/t30.h:60
int ecm_current_tx_frame
The current ECM frame, during ECM transmission.
Definition: private/t30.h:278
int ecm_frames_this_tx_burst
The number of frames sent in the current burst of image transmission, in ECM mode.
Definition: private/t30.h:276
int iaf
Internet aware FAX mode bit mask.
Definition: private/t30.h:50
const char * vendor
The vendor of the remote machine, if known, else NULL.
Definition: private/t30.h:91
int tcf_most_zeros
The maximum consecutive received zero bits seen to date, during the trainability test.
Definition: private/t30.h:189
int ecm_progress
A count of successfully received ECM frames, to assess progress as a basis for deciding whether to co...
Definition: private/t30.h:308
int rx_frame_received
True if a valid HDLC frame has been received in the current reception period.
Definition: private/t30.h:200
int supported_image_sizes
A bit mask of the currently supported image sizes.
Definition: private/t30.h:58
int dis_received
True if a valid DIS has been received from the far end.
Definition: private/t30.h:174
Definition: private/t4_tx.h:35
void * document_user_data
An opaque pointer supplied in document callbacks.
Definition: private/t30.h:120
Definition: t30.h:495
int receiver_not_ready_count
The current count of consecutive T30_RNR messages.
Definition: private/t30.h:257
int retransmit_capable
True if we are capable of retransmitting pages.
Definition: private/t30.h:64
t30_exchanged_info_t tx_info
The information fields to be transmitted.
Definition: private/t30.h:87
void( t30_real_time_frame_handler_t)(t30_state_t *s, void *user_data, int incoming, const uint8_t msg[], int len)
T.30 real time frame handler.
Definition: t30.h:191
int tx_start_page
The first page to be sent from the image file. -1 means no restriction.
Definition: private/t30.h:296
int timer_t8
This is only used in full duplex (e.g. ISDN) modes.
Definition: private/t30.h:226
int state
The current state of the T.30 state machine.
Definition: private/t30.h:157
int tcf_current_zeros
The current count of consecutive received zero bits, during the trainability test.
Definition: private/t30.h:187