Dialogic Brooktrout Fax Products SDK
Copyright and Legal Notice
Hardware Limited Warranty
Page
Bfv API Reference Manual Volumes 1
Bfv API Reference Manual Volume Media Processing
Contents
Developing Applications Using the Bfv API
Contents
Debugging
Contents
176
214
Robbed Bit Signaling
Isdn Call Processing and Management
Packaging Your Application for Windows
Glossary Index
About this Publication
Introduction
Related Documents
Operating System Support
Manual Conventions
Cd /Brooktrout/boston/bfv.api
Updated Terminology
Terminology
Dialogic Brooktrout TR1034 Fax Board Terminology
Getting Technical Support
Introduction to the Dialogic Brooktrout Bfv API
Bfv API and Associated Libraries
Bfv API and Associated Libraries
Bfv Application Configuration
Bfv API and Associated Libraries
Bfv API Functions
Bfv API Functions
Administration, Management, and Configuration
Administration and Initialization Functions Macros
Btline Structure
Function Line State
Channel Numbering
Configuration Functions
Firmware Functions and Macros
Configuration Files
Debugging, Error Handling, and Return Values
Module Status and Monitoring Functions
Functions
Structures and Return Values
Callres
Miscellaneous Functions and Macros
Call Control
Bfv Call Control
BSMI-Level Call Control
Bfv API Functions
Signal Generation and Tone Detection
Media Processing
Voice Record and Play
Fax Functions
Fax Functions by Type
Type/Level Function Names
File Format Manipulation Functions
Infopkts
Bfv API Functions
Tag Infopkts
Data Infopkts
Indirect Infopkts
INFOPKTUSER0USER1....USER9
Infopkt Stream
Creating an Infopkt Stream
Mkinfopk -o outputfname infopkttype arg
Indexed Prompt File Mkprompt
Embedded speech file Simple Speech File Mkinfopk
Index to prompt file
Smp rate, coding fmt, bits Smp, afe rate, data fmt
Mkinfopk -o fax.ips doc 1 ascii fax.c
Optional/conditional
BOP
Infopkt Structure
Speech Infopkt Parameters
Fax Infopkt Parameters
Strip parameters infopkts
Conversion of a Partial Infopkt Stream to a Fax Document
This two-page document contains a G3 fax document as a cover
API
Developing a Voice Application
Recording and Playing Voice
Developing a Voice Application
Recording Voice
Arguments
Using Prompt Files
Using Prompt Files
Playing Back the Voice Message
Using the mkprompt Utility
Creating a New Prompt File
Developing a Fax Application
Updating an Existing Prompt File
Sending and Receiving a Fax
Developing a Fax Application
Sending a Fax from One Channel to Another
Fax -u 0 -s wphonenum fax.ips
Sending a Fax to a Channel from an External Fax Machine
Using Bfv API Fax Functions
Using High- and Low-Level Functions
Transmits documents based on an infopkt stream
Opens the infopkt-formatted file called name for writing
Enables the call progress function
Finishes up when the infopkt stream is exhausted
Waits for the detection of an incoming call
Attaches to a free channel and gets a line pointer
Sets the G3 strip parameters for the G3 strip ltrhd.g3
Sets the G3 strip parameters for the G3 strip sig.G3
Attaches to a free channel and gets a Btline pointer
Call this function when there are no more pages to receive
Sending a Fax Using Calls for TIFF-F Files
Opens the TIFF-F file name for reading and transmission
Receiving a Fax Using Calls for TIFF-F Files
Opens the TIFF-F file name to store the received fax
Closes the Tiff file after the file is received
Receiving and Storing a Fax in MMR or MR Format
Argsfax.fmt = Fmtmmralignmsb BfvFaxSetReceiveFmtlp,&argsfax
Waits for the remote end to send its ID and capabilities
Sending a Noninfopkt-Formatted Fax Stored in MMR Format
BTZEROargsstrip
Accessing an Infopkt Stream from an Application
BTZEROargsinfopkt
Combining Data on a Single Page Using TIFF-F Fax Files
Sending a TIFF-F Fax File Within an Infopkt Stream
Developing a Fax Application
Set up call prior */ BTZEROargstiff
Accessing a TIFF-F File from an Application
Unsigned char buf1024 int n
If n = BfvTiffReadImage&argstiff = 0 break Processimagebuf,n
Determining Fax Status Information from an Application
Developing a Fax Application
Debugging
Bfv API Debug Mode
Bfv API Debug Mode
BfvDataFSK
BfvLineDumpStructure
Dump History
BfvLineDumpStructure
Invoking Dump History
Dump History
Most recent application corresponding
L1A 01 Admin 08 Event 06 Flowcontrolstatus
Interpreting the Output
Status Header Line
Event Logging Lines
Event Logging Line Format
Parsed Command Information
Parsed Command Information
Timing Information
Event Descriptions
Parsed Command Information
Utility Programs for Debugging
Command Syntax
Bsmi Debugging
Bsmi Message Tracing
Running a Layer 2 Trace
Level 2 Trace Example
November 102
Trace Report Values
Value Meaning
November 103
Understanding Trace Hexadecimal Strings
Interpreting the I Frame Header
November 104
Interpreting the Message Header
Bits Byte
Bits
General I Frame
Hex
November 106
Interpreting Information Elements
Hex Message
November 107
IE Formats 931 Information Element Identifiers
Hex Information Element
November 108
November 109
Vtty Tracing Feature
November 110
Vtty Console Commands
Vtty Commands
Command Meaning
November 111
Setting Output Options
Vtty Tracer GUI
¾ To start the Vtty Tracer, enter
November 112
Connecting to a Module
¾ Use the File menu to connect to a module
November 113
Using the Trace Menu
November 114
Using the Memory Menu
November 115
Using the Show Menu
Show Menu Information About Options
November 116
Vtty Trace Results
November 117
Call Tracer
Call Tracer
November 118
Command Syntax
Arguments
Brktcctrace -x 10 -n 5 -oc\Brooktrout\brktlogxxx.txt
November 119
Configuration File Format
November 120
November 121
November 122
# OFF
November 123
November 124
November 125
Page
Boardmon
November 127
Boardmon -m mod -s span -d -v -h
Boardmon
November 128
Btver
Sample boardmon Output
Btver
November 129
Connlist
Btver -m mod
Connlist -m mod
Connlist
Csend
Csend
November 131
Deact
Deact
November 132
November 133
Debugcontrol
Debugcontrol
November 134
Decode
Example
Decode -f filename
Decode filename.ips
Dfax
Divert
Dfax
November 136
Dlfax
Dlfax
November 137
Dstrip
Dlfax -l Dlfax options infopkt file
Dstrip -o outputbasedcxfilename
Dstrip
Eccllvoice
Eccllvoice
November 139
Fax
Eccllvoice options infopktfile
Fax
November 140
Faxhl
Fax options infopktfile
Faxhl options infopktfile
Faxhl
Faxll
Faxll
November 142
November 143
Faxml
F1 f2 -a f3 -b -g f4
Faxml
November 144
Faxp
Faxpml
Faxp options
Faxp
Feature
Feature -m mod action
Faxpml options
Actions
November 147
Firm
Firm -m mod -c confspec -t type firmwarefile
Firm
November 148
Firmload
Firmload -c confspec -d -b 01-q -e firmwaredir modulenum
Firmload
November 149
Font
Firmware Type Filename
Firmload Brooktrout/boston/fw
Font -m mod -q -d
Ipstrip
Ipstrip -h -o outputbase filename
Ipstrip
November 151
Ivr
Mkdcx
Ivr options
Mkdcx -o dcxfile pcxfilename
Mkinfopk
Mkinfopk -o outputfname -i inputfname Infopkttype arg
Mkinfopk
November 153
Tag type
November 154
Mkprompt
Mktiff
Mktiff -o tifffile g3filename
Mkprompt
Modinfo
Modinfo -p -c -s -h -H -a mod
Argument
Modinfo
Playp
Rtp
Playp -u unit promptfile phrasenum
Rtp -u unitno -v or Rtp -a
Telreset
Shoparam
Arguments
Telreset -m mod
Telsave
Telsave -m mod -v -s
Telsave
Tfax
Tiffdump
Tiffdump -d tifffilename
Tfax
Tones
Transfer
Tones options
Tones
Transfer options phonenum
Transfer
November 162
Transferll
Examples
Transfer.exe -u 0 -m 1 -t bstdialcomplete w110
Transfer.exe -u 0 -m 1 -t bstalerting w110
Transfer Transferll
November 164
Trombone
Trombone
November 165
Tstrip
Root@RedHat9 bapp.src$ make others
Trombone options
Tstrip
Voice
Tstrip -h -o outputbase -r tifffilename
Voice
November 167
Voice options infopktfile
November 168
Voiceraw
Voiceraw
November 169
Wave
Wave
November 170
Name
November 171
November 172
Using Brooktrout Files
File Naming Conventions
November 173
Compiling Sample Applications Using Makefiles
Compiling Sample Applications Using Makefiles
¾ To compile the sample applications
November 174
Combining the Sample Applications
Compatibility for Compiling
November 175
Transferring Calls
November 176
Making Call Transfers Using Bfv
Making Call Transfers Using Bfv
November 177
High-level Call Transfer using Bfv
November 178
Low-level Call Transfer using Bfv
November 179
Using Bfv Applications
Making Hookflash Transfers
Making Hookflash Transfers
November 180
Using Bsmi Applications
November 181
Making Two B-Channel Transfers
Making Two B-Channel Transfers
November 182
November 183
Making Call Transfers Using Qsig
Supplementary Services Support
Making Call Transfers Using Qsig
November 184
Enablecalldiversion flag
BFfvCallWaitForDivert, and BfvLineDivert. Once the call
BfvCallReject followed by BfvCallWaitForRelease
BfvLineTransferCapabilityQuery. However you must connect
Bfv APIs Associated with Qsig
November 186
Making Call Transfers Using Active Redirection Japan
Making Call Transfers Using Active Redirection Japan
November 187
Making Explicit Call Transfers ECT With E1 Isdn and BRI
Making Explicit Call Transfers ECT With E1 Isdn and BRI
November 188
November 189
Making Two-Channel Call Transfers Tromboning
Making Two-Channel Call Transfers Tromboning
November 190
Setting up the Two-Channel Call Transfer
Connecting Resources
November 191
Making Two-Channel Call Transfers Tromboning Out TSlot
November 192
Connections for a Two-Channel Call Transfer
November 193
Performing Echo Cancellation
Actions During a Two-Channel Call Transfer
November 194
November 195
Required Connections for Echo Cancellation
November 196
Playing Back Voice Recordings
Person B
November 197
Channel InOut Silence TSlot
November 198
Terminating the Two-Channel Call Transfer
November 199
Disconnecting Resources
November 200
November 201
Transferring Calls Using Release Link Trunk Transfer
Transferring Calls Using Release Link Trunk Transfer
November 202
L4L3CALLREQUEST
November 203
Call Control Sequence Diagrams
Non-RLT Call Transfer
Network Host
November 204
RLT Call Transfer
November 205
November 206
Sample Application
November 207
L4L3cntlp L4toL3struct Msg L4L3cntlp = &msg
November 208
November 209
Placing Calls on Hold Using Bsmi
Placing Calls on Hold Using Bsmi
Call Hold Values for L4L3mUNIVERSAL messages
November 210
= Mtdlretrieverej
November 211
Placing Calls on Hold Using Bsmi November 212
Page
Managing Fax and Voice over IP Sessions
November 214
Managing Calls Using IP Telephony
Managing Calls Using IP Telephony
November 215
Adding IP Call Control using the Bfv API
November 216
Outgoing IP Calls
November 217
Incoming IP Calls
November 218
Using a SIP Proxy Server
Understanding SIP Functionality
Verifying Dialed Strings
November 219
November 220
¾ initiates the following sequence of events
November 221
Sample Invite Request
November 222
SIP Invite
November 223
November 224
Call Progress Values
Mapping of SIP responses to Bfv FCP values
Bfv final call Progress code Response Code
November 225
Understanding H.323 Functionality
November 226
Using H.323 Address Forms
November 227
Phone Number
November 228
November 229
Failover Based on Telephony Cause Codes
Overview
Common Failures
Failover Based on Telephony Cause Codes
November 231
Failover Scenarios
Failover Cause Codes Description
November 232
Known Failures From Various Gateways
SIP
Known Failover Cause Code Data
November 233
SIP
November 234
November 235
SIP to Q.931 Conversion
SIP to Q.931 Conversion SIP Cause Description
November 236
SIP Cause Description
November 237
Processing Media Using the T.38 Protocol
Processing Media Using the T.38 Protocol
November 238
November 239
November 240
Sending and Receiving Faxes
November 241
Configuring T.38, RTP and IP Call Control Activities
Configuring T.38, RTP and IP Call Control Activities
November 242
Troubleshooting
Troubleshooting
November 243
Understanding the SIP Protocol
Introduction to the SIP Protocol
Understanding the SIP Protocol
November 244
Overview of SIP Functionality
November 245
November 246
Overview of Operation
November 247
SIP Session Setup Example With Sip Trapezoid
November 248
Via
November 249
Contact
November 250
November 251
November 252
November 253
November 254
November 255
Using Third Party IP Stacks
Using Third Party IP Stacks
November 256
Integrating Bfv IP Fax
November 257
Components
November 258
Configuration
Disable ECC Component
SR140 Software-Based Integration Linux
November 259
TR1034 Board-Based Integration Linux
November 260
Call Negotiation
Inbound Call
November 261
Inbound SIP Sequence
November 262
Outbound Call
November 263
General Information
November 264
General Information
November 265
November 266
November 267
Timer Definitions
November 268
Robbed Bit Signaling Timers
Timer
Definition Default Value
November 269
November 270
November 271
Granularity Definition Default Value
November 272
November 273
November 274
Timing Diagrams
November 275
Wink Start & Delay Dial Signaling
Wink Start & Delay Dial Signaling
November 276
Incoming Call Processing
November 277
Wink Start and Delay Dial Incoming Call Timing
November 278
Outgoing Call Processing
Call Teardown Processing
November 279
Wink Start and Delay Dial Outgoing Call Timing
November 280
Wink Start with Feature Group B & D
Wink Start with Feature Group B & D
November 281
November 282
Iisdn SMI Messages
November 283
November 284
Revised 20-Oct-03 Rev1.4
Immediate Start/Fixed Pause Signaling
Immediate Start/Fixed Pause Signaling
Incoming Call Processing Immediate Start
November 285
Timing Diagram
Start/Fixed Pause Signaling
Immediate 286
Outgoing Call Processing Fixed Pause Mode
November 287
Fixed Pause Outgoing Call Timing Diagram
November 288
Ground Start Signaling
Ground Start Signaling
FXO Ground Start
Incoming Call Processing
November 290
FXO Ground Start Incoming Call Timing Diagram
November 291
Outgoing Call Processing
Call Teardown Processing
November 292
FXO Ground Start Outgoing Call Timing Diagram
November 293
FXO Ground Start Incoming Clear Timing Diagram
November 294
FXO Ground Start Outgoing Clear Timing Diagram
November 295
FXS Ground Start
November 296
FXS Ground Start Incoming Call Timing Diagram
November 297
November 298
FXS Ground Start Outgoing Call Timing Diagram
November 299
FXS Ground Start Incoming Clear Timing Diagram
November 300
FXS Ground Start Outgoing Clear Timing Diagram
November 301
Loop Start Signaling
Loop Start Signaling
November 302
FXO Loop Start
November 303
November 304
FXO Loop Start Incoming Call Timing Diagram
November 305
FXO Loop Start Outgoing Call Timing Diagram
November 306
FXO Loop Start Outgoing Clear Timing Diagram
November 307
FXO Loop Start Incoming Clear Timing Diagram
November 308
FXS Loop Start
November 309
November 310
FXS Loop Start Incoming Call Timing Diagram
November 311
FXS Loop Start Outgoing Call Timing Diagram
November 312
FXS Loop Start Outgoing Clear Timing Diagram
November 313
Non-FXO/FXS RBS Protocols Incoming Clear Timing Diagram
November 314
Non-FXO/FXS RBS Protocols Outgoing Clear Timing Diagram
November 315
Isdn Call Processing and Management
November 316
November 317
Isdn Call Processing Overview
Making an Isdn Incoming Call
Isdn Call Processing Overview
November 318
L43.data.enable
November 319
Isdn Incoming Call
November 320
Making an Isdn Outgoing Call
November 321
Isdn Outgoing Call
November 322
Isdn Call Clearing Initiated by Module
Isdn Overlapped Dialing
November 323
Isdn Call Clearing Initiated by Module
November 324
Isdn Call Clearing Initiated by Network
November 325
Isdn Call Clearing Initiated by Network
November 326
Translating Q.931 to Simple Message Interface
Translating Q.931 to Simple Message Interface
November 327
Using the overlaprcv feature L4L3mENABLEPROTOCOL
What is Overlap Receive?
Using the overlaprcv feature of L4L3mENABLEPROTOCOL
November 328
Bsmi Reference Notes
November 329
November 330
Network Brooktrout Controller Host
921/Q.931 Timers
921 Timers Level 2 Parameters Data Type Mnemonic Definition
921/Q.931 Timers
November 332
921 Timers Level 2 Parameters
931 Timers Level 3 Parameters
Data Type Mnemonic Definition
November 333
November 334
Page
Using the Bsmi R2 Signaling Capability
November 336
CPE Signaling Model
CPE Signaling Model
November 337
Line Signaling Model State CAS Bits Outbound AB Inbound AB
November 338
November 339
November 340
Inter-register Signaling
November 341
Enabling the R2 Protocol
Enabling the R2 Protocol
November 342
R2 Digital Line Signaling Parameters
November 343
November 344
Protocol Control
November 345
Dnis
November 346
IISDNR2MFCPGROUPB Calledlineconditions
November 347
IISDNR2MFSIGNALCODES Enumeration
Protocol Parameter Mechanics
November 348
Forward Channel
IISDNR2MFCFORWARDACTIONS
November 349
Backward Channel
November 350
IISDNR2MFCPGROUPBCALLEDLINE Conditions Enumeration
November 351
IISDNR2MFCPBACKWARDACTIONS Name Description Valid State
November 352
Iisdncpgenmfparams
November 353
November 354
R2 Call Control
November 355
Outbound Call Setup
November 356
L4L3mCALLREQUEST L3L4mALERTING Host L3L4mCONNECT
November 357
L4L3mCALLREQUEST Host L3L4mCLEARREQUEST
November 358
Inbound Call Setup
November 359
L3L4mPRESEIZE L3L4mSETUPIND
L4L3mCONNECTREQUEST L3L4mCONNACKIND
L4L3mCLEARREQUEST L3L4mCLEARREQUEST
November 360
Call Tear Down
L3L4mDISCONNECT L4L3mCLEARREQUEST Host L3L4mCLEARREQUEST
November 361
L4L3mCLEARREQUEST Host L3L4mCLEARREQUEST
November 362
Channel Blocking
L4L3mCASCHANBLOCK L3L4mCASCHANBLOCKED
November 363
Packaging Your Application for Windows
November 364
Windows Server 64 bit
November 365
Package Options
Package Options
November 366
Installation
Installing Modules
Installing Virtual Modules SR140
Installation
Installing Software
Installing the Brooktrout SDK
Options for Spawning MSI
November 368
Brooktrout Fax Software System Files
November 369
November 370
Install Location File Name Purpose
November 371
November 372
Registry Entries
Name Value
November 373
Reboot Options
Shortcuts
Name Location
November 374
Installation
November 375
About the Merge Module Feature
Configurable Brooktrout SDK Installation Options
Dynamically Linked DLLs dynamicdlls.msm
November 376
Dynamically Linked 64-bit DLLs
Dynamicdllsx64.msm
November 377
Configuration and Protocol Files configdata.msm
File Names
November 378
Firmware firmware.msm
November 379
Configuration Tool configtool.msm
Shortcut Name Target
¾ Depends on the following modules
November 380
TECUpdate TECUpdate.msm
November 381
License Manager softwarelicense.msm
November 382
Utility Programs utilities.msm
November 383
Boston Host Service bostsrv.msm
File File Name Default Location Number
Service Name Default Start Mode
November 384
Installing the Merge Module Feature
Integrating the Modules
November 385
dynamicdllsx64.msm independent modules
November 386
Case
November 387
Merging Modules into a Single Feature
November 388
Merging Modules into Multiple Features
November 389
About Plug and Play Components
About Plug and Play Components
November 390
November 391
Plug and Play Installation Scenarios
Brooktrout Plug and Play Components
Reference Brooktrout Component
November 392
November 393
User places
November 394
Structure of the Brooktrout PnP Folder
About the INF File
November 395
About the Dialogic Brooktrout Plug and Play Co-Installer
Class = Computer Telephony Class Guid
November 396
Should You Launch the Configuration Tool
When Should You Launch the Configuration Tool
Displaying the Found New Hardware
November 397
About the Device Property
November 398
November 399
Modifying Configuration Files
Modifying Configuration Files
November 400
User-Defined Configuration File btcall.cfg
Parameter Description
November 401
Including the Brooktrout Configuration Tool
Call Control callctrl.cfg Configuration File
Including the Brooktrout Configuration Tool
November 402
Downloading Firmware Files
Downloading Firmware Files
November 403
Removing Software
Removing Software
November 404
Removing the Plug and Play Driver
For Earlier Versions Prior to
¾ To remove an earlier version of the Plug and Play driver
Expand the Brooktrout Hardware node
For Version
¾ To remove the Plug and Play driver
November 406
For 64-bit operating system
November 407
Appendix a
November 408
Utility Cut and Paste Utilities
November 409
Ascii to Fax Conversion Utility asctog3
Asctog3 argument-list Where
Asctog3 -imemo.txt -fibmpcps.fnt
Ascii to Fax Conversion Utility asctog3
Cut and Paste Utilities
Cut Utility g3chop
G3chop -sx -cy -ifile1.301 -ofile2.301 Where
G3chop -s5 -c20 -isalute.301 -oadvert.301
Paste Utility g3combin
G3combin file1.301 file2.301 file3.301 -l -s -pad
G3combin -1 lethd.301 sign.301 busrpt.301
November 412
Epson to Fax Conversion Utility epstog3
Epstog3 argument-list Where
Epson to Fax Conversion Utility epstog3
November 413
Epstog3 -icap001.epc
November 414
Fax Display and Edit Utility Supershow ss
Ss-rhceveava-xs#-ys#-x#-y#-w#-m# -ifilename
Fax Display and Edit Utility Supershow ss
November 415
Ss -rv -iletsig.301
November 416
G3 Conversion Utility g3cvt
G3cvt ifmt ifile ofmt ofile options
G3 Conversion Utility g3cvt
November 417
G3cvt MMR fax.mmr MH fax.mh
November 418
Print Utility p
Print Utility p
November 419
Phsd -xs10 -ys10 -idemo.301
November 420
Page
Appendix B
November 422
Make -f makefile.kerndep
November 423
For Red Hat Linux releases ES/AS 4.0 and later
November 424
Page
Channel
External-Telephony
Mode
Facility
Lapdid
Line
Logical channel number
Millennium Address
Stream
T1/E1 span
Time slot
Unit number
Page
Index
430
Bsmi API
November 431
November 432
November 433
L4L3CALLREQUEST
November 434
November 435
Call Proceeding 318, 321 Connect
November 436
SIP
November 437
November 438
November 439
November 440