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).