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.
MSP_FILTER_FAX_RELAY
MSP_FAX_CHANNEL_PARMS
Used in T.38 fax full duplex channels.
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.
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:
|
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 FAXRELAY_EVENTMASK_REPT_FAX_BEGIN_END FAXRELAY_EVENTMASK_REPT_PASSED_PAGE |
maxbitrate |
Sets the maximum bit rate of the fax transmission in bits/s:
|
timeout |
Sets the session timeout value in ms. The following constants are defined for this parameter:
|
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.
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:
Other session indicators include:
|
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.
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: