# T38UDP endpoint filter

Provide entry and exit points for duplex T.38 fax data carried in UDP packets. For more information about T38UDP endpoint filter endpoint filter parameters, refer to T38UDP endpoint filter endpoint address structure and T38UDP endpoint filter endpoint parameter structure.

Note: T38UDP endpoints do not currently support IPv6.

#### Filter ID

MSP_ENDPOINT_T38FDX

#### Initialization structure

T38UDP_ENDPOINT_PARMS

#### Restrictions

Used in T.38 fax full duplex connections.

#### Channel connections

Connect to T.38 fax full duplex channels.

#### Commands

T38UDP endpoints respond to the following commands:

Command ID | Description
MSP_CMD_T38UDPTLENC_CONFIG | Configures parameters associated with the endpoint's UDPTL encoder functions.
MSP_CMD_T38UDPTLDEC_CONFIG | Configures parameters associated with the endpoint's UDPTL decoder functions.
MSP_CMD_T38IFPENC_CONFIG | Configures parameters associated with the endpoint's IFP encoder functions.
MSP_CMD_T38IFPDEC_CONFIG | Configures parameters associated with the endpoint's IFP decoder functions.
MSP_CMD_T38UDP_CONFIG | Sets IP parameters in addition to all of the above parameters for the T38UDP endpoint. Note: T38UDP endpoints must be in a disabled state when receiving MSP_CMD_T38UDP_CONFIG commands.

With the exception of the MSP_CMD_T38UDP_CONFIG command (see above), T38UDP endpoints can receive filter commands any time after they are created.

When sending MSP_CMD_T38UDP_CONFIG commands, applications provide a pointer to an msp_ENDPOINT_T38UDP_CONFIG structure. This structure contains all the parameters used to configure the T38UDP endpoint when the application
created it.

When using the MSP_CMD_T38UDP_CONFIG command, applications can specify a value of 0xFFFF for 16-bit parameters or 0xFFFFFFFF for 32-bit parameters (or -1 in decimal format) to retain the existing settings for any endpoint parameters. Otherwise, the endpoint expects a new value for every parameter in the structure. For more information about T38UDP endpoint parameters, refer to the Overview of endpoint structures or to the mspinit.h header file.

For a list of command IDs and their associated structures, refer to the mspcmd.h header file.

#### Queries

T38UDP full duplex endpoint filters respond to the following query any time after the endpoint is created:

Query ID | Description
MSP_QRY_T38UDP_STATUS | Returns information about the UDP endpoint filter state in an msp_ENDPOINT_T38UDP_STATUS structure.

Sending an MSP_QRY_T38UDP_STATUS query returns the following structure:

typedef struct tag_msp_ENDPOINT_T38UDP_STATUS {
//T38 UDP Data
DWORD FilterId;
DWORD ipFilterState;
IPADDRESS localIPAddr;
DWORD localPort;
IPADDRESS remoteIPAddr;
DWORD remotePort;
//T38 UDP Stats
DWORD rxDrop;
DWORD rxPkts;
DWORD rxBytes;
DWORD txDrop;
DWORD txFail;
DWORD txPkts;
DWORD txBytes;
//T38 IFP Encoder Data
DWORD v21_bytes_per_ifp_packet;
DWORD page_modem_ifp_duration;
DWORD t30_indicator_send_count;
DWORD t30_indicator_send_period;
//T38 UDPTL Encoder Data
DWORD error_protection_scheme;
DWORD redundant_ifp_packets;
DWORD ifp_pkts_per_fec_message;
DWORD fec_messages_per_udptl_pkt;
DWORD num_duplicate_indicator_udptl_packets;
DWORD num_duplicate_v21_udptl_packets;
DWORD num_duplicate_page_modem_udptl_packets;
//T38 IFP Decoder Data
DWORD queue_size;
DWORD buffering_time;
DWORD page_data_keep_alive_time;
//T38 UDPTL Decoder Data
DWORD enable_error_recovery;
} msp_ENDPOINT_T38UDP_STATUS;

Note: FEC is not supported.

The msp_ENDPOINT_T38UDP_STATUS query structure provides the following information:

Field | Description
FilterId | Reserved.
ipFilterState | Indicates the current state of the filter and the socket state with the CG board IP stack: Created (0x00) The filter has been created. Configured (0x01) The filter has been configured with its IP parameters. Starting (0x02) The filter has been enabled and is in the process of opening a socket with the CG board IP stack. Active (0x03) The filter has an open socket and is processing data. Stopping (0x04) The filter has been disabled and is in the process of closing its socket with the CG board IP stack. Stop/Destroy (0x05) The filter has received a destroy indication, and it is currently in the process of closing its socket with the CG board IP stack prior to destroying itself. Destroying (0x06) The filter is cleaning up all on board resources prior to destroying itself.
localIPAddr | Address of the Ethernet interface where this transmission is running.
localPort | Local UDP port number for this transmission.
remoteIPAddr | IP address of the destination for this transmission.
remotePort | UDP port number used at the destination RTP session.
rxDrop | Number of packets dropped by the filter when not in an active state.
rxPkts | Number of valid packets received by this filter.
rxBytes | Number of bytes received by this filter. Includes header bytes as well as data bytes.
txDrop | Number of packets that filter is not able to send out through the IP interface due to internal error conditions.
txFail | Number of socket send errors that occurred.
txPkts | Number of packets delivered to the socket layer of the CG board's IP stack.
txBytes | Number of bytes delivered to the socket layer of the CG board's IP stack.
v21_bytes_per_ifp_packet | Number of V.21 bytes per T.38 IFP packet (default is 1 byte).
page_modem_ifp_duration | Page data time-content in an IFP packet. Time is specified in milliseconds, and is in multiples of 10 (for example, 10, 30 or 60 ms).
t30_indicator_send_count | Maximum number of T.38 indicator packets to transmit to the network.
t30_indicator_send_period | Determines intervals between T.38 indicators transmission to the network. Time is specified in milliseconds, and quantified in multiples of 10 (for example, 10, 90, or 210 ms.).
error_protection_scheme | Type of error protection used by the T.38 fax UDPTL encoder filter. This may be T38UDPTL_EPS_REDUNDANCY.
num_duplicate_v21_udptl_packets | Number of duplicate V.21 UDPTL packets to transmit.
num_duplicate_indicator_udptl_packets | Number of duplicate indicator UDPTL packets to transmit.
num_duplicate_page_modem_udptl_packets | Number of duplicate page modem UDPTL packets to transmit.
redundant_ifp_packets | Number of redundant IFP packets.
queue_size | Size (in number of IFP packets) of the reorder queue used for incoming packet storing, reordering, and error recovering.
buffering_time | Buffering time elapsing before sending data to a T.38 fax modulator/demodulator filter, in order to pre-fill the reordering queue. Time is specified in milliseconds and quantified in multiples of 10 (for example, 30, 90 or 210).
page_data_keep_alive_time | Sets the amount of time to keep a fax session, in the page transmission phase of a fax call, alive in the absence of data from the packet network (that is, absence of data in the IFP reorder queue). The T.4 specification allows the sending of null lines, which alerts the remote fax machine to pause printing until further notice. Note: If this parameter is set to a low value or to zero, packet loss in the network may cause the fax session to terminate since the remodulator will drop the carrier when it has no more data to send to the remote fax machine.
enable_error_recovery | Indicates whether the endpoint UDPTL decoder is recovering missing IFPs. 0x0001= enabled 0x0000 = disabled

#### Unsolicited event

When enabled, T38UDP endpoints return the following unsolicited event:

Event | Description
MSPEVN_T38_PACKET_DETECTED | Indicates that the endpoint has received a valid T.38 fax packet.

For information about using T38UPD endpoint unsolicited events to implement voice/T.38 fax switchover, refer to the Dialogic® NaturalAccess™Fusion VoIP API Developer's Manual.

#### Receiving T38 packets from the IP network

When the T38UDP endpoint receives T.38 packets from the packet network interface, it decodes them into primary IFP packets and, if applicable, error recovery information. This process is called T.38 UDPTL decoding. When enabled, T38UDP endpoints generate a MSPEVN_T38_PACKET_DETECTED event the first time that they receive a valid UDPTL packet. This event signals the application to switch over from voice to fax data transmission. When T.38 fax endpoints are disabled and re-enabled, they once again detect the arrival of the first fax packet and return an MSPEVN_T38_PACKET_DETECTED event.

The T38UDP endpoint's IFP decoder receives asynchronous input (IFP packets) from the endpoints UDPTL decoder. The T38UDP endpoint converts data from an asynchronous flow to a synchronous flow before it transfers the data to a T.38 fax full duplex channel. The endpoint reorders the IFP packets during the queuing process and, depending on the error recovery scheme used and the network conditions, lost IFP packets can be recovered from subsequent UDPTL packets.

To prevent underflows in the IFP decoding queue resulting from network jitter, the MSPP service uses a buffering mechanism (controlled by the buffering_time parameter) to pre-fill the queue prior to sending data to the T.38 full duplex channel. This buffering mechanism is similar to the jitter mechanism used by the MSPP voice channel jitter filter.

During unfavorable network conditions, the T38UDP endpoint's efficiency in recovering and reordering IFP packets increases as the number of packets kept in the IFP decoder reorder queue increases. Applications can increase the number of IFP packets in the queue by using the MSP_CMD_T38IFPDEC_CONFIG filter command to increase the value of the buffering_time parameter.

Note: Fax sessions are relatively immune to the delay introduced by IFP decoder buffering mechanism (unlike voice connections where users notice degraded performance when the delay exceeds 200 ms). However, the timing requirements of the T.30 protocol make it nearly impossible to maintain a fax transmission when the one-way delay (roughly, the sum of network delay + buffering time) exceeds 1500 ms.

The actual size of the IFP decoder reorder queue (specified by the queue_size parameter) must be set in accordance with the buffering time. The longer the buffering time, the larger the number of IFP packets that need to be stored in the reorder queue. The queue size should also be large enough to prevent (or limit) the number of overflows during network bursts.

If the IFP decoder queue runs empty during the course of a page transmission (for example, due to bad network conditions), that application can keep the modem signal alive by setting (either through the endpoint's initialization parameters, or through the MSP_CMD_T38IFPDEC_CONFIG filter command) an appropriate page_data_keep_alive_time parameter value. Setting this parameter to a non-zero value specifies that the T.38 fax IFP decoder filter keeps the modem signal alive for a specified (in ms.) duration. This parameter can be particularly useful for networks that frequently experience congestion. This feature only works for non-ECM fax sessions.

#### Receiving fax data from MSPP T.38 Full Duplex channels

In T.38 fax sessions, fax data and session progress indicators are conveyed through IFP packets. Gateways indicate when they detect signals such as CED, HDLC preamble flags, and modem modulation training by sending T30 indicators. T.38 fax emitting gateways send T30 indicators to receiving gateways and vice versa.

When a T38UDP endpoint receives demodulated data from a T.38 fax full duplex channel, the endpoint analyzes the data and assembles the appropriate IFP packet components depending on the nature of the signal (whether it contains session progress indicators or fax data).

Note: Since V.21 is a low bit rate modem, Dialogic recommends setting the v21_bytes_per_ifp_packet parameter to a low value. For example, a single IFP packet that contains two V.21 bytes, provides a packet period of approximately 2 x 26.6 = 53.3 ms. with the minimum amount of HDLC bit stuffing (2 x 32 = 64 ms. with the maximum amount of HDLC bit stuffing).

For all other modulations (ECM or non-ECM), the size of the page modem data IFP is determined by the page_modem_frames_per_ifp_packet parameter value.

Any parameters that the application sets for the IFP encoder process (either during endpoint initialization or through the MSP_CMD_T38IFPENC_CONFIG endpoint command) will effect the rate at which the T.38 fax gateway sends IFP packets over the IP network.

Before sending T.38 data to the IP network, the T38UDP endpoint encodes T.38 UDPTL packets by adding a primary IFP packet, and optionally adding any error recovery information.

The application specifies the type of T.38 error recovery information the T.38 fax UDPTL encoder filter adds to each T.38 packet by either specifying an appropriate error_protection_scheme parameter the endpoint's initialization parameters, or sending an MSP_CMD_T38UDPTLENC_CONFIG filter command.

To make a T.38 system more tolerant to packet loss, applications can use the UDP packet duplication (this feature is outside the scope of the ITU-T T.38 specification) in conjunction with a T.38 error recovery scheme. However, packet duplication can reduce the throughput of the system by increasing the packet processing load.

UDP packet duplication can be set individually for the following types of primary T.38 IFP packets:

- V21 IFP packets

- Page modem IFP packets

- Indicators

The following illustration shows a T38UDP endpoint:

#### See also

T.38 fax relay channel filter, Jitter channel filter, Voice decoder channel filter, Voice encoder channel filter