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
 Related Documents
Operating System Support
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
 Debugging, Error Handling, and Return Values
Module Status and Monitoring Functions
Functions
 Callres
Structures and Return Values
 Miscellaneous Functions and Macros
 Call Control
Bfv 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
 Infopkt Stream
Creating an Infopkt Stream
Mkinfopk -o outputfname infopkttype arg
 Smp rate, coding fmt, bits Smp, afe rate, data fmt
Indexed Prompt File Mkprompt
Embedded speech file Simple Speech File Mkinfopk
Index to prompt file
 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
 Developing a Voice Application
Recording and Playing Voice
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
 Developing a Fax Application
Developing a Fax Application
Updating an Existing Prompt File
Sending and Receiving a Fax
 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
 BfvLineDumpStructure
Dump History
BfvLineDumpStructure
 Dump History
Invoking Dump History
 Most recent application corresponding
 Interpreting the Output
L1A 01 Admin 08 Event 06 Flowcontrolstatus
 Status Header Line
Event Logging Lines
Event Logging Line Format
 Event Descriptions
Parsed Command Information
Parsed Command Information
Timing Information
 Parsed Command Information
 Utility Programs for Debugging
 Running a Layer 2 Trace
Command Syntax
Bsmi Debugging
Bsmi Message Tracing
 November 102
Level 2 Trace Example
 Trace Report Values
Value Meaning
November 103
 Understanding Trace Hexadecimal Strings
Interpreting the I Frame Header
November 104
 General I Frame
Interpreting the Message Header
Bits Byte
Bits
 November 106
Hex
 Interpreting Information Elements
Hex Message
November 107
 IE Formats 931 Information Element Identifiers
Hex Information Element
November 108
 November 109
 November 110
Vtty Tracing Feature
 November 111
Vtty Console Commands
Vtty Commands
Command Meaning
 November 112
Setting Output Options
Vtty Tracer GUI
¾ To start the Vtty Tracer, enter
 Connecting to a Module
¾ Use the File menu to connect to a module
November 113
 November 114
Using the Trace Menu
 November 115
Using the Memory Menu
 Using the Show Menu
Show Menu Information About Options
November 116
 November 117
Vtty Trace Results
 Call Tracer
Call Tracer
November 118
 November 119
Command Syntax
Arguments
Brktcctrace -x 10 -n 5 -oc\Brooktrout\brktlogxxx.txt
 November 120
Configuration File Format
 November 121
 November 122
 November 123
# OFF
 November 124
 November 125
Page
 November 127
Boardmon
 Boardmon -m mod -s span -d -v -h
Boardmon
November 128
 November 129
Btver
Sample boardmon Output
Btver
 Connlist
Connlist
Btver -m mod
Connlist -m mod
 Csend
Csend
November 131
 Deact
Deact
November 132
 November 133
 Debugcontrol
Debugcontrol
November 134
 Decode filename.ips
Decode
Example
Decode -f filename
 November 136
Dfax
Divert
Dfax
 Dlfax
Dlfax
November 137
 Dstrip
Dstrip
Dlfax -l Dlfax options infopkt file
Dstrip -o outputbasedcxfilename
 Eccllvoice
Eccllvoice
November 139
 November 140
Fax
Eccllvoice options infopktfile
Fax
 Faxhl
Faxhl
Fax options infopktfile
Faxhl options infopktfile
 Faxll
Faxll
November 142
 November 143
 November 144
Faxml
F1 f2 -a f3 -b -g f4
Faxml
 Faxp
Faxp
Faxpml
Faxp options
 Actions
Feature
Feature -m mod action
Faxpml options
 November 147
 November 148
Firm
Firm -m mod -c confspec -t type firmwarefile
Firm
 November 149
Firmload
Firmload -c confspec -d -b 01-q -e firmwaredir modulenum
Firmload
 Font -m mod -q -d
Font
Firmware Type Filename
Firmload Brooktrout/boston/fw
 November 151
Ipstrip
Ipstrip -h -o outputbase filename
Ipstrip
 Mkdcx -o dcxfile pcxfilename
Ivr
Mkdcx
Ivr options
 November 153
Mkinfopk
Mkinfopk -o outputfname -i inputfname Infopkttype arg
Mkinfopk
 November 154
Tag type
 Mkprompt
Mkprompt
Mktiff
Mktiff -o tifffile g3filename
 Modinfo
Modinfo
Modinfo -p -c -s -h -H -a mod
Argument
 Rtp -u unitno -v or Rtp -a
Playp
Rtp
Playp -u unit promptfile phrasenum
 Telreset
Shoparam
Arguments
 Telsave
Telreset -m mod
Telsave
Telsave -m mod -v -s
 Tfax
Tfax
Tiffdump
Tiffdump -d tifffilename
 Tones
Tones
Transfer
Tones options
 Transfer options phonenum
Transfer
November 162
 Transfer.exe -u 0 -m 1 -t bstalerting w110
Transferll
Examples
Transfer.exe -u 0 -m 1 -t bstdialcomplete w110
 November 164
Transfer Transferll
 Trombone
Trombone
November 165
 Tstrip
Tstrip
Root@RedHat9 bapp.src$ make others
Trombone options
 November 167
Voice
Tstrip -h -o outputbase -r tifffilename
Voice
 November 168
Voice options infopktfile
 Voiceraw
Voiceraw
November 169
 Wave
Wave
November 170
 November 171
Name
 November 172
 Using Brooktrout Files
File Naming Conventions
November 173
 November 174
Compiling Sample Applications Using Makefiles
Compiling Sample Applications Using Makefiles
¾ To compile the sample applications
 Combining the Sample Applications
Compatibility for Compiling
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
 November 180
Using Bfv Applications
Making Hookflash Transfers
Making Hookflash Transfers
 November 181
Using Bsmi Applications
 Making Two B-Channel Transfers
Making Two B-Channel Transfers
November 182
 November 183
 November 184
Making Call Transfers Using Qsig
Supplementary Services Support
Making Call Transfers Using Qsig
 BfvLineTransferCapabilityQuery. However you must connect
Enablecalldiversion flag
BFfvCallWaitForDivert, and BfvLineDivert. Once the call
BfvCallReject followed by BfvCallWaitForRelease
 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
 Setting up the Two-Channel Call Transfer
Connecting Resources
November 191
 November 192
Making Two-Channel Call Transfers Tromboning Out TSlot
 November 193
Connections for a Two-Channel Call Transfer
 Performing Echo Cancellation
Actions During a Two-Channel Call Transfer
November 194
 November 195
 November 196
Required Connections for Echo Cancellation
 Playing Back Voice Recordings
Person B
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
 November 204
Call Control Sequence Diagrams
Non-RLT Call Transfer
Network Host
 November 205
RLT Call Transfer
 November 206
 November 207
Sample Application
 November 208
L4L3cntlp L4toL3struct Msg L4L3cntlp = &msg
 November 209
 November 210
Placing Calls on Hold Using Bsmi
Placing Calls on Hold Using Bsmi
Call Hold Values for L4L3mUNIVERSAL messages
 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
 November 219
Using a SIP Proxy Server
Understanding SIP Functionality
Verifying Dialed Strings
 November 220
 November 221
¾ initiates the following sequence of events
 November 222
Sample Invite Request
 November 223
SIP Invite
 November 224
 November 225
Call Progress Values
Mapping of SIP responses to Bfv FCP values
Bfv final call Progress code Response Code
 November 226
Understanding H.323 Functionality
 November 227
Using H.323 Address Forms
 November 228
Phone Number
 November 229
 Failover Based on Telephony Cause Codes
Failover Based on Telephony Cause Codes
Overview
Common Failures
 November 231
 Failover Scenarios
Failover Cause Codes Description
November 232
 November 233
Known Failures From Various Gateways
SIP
Known Failover Cause Code Data
 November 234
SIP
 November 235
 SIP to Q.931 Conversion
SIP to Q.931 Conversion SIP Cause Description
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
 November 244
Understanding the SIP Protocol
Introduction to the SIP Protocol
Understanding the SIP Protocol
 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
 November 259
Configuration
Disable ECC Component
SR140 Software-Based Integration Linux
 November 260
TR1034 Board-Based Integration Linux
 Call Negotiation
Inbound Call
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
 November 269
Robbed Bit Signaling Timers
Timer
Definition Default Value
 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
 Outgoing Call Processing
Call Teardown 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
 November 285
Immediate Start/Fixed Pause Signaling
Immediate Start/Fixed Pause Signaling
Incoming Call Processing Immediate Start
 Timing Diagram
Start/Fixed Pause Signaling
Immediate 286
 November 287
Outgoing Call Processing Fixed Pause Mode
 November 288
Fixed Pause Outgoing Call Timing Diagram
 Incoming Call Processing
Ground Start Signaling
Ground Start Signaling
FXO Ground Start
 November 290
 November 291
FXO Ground Start Incoming Call Timing Diagram
 Outgoing Call Processing
Call Teardown 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
 November 318
Isdn Call Processing Overview
Making an Isdn Incoming Call
Isdn Call Processing Overview
 November 319
L43.data.enable
 November 320
Isdn Incoming Call
 November 321
Making an Isdn Outgoing Call
 November 322
Isdn Outgoing Call
 Isdn Call Clearing Initiated by Module
Isdn Overlapped Dialing
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
 November 328
Using the overlaprcv feature L4L3mENABLEPROTOCOL
What is Overlap Receive?
Using the overlaprcv feature of L4L3mENABLEPROTOCOL
 November 329
Bsmi Reference Notes
 November 330
 Network Brooktrout Controller Host
 November 332
921/Q.931 Timers
921 Timers Level 2 Parameters Data Type Mnemonic Definition
921/Q.931 Timers
 November 333
921 Timers Level 2 Parameters
931 Timers Level 3 Parameters
Data Type Mnemonic Definition
 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
 IISDNR2MFSIGNALCODES Enumeration
Protocol Parameter Mechanics
November 348
 Forward Channel
IISDNR2MFCFORWARDACTIONS
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
 November 360
L3L4mPRESEIZE L3L4mSETUPIND
L4L3mCONNECTREQUEST L3L4mCONNACKIND
L4L3mCLEARREQUEST L3L4mCLEARREQUEST
 Call Tear Down
L3L4mDISCONNECT L4L3mCLEARREQUEST Host L3L4mCLEARREQUEST
November 361
 November 362
L4L3mCLEARREQUEST Host L3L4mCLEARREQUEST
 Channel Blocking
L4L3mCASCHANBLOCK L3L4mCASCHANBLOCKED
November 363
 November 364
Packaging Your Application for Windows
 November 365
Windows Server 64 bit
 Package Options
Package Options
November 366
 Installation
Installation
Installing Modules
Installing Virtual Modules SR140
 November 368
Installing Software
Installing the Brooktrout SDK
Options for Spawning MSI
 November 369
Brooktrout Fax Software System Files
 November 370
 November 371
Install Location File Name Purpose
 November 372
 Registry Entries
Name Value
November 373
 November 374
Reboot Options
Shortcuts
Name Location
 November 375
Installation
 November 376
About the Merge Module Feature
Configurable Brooktrout SDK Installation Options
Dynamically Linked DLLs dynamicdlls.msm
 Dynamically Linked 64-bit DLLs
Dynamicdllsx64.msm
November 377
 Configuration and Protocol Files configdata.msm
File Names
November 378
 November 379
Firmware firmware.msm
 November 380
Configuration Tool configtool.msm
Shortcut Name Target
¾ Depends on the following modules
 November 381
TECUpdate TECUpdate.msm
 November 382
License Manager softwarelicense.msm
 November 383
Utility Programs utilities.msm
 November 384
Boston Host Service bostsrv.msm
File File Name Default Location Number
Service Name Default Start Mode
 Installing the Merge Module Feature
Integrating the Modules
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
 November 392
Plug and Play Installation Scenarios
Brooktrout Plug and Play Components
Reference Brooktrout Component
 User places
November 393
 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
 November 397
Should You Launch the Configuration Tool
When Should You Launch the Configuration Tool
Displaying the Found New Hardware
 November 398
About the Device Property
 November 399
 Modifying Configuration Files
Modifying Configuration Files
November 400
 User-Defined Configuration File btcall.cfg
Parameter Description
November 401
 November 402
Including the Brooktrout Configuration Tool
Call Control callctrl.cfg Configuration File
Including the Brooktrout Configuration Tool
 Downloading Firmware Files
Downloading Firmware Files
November 403
 Removing Software
Removing Software
November 404
 Expand the Brooktrout Hardware node
Removing the Plug and Play Driver
For Earlier Versions Prior to
¾ To remove an earlier version of the Plug and Play driver
 For Version
¾ To remove the Plug and Play driver
November 406
 November 407
For 64-bit operating system
 November 408
Appendix a
 November 409
Utility Cut and Paste Utilities
 Ascii to Fax Conversion Utility asctog3
Ascii to Fax Conversion Utility asctog3
Asctog3 argument-list Where
Asctog3 -imemo.txt -fibmpcps.fnt
 G3chop -s5 -c20 -isalute.301 -oadvert.301
Cut and Paste Utilities
Cut Utility g3chop
G3chop -sx -cy -ifile1.301 -ofile2.301 Where
 November 412
Paste Utility g3combin
G3combin file1.301 file2.301 file3.301 -l -s -pad
G3combin -1 lethd.301 sign.301 busrpt.301
 November 413
Epson to Fax Conversion Utility epstog3
Epstog3 argument-list Where
Epson to Fax Conversion Utility epstog3
 November 414
Epstog3 -icap001.epc
 November 415
Fax Display and Edit Utility Supershow ss
Ss-rhceveava-xs#-ys#-x#-y#-w#-m# -ifilename
Fax Display and Edit Utility Supershow ss
 November 416
Ss -rv -iletsig.301
 November 417
G3 Conversion Utility g3cvt
G3cvt ifmt ifile ofmt ofile options
G3 Conversion Utility g3cvt
 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
 Facility
Channel
External-Telephony
Mode
 Millennium Address
Lapdid
Line
Logical channel number
 Unit number
Stream
T1/E1 span
Time slot
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