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