spandsp  3.0.0
t38_core.h File Reference

Go to the source code of this file.

Classes

struct  t38_data_field_t
 

Macros

#define T38_RX_BUF_LEN   2048
 
#define T38_TX_BUF_LEN   16384
 

Typedefs

typedef enum t30_indicator_types_e t30_indicator_types_t
 
typedef enum t38_data_types_e t38_data_types_t
 
typedef enum t38_field_types_e t38_field_types_t
 
typedef enum t38_field_classes_e t38_field_classes_t
 
typedef enum t38_message_types_e t38_message_types_t
 
typedef enum t38_transport_types_e t38_transport_types_t
 
typedef enum t38_data_rate_management_types_e t38_data_rate_management_types_t
 
typedef enum t38_packet_categories_e t38_packet_categories_t
 
typedef enum t38_chunking_mode_e t38_chunking_mode_t
 
typedef struct t38_core_state_s t38_core_state_t
 
typedef int(* t38_tx_packet_handler_t) (t38_core_state_t *s, void *user_data, const uint8_t *buf, int len, int count)
 
typedef int(* t38_rx_indicator_handler_t) (t38_core_state_t *s, void *user_data, int indicator)
 
typedef int(* t38_rx_data_handler_t) (t38_core_state_t *s, void *user_data, int data_type, int field_type, const uint8_t *buf, int len)
 
typedef int(* t38_rx_missing_handler_t) (t38_core_state_t *s, void *user_data, int rx_seq_no, int expected_seq_no)
 

Enumerations

enum  t30_indicator_types_e {
  T38_IND_NO_SIGNAL = 0, T38_IND_CNG, T38_IND_CED, T38_IND_V21_PREAMBLE,
  T38_IND_V27TER_2400_TRAINING, T38_IND_V27TER_4800_TRAINING, T38_IND_V29_7200_TRAINING, T38_IND_V29_9600_TRAINING,
  T38_IND_V17_7200_SHORT_TRAINING, T38_IND_V17_7200_LONG_TRAINING, T38_IND_V17_9600_SHORT_TRAINING, T38_IND_V17_9600_LONG_TRAINING,
  T38_IND_V17_12000_SHORT_TRAINING, T38_IND_V17_12000_LONG_TRAINING, T38_IND_V17_14400_SHORT_TRAINING, T38_IND_V17_14400_LONG_TRAINING,
  T38_IND_V8_ANSAM, T38_IND_V8_SIGNAL, T38_IND_V34_CNTL_CHANNEL_1200, T38_IND_V34_PRI_CHANNEL,
  T38_IND_V34_CC_RETRAIN, T38_IND_V33_12000_TRAINING, T38_IND_V33_14400_TRAINING
}
 
enum  t38_data_types_e {
  T38_DATA_NONE = -1, T38_DATA_V21 = 0, T38_DATA_V27TER_2400, T38_DATA_V27TER_4800,
  T38_DATA_V29_7200, T38_DATA_V29_9600, T38_DATA_V17_7200, T38_DATA_V17_9600,
  T38_DATA_V17_12000, T38_DATA_V17_14400, T38_DATA_V8, T38_DATA_V34_PRI_RATE,
  T38_DATA_V34_CC_1200, T38_DATA_V34_PRI_CH, T38_DATA_V33_12000, T38_DATA_V33_14400
}
 
enum  t38_field_types_e {
  T38_FIELD_HDLC_DATA = 0, T38_FIELD_HDLC_SIG_END, T38_FIELD_HDLC_FCS_OK, T38_FIELD_HDLC_FCS_BAD,
  T38_FIELD_HDLC_FCS_OK_SIG_END, T38_FIELD_HDLC_FCS_BAD_SIG_END, T38_FIELD_T4_NON_ECM_DATA, T38_FIELD_T4_NON_ECM_SIG_END,
  T38_FIELD_CM_MESSAGE, T38_FIELD_JM_MESSAGE, T38_FIELD_CI_MESSAGE, T38_FIELD_V34RATE
}
 
enum  t38_field_classes_e { T38_FIELD_CLASS_NONE = 0, T38_FIELD_CLASS_HDLC, T38_FIELD_CLASS_NON_ECM }
 
enum  t38_message_types_e { T38_TYPE_OF_MSG_T30_INDICATOR = 0, T38_TYPE_OF_MSG_T30_DATA }
 
enum  t38_transport_types_e { T38_TRANSPORT_UDPTL = 0, T38_TRANSPORT_RTP, T38_TRANSPORT_TCP, T38_TRANSPORT_TCP_TPKT }
 
enum  t38_data_rate_management_types_e { T38_DATA_RATE_MANAGEMENT_LOCAL_TCF = 1, T38_DATA_RATE_MANAGEMENT_TRANSFERRED_TCF = 2 }
 
enum  t38_packet_categories_e {
  T38_PACKET_CATEGORY_INDICATOR = 0, T38_PACKET_CATEGORY_CONTROL_DATA = 1, T38_PACKET_CATEGORY_CONTROL_DATA_END = 2, T38_PACKET_CATEGORY_IMAGE_DATA = 3,
  T38_PACKET_CATEGORY_IMAGE_DATA_END = 4
}
 
enum  t38_chunking_mode_e {
  T38_CHUNKING_MERGE_FCS_WITH_DATA = 0x0001, T38_CHUNKING_WHOLE_FRAMES = 0x0002, T38_CHUNKING_ALLOW_TEP_TIME = 0x0004, T38_CHUNKING_SEND_REGULAR_INDICATORS = 0x0008,
  T38_CHUNKING_SEND_2S_REGULAR_INDICATORS = 0x0010
}
 

Functions

const char * t38_indicator_to_str (int indicator)
 Convert the code for an indicator to a short text name. More...
 
const char * t38_data_type_to_str (int data_type)
 Convert the code for a type of data to a short text name. More...
 
const char * t38_field_type_to_str (int field_type)
 Convert the code for a type of data field to a short text name. More...
 
const char * t38_cm_profile_to_str (int profile)
 Convert the code for a CM profile code to text description. More...
 
const char * t38_jm_to_str (const uint8_t *data, int len)
 Convert a JM message code to text description. More...
 
int t38_v34rate_to_bps (const uint8_t *data, int len)
 Convert a V34rate message to an actual bit rate. More...
 
int t38_core_send_indicator (t38_core_state_t *s, int indicator)
 Send an indicator packet. More...
 
int t38_core_send_flags_delay (t38_core_state_t *s, int indicator)
 Find the delay to allow for HDLC flags after sending an indicator. More...
 
int t38_core_send_training_delay (t38_core_state_t *s, int indicator)
 Find the delay to allow for modem training after sending an indicator. More...
 
int t38_core_send_data (t38_core_state_t *s, int data_type, int field_type, const uint8_t field[], int field_len, int category)
 Send a data packet. More...
 
int t38_core_send_data_multi_field (t38_core_state_t *s, int data_type, const t38_data_field_t field[], int fields, int category)
 Send a data packet. More...
 
int t38_core_rx_ifp_packet (t38_core_state_t *s, const uint8_t *buf, int len, uint16_t seq_no)
 Process a received T.38 IFP packet from an unreliable packet stream (e.g. UDPTL or RTP). This processing includes packet sequence number checking, missing packet recovery, and skipping repeat packets. More...
 
int t38_core_rx_ifp_stream (t38_core_state_t *s, const uint8_t *buf, int len, uint16_t log_seq_no)
 Process a received T.38 IFP packet from a reliable stream (e.g. TCP). More...
 
void t38_set_data_rate_management_method (t38_core_state_t *s, int method)
 
void t38_set_data_transport_protocol (t38_core_state_t *s, int data_transport_protocol)
 
void t38_set_fill_bit_removal (t38_core_state_t *s, bool fill_bit_removal)
 
void t38_set_mmr_transcoding (t38_core_state_t *s, bool mmr_transcoding)
 
void t38_set_jbig_transcoding (t38_core_state_t *s, bool jbig_transcoding)
 
void t38_set_max_buffer_size (t38_core_state_t *s, int max_buffer_size)
 
void t38_set_max_datagram_size (t38_core_state_t *s, int max_datagram_size)
 
void t38_set_redundancy_control (t38_core_state_t *s, int category, int setting)
 Send a data packet. More...
 
void t38_set_pace_transmission (t38_core_state_t *s, int pace_transmission)
 
void t38_set_fastest_image_data_rate (t38_core_state_t *s, int max_rate)
 
int t38_get_fastest_image_data_rate (t38_core_state_t *s)
 
void t38_set_t38_version (t38_core_state_t *s, int t38_version)
 
void t38_set_sequence_number_handling (t38_core_state_t *s, bool check)
 
void t38_set_tep_handling (t38_core_state_t *s, bool allow_for_tep)
 
void t38_set_tx_packet_interval (t38_core_state_t *s, int microseconds)
 
int t38_get_tx_packet_interval (t38_core_state_t *s)
 
logging_state_tt38_core_get_logging_state (t38_core_state_t *s)
 Get a pointer to the logging context associated with a T.38 context. More...
 
int t38_core_restart (t38_core_state_t *s)
 Restart a T.38 core context. More...
 
t38_core_state_tt38_core_init (t38_core_state_t *s, t38_rx_indicator_handler_t rx_indicator_handler, t38_rx_data_handler_t rx_data_handler, t38_rx_missing_handler_t rx_missing_handler, void *rx_user_data, t38_tx_packet_handler_t tx_packet_handler, void *tx_packet_user_data)
 Initialise a T.38 core context. More...
 
int t38_core_release (t38_core_state_t *s)
 Release a signaling tone transmitter context. More...
 
int t38_core_free (t38_core_state_t *s)
 Free a signaling tone transmitter context. More...
 

Typedef Documentation

◆ t30_indicator_types_t

T.38 indicator types

◆ t38_core_state_t

Core T.38 state, common to all modes of T.38.

◆ t38_data_rate_management_types_t

◆ t38_data_types_t

T.38 data types

◆ t38_field_classes_t

T.38 field classes

◆ t38_field_types_t

T.38 data field types

◆ t38_message_types_t

T.38 message types

◆ t38_packet_categories_t

T.38 Packet categories used for setting the redundancy level and packet repeat counts on a packet by packet basis.

◆ t38_transport_types_t

T.38 transport types

Enumeration Type Documentation

◆ t30_indicator_types_e

T.38 indicator types

◆ t38_chunking_mode_e

Enumerator
T38_CHUNKING_MERGE_FCS_WITH_DATA 

The FCS at the end of an HDLC block can be send with the last chunk of the packet, or as a separate packet.

T38_CHUNKING_WHOLE_FRAMES 

Send whole HDLC frames, rather than break them into mant packets for smooth analogue playout.

T38_CHUNKING_ALLOW_TEP_TIME 

Allow for the time TEP takes when playing out the data.

T38_CHUNKING_SEND_REGULAR_INDICATORS 

Send regular indicators when idle, rather than a single shot as the idle period begins.

T38_CHUNKING_SEND_2S_REGULAR_INDICATORS 

Send an indicator every 2s when idle.

◆ t38_data_rate_management_types_e

T.38 TCF management types

◆ t38_data_types_e

T.38 data types

◆ t38_field_classes_e

T.38 field classes

◆ t38_field_types_e

T.38 data field types

◆ t38_message_types_e

T.38 message types

◆ t38_packet_categories_e

T.38 Packet categories used for setting the redundancy level and packet repeat counts on a packet by packet basis.

Enumerator
T38_PACKET_CATEGORY_INDICATOR 

Indicator packet.

T38_PACKET_CATEGORY_CONTROL_DATA 

Control data packet.

T38_PACKET_CATEGORY_CONTROL_DATA_END 

Terminating control data packet.

T38_PACKET_CATEGORY_IMAGE_DATA 

Image data packet.

T38_PACKET_CATEGORY_IMAGE_DATA_END 

Terminating image data packet.

◆ t38_transport_types_e

T.38 transport types

Function Documentation

◆ t38_cm_profile_to_str()

const char* t38_cm_profile_to_str ( int  profile)

Convert the code for a CM profile code to text description.

Parameters
profileThe profile code from a CM message.
Returns
A pointer to a short text description of the profile.

◆ t38_core_free()

int t38_core_free ( t38_core_state_t s)

Free a signaling tone transmitter context.

Free a signaling tone transmitter context.

Parameters
sThe T.38 context.
Returns
0 for OK

◆ t38_core_get_logging_state()

logging_state_t* t38_core_get_logging_state ( t38_core_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_core_state_s::logging.

◆ t38_core_init()

t38_core_state_t* t38_core_init ( t38_core_state_t s,
t38_rx_indicator_handler_t  rx_indicator_handler,
t38_rx_data_handler_t  rx_data_handler,
t38_rx_missing_handler_t  rx_missing_handler,
void *  rx_user_data,
t38_tx_packet_handler_t  tx_packet_handler,
void *  tx_packet_user_data 
)

Initialise a T.38 core context.

Initialise a T.38 core context.

Parameters
sThe T.38 context.
rx_indicator_handlerReceive indicator handling routine.
rx_data_handlerReceive data packet handling routine.
rx_rx_missing_handlerMissing receive packet handling routine.
rx_packet_user_dataAn opaque pointer passed to the rx packet handling routines.
tx_packet_handlerPacket transmit handling routine.
tx_packet_user_dataAn opaque pointer passed to the tx_packet_handler.
Returns
A pointer to the T.38 context, or NULL if there was a problem.

◆ t38_core_release()

int t38_core_release ( t38_core_state_t s)

Release a signaling tone transmitter context.

Release a signaling tone transmitter context.

Parameters
sThe T.38 context.
Returns
0 for OK

◆ t38_core_restart()

int t38_core_restart ( t38_core_state_t s)

Restart a T.38 core context.

Restart a T.38 core context.

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

References t38_core_state_s::current_rx_data_type, t38_core_state_s::current_rx_field_type, t38_core_state_s::current_rx_indicator, t38_core_state_s::current_tx_indicator, and t38_core_state_s::rx_expected_seq_no.

◆ t38_core_rx_ifp_packet()

int t38_core_rx_ifp_packet ( t38_core_state_t s,
const uint8_t *  buf,
int  len,
uint16_t  seq_no 
)

Process a received T.38 IFP packet from an unreliable packet stream (e.g. UDPTL or RTP). This processing includes packet sequence number checking, missing packet recovery, and skipping repeat packets.

Parameters
sThe T.38 context.
bufThe packet contents.
lenThe length of the packet contents.
seq_noThe packet sequence number.
Returns
0 for OK, else -1.

◆ t38_core_rx_ifp_stream()

int t38_core_rx_ifp_stream ( t38_core_state_t s,
const uint8_t *  buf,
int  len,
uint16_t  log_seq_no 
)

Process a received T.38 IFP packet from a reliable stream (e.g. TCP).

Parameters
sThe T.38 context.
bufThe packet contents.
lenThe length of the packet contents.
seq_noThe packet sequence number, used for logging purposes.
Returns
The length of the packet processed, or -1 if there is an error in the packet, or too few bytes of data to complete it.

◆ t38_core_send_data()

int t38_core_send_data ( t38_core_state_t s,
int  data_type,
int  field_type,
const uint8_t  field[],
int  field_len,
int  category 
)

Send a data packet.

Parameters
sThe T.38 context.
data_typeThe packet's data type.
field_typeThe packet's field type.
fieldThe message data content for the packet.
field_lenThe length of the message data, in bytes.
categoryThe category of the packet being sent. This should be one of the values defined for t38_packet_categories_e.
Returns
0 for OK, else -1

◆ t38_core_send_data_multi_field()

int t38_core_send_data_multi_field ( t38_core_state_t s,
int  data_type,
const t38_data_field_t  field[],
int  fields,
int  category 
)

Send a data packet.

Parameters
sThe T.38 context.
data_typeThe packet's data type.
fieldThe list of fields.
fieldsThe number of fields in the list.
categoryThe category of the packet being sent. This should be one of the values defined for t38_packet_categories_e.
Returns
0 for OK, else -1

◆ t38_core_send_flags_delay()

int t38_core_send_flags_delay ( t38_core_state_t s,
int  indicator 
)

Find the delay to allow for HDLC flags after sending an indicator.

Parameters
sThe T.38 context.
indicatorThe indicator to check.
Returns
The delay to allow for initial HDLC flags after this indicator is sent.

References t38_core_state_s::pace_transmission.

◆ t38_core_send_indicator()

int t38_core_send_indicator ( t38_core_state_t s,
int  indicator 
)

Send an indicator packet.

Parameters
sThe T.38 context.
indicatorThe indicator to send.
Returns
The delay to allow after this indicator is sent.

◆ t38_core_send_training_delay()

int t38_core_send_training_delay ( t38_core_state_t s,
int  indicator 
)

Find the delay to allow for modem training after sending an indicator.

Parameters
sThe T.38 context.
indicatorThe indicator to check.
Returns
The delay to allow for modem training after this indicator is sent.

References t38_core_state_s::pace_transmission.

◆ t38_data_type_to_str()

const char* t38_data_type_to_str ( int  data_type)

Convert the code for a type of data to a short text name.

Parameters
data_typeThe data type.
Returns
A pointer to a short text name for the data type.

◆ t38_field_type_to_str()

const char* t38_field_type_to_str ( int  field_type)

Convert the code for a type of data field to a short text name.

Parameters
field_typeThe field type.
Returns
A pointer to a short text name for the field type.

◆ t38_get_tx_packet_interval()

int t38_get_tx_packet_interval ( t38_core_state_t s)

Get the time between packet transmissions.

Parameters
sThe T.38 context.

References t38_core_state_s::microseconds_per_tx_chunk.

◆ t38_indicator_to_str()

const char* t38_indicator_to_str ( int  indicator)

Convert the code for an indicator to a short text name.

Parameters
indicatorThe type of indicator.
Returns
A pointer to a short text name for the indicator.

◆ t38_jm_to_str()

const char* t38_jm_to_str ( const uint8_t *  data,
int  len 
)

Convert a JM message code to text description.

Parameters
dataThe data field of the message.
lenThe length of the data field.
Returns
A pointer to a short text description of the profile.

◆ t38_set_data_rate_management_method()

void t38_set_data_rate_management_method ( t38_core_state_t s,
int  method 
)

Set the method to be used for data rate management, as per the T.38 spec.

Parameters
sThe T.38 context.
method1 for pass TCF across the T.38 link, 2 for handle TCF locally.

References t38_core_state_s::data_rate_management_method.

◆ t38_set_data_transport_protocol()

void t38_set_data_transport_protocol ( t38_core_state_t s,
int  data_transport_protocol 
)

Set the data transport protocol.

Parameters
sThe T.38 context.
data_transport_protocolUDPTL, RTP or TPKT.

References t38_core_state_s::data_transport_protocol.

◆ t38_set_fill_bit_removal()

void t38_set_fill_bit_removal ( t38_core_state_t s,
bool  fill_bit_removal 
)

Set the non-ECM fill bit removal mode.

Parameters
sThe T.38 context.
fill_bit_removalTrue to remove fill bits across the T.38 link.

References t38_core_state_s::fill_bit_removal.

◆ t38_set_jbig_transcoding()

void t38_set_jbig_transcoding ( t38_core_state_t s,
bool  jbig_transcoding 
)

Set the JBIG transcoding mode.

Parameters
sThe T.38 context.
jbig_transcodingTrue to transcode to JBIG across the T.38 link.

References t38_core_state_s::jbig_transcoding.

◆ t38_set_max_buffer_size()

void t38_set_max_buffer_size ( t38_core_state_t s,
int  max_buffer_size 
)

Set the maximum buffer size for received data at the far end.

Parameters
sThe T.38 context.
max_buffer_sizeThe maximum buffer size.

References t38_core_state_s::max_buffer_size.

◆ t38_set_max_datagram_size()

void t38_set_max_datagram_size ( t38_core_state_t s,
int  max_datagram_size 
)

Set the maximum size of an IFP packet that is acceptable by the far end.

Parameters
sThe T.38 context.
max_datagram_sizeThe maximum IFP packet length, in bytes.

References t38_core_state_s::max_datagram_size.

◆ t38_set_mmr_transcoding()

void t38_set_mmr_transcoding ( t38_core_state_t s,
bool  mmr_transcoding 
)

Set the MMR transcoding mode.

Parameters
sThe T.38 context.
mmr_transcodingTrue to transcode to MMR across the T.38 link.

References t38_core_state_s::mmr_transcoding.

◆ t38_set_redundancy_control()

void t38_set_redundancy_control ( t38_core_state_t s,
int  category,
int  setting 
)

Send a data packet.

Parameters
sThe T.38 context.
categoryThe category of the packet being sent. This should be one of the values defined for t38_packet_categories_e.
settingThe repeat count for the category. This should be at least one for all categories other an indicator packets. Zero is valid for indicator packets, as it suppresses the sending of indicator packets, as an application using TCP for the transport would require. As the setting is passed through to the transmission channel, additional information may be encoded in it, such as the redundancy depth for the particular packet category.

References t38_core_state_s::category_control.

Referenced by t31_set_t38_config().

◆ t38_set_sequence_number_handling()

void t38_set_sequence_number_handling ( t38_core_state_t s,
bool  check 
)

Set the sequence number handling option.

Parameters
sThe T.38 context.
checkTrue to check sequence numbers, and handle gaps reasonably. False for no sequence number processing (e.g. for TPKT over TCP transport).

References t38_core_state_s::check_sequence_numbers.

◆ t38_set_t38_version()

void t38_set_t38_version ( t38_core_state_t s,
int  t38_version 
)

Set the T.38 version to be emulated.

Parameters
sThe T.38 context.
t38_versionVersion number, as in the T.38 spec.

◆ t38_set_tep_handling()

void t38_set_tep_handling ( t38_core_state_t s,
bool  allow_for_tep 
)

Set the TEP handling option.

Parameters
sThe T.38 context.
allow_for_tepTrue to allow for TEP playout.

References t38_core_state_s::allow_for_tep.

Referenced by t38_terminal_set_tep_mode().

◆ t38_set_tx_packet_interval()

void t38_set_tx_packet_interval ( t38_core_state_t s,
int  microseconds 
)

Set the time between packet transmissions.

Parameters
sThe T.38 context.
microsecondsThe time between packets in microseconds.

References t38_core_state_s::microseconds_per_tx_chunk.

Referenced by t31_set_t38_config().

◆ t38_v34rate_to_bps()

int t38_v34rate_to_bps ( const uint8_t *  data,
int  len 
)

Convert a V34rate message to an actual bit rate.

Parameters
dataThe data field of the message.
lenThe length of the data field.
Returns
The bit rate, or -1 for a bad message.