| Page Properties | ||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
...
Version | Author | Date | State | Description of Changes |
|---|---|---|---|---|
0.1 | Toshan Lash | 02/10/2015 | Working Draft | Initial version. |
0.2 | Toshan Lash | 02/12/2015 | Working Draft | Updated features for further study information. |
0.3 | Toshan Lash |
|
|
|
...
Acronym | Description | |||
|---|---|---|---|---|
API | 02/23/2015 | Approved | Changes based on feedback and sample application changes. | |
| 0.4 | Toshan Lash | 04/10/2015 | Updated flow diagrams and test diagrams. Added new tag to event to indicate whether a T.4 timeout occurred. | |
Acronyms
Acronym | Description |
|---|---|
API | Application Programming Interface |
BFV | Boston Fax and Voice API |
SDK | Software Development Kit |
...
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 and , the current value of the T4 timer setting . The host application would then send 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 three the four new members args_fax.t4TimerValue, args_fax.t4Duration, args_fax.t4Attempt and args_fax.t4Attemptt4Timeout. Once these three 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.
...
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.
...
- The args_fax structure in the BFV API will be modified with 3 with 4 new fields, t4TimerValue, t4Duration, t4Attempt and t4Attemptt4Timeout.
- A new API function BfvFaxT4TimerParams(MILL_LINE *lp, struct args_fax *args) will be added.
...
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 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 and , 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.
...
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