Dialogic Brooktrout User Manual

0 (0)

Dialogic® Brooktrout® Fax Products SDK

Developer Guide Release 6.2

November 2009 931-132-06

www.dialogic.com

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

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

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 5 9

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 Transfers (T ro mb o ning) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 Presentation . . . . . . . . . . 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

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

About this Publication

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.

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

November 2009

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

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 wit h 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  T1/E1 PRI  R2 CAS signaling  Analog  BRI  QSIG  IP

Bfv API and Associated Libraries

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 o nly one IP stack at a time.  Provides the same level of debugging and tr acing that is

available on the TR1034 platform.

 After configuration and licensing, the same applicati 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, which 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

 Signal Generation and Detection  Voice Play and Record  Fax  File Format Manipulation

The Bfv API Functions

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:

 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 Bfv API Functions

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 LINE_STATE_RINGING LINE_STATE_TURNAROUND

November 2009 28

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 and i nterrupts a nd the 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

+ 411 hidden pages