SDK 6.7.3 is the latest Brooktrout development kit providing feature rich capabilities to our partners.  As usual, we’ve added some new features that will be quite useful, and I will discuss a few of them here to give more details on what they do and why they can help you. First up is the ability to enable or disable Error Correction Mode on a per call basis.

Error Correction Mode (ECM) is a fax feature where image data is broken up into chunks called frames and each frame has a checksum applied to it.  If any data is corrupted during transmit, the receiving side tells the sender about it and which frames were bad so that the sender can re-send the bad ones.  Previously, the Brooktrout SDK allowed the ability to enable or disable ECM only during the channel reset, usually from the btcall.cfg file with the ecm_enable parameter.

There can be times though when you want to disable ECM for a particular call.  Maybe you know a particular phone number doesn't handle ECM well for some reason and so you'd rather not use ECM then.  In SDK 6.7.3, you can now override the btcall.cfg setting when you call your first fax function (e.g. BfvFaxBeginReceive, BfvFaxBeginSendTiff).  We've added a new parameter in the args_fax structure called ecm_override.  If you leave it at 0, then whatever is set for the ecm_enable parameter in the btcall.cfg file will still be in control.  If you set ecm_override to a positive value, it will override ecm_enable and enable ECM, and if you set it to a negative value, it will override ecm_enable and disable ECM.

This feature can be especially useful in conjunction with the "Support for a Changed DIS" feature added in SDK 6.7.2 where if a receiving fax device changes certain DIS parameters, the Brooktrout board will no longer hang up the call with an error 33.  If the changed DIS changes one of the more "important parameters" (width, resolution, line compression, ECM), then the change must be something that would not affect the settings the Brooktrout side was planning to use.  To put it another way, if the remote end sends a changed DIS that disables ECM (when at the beginning of the call, the first DIS had ECM enabled), there would be no issue as long as the Brooktrout side already had ECM disabled as well.

So with the new feature, an application could disable ECM only to this particular number that it recognizes as disabling ECM so that the call can go through.  You can think of this as sort of an ECM blacklist.

Here's a piece of a Brooktrout debug log to show you ecm_override in action.  The first section is from during a channel reset.  (Resets have a lot of information so I'm showing only a piece of it.)

06/19 16:41:25.08 56[41,2] >+ (09) FAX (0A) REQUEST (7F) GET_CAPABILITIES
06/19 16:41:25.08 56[41,2] < (09) FAX (08) EVENT (7E) CAPABILITIES_LIST
    (37) CAP_FORMATS [02: Fix Uns Long Unitless] 0000000F
    (38) CAP_FEATURES [02: Fix Uns Long Unitless] 005FF6B7
06/19 16:41:25.08 56[41,2] > (09) FAX (04) SET
    (2E) ECM_ENABLE [00: Fix Uns Byte Unitless] 01
    (2F) ERROR_ENABLE [20: Fix Uns Byte Boolean] 01
    (30) ERROR_MULT [00: Fix Uns Byte Unitless] 28
    (55) RTP_MULT [00: Fix Uns Byte Unitless] C8
    (31) ERROR_THRESH [00: Fix Uns Byte Unitless] 03

The line above with "ECM_ENABLE" in it has a 01 at the end to indicate the ECM is enabled here from the btcall.cfg file.  Then later in the log after the SR140 has answered the call, the BfvFaxBeginReceive API function is called with ecm_override set to -1.  The code would look something like this:

printf( "BfvFaxBeginReceive\n" );
BT_ZERO(args_fax); args_fax.ecm_override = -1;       // override ecm_enable in btcall.cfg and disable ECM
if (BfvFaxBeginReceive(lp, &args_fax) < 0)
Error handling code here

This causes there to be another "ECM_ENABLE" line in the debug log, but this time the line has a 00 in it.  The 00 indicates that ECM is now disabled regardless of the ecm_enable setting in the btcall.cfg file.

06/19 16:41:29.31 56[41,2] rcv startup
06/19 16:41:29.31 56[41,2] > (09) FAX (04) SET
    (2E) ECM_ENABLE [00: Fix Uns Byte Unitless] 00
06/19 16:41:29.31 56[41,2] > (09) FAX (04) SET
    (4D) V34_ENABLE [20: Fix Uns Byte Boolean] 00