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 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 }

## Functions

const char * | t38_indicator_to_str (int indicator)
| Convert the code for an indicator to a short text name.
const char * | t38_data_type_to_str (int data_type)
| Convert the code for a type of data to a short text name.
const char * | t38_field_type_to_str (int field_type)
| Convert the code for a type of data field to a short text name.
const char * | t38_cm_profile_to_str (int profile)
| Convert the code for a CM profile code to text description.
const char * | t38_jm_to_str (const uint8_t *data, int len)
| Convert a JM message code to text description.
int | t38_v34rate_to_bps (const uint8_t *data, int len)
| Convert a V34rate message to an actual bit rate.
int | t38_core_send_indicator (t38_core_state_t *s, int indicator)
| Send an indicator packet.
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.
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.
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.
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.
| SPAN_DECLARE_NONSTD (int) t38_core_rx_ifp_packet(t38_core_state_t *s
| 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.
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, int fill_bit_removal)
void | t38_set_mmr_transcoding (t38_core_state_t *s, int mmr_transcoding)
void | t38_set_jbig_transcoding (t38_core_state_t *s, int 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.
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, int check)
void | t38_set_tep_handling (t38_core_state_t *s, int allow_for_tep)
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.
int | t38_core_restart (t38_core_state_t *s)
| Restart a T.38 core context.
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.
int | t38_core_release (t38_core_state_t *s)
| Release a signaling tone transmitter context.
int | t38_core_free (t38_core_state_t *s)
| Free a signaling tone transmitter context.

## Variables

const uint8_t * | buf
const uint8_t int | len
const uint8_t int uint16_t | seq_no
const uint8_t int uint16_t | log_seq_no

## Typedef Documentation

## t38_core_state_t

typedef struct t38_core_state_s t38_core_state_t

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

## Enumeration Type Documentation

## t30_indicator_types_e

enum t30_indicator_types_e

T.38 indicator types

## t38_data_rate_management_types_e

enum t38_data_rate_management_types_e

T.38 TCF management types

## t38_data_types_e

enum t38_data_types_e

T.38 data types

## t38_field_classes_e

enum t38_field_classes_e

T.38 field classes

## t38_field_types_e

enum t38_field_types_e

T.38 data field types

## t38_message_types_e

enum t38_message_types_e

T.38 message types

## t38_packet_categories_e

enum 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

enum t38_transport_types_e

T.38 transport types

## Function Documentation

## SPAN_DECLARE_NONSTD()

SPAN_DECLARE_NONSTD | ( | int |  | ) |

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.

Get the next bit of data from a T.38 rate adapting non-ECM buffer context.

Get a bit of received non-ECM image data.

Get the next bit of a transmitted serial bit stream.

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

Parameters

  s | The T.38 context.
  buf | The packet contents.
  len | The length of the packet contents.
  seq_no | The packet sequence number.

Returns
  0 for OK, else -1.

Parameters

  s | The T.38 context.
  buf | The packet contents.
  len | The length of the packet contents.
  seq_no | The 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_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

  profile | The 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

  s | The 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

  s | The 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

  s | The T.38 context.
  rx_indicator_handler | Receive indicator handling routine.
  rx_data_handler | Receive data packet handling routine.
  rx_rx_missing_handler | Missing receive packet handling routine.
  rx_packet_user_data | An opaque pointer passed to the rx packet handling routines.
  tx_packet_handler | Packet transmit handling routine.
  tx_packet_user_data | An opaque pointer passed to the tx_packet_handler.

Returns
  A pointer to the T.38 context, or NULL if there was a problem.

References t38_core_state_s::category_control, t38_core_state_s::check_sequence_numbers, t38_core_state_s::data_rate_management_method, t38_core_state_s::data_transport_protocol, t38_core_state_s::fill_bit_removal, t38_core_state_s::jbig_transcoding, t38_core_state_s::logging, t38_core_state_s::max_buffer_size, t38_core_state_s::max_datagram_size, t38_core_state_s::mmr_transcoding, t38_core_state_s::pace_transmission, t38_core_state_s::rx_data_handler, t38_core_state_s::rx_indicator_handler, t38_core_state_s::rx_missing_handler, t38_core_state_s::rx_user_data, t38_core_restart(), T38_PACKET_CATEGORY_CONTROL_DATA, T38_PACKET_CATEGORY_CONTROL_DATA_END, T38_PACKET_CATEGORY_IMAGE_DATA, T38_PACKET_CATEGORY_IMAGE_DATA_END, T38_PACKET_CATEGORY_INDICATOR, t38_core_state_s::t38_version, t38_core_state_s::tx_packet_handler, and t38_core_state_s::tx_packet_user_data.

## 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

  s | The 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

  s | The 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.

Referenced by t38_core_init().

## 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

  s | The T.38 context.
  data_type | The packet's data type.
  field_type | The packet's field type.
  field | The message data content for the packet.
  field_len | The length of the message data, in bytes.
  category | The 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

References t38_core_state_s::category_control, t38_data_field_t::field, t38_data_field_t::field_len, t38_data_field_t::field_type, t38_core_state_s::logging, span_log(), t38_core_state_s::tx_packet_handler, t38_core_state_s::tx_packet_user_data, and t38_core_state_s::tx_seq_no.

## 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

  s | The T.38 context.
  data_type | The packet's data type.
  field | The list of fields.
  fields | The number of fields in the list.
  category | The 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

References t38_core_state_s::category_control, t38_core_state_s::logging, span_log(), t38_core_state_s::tx_packet_handler, t38_core_state_s::tx_packet_user_data, and t38_core_state_s::tx_seq_no.

## 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

  s | The T.38 context.
  indicator | The 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

  s | The T.38 context.
  indicator | The indicator to send.

Returns
  The delay to allow after this indicator is sent.

References t38_core_state_s::allow_for_tep, t38_core_state_s::category_control, t38_core_state_s::current_tx_indicator, t38_core_state_s::logging, t38_core_state_s::pace_transmission, span_log(), t38_indicator_to_str(), T38_PACKET_CATEGORY_INDICATOR, t38_core_state_s::tx_packet_handler, t38_core_state_s::tx_packet_user_data, and t38_core_state_s::tx_seq_no.

## 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

  s | The T.38 context.
  indicator | The 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_type | The 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_type | The field type.

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

## t38_indicator_to_str()

const char * t38_indicator_to_str | ( | int | indicator | ) |

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

Parameters

  indicator | The type of indicator.

Returns
  A pointer to a short text name for the indicator.

Referenced by t38_core_send_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

  data | The data field of the message.
  len | The 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

  s | The T.38 context.
  method | 1 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

  s | The T.38 context.
  data_transport_protocol | UDPTL, 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,
|  | int | fill_bit_removal )

Set the non-ECM fill bit removal mode.

Parameters

  s | The T.38 context.
  fill_bit_removal | TRUE to remove fill bits across the T.38 link, else FALSE.

References t38_core_state_s::fill_bit_removal.

## t38_set_jbig_transcoding()

void t38_set_jbig_transcoding | ( | t38_core_state_t * | s,
|  | int | jbig_transcoding )

Set the JBIG transcoding mode.

Parameters

  s | The T.38 context.
  jbig_transcoding | TRUE to transcode to JBIG across the T.38 link, else FALSE.

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

  s | The T.38 context.
  max_buffer_size | The 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

  s | The T.38 context.
  max_datagram_size | The 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,
|  | int | mmr_transcoding )

Set the MMR transcoding mode.

Parameters

  s | The T.38 context.
  mmr_transcoding | TRUE to transcode to MMR across the T.38 link, else FALSE.

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

  s | The T.38 context.
  category | The category of the packet being sent. This should be one of the values defined for t38_packet_categories_e.

  setting

  The 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(), and t38_terminal_set_config().

## t38_set_sequence_number_handling()

void t38_set_sequence_number_handling | ( | t38_core_state_t * | s,
|  | int | check )

Set the sequence number handling option.

Parameters

  s | The T.38 context.
  check | TRUE 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

  s | The T.38 context.
  t38_version | Version number, as in the T.38 spec.

References t38_core_state_s::t38_version.

## t38_set_tep_handling()

void t38_set_tep_handling | ( | t38_core_state_t * | s,
|  | int | allow_for_tep )

Set the TEP handling option.

Parameters

  s | The T.38 context.
  allow_for_tep | TRUE to allow for TEP playout, else FALSE.

References t38_core_state_s::allow_for_tep.

Referenced by t38_terminal_set_tep_mode().

## 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

  data | The data field of the message.
  len | The length of the data field.

Returns
  The bit rate, or -1 for a bad message.