private/t30.h

Go to the documentation of this file.
00001 /*
00002  * SpanDSP - a series of DSP components for telephony
00003  *
00004  * private/t30.h - definitions for T.30 fax processing
00005  *
00006  * Written by Steve Underwood <steveu@coppice.org>
00007  *
00008  * Copyright (C) 2003 Steve Underwood
00009  *
00010  * All rights reserved.
00011  *
00012  * This program is free software; you can redistribute it and/or modify
00013  * it under the terms of the GNU Lesser General Public License version 2.1,
00014  * as published by the Free Software Foundation.
00015  *
00016  * This program is distributed in the hope that it will be useful,
00017  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00018  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00019  * GNU Lesser General Public License for more details.
00020  *
00021  * You should have received a copy of the GNU Lesser General Public
00022  * License along with this program; if not, write to the Free Software
00023  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
00024  */
00025 
00026 /*! \file */
00027 
00028 #if !defined(_SPANDSP_PRIVATE_T30_H_)
00029 #define _SPANDSP_PRIVATE_T30_H_
00030 
00031 /*!
00032     T.30 FAX channel descriptor. This defines the state of a single working
00033     instance of a T.30 FAX channel.
00034 */
00035 struct t30_state_s
00036 {
00037     /*! \brief T.4 context for reading or writing image data. */
00038     union
00039     {
00040         t4_state_t rx;
00041         t4_state_t tx;
00042     } t4;
00043     /*! \brief The type of FAX operation currently in progress */
00044     int operation_in_progress;
00045 
00046     /*! \brief TRUE if behaving as the calling party */
00047     int calling_party;
00048     
00049     /*! \brief Internet aware FAX mode bit mask. */
00050     int iaf;
00051     /*! \brief A bit mask of the currently supported modem types. */
00052     int supported_modems;
00053     /*! \brief A bit mask of the currently supported image compression modes. */
00054     int supported_compressions;
00055     /*! \brief A bit mask of the currently supported image resolutions. */
00056     int supported_resolutions;
00057     /*! \brief A bit mask of the currently supported image sizes. */
00058     int supported_image_sizes;
00059     /*! \brief A bit mask of the currently supported T.30 special features. */
00060     int supported_t30_features;
00061     /*! \brief TRUE is ECM mode handling is enabled. */
00062     int ecm_allowed;
00063     /*! \brief TRUE if we are capable of retransmitting pages */
00064     int retransmit_capable;
00065 
00066     /*! \brief The received DCS, formatted as an ASCII string, for inclusion
00067                in the TIFF file. */
00068     char rx_dcs_string[T30_MAX_DIS_DTC_DCS_LEN*3 + 1];
00069     /*! \brief The text which will be used in FAX page header. No text results
00070                in no header line. */
00071     char header_info[T30_MAX_PAGE_HEADER_INFO + 1];
00072     /*! \brief TRUE for FAX page headers to overlay (i.e. replace) the beginning of the
00073                page image. FALSE for FAX page headers to add to the overall length of
00074                the page. */
00075     int header_overlays_image;
00076     /*! \brief TRUE if remote T.30 procedural interrupts are allowed. */
00077     int remote_interrupts_allowed;
00078 
00079     /*! \brief The information fields received. */
00080     t30_exchanged_info_t rx_info;
00081     /*! \brief The information fields to be transmitted. */
00082     t30_exchanged_info_t tx_info;
00083     /*! \brief The country of origin of the remote machine, if known, else NULL. */
00084     const char *country;
00085     /*! \brief The vendor of the remote machine, if known, else NULL. */
00086     const char *vendor;
00087     /*! \brief The model of the remote machine, if known, else NULL. */
00088     const char *model;
00089 
00090     /*! \brief A pointer to a callback routine to be called when phase B events
00091         occur. */
00092     t30_phase_b_handler_t *phase_b_handler;
00093     /*! \brief An opaque pointer supplied in event B callbacks. */
00094     void *phase_b_user_data;
00095     /*! \brief A pointer to a callback routine to be called when phase D events
00096         occur. */
00097     t30_phase_d_handler_t *phase_d_handler;
00098     /*! \brief An opaque pointer supplied in event D callbacks. */
00099     void *phase_d_user_data;
00100     /*! \brief A pointer to a callback routine to be called when phase E events
00101         occur. */
00102     t30_phase_e_handler_t *phase_e_handler;
00103     /*! \brief An opaque pointer supplied in event E callbacks. */
00104     void *phase_e_user_data;
00105     /*! \brief A pointer to a callback routine to be called when frames are
00106         exchanged. */
00107     t30_real_time_frame_handler_t *real_time_frame_handler;
00108     /*! \brief An opaque pointer supplied in real time frame callbacks. */
00109     void *real_time_frame_user_data;
00110 
00111     /*! \brief A pointer to a callback routine to be called when document events
00112         (e.g. end of transmitted document) occur. */
00113     t30_document_handler_t *document_handler;
00114     /*! \brief An opaque pointer supplied in document callbacks. */
00115     void *document_user_data;
00116 
00117     /*! \brief The handler for changes to the receive mode */
00118     t30_set_handler_t *set_rx_type_handler;
00119     /*! \brief An opaque pointer passed to the handler for changes to the receive mode */
00120     void *set_rx_type_user_data;
00121     /*! \brief The handler for changes to the transmit mode */
00122     t30_set_handler_t *set_tx_type_handler;
00123     /*! \brief An opaque pointer passed to the handler for changes to the transmit mode */
00124     void *set_tx_type_user_data;
00125 
00126     /*! \brief The transmitted HDLC frame handler. */
00127     t30_send_hdlc_handler_t *send_hdlc_handler;
00128     /*! \brief An opaque pointer passed to the transmitted HDLC frame handler. */
00129     void *send_hdlc_user_data;
00130 
00131     /*! \brief The DIS code for the minimum scan row time we require. This is usually 0ms,
00132         but if we are trying to simulate another type of FAX machine, we may need a non-zero
00133         value here. */
00134     uint8_t local_min_scan_time_code;
00135 
00136     /*! \brief The current T.30 phase. */
00137     int phase;
00138     /*! \brief The T.30 phase to change to when the current phase ends. */
00139     int next_phase;
00140     /*! \brief The current state of the T.30 state machine. */
00141     int state;
00142     /*! \brief The step in sending a sequence of HDLC frames. */
00143     int step;
00144 
00145     /*! \brief The preparation buffer for the DCS message to be transmitted. */
00146     uint8_t dcs_frame[T30_MAX_DIS_DTC_DCS_LEN];
00147     /*! \brief The length of the DCS message to be transmitted. */
00148     int dcs_len;
00149     /*! \brief The preparation buffer for DIS or DTC message to be transmitted. */
00150     uint8_t local_dis_dtc_frame[T30_MAX_DIS_DTC_DCS_LEN];
00151     /*! \brief The length of the DIS or DTC message to be transmitted. */
00152     int local_dis_dtc_len;
00153     /*! \brief The last DIS or DTC message received form the far end. */
00154     uint8_t far_dis_dtc_frame[T30_MAX_DIS_DTC_DCS_LEN];
00155     /*! \brief The length of the last DIS or DTC message received form the far end. */
00156     int far_dis_dtc_len;
00157     /*! \brief TRUE if a valid DIS has been received from the far end. */
00158     int dis_received;
00159 
00160     /*! \brief TRUE if the short training sequence should be used. */
00161     int short_train;
00162 
00163     /*! \brief A count of the number of bits in the trainability test. This counts down to zero when
00164         sending TCF, and counts up when receiving it. */
00165     int tcf_test_bits;
00166     /*! \brief The current count of consecutive received zero bits, during the trainability test. */
00167     int tcf_current_zeros;
00168     /*! \brief The maximum consecutive received zero bits seen to date, during the trainability test. */
00169     int tcf_most_zeros;
00170 
00171     /*! \brief The current fallback step for the fast message transfer modem. */
00172     int current_fallback;
00173     /*! \brief The subset of supported modems allowed at the current time, allowing for negotiation. */
00174     int current_permitted_modems;
00175     /*! \brief TRUE if a carrier is present. Otherwise FALSE. */
00176     int rx_signal_present;
00177     /*! \brief TRUE if a modem has trained correctly. */
00178     int rx_trained;
00179     /*! \brief TRUE if a valid HDLC frame has been received in the current reception period. */
00180     int rx_frame_received;
00181 
00182     /*! \brief Current reception mode. */
00183     int current_rx_type;
00184     /*! \brief Current transmission mode. */
00185     int current_tx_type;
00186 
00187     /*! \brief T0 is the answer timeout when calling another FAX machine.
00188         Placing calls is handled outside the FAX processing, but this timeout keeps
00189         running until V.21 modulation is sent or received.
00190         T1 is the remote terminal identification timeout (in audio samples). */
00191     int timer_t0_t1;
00192     /*! \brief T2, T2A and T2B are the HDLC command timeouts.
00193                T4, T4A and T4B are the HDLC response timeouts (in audio samples). */
00194     int timer_t2_t4;
00195     /*! \brief A value specifying which of the possible timers is currently running in timer_t2_t4 */
00196     int timer_t2_t4_is;
00197     /*! \brief Procedural interrupt timeout (in audio samples). */
00198     int timer_t3;
00199     /*! \brief This is only used in error correcting mode. */
00200     int timer_t5;
00201     /*! \brief This is only used in full duplex (e.g. ISDN) modes. */
00202     int timer_t6;
00203     /*! \brief This is only used in full duplex (e.g. ISDN) modes. */
00204     int timer_t7;
00205     /*! \brief This is only used in full duplex (e.g. ISDN) modes. */
00206     int timer_t8;
00207 
00208     /*! \brief TRUE once the far end FAX entity has been detected. */
00209     int far_end_detected;
00210 
00211     /*! \brief TRUE if a local T.30 interrupt is pending. */
00212     int local_interrupt_pending;
00213     /*! \brief The image coding being used on the line. */
00214     int line_encoding;
00215     /*! \brief The image coding being used for output files. */
00216     int output_encoding;
00217     /*! \brief The current DCS message minimum scan time code. */
00218     uint8_t min_scan_time_code;
00219     /*! \brief The X direction resolution of the current image, in pixels per metre. */
00220     int x_resolution;
00221     /*! \brief The Y direction resolution of the current image, in pixels per metre. */
00222     int y_resolution;
00223     /*! \brief The width of the current image, in pixels. */
00224     t4_image_width_t image_width;
00225     /*! \brief Current number of retries of the action in progress. */
00226     int retries;
00227     /*! \brief TRUE if error correcting mode is used. */
00228     int error_correcting_mode;
00229     /*! \brief The number of HDLC frame retries, if error correcting mode is used. */
00230     int error_correcting_mode_retries;
00231     /*! \brief The current count of consecutive T30_PPR messages. */
00232     int ppr_count;
00233     /*! \brief The current count of consecutive T30_RNR messages. */
00234     int receiver_not_ready_count;
00235     /*! \brief The number of octets to be used per ECM frame. */
00236     int octets_per_ecm_frame;
00237     /*! \brief The ECM partial page buffer. */
00238     uint8_t ecm_data[256][260];
00239     /*! \brief The lengths of the frames in the ECM partial page buffer. */
00240     int16_t ecm_len[256];
00241     /*! \brief A bit map of the OK ECM frames, constructed as a PPR frame. */
00242     uint8_t ecm_frame_map[3 + 32];
00243     
00244     /*! \brief The current page number for receiving, in ECM or non-ECM mode. This is reset at the start of a call. */
00245     int rx_page_number;
00246     /*! \brief The current page number for sending, in ECM or non-ECM mode. This is reset at the start of a call. */
00247     int tx_page_number;
00248     /*! \brief The current block number, in ECM mode */
00249     int ecm_block;
00250     /*! \brief The number of frames in the current block number, in ECM mode */
00251     int ecm_frames;
00252     /*! \brief The number of frames sent in the current burst of image transmission, in ECM mode */
00253     int ecm_frames_this_tx_burst;
00254     /*! \brief The current ECM frame, during ECM transmission. */
00255     int ecm_current_tx_frame;
00256     /*! \brief TRUE if we are at the end of an ECM page to se sent - i.e. there are no more
00257         partial pages still to come. */
00258     int ecm_at_page_end;
00259 
00260     /*! \brief The transmission step queued to follow the one in progress. */
00261     int next_tx_step;
00262     /*! \brief The FCF for the next receive step. */
00263     uint8_t next_rx_step;
00264     /*! \brief Image file name for image reception. */
00265     char rx_file[256];
00266     /*! \brief The last page we are prepared accept for a received image file. -1 means no restriction. */
00267     int rx_stop_page;
00268     /*! \brief Image file name to be sent. */
00269     char tx_file[256];
00270     /*! \brief The first page to be sent from the image file. -1 means no restriction. */
00271     int tx_start_page;
00272     /*! \brief The last page to be sent from the image file. -1 means no restriction. */
00273     int tx_stop_page;
00274     /*! \brief The current completion status. */
00275     int current_status;
00276 
00277     /*! \brief The number of RTP events */
00278     int rtp_events;
00279     /*! \brief The number of RTN events */
00280     int rtn_events;
00281 
00282     /*! \brief the FCF2 field of the last PPS message we received. */
00283     uint8_t last_pps_fcf2;
00284     /*! \brief TRUE if all frames of the current received ECM block are now OK */
00285     int rx_ecm_block_ok;
00286     /*! \brief A count of successfully received ECM frames, to assess progress as a basis for
00287         deciding whether to continue error correction when PPRs keep repeating. */
00288     int ecm_progress;
00289 
00290     /*! \brief Error and flow logging control */
00291     logging_state_t logging;
00292 };
00293 
00294 #endif
00295 /*- End of file ------------------------------------------------------------*/

Generated on Thu Dec 9 21:11:50 2010 for spandsp by  doxygen 1.5.9