Dialogic® Brooktrout® Fax Products SDK
Developer Guide
Release 6.2
November 2009 931-132-06
www.dialogic.com
Copyright and Legal Notice
Copyright © 1998-2009 Dialogic Corporation. All Rights Reserved. You may not reproduce thi s document in whole or in
part without permission in writing from Dialogic Corporation at the address provided below.
All contents of this document are furnished for informational use only and are subject to ch ange 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 contai ned in the docume nt. However, Di alogic does not warra nt 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.
Dialogic products are not intended for use in medical, life saving, life sustaining, critical control or safety systems, or in
nuclear facility applications.
Due to differing national regulations and approval requirements, certain Dialogic products may be suitable for use only
in specific countries, and thus may not function properly in other countries. You are responsible for ensuring that your
use of such products occurs only in the countries where such use is suitable. For information on specific products, contact
Dialogic Corporation at the address indicated below or on the web at www.dialogic.com.
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., 5th 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 re sponsibility
of those who develop the concepts or applications to be aware of and comply with different national license
requirements.
Dialogic, Dialogic Pro, Brooktrout, Diva, Cantata, SnowShore, Eicon, Eicon Networks, NMS Communications, NMS
(stylized), Eiconcard, SIPcontrol, Diva ISDN, TruFax, Ex net, EXS, SwitchKit, N20, Making Innovation Thrive,
Connecting to Growth, Video is the New Voice, Fusion, Vision, PacketMedia, NaturalAccess, NaturalCallControl,
NaturalConference, NaturalFax and Shiva, among others as well as related logos, are either registered trademarks or
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.
Microsoft, Developer Studio, Visual Basic,
registered trademarks of Microsoft Corporation in the United States and/or other countries. Other names of actual
companies and products mentioned herein are the trademarks of their respective owners.
This document discusses one or more open source products, systems and/or releases. Dialogic is not responsible for your
decision to use open source in connection with Dialogic products (including without limitation those referred to herein),
nor is Dialogic responsible for any present or future effects such usage might have, including without limitation effects on
your products, your business, or your intellectual property rights.
Visual C++, Visual Studio, Windows, Windows NT, and Windows Server are
page 2
Hardware Limited Warranty
Warranty for Hardware Products: Dialogic Corporation or its subsidiary that originally sold the hardware product
("Dialogic") warrants to the original purchaser of this hardware product, that at the time of delivery the hardware
product supplied hereunder will be free from defects in material and workmanship. This warranty is for the standard
period set out on Dialogic's website at http://www.dialogic.com/warranties and is void if the defect has resulted from
accident, misuse, abuse or misapplication. Any hardware product which becomes defective during the warranty period
and is returned by the original purchaser to Dialogic's Authorized Service Center with a Return Material Authorization
(RMA) number (which must be obtained from Dialogic before any return) within thirty (30) days after discovery of the
defect with a written description of the defect will be repaired or replaced at Dialogic's option. Freight charges will be
paid by Dialogic only for shipment back to you.
Additional Exclusions: Dialogic will have no obligation to make repairs or replacements necessitated by your fault or
negligence, improper or unauthorized use of the product, repairs or modifications made without Dialogic's prior writte n
approval or by causes beyond the control of Dialogic, including, but not limited to, power or air conditioning failure, acts
of God, improper interfac e with other units, or malfunct ion of any equipment or software used with the Dialogic
product(s). If Dialogic is requested and agrees to make repairs or replacements necessitated by any s uch caus es, y ou w ill
pay for such service or replacement at Dialogic's then prevailing rates.
No Other Warranties: DIALOGIC DISCLAIMS AND YOU WAIVE ALL OTHER WARRANTIES, EITHER EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO IMPLIED WARRANTIES OF MERCHANTABILITY,
NON-INFRINGEMENT AND FITNESS FOR A PARTICULAR PURPOSE AND ANY WARRANTY AGAINST LATENT
DEFECTS, WITH RESPECT TO ANY DIALOGIC PRODUCT.
No Liability for Damages: IN NO EVENT SHALL DIALOGIC OR ITS SUPPLIERS BE LIABLE FOR ANY
DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF PROFITS,
INTERRUPTION OF ACTIVITIES, LOSS OF INFORMATION OR OTHER PECUNIARY LOSS AND DIRECT OR
INDIRECT, CONSEQUENTIAL, INCIDENTAL, ECONOMIC OR PUNITIVE DAMAGES) ARISING OUT OF THE USE
OF OR INABILITY TO USE ANY DIALOGIC PRODUCT.
Limitation of Liability: DIALOGIC'S MAXIMUM CUMULATIVE LIABILITY SHALL BE LIMITED TO THE
AMOUNTS ACTUALLY PAID BY YOU TO DIALOGIC FOR THE SPECIFIC PRODUCT BEING THE OBJECT OF
THE CLAIM. YOU RELEASE DIALOGIC FROM ALL AMOUNTS IN EXCESS OF THE LIMITATION. YOU
ACKNOWLEDGE THAT THIS CONDITION IS ESSENTIAL AND THAT DIALOGIC WOULD NOT SUPPLY TO YOU
IF IT WERE NOT INCLUDED.
page 3
page 4
y
Bfv API Reference Manual Volumes 1 - 6
Bfv API Reference Manual
Volume 1
Administration, Managem ent,
and Confi g uration
Bfv API Overview
Administration and Initialization
Firmware
Configuration, Status and Monitoring
Debugging, Error Handli ng and Retur n Values
Miscellaneous Functions
Bfv API Reference Manual
Volume 2
Bfv-Level Call Control and Call Switching
Bfv API Overview
Call Control Overview
Bfv-Level Call Control
Dialing Database Functions
Data Structures
Bfv API Reference Manual
Volume 4
Fax Processing
Bfv API Overview
Fax Overview
Fax Functions
T IFF- F Fi les Fun c t i ons
Bfv API Reference Manual
Volume 5
BSMI-Level Call Control and Call Switching
Bfv API Overview
BOSTON Simple Message Interface (BSMI)
BSMI General Message Structure
R2 Signaling Protocol with BSMI
LEC Protocols with BSMI
Host to Module (L4L3m) Messages
Module to Host (L3L4m) Messages
B-Channel and D-Channel Maintenance
Bfv API Reference Manual
Volume 3
Media Processing
Bfv API Overview
Signal Generation and Detection
Voice Play /R ecor d
Infopkt File Functions
Audio Conferencing
Audio Conferencing Functions
Audio Conferencing Programming Examples
Bfv API Reference Manual
Volume 6
Appendices
App A - Configuration Files
App B - Bfv API Structures
App C - Hangup Codes
App D - BSMI and ISDN Cause Codes
App E - Infopkt Parameter Values
App F - Call Progress Notes
App G - Country-Specific Parameter Files
App H - Deprecated and Unsupported
Functionalit
page 5
Contents
Chapter 1 – About this Publication . . . . . . . . . . . . . . . . . . . . . . . . . 16
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Related Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Operating System Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Manual Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Updated Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Chapter 2 – Introduction to the Dialogic® Brooktrout®
Bfv API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
This chapter describes the Dialogic® Brooktrout® Bfv API and its
capabilities.
Bfv API and Associated Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
The Bfv API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Administration, Management, and Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Administration and Initialization Functions and Macros . . . . . . . . . . . . . . . . . . . . . 27
Firmware Functions and Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Configuration Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Module Status and Monitoring Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Debugging, Error Handling, and Return Values . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Miscellaneous Functions and Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Call Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Bfv Call Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
November 2009 6
Contents
BSMI-Level Call Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Media Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Signal Generation and Tone Detection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Voice Record and Play . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Fax Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
File Format Manipulation Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
The Infopkt Stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Fax Infopkt Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Chapter 3 – Developing Applications Using the Bfv API. . . . . . . . 56
This chapter describes how to develop applications with Brooktrout Fax
Software.
Developing a Voice Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Recording and Playing Voice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Recording Voice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Playing Back the Voice Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Using Prompt Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Using the mkprompt Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Creating a New Prompt File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Updating an Existing Prompt File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Developing a Fax Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Sending and Receiving a Fax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Sending a Fax from One Channel to Another . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Sending a Fax to a Channel from an External Fax Machine . . . . . . . . . . . . . . . . . . 63
Using Bfv API Fax Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Using High- and Low-Level Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Sending a Fax Using Function Calls for Noninfopkt-Formatted Raw G3 Files . . . . 70
Receiving a Fax Using Function Calls for Noninfopkt-Formatted Raw G3 Files . . . 73
Sending a Fax Using Calls for TIFF-F Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Receiving a Fax Using Calls for TIFF-F Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Receiving and Storing a Fax in MMR or MR Format . . . . . . . . . . . . . . . . . . . . . . . 78
Accessing an Infopkt Stream from an Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Sending a TIFF-F Fax File Within an Infopkt Stream . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Combining Data on a Single Page Using TIFF-F Fax Files . . . . . . . . . . . . . . . . . . 84
Accessing a TIFF-F File from an Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
November 2009 7
Contents
Determining Fax Status Information from an Application . . . . . . . . . . . . . . . . . . . . . . . 89
Chapter 4 – Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
This chapter describes how to use the debugging tools.
Bfv API Debug Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
BfvDataFSK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
BfvLineDumpStructure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Dump History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Invoking Dump History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Interpreting the Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Status Header Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Event Logging Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Event Logging Line Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Parsed Command Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Utility Programs for Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
btver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
connlist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
feature -q . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
modinfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
shoparam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
BSMI Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
BSMI Message Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Running a Layer 2 Trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Understanding Trace Hexadecimal Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
VTTY Tracing Feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
VTTY Console Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
VTTY Tracer GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Call Tracer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Command Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Configuration File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Chapter 5 – Sample Applications and Utilities . . . . . . . . . . . . . . . 127
This chapter describes the sample applications and utilities that come as
part of the Dialogic® Brooktrout® SDK.
November 2009 8
Contents
boardmon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
btver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
connlist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
csend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
deact . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
debug_control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
decode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
dfax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
divert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
dlfax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
dstrip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
eccllvoice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
fax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
faxhl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
faxll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
faxml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
faxp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
faxpml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 46
firm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
firmload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
font . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
ipstrip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
ivr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
mkdcx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
mkinfopk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
mkprompt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
mktiff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
modinfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
playp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
rtp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
shoparam . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
telreset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
telsave . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 59
tfax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
tiffdump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
November 2009 9
Contents
tones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
transferll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
trombone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
tstrip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
voice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
voiceraw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
wave . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Compiling Sample Applications Using Microsoft® Developer Studio Project Files . . . . . . 172
Using Brooktrout Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Compiling Sample Applications Using Makefiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Combining the Sample Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Compatibility for Compiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Chapter 6 – Transferring Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
This chapter describes transferring calls using the Bfv API-level and
BSMI-level call control functionality.
Making Call Transfers Using Bfv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Making Hookflash Transfers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Using Bfv Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Using BSMI Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Making Two B-Channel Transfers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Making Call Transfers Using QSIG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
ISDN QSIG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
Supplementary Services Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
Making Call Transfers Using Active Redirection (Japan) . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Making Explicit Call Transfers (ECT) With E1 ISDN and BRI . . . . . . . . . . . . . . . . . . . . . . 188
Making Two-Channel Call Transfer s (T ro mb o nin g) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Setting up the Two-Channel Call Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
Connecting Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
Actions During a Two-Channel Call Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Performing Echo Cancellation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Playing Back Voice Recordings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Terminating the Two-Channel Call Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
Disconnecting Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
November 2009 10
Contents
Transferring Calls Using Release Link Trunk Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
Using Bfv Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
Using BSMI Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
Call Control Sequence Diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
Non-RLT Call Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
RLT Call Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
Sample Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Placing Calls on Hold Using BSMI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
Chapter 7 – Managing Fax and Voice over IP Sessions . . . . . . . 214
This chapter describes how to develop applications that use the internet
for fax and voice media.
Managing Calls Using IP Telephony . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
Adding IP Call Control using the Bfv API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
Outgoing IP Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
Incoming IP Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
Understanding SIP Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
Using a SIP Proxy Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
Verifying Dialed Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
Sample INVITE Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
Call Progress Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
Understanding H.323 Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
Using H.323 Address Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
Failover Based on Telephony Cause Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
Common Failures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
Failover Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
Known Failures From Various Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
H.323 and SIP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
SIP to Q.931 Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
Processing Media Using the T.38 Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
Sending and Receiving Faxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
Configuring T.38, RTP and IP Call Control Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
Understanding the SIP Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
November 2009 11
Contents
Introduction to the SIP Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
Overview of SIP Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
Overview of Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
Using Third Party IP Stacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
Integrating Bfv IP Fax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
Disable ECC Component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
SR140 Software-Based Integration - Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
TR1034 Board-Based Integration - Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
Call Negotiation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
Inbound Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
Outbound Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
Chapter 8 – Robbed Bit Signaling . . . . . . . . . . . . . . . . . . . . . . . . . 264
This chapter describes robbed bit signaling as used with BSMI-level call
control.
General Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
Timer Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Timing Diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
Wink Start & Delay Dial Signaling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
Incoming Call Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Outgoing Call Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Call Teardown Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Wink Start with Feature Group B & D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
Incoming Call Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
Outgoing Call Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
Call Teardown Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
Immediate Start/Fixed Pause Signaling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
Incoming Call Processing (Immediate Start) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
Outgoing Call Processing (Fixed Pause Mode) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
Call Teardown Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
Ground Start Signaling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
FXO Ground Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
Incoming Call Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
November 2009 12
Contents
Outgoing Call Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
Call Teardown Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
FXS Ground Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Incoming Call Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Outgoing Call Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
Call Teardown Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
Loop Start Signaling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
FXO Loop Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
Incoming Call Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Outgoing Call Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Call Teardown Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
FXS Loop Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Incoming Call Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Outgoing Call Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Call Teardown Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
Chapter 9 – ISDN Call Processing and Management. . . . . . . . . . 316
This chapter describes ISDN call processing using BSMI-level call
control.
ISDN Call Processing Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
Making an ISDN Incoming Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
Making an ISDN Outgoing Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
ISDN Overlapped Dialing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
ISDN Call Clearing - Initiated by Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
ISDN Call Clearing - Initiated by Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
Translating Q.931 to Simple Message Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
Using the overlap_rcv feature of L4L3mENABLE_PROTOCOL . . . . . . . . . . . . . . . . . . . . 328
What is Overlap Receive? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
BSMI Reference Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
How Overlap Receive Mode Changes Call Control Events Pre sentation . . . . . . . . . . 330
Q.921/Q.931 Timers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
Chapter 10 – Using the BSMI R2 Signaling Capability. . . . . . . . . 336
This chapter describes R2 signaling as used with BSMI-level call control.
November 2009 13
Contents
CPE Signaling Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
Enabling the R2 Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
Protocol Parameter Mechanics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
Forward Channel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
Backward Channel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
R2 Call Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
Outbound Call Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
Inbound Call Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
Call Tear Down . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
Channel Blocking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
Chapter 11 – Packaging Your Application for Windows®. . . . . . 364
This chapter describes how to package Dialogic® Brooktrout® software
so that you can deliver it to your customers as part of your product.
Package Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366
Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
Installing Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
Installing Virtual Modules (SR140) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
Installing Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
Installing the Brooktrout SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
About the Merge Module Feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
Installing the Merge Module Feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
Integrating the Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
About Plug and Play Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
Plug and Play Installation Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
Structure of the Brooktrout PnP Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
About the INF File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
About the Dialogic® Brooktrout® Plug and Play Co-Installer . . . . . . . . . . . . . . . . . . . 396
About the Device Property Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
Modifying Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
User-Defined Configuration File (btcall.cfg) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
Call Control (callctrl.cfg) Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
Including the Brooktrout Configuration Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
Downloading Firmware Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
Removing Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
Novem ber 2009
14
Contents
Removing the Plug and Play Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
For Earlier Versions (Prior to 5.2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
For Version 5.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
Appendix A – G3 Legacy Utilities . . . . . . . . . . . . . . . . . . . . . . . . . 408
This appendix describes legacy utilities that help manipulate raw G3 fax
files.
ASCII to Fax Conversion Utility (asctog3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
Cut and Paste Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
Cut Utility (g3chop) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
Paste Utility (g3combin) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412
Epson to Fax Conversion Utility (epstog3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
Fax Display and Edit Utility: Supershow (ss) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415
G3 Conversion Utility (g3cvt) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
Print Utility (p) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
Appendix B – Recompiling On Linux Platforms. . . . . . . . . . . . . . 422
This appendix provides instructions for recompiling the Boston driver to
support new kernel patches.
Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
November 2009 15
Introduction
The Dialogic® Brooktrout® Fax Products SDK Developer Guide describes
the Bfv API used to create applications to control the features of the
Dialogic® Brooktrout® TR1034® Fax Boards, Dialogic® Brooktrout®
TruFax® Fax Boards, and the Dialogic® Brooktrout® SR140 Fax Software.
The manual gives information about Call Transfer, Automatic Speech
Recognition, IP functionality, and BSMI functionality. Finally, it explains
how one can include and package software supporting Brooktrout Fax
Boards or Dialogic® Brooktrout® SR140 Fax Software in your product.
About this Publication
November 2009
The manual contains the following chapters:
Chapters 1 through 4 provide information about:
The structure of the BFv API
How to develop applications using the Bfv API
Debugging
Sample applications
Chapters 5 through 10 describe some advanced topics such as:
Call Transfer
Automatic Speech Recognition
Internet Fax Sessions
Robbed bit signaling
ISDN protocols
16
Chapter 11 describes how to package software supporting
Appendix A provides instructions for a set of legacy G3 utility
Appendix B provides instructions for recompiling the Boston
A glossary gives definitions for some of the terms used in the
A copy of this manual in Adobe Acrobat PDF format is installed in the
Documents directory on the Brooktrout TR1034/SR140/TruFax® SDK
CD-ROM.
Related Documents
The Dialogic® Brooktrout® Bfv API Reference Manual is made up of
six volumes that contain the Bfv API function libraries, including the
Bfv API, BSMI API and messages, and the ACC API.
R2 signaling
Brooktrout software or SR140 Fax in your product.
programs.
driver to support new kernel patches.
manual.
The installation and configuration guide that came with your software
explains how to install the software (firmware, Bfv API, and driver for
the TR1034/SR140/TruFax® products) on your host system. It also
describes how to configure the driver, configure call control, and
download the firmware to a board.
For product information, white papers, FAQs, and more, access the
Dialogic web site at www.dialogic.com.
Operating System Support
See the latest release notes that came with your SDK for the
supported operating systems and their versions. A copy of the release
notes is located in the Documents directory on the
/TR1034/SR140/TruFax® SDK CD-ROM.
Manual Conventions
This manual uses the following conventions:
November 2009 17
Italics denote the names of variables in the prototype of a function
and file names, directory names, and program names within the
general text.
The Courier font in bold indicates a command sequence entered
by the user at the system prompt, for example:
cd /Brooktrout/boston/bfv.api
The Courier font not bolded indicates system output, for example:
C:>Files installed.
The Courier font also denotes programming code, such as C, C++,
Microsoft® Visual Basic®, and TSL. Programming code appears in
program examples.
Bold indicates the data type of the prototype of a function, Bfv API
functions, dialog boxes, dialog box controls, windows, and menu
items.
Square brackets [] indicate that the information to be typed is
optional.
Angle brackets < > indicate that you must supply a value w ith the
parameter.
The Caution icon is used to indicate an action that could cause harm to the
software or hardware.
The Warning icon is used to indicate an action that could cause harm to
the user.
November 2009 18
Terminology
Updated Terminology
The current version of this document includes terminology that differs
from previous versions. Please note the changes below:
Former Terminology Replaced with...
Host-based fax Dialogic® Brooktrout® SR140 Fax Software
Virtual modules
Virtual boards
Software modules
VoIP modules
SR140 virtual modules
TR1000 Series SDK Dialogic® Brooktrout® SDK
TR1000 Series Product Dialogic® Brooktrout® Fax Board
TR1000 Series Module
TR1000 Series Board
Brooktrout System Software Dialogic® Brooktrout® Runtime Software
or
Brooktrout SR140 Fax Software
or
SR140 Software
or
SR140
or
Brooktrout fax board
or
board
November 2009 19
Dialogic® Brooktrout® TR1034 Fax Board Terminology
The Dialogic® Brooktrout® TR1034 Fax Board is also referred to
herein by one or more of the following terms, or like terms including
“TR1034”:
Brooktrout TR1034 Fax Board
Brooktrout TR1034 Board
TR1034 Fax Board
TR1034 Board
TR1034
November 2009 20
Getting Technical Support
Dialogic provides technical services and support for customers who
have purchased hardware or software products from Dialogic. If you
purchased products from a reseller, please contact that reseller for
technical support.
To obtain technical support, please use the web site below:
www.dialogic.com/support/
November 2009 21
1 - Introduction to the
Dialogic® Brooktrout®
Bfv API
This chapter describes the Dialogic® Brooktrout® Bfv API and its
capabilities.
The chapter has the following sections:
Bfv API and Associated Libraries
The Bfv API Functions
November 2009 22
Bfv API and Associated Libraries
The Bfv Application Programming Interface (API) provides a set of
functions that enables applications programmers to write
telephony- or packet-network applications that run on Brooktrout’s
telecommunications boards or SR140 Fax software products. Using
the Bfv API, you can generate sophisticated, multichannel voice, fax,
and conferencing applications under Linux, Solaris, and Windows®
operating systems.
The Bfv API comprises several libraries that work together to give
flexibility in a variety of applications such as:
Voice processing (Dialogic® Brooktrout® TR1034 Fax Boards
only) and signal generation and detection
Fax
Connection to a variety of telephony interfaces:
T1 robbed bit
Bfv API and Associated Libraries
T1/E1 PRI
R2 CAS signaling
Analog
BRI
QSIG
IP
The libraries include:
Bfv API
Provides telephone line administration and initialization; board,
firmware, call control, and packet network configuration and
control; debugging and error handling, high-level call control for
analog, T1 robbed bit signaling, BRI, QSIG, and T1/E1 PRI; voice
play and record; signal generation and detection; fax
manipulation from high to low level; and file formatting for voice
and fax messages.
Boston Simple Message Interface (BSMI)
Provides very low-level call control for T1/E1 ISDN and
R2 signaling. The Bfv API uses the BSMI library to handle the
T1/E1 call control, but the higher-level call control functions
manage BSMI for you.
November 2009 23
Bfv API and Associated Libraries
By using the Bfv API libraries, the application running on the host
processor can communicate through the Boston driver and firmware
to one or more Brooktrout boards.
Figure 1. Bfv Application Configuration
Fax boards have an exact module number of the TR1034 or TruFax®
board as indicated on the rotary switch on top of the board, so you
can have control over channels on individual boards in a multi-board
system. The Dialogic® Brooktrout® SR140 uses a module number of
0x41 for up to a maximum of 120 channels in a system.
The SR140 does the following:
Works on supported Windows® platforms running on Intel
processors.
Works with SIP and H.323 IP call control.
Operates with only one IP stack at a time.
Provides the same level of debugg ing and tracing that is
available on the TR1034 platform.
After configuration and licensing, the same applic ati on supp orts
the SR140 and your hardware based T.38 solution.
Because H.323 support occurs wholly within configuration, there
are additional configuration options for H.323 call control that
you can access using the Dialogic® Brooktrout® Configuration
November 2009 24
Bfv API and Associated Libraries
Tool. You can also configure H.323 support using the
configuration file. See the installation and configuration guide
that came with your software for more information about
configuring for H.323.
The TR1034 Boston modules are driven by the Bfv API. Call control
on Boston modules is driven by BSMI.
The Bfv API libraries are based on the BTLINE structure, wh ich is a
logical abstraction of a physical channel. Each active channel stores
its information within its own BTLINE structure. You can access
and modify the BTLINE information through the Bfv API functions.
You can access other information kept in the Bfv API library, using
macros found in btlib.h.
November 2009 25
The Bfv API Functions
The Bfv API functions in all the Bfv API libraries are separated into
categories according to the tasks they perform. They are:
Configuration, Administration, and Management
Administration and Initialization
Firmware
Configuration
Debugging, Error Handling, and Return Values
Miscellaneous (for example, _dll_ and getopt)
Call Control
High Level Call Control
Low Level Call Control
Media Processing
The Bfv API Functions
Signal Generation and Detection
Voice Play and Record
Fax
File Format Manipulation
In addition to the functions, Dialogic supplies macros to provide
information or perform a specific task.
November 2009 26
Administration, Management, and Configuration
Administration and Initialization Functions and
Macros
The administration and initialization functions allow you to:
Attach and detach from a line or a session.
Configure the module instead of using a user-defined
configuration file such as btcall.cfg.
Interrupt a thread or process on an active line.
Reset the specified channel.
Get information about the module and channel address for the
specified channel.
Get the number of available channels.
You can also use specialized functions to:
The Bfv API Functions
Check for an address or facility.
Download and query the feature set.
Get information about and deactivate a board or SR140.
Receive a packet containing Boston addresses and commands
and perform internal Bfv API processing on all commands with
the packet (requires the Boston command set).
The line administration and initialization macros allow you to:
Get information about the current version of the Bfv API or
driver and some information about the operating system
environment.
Clear an item.
Get information about a line.
November 2009 27
The Bfv API Functions
The BTLINE Structure
When an application calls the BfvLineAttach (or
BfvSessionAttach) function to open and attach a specified channel,
the function creates a separate BTLINE structure for a channel and
returns a pointer to the line structure. All information about the
channel is stored in its BTLINE structure, but only the line state,
the line type, and channel number are actually relevant. The
BfvLineDetach (or BfvSessionDetach) function deallocates a
BTLINE structure.
Applications do not directly access the internal fields of the BTLINE
structure, but instead use functions, described in detail in the
Bfv API Reference Manual, and the following macros, described in
detail with other macros in the Bfv API Reference Manual:
LINE_HAS_CAP(lp, cap)
Confirms whether or not the line has the specified capability cap.
LINE_STATE(lp)
Returns or sets the line state of the specified line.
LINE_TYPE(lp)
Returns the line type of the specified line.
LINE_UNIT_NUM(lp)
Returns the channel number of the specified line.
A line is always in one of the following states:
LINE_STATE_AWAIT_TRAINING
LINE_STATE_CONNECTED
LINE_STATE_FAX_MODE
LINE_STATE_HOLDUP
LINE_STATE_IDLE
LINE_STATE_NOLOOP
LINE_STATE_OFF_HOOK
LINE_STATE_RCV_INFO
LINE_STATE_RESETTING
LINE_STATE_RETAIN
November 2009 28
LINE_STATE_RINGING
LINE_STATE_TURNAROUND
The Bfv API Functions
Hereafter each of the line states is referred to by the descriptive part
of its name only (for example, LINE_STATE_IDLE is referred to as
IDLE).
The current state of the line is stored in the BTLINE structure. A
pointer to this structure is passed as an argument to nearly all Bfv
API entry points and is provided to the application by the
BfvLineAttach function.
A number of functions and interrupts serve as inputs to the BTLINE
structure and affect the transition to different line states. Other
functions check the current line state.
Some functions conditionally branch to other points in the code, and
some prevent inappropriate action from occurring, for example,
frequent checking for CONNECTED before attempting to transmit
data.
The following is a partial list of the functions an d interrupt s and t he
line state they set:
FUNCTION LINE STATE
BfvLineAnswer Sets the state to CONNECTED.
BfvLineAttach Initializes the state to IDLE.
BfvLineOriginateCall Sets the state to CONNECTED or OFF_HOOK
depending on the results from call
progress monitoring.
BfvLineReset Resets the state to IDLE.
BfvLineTerminateCall Sets the state to IDLE.
INTERRUPTS LINE STATE
Answer tone detect Sets the state to CONNECTED.
Direction change Sets the state to TURNAROUND.
Disconnect Sets the state to IDLE.
Received FSK data Sets the state to AWAIT_TRAINING.
Ring detect Sets the state to RINGING.
Training Sets the state to FAX_MODE.
November 2009 29
The Bfv API Functions
Channel Numbering
The Bfv API uses two numbering schemes when referencing
channels within a system. One is the unit number or ordinal channel
number; the other is the logical channel number.
The unit number is a number range 0…n-1, where n is the number of
channels in the system. The BfvLineAttach function uses the unit
number in its argument and returns a pointer to the BTLINE
structure, providing a means to reference the channel in future
function calls. For example, a system comprising two 60-channel
modules would have a unit number range of 0-119. The module that
had the firmware downloaded first would contain the channels
starting from 0.
The logical channel number is used together with the module
number to reference a work channel (also called a hardware channel)
in a system. The BfvSessionAttach function uses the module and
logical channel numbers in its arguments. Logical channels not only
include work channels traditionally considered to be channels, but
also administrative channels. The work channel number range for
logical channels is 2…n+1, where n is the number of work channels
on this hardware module.
Each module has a unique module number. For example, the same
system comprising two 60-channel modules could have the following
configuration:
First module: Module 2, work channels 2-61
Second module: Module 3, work channels 2-61
Each virtual module has 120 channels (the maximum allowed in a
system).
The BfvSessionAttach function also returns a BTLINE structure;
other functions that accept a BTLINE structure as an argument can
use either that returned from BfvLineAttach or
BfvSessionAttach. When detaching, use the corresponding detach
functions BfvLineDetach or BfvSessionDetach.
Unit numbers and BfvLineAttach are typical of our legacy product.
November 2009 30
Loading...