T4 Timer Mode 2

Legal Disclaimer
All contents of this document are furnished for informational use only and are subject to change without notice and do not represent a commitment on the part of Dialogic Corporation or its subsidiaries ("Dialogic"). Reasonable effort is made to ensure the accuracy of the information contained in the document. However, Dialogic does not warrant the accuracy of this information and cannot accept responsibility for errors, inaccuracies or omissions that may be contained in this document.
INFORMATION IN THIS DOCUMENT IS PROVIDED IN CONNECTION WITH DIALOGIC^® PRODUCTS. NO LICENSE, EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, TO ANY INTELLECTUAL PROPERTY RIGHTS IS GRANTED BY THIS DOCUMENT. EXCEPT AS PROVIDED IN A SIGNED AGREEMENT BETWEEN YOU AND DIALOGIC, DIALOGIC ASSUMES NO LIABILITY WHATSOEVER, AND DIALOGIC DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY, RELATING TO SALE AND/OR USE OF DIALOGIC PRODUCTS INCLUDING LIABILITY OR WARRANTIES RELATING TO FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR INFRINGEMENT OF ANY INTELLECTUAL PROPERTY RIGHT OF A THIRD PARTY. ANY STATEMENTS IN THIS DOCUMENT REGARDING THE PERFORMANCE, CAPABILITY AND FUNCTIONALITY OF DIALOGIC PRODUCTS ARE DEEMED TO HAVE BEEN MADE AS OF THE DATE OF CREATION OF THIS DOCUMENT AND THUS MIGHT NOT APPLY IN THE FUTURE.
Dialogic products are not intended for use in medical, life saving, life sustaining, critical control or safety systems, or in nuclear facility applications.
It is possible that the use or implementation of any one of the concepts, applications, or ideas described in this document, in marketing collateral produced by or on web pages maintained by Dialogic may infringe one or more patents or other intellectual property rights owned by third parties. Dialogic does not provide any intellectual property licenses with the sale of Dialogic products other than a license to use such product in accordance with intellectual property owned or validly licensed by Dialogic and no such licenses are provided except pursuant to a signed agreement with Dialogic. More detailed information about such intellectual property is available from Dialogic's legal department at 9800 Cavendish Blvd., 5^th Floor, Montreal, Quebec, Canada H4M 2V9. Dialogic encourages all users of its products to procure all necessary intellectual property licenses required to implement any concepts or applications and does not condone or encourage any intellectual property infringement and disclaims any responsibility related thereto. These intellectual property licenses may differ from country to country and it is the responsibility of those who develop the concepts or applications to be aware of and comply with different national license requirements.
Dialogic, Brooktrout and TruFax are registered trademarks of Dialogic Corporation or its subsidiaries. Dialogic's trademarks may be used publicly only with permission from Dialogic. Such permission may only be granted by Dialogic's legal department at 9800 Cavendish Blvd., 5th Floor, Montreal, Quebec, Canada H4M 2V9. Any authorized use of Dialogic's trademarks will be subject to full respect of the trademark guidelines published by Dialogic from time to time and any use of Dialogic's trademarks requires proper acknowledgement.  The names of actual companies and products mentioned herein are the trademarks of their respective owners.

Revision History

Document state can be one of Working Draft; Final Draft; Approved; Obsolete

 
 
Acronyms

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 the new mode 2 (t4_timer_mode = 2) there is only one T4 timer value for the different attempts, instead of three. If the fax session is the originator and the keyword t4_xmit_timer is not in the user configuration file or is set to 0 the T4 timer value will be initialized to a value based on the media type and manual or automatic fax operation. For T.38 the initial value will be 5.12 seconds. For G.711/PSTN the initial value will be 4.5 seconds for manual fax operation and 3.4 seconds for automatic fax operation. If the fax session is the originator and the keyword t4_xmit_timer is in the user configuration file and has a value other than 0 then the T4 timer value will be initialized to the t4_xmit_timer value (limited to 3,000 to 15,000 ms). If the fax session is the answerer and the keyword t4_recv_timer is not in the user configuration file or is set to 0 the T4 timer value will be initialized to a value based on the media type and manual or automatic fax operation. For T.38 the initial value will be 5.12 seconds. For G.711/PSTN the initial value will be 4.5 seconds for manual fax operation and 3.4 seconds for automatic fax operation. If the fax session is the answerer and the keyword t4_recv_timer is in the user configuration file and has a value other than 0 then the T4 timer value will be initialized to the t4_recv_timer value (limited to 3,000 to 15,000 ms). 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, the current value of the T4 timer setting and whether the event is due to a response received or the T4 timer expiring. The host application could 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 the new member args_fax.t4TimerValue equal to 0 which indicates to the function that it should obtain the values of the four new members args_fax.t4TimerValue, args_fax.t4Duration, args_fax.t4Attempt and args_fax.t4Timeout. Once these four 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

• Do we want to limit the range of the T4 timer value which the end user can set via the function BfvFaxT4TimerParams(lp, &args_fax) in the firmware? For example, we might limit the value from 3,000 ms to 15,000 ms. It has been decided that the value will be limited from 3,000 ms to 15,000 ms.
• Do we want to include the t4_timer_mode keyword in the Configtool? It has been decided to not include the t4_timer_mode keyword in the Configtool.

Assumptions

• None

Feature Limitations, Caveats or Restrictions

• None

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;
    unsigned t4TimerValue;
    unsigned t4Duration;
    unsigned t4Attempt;
    unsigned t4Timeout;

    // 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, the T4 attempt and the T4 timeout indication.
        BT_ZERO(args_fax);
        BfvFaxT4TimerParams(lp, &args_fax);
        t4TimerValue = args_fax.t4TimerValue;
        t4Duration = args_fax.t4Duration;
        t4Attempt = args_fax.t4Attempt;
        t4Timeout = args_fax.t4Timeout;
       
        printf("t4TimerProcessEvent:       attempt %u  duration %u  T4TimerValue %u  timeout %u\n",
               args_fax.t4Attempt,
               args_fax.t4Duration,
               args_fax.t4TimerValue,
               args_fax.t4Timeout
               );

        // 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 plus 500 ms.
        // The 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 %u\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.

API/Library Change(s)

• The args_fax structure in the BFV API will be modified with 4 new fields, t4TimerValue, t4Duration, t4Attempt and t4Timeout.
• A new API function BfvFaxT4TimerParams(MILL_LINE *lp, struct args_fax *args) will be added.

Performance Change(s)

• None

Documentation Change(s)

• The Dialogic Brooktrout Bfv API Reference Manual will be updated with documentation of the new API function BfvFaxT4TimerParams(MILL_LINE *lp, struct args_fax *args)
• The user configuration keywords t4_recv_timer, t4_xmit_timer and t4_timer_mode will need to be updated.
• If the Configtool is modified to add the t4_timer_mode keyword, the Dialogic Brooktrout Fax Products SDK Installation and Configuration Guide will need to be updated.
• Boston Series Command Set document (CmndSet.doc) with the new T4 command and event.

Configuration Change(s)

• None

Build and Installation Change(s)

• None

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, the current T4 timer value and the T4 timeout indication. 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, the current T4 timer value and the T4 timeout indication. 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.

 
Target Release
SDK 6.7.3

Backward Propagation Release(s)
None

Risks
None