spandsp 3.0.0
t38_gateway.c File Reference
#include <inttypes.h>
#include <stdlib.h>
#include <stdio.h>
#include <fcntl.h>
#include <time.h>
#include <string.h>
#include "spandsp/stdbool.h"
#include "floating_fudge.h"
#include <assert.h>
#include <tiffio.h>
#include "spandsp/telephony.h"
#include "spandsp/alloc.h"
#include "spandsp/logging.h"
#include "spandsp/queue.h"
#include "spandsp/vector_int.h"
#include "spandsp/dc_restore.h"
#include "spandsp/bit_operations.h"
#include "spandsp/power_meter.h"
#include "spandsp/complex.h"
#include "spandsp/tone_detect.h"
#include "spandsp/tone_generate.h"
#include "spandsp/async.h"
#include "spandsp/crc.h"
#include "spandsp/hdlc.h"
#include "spandsp/silence_gen.h"
#include "spandsp/fsk.h"
#include "spandsp/v29tx.h"
#include "spandsp/v29rx.h"
#include "spandsp/v27ter_tx.h"
#include "spandsp/v27ter_rx.h"
#include "spandsp/v17tx.h"
#include "spandsp/v17rx.h"
#include "spandsp/super_tone_rx.h"
#include "spandsp/modem_connect_tones.h"
#include "spandsp/timezone.h"
#include "spandsp/t4_rx.h"
#include "spandsp/t4_tx.h"
#include "spandsp/image_translate.h"
#include "spandsp/t81_t82_arith_coding.h"
#include "spandsp/t85.h"
#include "spandsp/t42.h"
#include "spandsp/t43.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_logging.h"
#include "spandsp/fax_modems.h"
#include "spandsp/t38_core.h"
#include "spandsp/t38_non_ecm_buffer.h"
#include "spandsp/t38_gateway.h"
#include "spandsp/private/logging.h"
#include "spandsp/private/silence_gen.h"
#include "spandsp/private/power_meter.h"
#include "spandsp/private/fsk.h"
#include "spandsp/private/v17tx.h"
#include "spandsp/private/v17rx.h"
#include "spandsp/private/v27ter_tx.h"
#include "spandsp/private/v27ter_rx.h"
#include "spandsp/private/v29tx.h"
#include "spandsp/private/v29rx.h"
#include "spandsp/private/modem_connect_tones.h"
#include "spandsp/private/hdlc.h"
#include "spandsp/private/fax_modems.h"
#include "spandsp/private/timezone.h"
#include "spandsp/private/t81_t82_arith_coding.h"
#include "spandsp/private/t85.h"
#include "spandsp/private/t42.h"
#include "spandsp/private/t43.h"
#include "spandsp/private/t4_t6_decode.h"
#include "spandsp/private/t4_t6_encode.h"
#include "spandsp/private/image_translate.h"
#include "spandsp/private/t4_rx.h"
#include "spandsp/private/t4_tx.h"
#include "spandsp/private/t30.h"
#include "spandsp/private/t38_core.h"
#include "spandsp/private/t38_non_ecm_buffer.h"
#include "spandsp/private/t38_gateway.h"

Macros

#define DEFAULT_MS_PER_TX_CHUNK   30
 
#define HDLC_START_BUFFER_LEVEL   8
 
#define INDICATOR_TX_COUNT   3
 
#define DATA_TX_COUNT   1
 
#define DATA_END_TX_COUNT   3
 
#define HDLC_FRAMING_OK_THRESHOLD   5
 
#define HDLC_TRAMISSION_LAG_OCTETS   2
 

Enumerations

enum  {
  DISBIT1 = 0x01 , DISBIT2 = 0x02 , DISBIT3 = 0x04 , DISBIT4 = 0x08 ,
  DISBIT5 = 0x10 , DISBIT6 = 0x20 , DISBIT7 = 0x40 , DISBIT8 = 0x80
}
 
enum  { HDLC_FLAG_FINISHED = 0x01 , HDLC_FLAG_CORRUPT_CRC = 0x02 , HDLC_FLAG_PROCEED_WITH_OUTPUT = 0x04 , HDLC_FLAG_MISSING_DATA = 0x08 }
 
enum  { FLAG_INDICATOR = 0x100 , FLAG_DATA = 0x200 }
 
enum  {
  TIMED_MODE_STARTUP = 0 , TIMED_MODE_IDLE , TIMED_MODE_TCF_PREDICTABLE_MODEM_START_FAST_MODEM_ANNOUNCED , TIMED_MODE_TCF_PREDICTABLE_MODEM_START_FAST_MODEM_SEEN ,
  TIMED_MODE_TCF_PREDICTABLE_MODEM_START_PAST_V21_MODEM , TIMED_MODE_TCF_PREDICTABLE_MODEM_START_BEGIN
}
 

Functions

int t38_gateway_rx (t38_gateway_state_t *s, int16_t amp[], int len)
 Process a block of received FAX audio samples. More...
 
int t38_gateway_rx_fillin (t38_gateway_state_t *s, int len)
 Apply fake received audio processing. More...
 
int t38_gateway_tx (t38_gateway_state_t *s, int16_t amp[], int max_len)
 Generate a block of FAX audio samples. More...
 
void t38_gateway_get_transfer_statistics (t38_gateway_state_t *s, t38_stats_t *t)
 Get the current transfer statistics. More...
 
t38_core_state_tt38_gateway_get_t38_core_state (t38_gateway_state_t *s)
 Get a pointer to the T.38 core IFP packet engine associated with a T.38 context. More...
 
logging_state_tt38_gateway_get_logging_state (t38_gateway_state_t *s)
 Get a pointer to the logging context associated with a T.38 context. More...
 
void t38_gateway_set_ecm_capability (t38_gateway_state_t *s, bool ecm_allowed)
 Control whether error correcting mode (ECM) is allowed. More...
 
void t38_gateway_set_transmit_on_idle (t38_gateway_state_t *s, bool transmit_on_idle)
 Select whether silent audio will be sent when transmit is idle. More...
 
void t38_gateway_set_supported_modems (t38_gateway_state_t *s, int supported_modems)
 Specify supported modems. More...
 
void t38_gateway_set_nsx_suppression (t38_gateway_state_t *s, const uint8_t *from_t38, int from_t38_len, const uint8_t *from_modem, int from_modem_len)
 Select whether NSC, NSF, and NSS should be suppressed. More...
 
void t38_gateway_set_tep_mode (t38_gateway_state_t *s, bool use_tep)
 Select whether TEP will be sent for the image modems. More...
 
void t38_gateway_set_fill_bit_removal (t38_gateway_state_t *s, bool remove)
 Select whether non-ECM fill bits are to be removed during transmission. More...
 
void t38_gateway_set_real_time_frame_handler (t38_gateway_state_t *s, t38_gateway_real_time_frame_handler_t handler, void *user_data)
 Set a callback function for T.30 frame exchange monitoring. More...
 
t38_gateway_state_tt38_gateway_init (t38_gateway_state_t *s, t38_tx_packet_handler_t tx_packet_handler, void *tx_packet_user_data)
 Initialise a gateway mode T.38 context. More...
 
int t38_gateway_release (t38_gateway_state_t *s)
 Release a T.38 context. More...
 
int t38_gateway_free (t38_gateway_state_t *s)
 Free a T.38 context. More...
 

Macro Definition Documentation

◆ DATA_END_TX_COUNT

#define DATA_END_TX_COUNT   3

The number of transmissions of terminating data IFP packets

◆ DATA_TX_COUNT

#define DATA_TX_COUNT   1

The number of transmissions of data IFP packets

◆ DEFAULT_MS_PER_TX_CHUNK

#define DEFAULT_MS_PER_TX_CHUNK   30

The default number of milliseconds per transmitted IFP when sending bulk T.38 data

◆ HDLC_FRAMING_OK_THRESHOLD

#define HDLC_FRAMING_OK_THRESHOLD   5

The number of consecutive flags to declare HDLC framing is OK.

◆ HDLC_START_BUFFER_LEVEL

#define HDLC_START_BUFFER_LEVEL   8

The number of bytes which must be in the audio to T.38 HDLC buffer before we start outputting them as IFP messages.

◆ INDICATOR_TX_COUNT

#define INDICATOR_TX_COUNT   3

The number of transmissions of indicator IFP packets

Function Documentation

◆ t38_gateway_free()

int t38_gateway_free ( t38_gateway_state_t s)

Free a T.38 context.

Free a gateway mode T.38 context.

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

◆ t38_gateway_get_logging_state()

logging_state_t * t38_gateway_get_logging_state ( t38_gateway_state_t s)

Get a pointer to the logging context associated with a T.38 context.

Get a pointer to the logging context associated with a T.38 context.

Parameters
sThe T.38 context.
Returns
A pointer to the logging context, or NULL.

References t38_gateway_state_s::logging.

◆ t38_gateway_get_t38_core_state()

t38_core_state_t * t38_gateway_get_t38_core_state ( t38_gateway_state_t s)

Get a pointer to the T.38 core IFP packet engine associated with a T.38 context.

Get a pointer to the T.38 core IFP packet engine associated with a gateway mode T.38 context.

Parameters
sThe T.38 context.
Returns
A pointer to the T.38 core context, or NULL.

References t38_gateway_t38_state_t::t38, and t38_gateway_state_s::t38x.

◆ t38_gateway_get_transfer_statistics()

void t38_gateway_get_transfer_statistics ( t38_gateway_state_t s,
t38_stats_t t 
)

Get the current transfer statistics.

Get the current transfer statistics for the current T.38 session.

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

References t38_stats_t::bit_rate, t38_gateway_state_s::core, t38_gateway_core_state_t::ecm_mode, t38_stats_t::error_correcting_mode, t38_gateway_core_state_t::fast_bit_rate, t38_gateway_core_state_t::pages_confirmed, and t38_stats_t::pages_transferred.

◆ t38_gateway_init()

t38_gateway_state_t * t38_gateway_init ( t38_gateway_state_t s,
t38_tx_packet_handler_t  tx_packet_handler,
void *  tx_packet_user_data 
)

Initialise a gateway mode T.38 context.

Parameters
sThe T.38 context.
tx_packet_handlerA callback routine to encapsulate and transmit T.38 packets.
tx_packet_user_dataAn opaque pointer passed to the tx_packet_handler routine.
Returns
A pointer to the termination mode T.38 context, or NULL if there was a problem.

◆ t38_gateway_release()

int t38_gateway_release ( t38_gateway_state_t s)

Release a T.38 context.

Release a gateway mode T.38 context.

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

◆ t38_gateway_rx()

int t38_gateway_rx ( t38_gateway_state_t s,
int16_t  amp[],
int  len 
)

Process a block of received FAX audio samples.

Process a block of received FAX audio samples.

Parameters
sThe T.38 context.
ampThe audio sample buffer.
lenThe number of samples in the buffer.
Returns
The number of samples unprocessed.

◆ t38_gateway_rx_fillin()

int t38_gateway_rx_fillin ( t38_gateway_state_t s,
int  len 
)

Apply fake received audio processing.

Apply fake processing when a block of audio samples is missing (e.g due to packet loss).

Parameters
sThe T.38 context.
lenThe number of samples to fake.
Returns
The number of samples unprocessed. This should only be non-zero if the software has reached the end of the FAX call.

References t38_gateway_state_s::audio, fax_modems_state_s::audio_rx_log, and t38_gateway_audio_state_t::modems.

◆ t38_gateway_set_ecm_capability()

void t38_gateway_set_ecm_capability ( t38_gateway_state_t s,
bool  ecm_allowed 
)

Control whether error correcting mode (ECM) is allowed.

Control whether error correcting mode (ECM) is allowed.

Parameters
sThe T.38 context.
ecm_allowedTrue is ECM is to be allowed.

References t38_gateway_state_s::core, and t38_gateway_core_state_t::ecm_allowed.

◆ t38_gateway_set_fill_bit_removal()

void t38_gateway_set_fill_bit_removal ( t38_gateway_state_t s,
bool  remove 
)

Select whether non-ECM fill bits are to be removed during transmission.

Select whether non-ECM fill bits are to be removed during transmission.

Parameters
sThe T.38 context.
removeTrue if fill bits are to be removed.

References t38_gateway_state_s::core, t38_gateway_to_t38_state_t::fill_bit_removal, and t38_gateway_core_state_t::to_t38.

◆ t38_gateway_set_nsx_suppression()

void t38_gateway_set_nsx_suppression ( t38_gateway_state_t s,
const uint8_t *  from_t38,
int  from_t38_len,
const uint8_t *  from_modem,
int  from_modem_len 
)

Select whether NSC, NSF, and NSS should be suppressed.

Select whether NSC, NSF, and NSS should be suppressed. It selected, the contents of these messages are forced to zero for all octets beyond the message type. This makes them look like manufacturer specific messages, from a manufacturer which does not exist.

Parameters
sThe T.38 context.
from_t38A string of bytes to overwrite the header of any NSC, NSF, and NSS frames passing through the gateway from T.38 the the modem.
from_t38_lenThe length of the overwrite string.
from_modemA string of bytes to overwrite the header of any NSC, NSF, and NSS frames passing through the gateway from the modem to T.38.
from_modem_lenThe length of the overwrite string.

References MAX_NSX_SUPPRESSION, t38_gateway_t38_state_t::suppress_nsx_len, t38_gateway_t38_state_t::suppress_nsx_string, and t38_gateway_state_s::t38x.

◆ t38_gateway_set_real_time_frame_handler()

void t38_gateway_set_real_time_frame_handler ( t38_gateway_state_t s,
t38_gateway_real_time_frame_handler_t  handler,
void *  user_data 
)

Set a callback function for T.30 frame exchange monitoring.

Set a callback function for T.30 frame exchange monitoring. This is called from the heart of the signal processing, so don't take too long in the handler routine.

Parameters
sThe T.30 context.
handlerThe callback function.
user_dataAn opaque pointer passed to the callback function.

References t38_gateway_state_s::core, t38_gateway_core_state_t::real_time_frame_handler, and t38_gateway_core_state_t::real_time_frame_user_data.

◆ t38_gateway_set_supported_modems()

void t38_gateway_set_supported_modems ( t38_gateway_state_t s,
int  supported_modems 
)

Specify supported modems.

Specify which modem types are supported by a T.30 context.

Parameters
sThe T.38 context.
supported_modemsBit field list of the supported modems.

References t38_gateway_state_s::core, t38_gateway_core_state_t::supported_modems, and T30_SUPPORT_V17.

◆ t38_gateway_set_tep_mode()

void t38_gateway_set_tep_mode ( t38_gateway_state_t s,
bool  use_tep 
)

Select whether TEP will be sent for the image modems.

Select whether talker echo protection tone will be sent for the image modems.

Parameters
sThe T.38 context.
use_tepTrue if TEP should be sent.

◆ t38_gateway_set_transmit_on_idle()

void t38_gateway_set_transmit_on_idle ( t38_gateway_state_t s,
bool  transmit_on_idle 
)

Select whether silent audio will be sent when transmit is idle.

Select whether silent audio will be sent when transmit is idle.

Parameters
sThe T.38 context.
transmit_on_idleTrue if silent audio should be output when the FAX transmitter is idle. False to transmit zero length audio when the FAX transmitter is idle. The default behaviour is false.

References t38_gateway_state_s::audio, t38_gateway_audio_state_t::modems, and fax_modems_state_s::transmit_on_idle.

◆ t38_gateway_tx()

int t38_gateway_tx ( t38_gateway_state_t s,
int16_t  amp[],
int  max_len 
)

Generate a block of FAX audio samples.

Generate a block of FAX audio samples.

Parameters
sThe T.38 context.
ampThe audio sample buffer.
max_lenThe number of samples to be generated.
Returns
The number of samples actually generated.