...
Product Issue Description
Nexway, a Dialogic Brooktrout customer, needs a new T4 timer mode to allow them to set the T4 timer to a value which can be used while waiting for the next response. This will allow Nexway to set the T4 timer to a value, which they can determine via some algorithm, to be beneficial in completing the fax in as short a time as possible. It will allow Nexway to have complete control over the T4 timer, giving them the flexibility to use whatever algorithm they would like, to set it. If they would like to use some new algorithm to set the T4 timer, they would not need to wait for Dialogic to implement a new T4 timer adaptation mode and the associated SDK release.
Overall Feature Description
The current implementation of the Dialogic Brooktrout product provides support for two T4 timer modes. The modes are set via the keyword t4_timer_mode in the user configuration file. Mode 0 is the original mode which will adapt the T4 timer using an algorithm based on the attempt number, the duration to receive the last response or the T4 timeout value if no response is received and the T4 timer value which was used to set the T4 timer after sending a command to the remote fax machine. Mode 1 is a new mode which was implemented recently, which initializes the T4 timer value but doesn't adapt the T4 timer.
For mode 0 (t4_timer_mode = 0) if both T4_recv_timer and T4_xmit_timer are not in the user configuration file or both have a value of 0 the T4 timer values will be initialized to a value based on the media type and manual or automatic fax operation, and will adapt to network conditions. If one of these keywords has a value other than 0 in the user configuration file, then the T4 timer will use this value (limited to 3,000 to 15,000 ms) for the T4 timer values and will not adapt.
...
For the new mode 2 (t4_timer_mode = 2) there is only one T4 timer value for the different attempts, instead of three. In this case, if both T4_recv_timer and T4_xmit_timer are not in the user configuration file or both have a value of 0 the T4 timer value will be initialized to a value based on the media type and manual or automatic fax operation. If one of these keywords has a value other than 0 in the user configuration file, then the T4 timer will use this value (limited to 3,000 to 15,000 ms) for the T4 timer value. In this mode, the firmware does not do any T4 timer adaptation itself. An event is sent to the host application which informs the host application of the attempt number which just took place, the duration to receive the last response or the T4 timeout value if no response is received and the current value of the T4 timer setting. The host application would then send an adapted T4 timer value (limited by the firmware to 3,000 to 15,000 ms) for the next command response exchange.
The end user application will need to use the existing macro LINE_SET_INCOMING_CMD_FUNC(lp. t4TimerProcessEvent); where the parameter t4TimerProcessEvent is a function which checks if the received event is from the fax facility and has a command specifier indicating it is a FAX_T4_ADAPT_INFO_EVENT. If it is, then the new API function BfvFaxT4TimerParams(lp, &args_fax) can be called, with one of the new members args_fax.t4TimerValue equal to 0 which indicates to the function that it should obtain the values of the three new members args_fax.t4TimerValue, args_fax.t4Duration and args_fax.t4Attempt. Once these three values have been obtained, the t4TimerProcessEvent(BTLINE *lp, struct args_packet *args) function can calculate a new value for the T4 timer and set args_fax.t4TimerValue equal to this value and then call BfvFaxT4TimerParams(lp, &args_fax) which will send a command to the firmware to set the new T4 timer value.
Features for Further Study
...
Sample Call Flows
Below are a couple call flows depicting the use of the new mode 2.
Sample Application Coding
Set the function which will be called when an event is received by the host code:
LINE_SET_INCOMING_CMD_FUNC(lp, t4TimerProcessEvent);
The following is the function which is called when any event is received by the host code. The function will check for the T4 timer event.
void t4TimerProcessEvent(BTLINE *lp, struct args_packet *args)
{
struct args_fax args_fax;
struct args_packet args_pkt;
unsigned short t4TimerValue;
int t4Duration;
int t4Attempt;
// Check to see if the event received is from the fax facility and is the
// T4 adaptation information event.
if ((args->facility == MILL_FACILITY_FAX) &&
(args->cmd_verb == MILL_VERB_EVENT) &&
(args->cmd_specifier == FAX_T4_ADAPT_INFO_EVENT))
{
// Obtain the current T4 timer value, the T4 duration to receive
// a response or T4 time out and the T4 attempt.
BT_ZERO(args_fax);
BfvFaxT4TimerParams(lp, &args_fax);
t4TimerValue = args_fax.t4TimerValue;
t4Duration = args_fax.t4Duration;
t4Attempt = args_fax.t4Attempt;
printf("t4TimerProcessEvent T4TimerValue %d duration %d attempt %d\n",
args_fax.t4TimerValue,
args_fax.t4Duration,
args_fax.t4Attempt
);
// Set the T4 timer value to a new value. For example, the following
// checks to see if the attempt just completed is 1 and if so it will set the
// T4 timer value to the existing T4 timer value minus 500 ms.
// End user can change the following to set the T4 timer value to a new
// value according to some algorithm determined by the end user
if (t4Attempt == 1)
{
BT_ZERO(args_fax);
args_fax.t4TimerValue = t4TimerValue - 500;
printf("t4TimerProcessEvent Set T4TimerValue %d\n",
args_fax.t4TimerValue
);
BfvFaxT4TimerParams(lp, &args_fax);
}
}
}
Product Areas Affected
- This feature will affect the T4 timer operation in a fax session if the keyword t4_timer_mode is set to 2.
...
Test Scenario(s)
The following testing shall be done at a minimum. The two sample call flows shown above will be tested and it will be confirmed that the results are what is expected. In order to perform the testing, the firmware will need to be modified in several ways. In the firmware function faxSetAdaptiveT4Timer(), faxSendDebug will be called to send to the API debug log the attempt number and the value to be used for setting the T4 timer. In the firmware function faxUpdateAdaptiveT4Timer(), faxSendDebug will be called to send to the API debug log the attempt number, the duration to receive the response or the T4 time out if no response is received and the current T4 timer value. In the firmware function faxT4TimerValue(), faxSendDebug will be called to send to the API debug log the new T4 timer value sent to the firmware from the host application.
For the sample call flow number 2, the firmware needs to be modified so that the transmitter ignores the first two CFR responses to the TSI.DCS.TCF sequence.
The sample application for this enhancement based on the sample application fax.c will be modified as described above under Sample Application Coding. It will print to the API debug log the attempt number, the duration to receive the response or the T4 time out if no response is received and the current T4 timer value. It will also print to the API debug log the new T4 timer value sent to the firmware if it is in fact sent.
The testing will be performed on an SR140 between channels 0 and 1. The keyword t4_timer_mode in the user configuration file btcall.cfg needs to be set to 2. The two keywords t4_xmit_timer and t4_recv_timer should not be placed in the user configuration file. The media type used should be T.38. The sample application faxt4.c for this enhancement which is based on fax.c shall be used for at least the transmit side. The results shown below are for the transmit side only. The two call sample flows will be tested for both V.17 and V.34. The results below show the expected results for V.17. Similar results are expected for V.34, but the durations might be different.
Filelist will also be run on an SR140 doing 60 channels to 60 channels for 15 minutes using firmware which has not been modified to ignore the first couple CFRs. It will be confirmed that the results are OK.
Results embedded in the API debug log similar to the results shown below in red are expected.
...