spandsp 0.0.6
t30.c File Reference
#include <stdlib.h>
#include <stdio.h>
#include <inttypes.h>
#include <string.h>
#include <fcntl.h>
#include <time.h>
#include "spandsp/stdbool.h"
#include "floating_fudge.h"
#include <tiffio.h>
#include "spandsp/telephony.h"
#include "spandsp/logging.h"
#include "spandsp/bit_operations.h"
#include "spandsp/queue.h"
#include "spandsp/power_meter.h"
#include "spandsp/complex.h"
#include "spandsp/tone_generate.h"
#include "spandsp/async.h"
#include "spandsp/hdlc.h"
#include "spandsp/fsk.h"
#include "spandsp/v29rx.h"
#include "spandsp/v29tx.h"
#include "spandsp/v27ter_rx.h"
#include "spandsp/v27ter_tx.h"
#include "spandsp/timezone.h"
#include "spandsp/t4_rx.h"
#include "spandsp/t4_tx.h"
#include "spandsp/t4_t6_decode.h"
#include "spandsp/t4_t6_encode.h"
#include "spandsp/t30_fcf.h"
#include "spandsp/t35.h"
#include "spandsp/t30.h"
#include "spandsp/t30_api.h"
#include "spandsp/t30_logging.h"
#include "spandsp/private/logging.h"
#include "spandsp/private/timezone.h"
#include "spandsp/private/t4_t6_decode.h"
#include "spandsp/private/t4_t6_encode.h"
#include "spandsp/private/t4_rx.h"
#include "spandsp/private/t4_tx.h"
#include "spandsp/private/t30.h"
#include "spandsp/private/t30_dis_dtc_dcs_bits.h"
#include "t30_local.h"

Macros

#define MAX_COMMAND_TRIES   3
 
#define MAX_RESPONSE_TRIES   6
 
#define DEFAULT_TIMER_T0   60000
 
#define DEFAULT_TIMER_T1   35000
 
#define DEFAULT_TIMER_T1A   35000
 
#define DEFAULT_TIMER_T2   7000
 
#define DEFAULT_TIMER_T2A   3000
 
#define DEFAULT_TIMER_T2B   200
 
#define DEFAULT_TIMER_T3   15000
 
#define DEFAULT_TIMER_T4   3450
 
#define DEFAULT_TIMER_T4A   3000
 
#define DEFAULT_TIMER_T4B   200
 
#define DEFAULT_TIMER_T5   65000
 
#define DEFAULT_TIMER_T6   5000
 
#define DEFAULT_TIMER_T7   7000
 
#define DEFAULT_TIMER_T8   10000
 
#define FINAL_FLUSH_TIME   1000
 
#define PPR_LIMIT_BEFORE_CTC_OR_EOR   4
 
#define ADDRESS_FIELD   0xFF
 
#define CONTROL_FIELD_NON_FINAL_FRAME   0x03
 
#define CONTROL_FIELD_FINAL_FRAME   0x13
 
#define T30_V17_FALLBACK_START   0
 
#define T30_V29_FALLBACK_START   3
 
#define T30_V27TER_FALLBACK_START   6
 
#define test_ctrl_bit(s, bit)   ((s)[3 + ((bit - 1)/8)] & (1 << ((bit - 1)%8)))
 
#define set_ctrl_bit(s, bit)   (s)[3 + ((bit - 1)/8)] |= (1 << ((bit - 1)%8))
 
#define set_ctrl_bits(s, val, bit)   (s)[3 + ((bit - 1)/8)] |= ((val) << ((bit - 1)%8))
 
#define clr_ctrl_bit(s, bit)   (s)[3 + ((bit - 1)/8)] &= ~(1 << ((bit - 1)%8))
 

Enumerations

enum  {
  T30_PHASE_IDLE = 0 , T30_PHASE_A_CED , T30_PHASE_A_CNG , T30_PHASE_B_RX ,
  T30_PHASE_B_TX , T30_PHASE_C_NON_ECM_RX , T30_PHASE_C_NON_ECM_TX , T30_PHASE_C_ECM_RX ,
  T30_PHASE_C_ECM_TX , T30_PHASE_D_RX , T30_PHASE_D_TX , T30_PHASE_E ,
  T30_PHASE_CALL_FINISHED
}
 
enum  {
  T30_STATE_ANSWERING = 1 , T30_STATE_B , T30_STATE_C , T30_STATE_D ,
  T30_STATE_D_TCF , T30_STATE_D_POST_TCF , T30_STATE_F_TCF , T30_STATE_F_CFR ,
  T30_STATE_F_FTT , T30_STATE_F_DOC_NON_ECM , T30_STATE_F_POST_DOC_NON_ECM , T30_STATE_F_DOC_ECM ,
  T30_STATE_F_POST_DOC_ECM , T30_STATE_F_POST_RCP_MCF , T30_STATE_F_POST_RCP_PPR , T30_STATE_F_POST_RCP_RNR ,
  T30_STATE_R , T30_STATE_T , T30_STATE_I , T30_STATE_II ,
  T30_STATE_II_Q , T30_STATE_III_Q , T30_STATE_IV , T30_STATE_IV_PPS_NULL ,
  T30_STATE_IV_PPS_Q , T30_STATE_IV_PPS_RNR , T30_STATE_IV_CTC , T30_STATE_IV_EOR ,
  T30_STATE_IV_EOR_RNR , T30_STATE_CALL_FINISHED
}
 
enum  {
  T30_MIN_SCAN_20MS = 0 , T30_MIN_SCAN_5MS = 1 , T30_MIN_SCAN_10MS = 2 , T30_MIN_SCAN_40MS = 4 ,
  T30_MIN_SCAN_0MS = 7
}
 
enum  { T30_MODE_SEND_DOC = 1 , T30_MODE_RECEIVE_DOC }
 
enum  { T30_COPY_QUALITY_PERFECT = 0 , T30_COPY_QUALITY_GOOD , T30_COPY_QUALITY_POOR , T30_COPY_QUALITY_BAD }
 
enum  {
  DISBIT1 = 0x01 , DISBIT2 = 0x02 , DISBIT3 = 0x04 , DISBIT4 = 0x08 ,
  DISBIT5 = 0x10 , DISBIT6 = 0x20 , DISBIT7 = 0x40 , DISBIT8 = 0x80
}
 
enum  {
  OPERATION_IN_PROGRESS_NONE = 0 , OPERATION_IN_PROGRESS_T4_RX , OPERATION_IN_PROGRESS_T4_TX , OPERATION_IN_PROGRESS_POST_T4_RX ,
  OPERATION_IN_PROGRESS_POST_T4_TX
}
 
enum  {
  TIMER_IS_IDLE = 0 , TIMER_IS_T2 , TIMER_IS_T1A , TIMER_IS_T2A ,
  TIMER_IS_T2B , TIMER_IS_T2C , TIMER_IS_T4 , TIMER_IS_T4A ,
  TIMER_IS_T4B , TIMER_IS_T4C
}
 

Functions

int t30_build_dis_or_dtc (t30_state_t *s)
 
void t30_non_ecm_put_bit (void *user_data, int bit)
 
void t30_non_ecm_put_byte (void *user_data, int byte)
 Process a byte of received non-ECM image data. More...
 
void t30_non_ecm_put_chunk (void *user_data, const uint8_t buf[], int len)
 Process a chunk of received non-ECM image data. More...
 
int t30_non_ecm_get_bit (void *user_data)
 
int t30_non_ecm_get_byte (void *user_data)
 Get a byte of received non-ECM image data. More...
 
int t30_non_ecm_get_chunk (void *user_data, uint8_t buf[], int max_len)
 Get a bit of received non-ECM image data. More...
 
void t30_hdlc_accept (void *user_data, const uint8_t *msg, int len, int ok)
 
void t30_front_end_status (void *user_data, int status)
 Inform the T.30 engine of a status change in the front end (end of tx, rx signal change, etc.). More...
 
void t30_timer_update (t30_state_t *s, int samples)
 Report the passage of time to the T.30 engine. More...
 
void t30_terminate (t30_state_t *s)
 Cleanup a T.30 context if the call terminates. More...
 
void t30_get_transfer_statistics (t30_state_t *s, t30_stats_t *t)
 Get the current transfer statistics. More...
 
void t30_local_interrupt_request (t30_state_t *s, int state)
 Request a local interrupt of FAX exchange. More...
 
void t30_remote_interrupts_allowed (t30_state_t *s, int state)
 Allow remote interrupts of FAX exchange. More...
 
int t30_restart (t30_state_t *s)
 Restart a T.30 context. More...
 
t30_state_tt30_init (t30_state_t *s, int calling_party, t30_set_handler_t *set_rx_type_handler, void *set_rx_type_user_data, t30_set_handler_t *set_tx_type_handler, void *set_tx_type_user_data, t30_send_hdlc_handler_t *send_hdlc_handler, void *send_hdlc_user_data)
 Initialise a T.30 context. More...
 
int t30_release (t30_state_t *s)
 Release a T.30 context. More...
 
int t30_free (t30_state_t *s)
 Free a T.30 context. More...
 
int t30_call_active (t30_state_t *s)
 Check if a T.30 call is still active. More...
 

Macro Definition Documentation

◆ clr_ctrl_bit

#define clr_ctrl_bit (   s,
  bit 
)    (s)[3 + ((bit - 1)/8)] &= ~(1 << ((bit - 1)%8))

Clear a specified bit within a DIS, DTC or DCS frame

◆ DEFAULT_TIMER_T0

#define DEFAULT_TIMER_T0   60000

Time-out T0 defines the amount of time an automatic calling terminal waits for the called terminal to answer the call. T0 begins after the dialling of the number is completed and is reset: a) when T0 times out; or b) when timer T1 is started; or c) if the terminal is capable of detecting any condition which indicates that the call will not be successful, when such a condition is detected. The recommended value of T0 is 60+-5s. However, when it is anticipated that a long call set-up time may be encountered, an alternative value of up to 120s may be used. NOTE - National regulations may require the use of other values for T0.

◆ DEFAULT_TIMER_T1

#define DEFAULT_TIMER_T1   35000

Time-out T1 defines the amount of time two terminals will continue to attempt to identify each other. T1 is 35+-5s, begins upon entering phase B, and is reset upon detecting a valid signal or when T1 times out. For operating methods 3 and 4 (see 3.1), the calling terminal starts time-out T1 upon reception of the V.21 modulation scheme. For operating method 4 bis a (see 3.1), the calling terminal starts time-out T1 upon starting transmission using the V.21 modulation scheme. Annex A says T1 is also the timeout to be used for the receipt of the first HDLC frame after the start of high speed flags in ECM mode. This seems a strange reuse of the T1 name, so we distinguish it here by calling it T1A.

◆ DEFAULT_TIMER_T2

#define DEFAULT_TIMER_T2   7000

Time-out T2 makes use of the tight control between commands and responses to detect the loss of command/response synchronization. T2 is 6+-1s, and begins when initiating a command search (e.g., the first entrance into the "command received" subroutine, reference flow diagram in section 5.2). T2 is reset when an HDLC flag is received or when T2 times out.

◆ DEFAULT_TIMER_T2A

#define DEFAULT_TIMER_T2A   3000

Once HDLC flags begin, T2 is reset, and a 3s timer begins. This timer is unnamed in T.30. Here we term it T2A. No tolerance is specified for this timer. T2A specifies the maximum time to wait for the end of a frame, after the initial flag has been seen.

◆ DEFAULT_TIMER_T2B

#define DEFAULT_TIMER_T2B   200

If the HDLC carrier falls during reception, we need to apply a minimum time before continuing. If we don't, there are circumstances where we could continue and reply before the incoming signals have really finished. E.g. if a bad DCS is received in a DCS-TCF sequence, we need wait for the TCF carrier to pass, before continuing. This timer is specified as 200ms, but no tolerance is specified. It is unnamed in T.30. Here we term it T2B

◆ DEFAULT_TIMER_T3

#define DEFAULT_TIMER_T3   15000

Time-out T3 defines the amount of time a terminal will attempt to alert the local operator in response to a procedural interrupt. Failing to achieve operator intervention, the terminal will discontinue this attempt and shall issue other commands or responses. T3 is 10+-5s, begins on the first detection of a procedural interrupt command/response signal (i.e., PIN/PIP or PRI-Q) and is reset when T3 times out or when the operator initiates a line request.

◆ DEFAULT_TIMER_T4

#define DEFAULT_TIMER_T4   3450

Time-out T4 defines the amount of time a terminal will wait for flags to begin, when waiting for a response from a remote terminal. T2 is 3s +-15%, and begins when initiating a response search (e.g., the first entrance into the "response received" subroutine, reference flow diagram in section 5.2). T4 is reset when an HDLC flag is received or when T4 times out. NOTE - For manual FAX units, the value of timer T4 may be either 3.0s +-15% or 4.5s +-15%. If the value of 4.5s is used, then after detection of a valid response to the first DIS, it may be reduced to 3.0s +-15%. T4 = 3.0s +-15% for automatic units.

◆ DEFAULT_TIMER_T4A

#define DEFAULT_TIMER_T4A   3000

Once HDLC flags begin, T4 is reset, and a 3s timer begins. This timer is unnamed in T.30. Here we term it T4A. No tolerance is specified for this timer. T4A specifies the maximum time to wait for the end of a frame, after the initial flag has been seen. Note that a different timer is used for the fast HDLC in ECM mode, to provide time for physical paper handling.

◆ DEFAULT_TIMER_T4B

#define DEFAULT_TIMER_T4B   200

If the HDLC carrier falls during reception, we need to apply a minimum time before continuing. if we don't, there are circumstances where we could continue and reply before the incoming signals have really finished. E.g. if a bad DCS is received in a DCS-TCF sequence, we need wait for the TCF carrier to pass, before continuing. This timer is specified as 200ms, but no tolerance is specified. It is unnamed in T.30. Here we term it T4B

◆ DEFAULT_TIMER_T5

#define DEFAULT_TIMER_T5   65000

Time-out T5 is defined for the optional T.4 error correction mode. Time-out T5 defines the amount of time waiting for clearance of the busy condition of the receiving terminal. T5 is 60+-5s and begins on the first detection of the RNR response. T5 is reset when T5 times out or the MCF or PIP response is received or when the ERR or PIN response is received in the flow control process after transmitting the EOR command. If the timer T5 has expired, the DCN command is transmitted for call release.

◆ DEFAULT_TIMER_T6

#define DEFAULT_TIMER_T6   5000

(Annex C - ISDN) Time-out T6 defines the amount of time two terminals will continue to attempt to identify each other. T6 is 5+-0.5s. The timeout begins upon entering Phase B, and is reset upon detecting a valid signal, or when T6 times out.

◆ DEFAULT_TIMER_T7

#define DEFAULT_TIMER_T7   7000

(Annex C - ISDN) Time-out T7 is used to detect loss of command/response synchronization. T7 is 6+-1s. The timeout begins when initiating a command search (e.g., the first entrance into the "command received" subroutine - see flow diagram in C.5) and is reset upon detecting a valid signal or when T7 times out.

◆ DEFAULT_TIMER_T8

#define DEFAULT_TIMER_T8   10000

(Annex C - ISDN) Time-out T8 defines the amount of time waiting for clearance of the busy condition of the receiving terminal. T8 is 10+-1s. The timeout begins on the first detection of the combination of no outstanding corrections and the RNR response. T8 is reset when T8 times out or MCF response is received. If the timer T8 expires, a DCN command is transmitted for call release.

◆ FINAL_FLUSH_TIME

#define FINAL_FLUSH_TIME   1000

Final time we allow for things to flush through the system, before we disconnect, in milliseconds. 200ms should be fine for a PSTN call. For a T.38 call something longer is desirable. This delay is to allow sufficient time for the last message to be flushed all the way through to the far end.

◆ MAX_COMMAND_TRIES

#define MAX_COMMAND_TRIES   3

The maximum permitted number of retries of a single command allowed.

◆ MAX_RESPONSE_TRIES

#define MAX_RESPONSE_TRIES   6

The maximum permitted number of retries of a single response request allowed. This is not specified in T.30. However, if you don't apply some limit a messed up FAX terminal could keep you retrying all day. Its a backstop protection.

◆ PPR_LIMIT_BEFORE_CTC_OR_EOR

#define PPR_LIMIT_BEFORE_CTC_OR_EOR   4

The number of PPRs received before CTC or EOR is sent in ECM mode. T.30 defines this as 4, but it could be varied, and the Japanese spec, for example, does make this value a variable.

◆ set_ctrl_bit

#define set_ctrl_bit (   s,
  bit 
)    (s)[3 + ((bit - 1)/8)] |= (1 << ((bit - 1)%8))

Set a specified bit within a DIS, DTC or DCS frame

◆ set_ctrl_bits

#define set_ctrl_bits (   s,
  val,
  bit 
)    (s)[3 + ((bit - 1)/8)] |= ((val) << ((bit - 1)%8))

Set a specified block of bits within a DIS, DTC or DCS frame

◆ T30_V17_FALLBACK_START

#define T30_V17_FALLBACK_START   0

The starting point in the modem fallback sequence if V.17 is allowed

◆ T30_V27TER_FALLBACK_START

#define T30_V27TER_FALLBACK_START   6

The starting point in the modem fallback sequence if V.29 is not allowed

◆ T30_V29_FALLBACK_START

#define T30_V29_FALLBACK_START   3

The starting point in the modem fallback sequence if V.17 is not allowed

◆ test_ctrl_bit

#define test_ctrl_bit (   s,
  bit 
)    ((s)[3 + ((bit - 1)/8)] & (1 << ((bit - 1)%8)))

Test a specified bit within a DIS, DTC or DCS frame

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

These are internal assessments of received image quality, used to determine whether we continue, retrain, or abandon the call. This is only relevant to non-ECM operation.

◆ anonymous enum

anonymous enum

There are high level indications of what is happening at any instant, to guide the cleanup continue, retrain, or abandoning of the call.

Function Documentation

◆ t30_call_active()

int t30_call_active ( t30_state_t s)

Check if a T.30 call is still active.

Check if a T.30 call is still active. This may be used to regularly poll if the job has finished.

Parameters
sThe T.30 context.
Returns
TRUE for call still active, or FALSE for call completed.

References t30_state_s::phase.

◆ t30_free()

int t30_free ( t30_state_t s)

Free a T.30 context.

Free a T.30 context.

Parameters
sThe T.30 context.
Returns
0 for OK, else -1.

References t30_release().

◆ t30_front_end_status()

void t30_front_end_status ( void *  user_data,
int  status 
)

Inform the T.30 engine of a status change in the front end (end of tx, rx signal change, etc.).

Inform the T.30 engine of a status change in the front end (end of tx, rx signal change, etc.).

Parameters
user_dataThe T.30 context.
statusThe type of status change which occured.

◆ t30_get_transfer_statistics()

void t30_get_transfer_statistics ( t30_state_t s,
t30_stats_t t 
)

Get the current transfer statistics.

Get the current transfer statistics for the file being sent or received.

Parameters
sThe T.30 context.
tA pointer to a buffer for the statistics.

References t30_stats_t::bit_rate.

◆ t30_init()

t30_state_t * t30_init ( t30_state_t s,
int  calling_party,
t30_set_handler_t set_rx_type_handler,
void *  set_rx_type_user_data,
t30_set_handler_t set_tx_type_handler,
void *  set_tx_type_user_data,
t30_send_hdlc_handler_t send_hdlc_handler,
void *  send_hdlc_user_data 
)

Initialise a T.30 context.

Initialise a T.30 context.

Parameters
sThe T.30 context.
calling_partyTRUE if the context is for a calling party. FALSE if the context is for an answering party.
set_rx_type_handler
set_rx_type_user_data
set_tx_type_handler
set_tx_type_user_data
send_hdlc_handler
send_hdlc_user_data
Returns
A pointer to the context, or NULL if there was a problem.

◆ t30_local_interrupt_request()

void t30_local_interrupt_request ( t30_state_t s,
int  state 
)

Request a local interrupt of FAX exchange.

Request a local interrupt of FAX exchange.

Parameters
sThe T.30 context.
stateTRUE to enable interrupt request, else FALSE.

◆ t30_non_ecm_get_byte()

int t30_non_ecm_get_byte ( void *  user_data)

Get a byte of received non-ECM image data.

Get a byte of received non-ECM image data.

Parameters
user_dataAn opaque pointer, which must point to the T.30 context.
Returns
The next byte to transmit.

References t30_state_s::state.

◆ t30_non_ecm_get_chunk()

int t30_non_ecm_get_chunk ( void *  user_data,
uint8_t  buf[],
int  max_len 
)

Get a bit of received non-ECM image data.

Get a chunk of received non-ECM image data.

Parameters
user_dataAn opaque pointer, which must point to the T.30 context.
bufThe buffer to contain the data.
max_lenThe maximum length of the chunk.
Returns
The actual length of the chunk.

◆ t30_non_ecm_put_byte()

void t30_non_ecm_put_byte ( void *  user_data,
int  byte 
)

Process a byte of received non-ECM image data.

Process a byte of received non-ECM image data.

Parameters
user_dataAn opaque pointer, which must point to the T.30 context.
byteThe received byte.

◆ t30_non_ecm_put_chunk()

void t30_non_ecm_put_chunk ( void *  user_data,
const uint8_t  buf[],
int  len 
)

Process a chunk of received non-ECM image data.

Process a chunk of received non-ECM image data.

Parameters
user_dataAn opaque pointer, which must point to the T.30 context.
bufThe buffer containing the received data.
lenThe length of the data in buf.

◆ t30_release()

int t30_release ( t30_state_t s)

Release a T.30 context.

Release a T.30 context.

Parameters
sThe T.30 context.
Returns
0 for OK, else -1.

Referenced by fax_free(), fax_release(), t30_free(), and t38_terminal_release().

◆ t30_remote_interrupts_allowed()

void t30_remote_interrupts_allowed ( t30_state_t s,
int  state 
)

Allow remote interrupts of FAX exchange.

Allow remote interrupts of FAX exchange.

Parameters
sThe T.30 context.
stateTRUE to allow interruptd, else FALSE.

◆ t30_restart()

int t30_restart ( t30_state_t s)

Restart a T.30 context.

Restart a T.30 context.

Parameters
sThe T.30 context.
Returns
0 for OK, else -1.

References t30_state_s::phase.

◆ t30_terminate()

void t30_terminate ( t30_state_t s)

Cleanup a T.30 context if the call terminates.

Cleanup a T.30 context if the call terminates.

Parameters
sThe T.30 context.

References t30_state_s::phase.

◆ t30_timer_update()

void t30_timer_update ( t30_state_t s,
int  samples 
)

Report the passage of time to the T.30 engine.

Report the passage of time to the T.30 engine.

Parameters
sThe T.30 context.
samplesThe time change in 1/8000th second steps.

References t30_state_s::far_end_detected, and t30_state_s::timer_t0_t1.