The Dialogic® Brooktrout® Fax SDK Release 6.11 is the latest Brooktrout development kit providing feature rich capabilities to our partners. In this blog post, I will discuss a new feature and why it can help you.

When using ISDN, you would place a call out by sending what’s known as a Setup message. This message contains different sections called Information Elements (IEs). For example, there is an IE for the called party number (the number you’re dialing) and another IE for the calling party number (your “caller ID”) as well as some IE’s for administrative purposes.

The calling party number and called party number IE’s themselves contain other information as well as the actual numbers. The numbering type and numbering plan add additional information the ISDN switch uses when placing calls, mostly having to do with the destination being a national or an international one. The called party number and calling party number IE’s each have their own numbering type and numbering plan. Whether you need to change the numbering type and plan is up to your ISDN switch, but for the most part, the default value of “Unknown” is used for both.

Prior to SDK 6.10, the numbering type and numbering plan could be only set statically from callctrl.cfg using the “numbering_type” and “numbering_plan” parameters, respectively. With SDK 6.10, you can now set them from your application on a per call basis. This can be useful if your setup sends calls both nationally and internationally and ISDN switch requires different information when doing so. Further, you can now set the numbering type and numbering plan separately for the called party number IE and the calling party number IE in case your ISDN switch needs that done as well. Prior to this the numbering type and number plan were the same for both.

To set these parameters per call, your application would need to place calls with the API functions BfvCallSetup() and BfvCallWaitForComplete(). In BfvCallSetup(), you would select the value you want for each setting and OR it with "OVERRIDE_NUMBERING_FLAG". Below is a code snippet that shows an example of setting the various parameters.

BT_ZERO(args_cc);
args_cc.phonenum = "5551212";
args_cc.call_protocol_code = CALL_PROTOCOL_FAX;
args_cc.calling_party = "5555555";
args_cc.override_calling_type = ECC_NUM_TYPE_ABBREVIATED|OVERRIDE_NUMBERING_FLAG;
args_cc.override_called_type = ECC_NUM_TYPE_NATIONAL|OVERRIDE_NUMBERING_FLAG;
args_cc.override_calling_plan = ECC_NUM_PLAN_ISDN|OVERRIDE_NUMBERING_FLAG;
args_cc.override_called_plan = ECC_NUM_PLAN_PRIVATE|OVERRIDE_NUMBERING_FLAG;
args_cc.calling_party_presentation = ECC_PRES_RESTRICTED;
args_cc.calling_party_screening = ECC_SCRN_USER_VERIFICATION_PASSED;
BfvCallSetup(lp, &args_cc);

The values you can use for these settings are all located in ecclib.h (installed with the Brooktrout SDK under \brooktrout\boston\bfv.api\inc), e.g. "ECC_NUM_TYPE_ABBREVIATED" and "ECC_NUM_PLAN_ISDN".

Also, for the calling party number IE, there are two other parameters called Presentation and Screening which have to do with how the switch presents the calling party number. We didn’t add any new features for these parameters in SDK 6.10 – you’ve always been able to set them from your application if you wish – but for completeness, I’ll provide information on them here as well. In the above code snippet, the presentation gets set with args_cc.calling_party_presentation and the screening with args_cc.calling_party_screening. The available values for these are also located in ecclib.h. However, in order to set these two parameters dynamically, you need to set their respective callctrl.cfg parameters (“presentation” and “screening”) to “APP_DEFINED”. Only then will the settings being used from BfvCallSetup take effect.

There is more information in the Dialogic Brooktrout APIs Reference Manual as well in the description for BfvCallSetup().

The final new feature in SDK 6.10 I’ll be discussing is the ability to alter the loudness of a call on a per call basis.

On occasion we run across a case where echo exists on the end to end connection to one specific phone number. When this happens, signals sent out by the Brooktrout board are received back to itself. The Brooktrout board would then attempt to process the echoed signal instead of the actual signal the far end fax device had sent. This would often cause a fax session to fail because the Brooktrout board would never receive the correct responses.

Usually the cure for echo would be reducing the outbound signal volume a little bit. That way any echoed signal would be similarly reduced and hopefully no longer be detected. Then the real incoming signal from the far end would be handled normally. In most cases though, some other device would need to do this signal attenuation. For example, the IP gateway or PBX being used. (Analog TR1034 and Trufax boards do already have the capability to attenuate the volume from the board, but other Brooktrout devices – digital TR1034 and SR140 – do not.) However, making this adjustment would apply to all calls, not just the one giving echo.

In SDK 6.10, we have provided a way to attenuate the Brooktrout board’s outbound signal on a per call basis. So if you run across a destination phone number whose calls fail because of echo, you can select to reduce the Brooktrout board’s signal a little for that call so that any echo will be too quiet to hear.

So how is this done?

We have added the signal attenuation functionality to the existing API function BfvFaxT30Params(). BfvFaxT30Params() allows an application to specify a number of fax parameters at the beginning of a fax call. For example, you can specify a maximum fax speed or line compression that will apply to just that particular call. In SDK 6.10, we have added a new parameter: “args.xmt_level”. args.xmit_level has a unit of 0.5 dB and you can adjust it up and down to change the outbound volume of the Brooktrout board’s signal.

In addition, in case you would like to reduce the signal volume on all calls, we have also added a new configuration parameter in our btcall.cfg file called xmt_level_override, also with units of 0.5 dB. args.xmt_level from BfvFaxT30Params() works in conjunction with the xmt_level_override parameter in that their effect will be added together. So if you wish, you could decrease your volume a little bit globally with xmt_level_override and then a little more for a specific call with BfvFaxT30Params. For example, you could attenuate the outbound volume for all calls by 0.5 dB by setting xmt_level_override to -1 and then attenuate the signal for one specific call another 1.0 dB by setting args.xmt_level to -2 when calling BfvFaxT30Params(). For that one troublesome call, the Brooktrout board’s signal will be reduced by 1.5 dB.

A note of caution. When using this feature, make sure to change the volume only a little at a time until you achieve good results. Attenuating the volume too much from the start could cause other issues with the call.

One last thing to mention here is that this feature I’ve described applies to when the Brooktrout board is sending an actual audible signal. So if you’re using any TR1034 board or the SR140 with G.711, then you could reduce the signal as you see fit. However, if you’re using SR140 with T.38, then there is no audible signal since T.38 is completely out of band. For those cases, any signal reduction would still need to be done from the gateway or SIP trunk.

The Dialogic® Brooktrout® Fax SDK Release 6.10 is the latest Brooktrout development kit providing feature rich capabilities to our partners. We’ve added some new features that will be quite useful, in this series of blog posts, I will discuss a couple of them on what they do and why they can help you.

The next new feature we’ve added in the Brooktrout SDK 6.10 is ability to read in SIP headers from a 183 Session Progress message.

The 183 Session Progress (or sometimes referred to as “183 Progress” or simply “183”) is an optional intermediate SIP call progress message that some gateways may send. It indicates the call is in the process of being answered and is often used to let the two sides play media before the connection has completed.

The 183 Progress may also include SIP headers to convey information about the call as well. As an example, if a network element is not able to complete a SIP call, it can include a particular header in its 183 Progress message to indicate this. If the calling SIP endpoint were able to read this header, it would know the call cannot proceed and decide to terminate the call attempt early. Without being able to read in this header information though, the calling side would need to wait for the call to time out or just decide to give up after some time period. You could think of this as making a call at home and either hearing a message right away saying your call can’t be connected as dialed or just hearing ringback tone for a minute or so.

The Brooktrout SR140 already has the ability to read in SIP headers for an incoming call (New Features in Brooktrout SDK 6.7.3 - SIP Headers Available to the Application) but not for outbound calls. The Brooktrout SDK 6.10 allows the application to read in the headers from a SIP 183 Progress message during the call setup. This allows the application to terminate the call attempt early if it wants to based on the information provided in the 183 headers.

So how does one use this feature? The reading of the headers is very similar to how it’s done for inbound calls. Your application places calls using Brooktrout API functions, specifically either BfvLineOriginateCall() or the combination of BfvCallSetup() and BfvCallWaitForComplete(). These functions allow you to use a callback function and you would read the 183 Progress headers from there. Inside the callback function you would supply a buffer that the headers would be put in and then your application would need to parse through the headers. Each header would consist of a header name and header value. Also by returning a 1 from the callback function, the Brooktrout API function would stop the call attempt immediately.

You can see an example of using this feature in our faxll.c sample application. This is one of the sample apps that are supplied with the SDK. (The source to all sample applications is provided in Brooktrout\boston\bfv.api\app.src for Windows or /usr/sys/Brooktrout/boston/bfv.api/app.src for Linux.) faxll.c sets up a callback function called “cp_func” and parses out any available 183 Progress headers there (among other functionality).

The Dialogic® Brooktrout® Fax SDK Release 6.10 is the latest Brooktrout development kit providing feature rich capabilities to our partners. We’ve added some new features that will be quite useful, and I will discuss a couple of them on what they do and why they can help you.

The first new feature in SDK 6.10 I’ll discuss is the ability to for the Brooktrout SR140 software to detect incoming RFC 2833 DTMF digits. (RFC 2833 has actually been superseded by RFC 4733 but the term “RFC 2833” is still commonly used.) The use of RFC 2833 digits has become fairly common.

RFC 2833 digits are DTMF that arrive out of band. That means that they are not audible.

You can think of it like this. If I were to say to you “one…two…three…”, your ears would hear the sound of my voice and your brain would translate those sounds into the numbers that I said. This analogy is similar to when in-band digits are send on an IP session. You can hear the digits. They are audible.

Now, instead of saying words to you, I hand you a piece of paper that has “one”, “two”, and “three” written on it. You would now be using your eyes to gather the communicated information. This is like RFC 2833 digits. They are out of band so you cannot hear them but you know what they are via a different means.

So what does one need to do to use this feature? Two things.

First, we have implemented a new parameter in callctrl.cfg called “rfc_2833_enabled”. This parameter goes into the [host_module.x/rtp] section, and when you set it to true (default is false), the SR140’s SIP messages will have an entry indicating that it supports RFC 2833. Note that “rfc_2833_enabled” is not available to be set from Configtool, so you would need to add it yourself.

Second, in order to detect any DTMF digits, whether in-band or out of band, your application needs to turn on tone detection with the BfvToneDetectEnable API function. This API function takes a parameter called decode_flag that specifies what kind of tones you want to detect. Things like detecting 12 digits (0-9,*,#) vs. 16 digits (0-9,*,#, A,B,C,D) and whether you want to report the tone at its beginning or its end. Values are OR’d together to specify the digits to detect. To detect RFC 2833 digits, you would OR “RTP_EVENTS” into decode_flag. Our tones.c sample application provides an example of how this is done.

An important thing to mention is that when you set rfc_2833_enabled to true, you are telling the gateway or SIP trunk that you want to use RFC 2833 digits. So that is what it will send (assuming it too supports RFC 2833) and you need to make sure you use the proper settings with BfvToneDetectEnable. The Brooktrout SR140 software cannot be set up to detect both in-band and out of band tones at the same time. You would choose one or the other.