# T.38 fax relay channel filter

Demodulates the analog signal coming from the PSTN line and delivers the data to a T38UDP endpoint. This filter also remodulates the appropriate analog signal to be sent to the PSTN based on the information received from a T38UDP endpoint.

#### Filter ID

MSP_FILTER_FAX_RELAY

#### Initialization structure

MSP_FAX_CHANNEL_PARMS

#### Restrictions

Used in T.38 fax full duplex channels.

#### Filter connections

T.38 fax relay filters connect to DS0 endpoints on the PSTN side of the gateway and T38UDP full duplex endpoints on the IP side of the gateway.

#### Commands

A T.38 fax relay filter responds to the following command when the associated channel is enabled:

Command ID | Description
MSP_CMD_FAXRELAY_CONFIG | Configures the T.38 fax relay filter.

T.38 fax relay filters must be enabled before receiving commands.

When sending the msp_CMD_FAXRELAY_CONFIG command to a T.38 fax relay filter, include a pointer to the msp_FILTER_FAXRELAY_CONFIG structure. Specify the following parameters for this structure:

Parameter | Description
modemask | Assigns a configuration mask. The following constants are defined for this parameter: FAXRELAY_MODEMASK_DEFAULT (ECM and NSF enabled) FAXRELAY_MODEMASK_DISABLE_NSF_FILTERING FAXRELAY_MODEMASK_DISABLE_ECM FAXRELAY_MODEMASK_ENABLE_NON_STD_T38_ECM
eventmask | Assigns an event mask that determines the types of unsolicited events the filter returns. The following constants are defined for this parameter (these can be combined using the OR operator together): FAXRELAY_EVENTMASK_DEFAULT All enabled. FAXRELAY_EVENTMASK_REPT_FAX_BEGIN_END Report the beginning and ending of a fax session. FAXRELAY_EVENTMASK_REPT_PASSED_PAGE Report successful passing of a fax page.
maxbitrate | Sets the maximum bit rate of the fax transmission in bits/s: FAXRELAY_MAXBITRATE_DEFAULT (14400) FAXRELAY_MAXBITRATE_14400 FAXRELAY_MAXBITRATE_9600 FAXRELAY_MAXBITRATE_4800 FAXRELAY_MAXBITRATE_2400 FAXRELAY_MAXBITRATE_DISABLE_FILTER
timeout | Sets the session timeout value in ms. The following constants are defined for this parameter: FAXRELAY_TIMEOUT_DEFAULT (15000 ms) FAXRELAY_TIMEOUT_MIN (0 ms) FAXRELAY_TIMEOUT_MAX (65000 ms)

When using the MSP_CMD_FAXRELAY_CONFIG command, applications provide a pointer to an MSP_FAX_CHANNEL_PARMS structure. This structure contains all of the parameters used to configure the T.38 fax relay filter when the application created the T.38 fax channel.

When using the MSP_CMD_FAXRELAY_CONFIG command, applications can specify a value of #FFFF for 16-bit parameters or 0xFFFFFFFF for 32-bit parameters (or -1 in decimal format) to retain the existing settings for any T.38 parameter. Otherwise the filter expects a new value for every parameter in the MSP_FAX_CHANNEL_PARMS structure. For more information about fax relay parameters, refer to the mspcmd.h header file.

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

#### Queries

The T.38 fax relay channel filter responds to the following query when the associated channel is enabled:

Query ID | Description
MSP_QRY_FAXRELAY_SESSION_STATUS | Retrieves information about the T.38 relay filter status. This information is returned in a FAXRELAY_SESSION_STATUS structure.

The FAXRELAY_SESSION_STATUS query structure appears as follows:

typedef struct tag_FAXRELAY_SESSION_STATUS{
DWORD timestamp;
WORD bitrate;
WORD ecm;
WORD ecm_errors;
WORD retrain_count;
WORD page_count;
WORD poll_ecm_errors;
WORD poll_retrain_count;
WORD poll_page_count;
WORD page_modem_count;
WORD tcf_count;
FAXRELAY_STS_FLAGS flags;
} FAXRELAY_SESSION_STATUS;

The FAXRELAY_SESSION_STATUS structure provides the following information:

Field | Description
timestamp | Timestamp in milliseconds (10 ms resolution).
bitrate | Last connect rate (2400 - 14400 bits/s).
ecm | Specifies whether fax session used error correction mode.
ecm_errors | If the ecm parameter is set: the number of PPR messages received.
retrain_count | If the ecm parameter is not set: the number of RTN messages received.
page_count | Number of pages passed (emitted or received).
poll_ecm_errors | If the fax session was polled and in ecm mode, the number of PPR messages received in polling mode.
poll_retrain_count | If the fax session was polled and not in ecm mode, the number of RTN messages received in polling mode.
poll_page_count | If the fax session was polled, the number of pages passed (received or emitted).
page_modem_count | Number of times a high speed modem (page modem) was activated (for modulation or demodulation).
tcf_count | Number of times high speed modem (page modem) training was performed (that is, the number of TCFs).
flags | Indicates if certain T.30 messages and other session indicators were ever detected: The following T.30 indicators are monitored: DIS (digital identification signal) DCS (digital command signal) DTC (digital transmit command) NSF (non-Standard facilities) CFR (confirmation received) MCF (message confirmation) RTP (retrain positive) RTN (retrain negative) CRP (command repeat message) DCN (disconnect message) Other session indicators include: FCF ever V.21 frame start V.21 frame end V.21 bytes received HSM ever

#### Unsolicited events

T.38 fax relay filters return unsolicited events depending on the flags set with the eventmask parameter. The filter can return the following unsolicited events:

Unsolicited event | Description
MSPEVN_FAXRELAY_FAX_BEGIN | Returned at the beginning of a fax session. This event's data buffer contains a FAXRELAY_FAX_BEGIN structure.
MSPEVN_FAXRELAY_PASSED_PAGE | Returned whenever a page is successfully transferred by the T.38 fax relay channel filter. The event data buffer contains a pointer to a FAXRELAY_PASSED_PAGE structure.
MSPEVN_FAXRELAY_FAX_END | Returned at the end of a fax session. This event's data buffer contains a pointer to the FAXRELAY_SESSION_STATUS structure.

For more information about unsolicited events returned by T.38 fax relay filters, refer to the mspunsol.h header file.

#### Details

The T.38 fax relay filter is the only filter contained within a T.38 fax full duplex channel. A T.38 fax relay filter includes both an encoder (demodulator) and decoder (modulator) component. Only one instance of this filter is used within a full duplex T.38 fax channel to demodulate the analog data received from the DS0 endpoint and to remodulate data received from T38UDP endpoints into analog form.

The following illustration shows a T.38 fax relay filter:

#### See also

DS0 full duplex, T38UDP