Bfv API Reference Manual Volumes 1 | Dialogic 6.2 manual

Bfv API Reference Manual Volumes 1 - 6

Bfv API Reference Manual

Volume 1

Administration, Management,

and Configuration

Bfv API Overview

Administration and Initialization

Firmware

Configuration, Status and Monitoring

Debugging, Error Handling and Return 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 3

Media Processing

Bfv API Overview

Signal Generation and Detection

Voice Play/Record

Infopkt File Functions

Audio Conferencing

Audio Conferencing Functions

Audio Conferencing Programming Examples

Bfv API Reference Manual

Volume 4

Fax Processing

Bfv API Overview

Fax Overview

Fax Functions

TIFF-F Files Functions

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

Functionality

page 5

Image 5

Dialogic 6.2 manual Bfv API Reference Manual Volumes 1, Bfv API Reference Manual Volume Media Processing

Contents

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 Manual Conventions Related DocumentsOperating System Support 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 Functions Debugging, Error Handling, and Return ValuesModule Status and Monitoring Functions Callres Structures and Return Values Miscellaneous Functions and Macros BSMI-Level Call Control Call ControlBfv 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 Mkinfopk -o outputfname infopkttype arg Infopkt StreamCreating an Infopkt Stream Embedded speech file Simple Speech File Mkinfopk Indexed Prompt File MkpromptIndex 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 Developing a Voice Application Developing a Voice ApplicationRecording and Playing Voice Arguments Recording Voice Playing Back the Voice Message Using Prompt FilesUsing Prompt Files Creating a New Prompt File Using the mkprompt Utility Updating an Existing Prompt File Developing a Fax ApplicationSending 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 BfvDataFSK Bfv API Debug ModeBfv API Debug Mode BfvLineDumpStructure BfvLineDumpStructureDump History Dump History Invoking Dump History Most recent application corresponding Interpreting the Output L1A 01 Admin 08 Event 06 Flowcontrolstatus Event Logging Line Format Status Header LineEvent Logging Lines Parsed Command Information Parsed Command InformationTiming Information Event Descriptions Parsed Command Information Utility Programs for Debugging Bsmi Debugging Command SyntaxBsmi Message Tracing Running a Layer 2 Trace November 102 Level 2 Trace Example November 103 Trace Report ValuesValue Meaning November 104 Understanding Trace Hexadecimal StringsInterpreting the I Frame Header Bits Byte Interpreting the Message HeaderBits General I Frame November 106 Hex November 107 Interpreting Information ElementsHex Message November 108 IE Formats 931 Information Element IdentifiersHex Information Element November 109 November 110 Vtty Tracing Feature Vtty Commands Vtty Console CommandsCommand Meaning November 111 Vtty Tracer GUI Setting Output Options¾ To start the Vtty Tracer, enter November 112 November 113 Connecting to a Module¾ Use the File menu to connect to a module November 114 Using the Trace Menu November 115 Using the Memory Menu November 116 Using the Show MenuShow Menu Information About Options November 117 Vtty Trace Results November 118 Call TracerCall Tracer Arguments Command SyntaxBrktcctrace -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 November 128 Boardmon -m mod -s span -d -v -hBoardmon Sample boardmon Output BtverBtver November 129 Btver -m mod ConnlistConnlist -m mod Connlist November 131 CsendCsend November 132 DeactDeact November 133 November 134 DebugcontrolDebugcontrol Example DecodeDecode -f filename Decode filename.ips Divert DfaxDfax November 136 November 137 DlfaxDlfax Dlfax -l Dlfax options infopkt file DstripDstrip -o outputbasedcxfilename Dstrip November 139 EccllvoiceEccllvoice Eccllvoice options infopktfile FaxFax November 140 Fax options infopktfile FaxhlFaxhl options infopktfile Faxhl November 142 FaxllFaxll November 143 F1 f2 -a f3 -b -g f4 FaxmlFaxml November 144 Faxpml FaxpFaxp options Faxp Feature -m mod action FeatureFaxpml options Actions November 147 Firm -m mod -c confspec -t type firmwarefile FirmFirm November 148 Firmload -c confspec -d -b 01-q -e firmwaredir modulenum FirmloadFirmload November 149 Firmware Type Filename FontFirmload Brooktrout/boston/fw Font -m mod -q -d Ipstrip -h -o outputbase filename IpstripIpstrip November 151 Mkdcx IvrIvr options Mkdcx -o dcxfile pcxfilename Mkinfopk -o outputfname -i inputfname Infopkttype arg MkinfopkMkinfopk November 153 November 154 Tag type Mktiff MkpromptMktiff -o tifffile g3filename Mkprompt Modinfo -p -c -s -h -H -a mod ModinfoArgument Modinfo Rtp PlaypPlayp -u unit promptfile phrasenum Rtp -u unitno -v or Rtp -a Arguments TelresetShoparam Telsave Telreset -m modTelsave -m mod -v -s Telsave Tiffdump TfaxTiffdump -d tifffilename Tfax Transfer TonesTones options Tones November 162 Transfer options phonenumTransfer Examples TransferllTransfer.exe -u 0 -m 1 -t bstdialcomplete w110 Transfer.exe -u 0 -m 1 -t bstalerting w110 November 164 Transfer Transferll November 165 TromboneTrombone Root@RedHat9 bapp.src$ make others TstripTrombone options Tstrip Tstrip -h -o outputbase -r tifffilename VoiceVoice November 167 November 168 Voice options infopktfile November 169 VoicerawVoiceraw November 170 WaveWave November 171 Name November 172 November 173 Using Brooktrout FilesFile Naming Conventions Compiling Sample Applications Using Makefiles Compiling Sample Applications Using Makefiles¾ To compile the sample applications November 174 November 175 Combining the Sample ApplicationsCompatibility for Compiling November 176 Transferring Calls November 177 Making Call Transfers Using BfvMaking Call Transfers Using Bfv November 178 High-level Call Transfer using Bfv November 179 Low-level Call Transfer using Bfv Making Hookflash Transfers Using Bfv ApplicationsMaking Hookflash Transfers November 180 November 181 Using Bsmi Applications November 182 Making Two B-Channel TransfersMaking Two B-Channel Transfers November 183 Supplementary Services Support Making Call Transfers Using QsigMaking Call Transfers Using Qsig November 184 BFfvCallWaitForDivert, and BfvLineDivert. Once the call Enablecalldiversion flagBfvCallReject followed by BfvCallWaitForRelease BfvLineTransferCapabilityQuery. However you must connect November 186 Bfv APIs Associated with Qsig November 187 Making Call Transfers Using Active Redirection JapanMaking Call Transfers Using Active Redirection Japan November 188 Making Explicit Call Transfers ECT With E1 Isdn and BRIMaking Explicit Call Transfers ECT With E1 Isdn and BRI November 189 November 190 Making Two-Channel Call Transfers TromboningMaking Two-Channel Call Transfers Tromboning November 191 Setting up the Two-Channel Call TransferConnecting Resources November 192 Making Two-Channel Call Transfers Tromboning Out TSlot November 193 Connections for a Two-Channel Call Transfer November 194 Performing Echo CancellationActions During a Two-Channel Call Transfer November 195 November 196 Required Connections for Echo Cancellation November 197 Playing Back Voice RecordingsPerson B November 198 Channel InOut Silence TSlot November 199 Terminating the Two-Channel Call Transfer November 200 Disconnecting Resources November 201 November 202 Transferring Calls Using Release Link Trunk TransferTransferring Calls Using Release Link Trunk Transfer November 203 L4L3CALLREQUEST Non-RLT Call Transfer Call Control Sequence DiagramsNetwork 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 BsmiCall 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 November 215 Managing Calls Using IP TelephonyManaging Calls Using IP Telephony 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 ServerVerifying 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 ValuesBfv 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 CodesCommon Failures Failover Based on Telephony Cause Codes November 231 November 232 Failover ScenariosFailover Cause Codes Description SIP Known Failures From Various GatewaysKnown Failover Cause Code Data November 233 November 234 SIP November 235 November 236 SIP to Q.931 ConversionSIP to Q.931 Conversion SIP Cause Description November 237 SIP Cause Description November 238 Processing Media Using the T.38 ProtocolProcessing Media Using the T.38 Protocol November 239 November 240 November 241 Sending and Receiving Faxes November 242 Configuring T.38, RTP and IP Call Control ActivitiesConfiguring T.38, RTP and IP Call Control Activities November 243 TroubleshootingTroubleshooting Introduction to the SIP Protocol Understanding the SIP ProtocolUnderstanding 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 November 256 Using Third Party IP StacksUsing Third Party IP Stacks November 257 Integrating Bfv IP Fax November 258 Components Disable ECC Component ConfigurationSR140 Software-Based Integration Linux November 259 November 260 TR1034 Board-Based Integration Linux November 261 Call NegotiationInbound Call 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 TimersDefinition Default Value November 269 November 270 November 271 November 272 Granularity Definition Default Value November 273 November 274 November 275 Timing Diagrams November 276 Wink Start & Delay Dial SignalingWink Start & Delay Dial Signaling November 277 Incoming Call Processing November 278 Wink Start and Delay Dial Incoming Call Timing November 279 Outgoing Call ProcessingCall Teardown Processing November 280 Wink Start and Delay Dial Outgoing Call Timing November 281 Wink Start with Feature Group B & DWink Start with Feature Group B & D Iisdn SMI Messages November 282 November 283 Revised 20-Oct-03 Rev1.4 November 284 Immediate Start/Fixed Pause Signaling Immediate Start/Fixed Pause SignalingIncoming Call Processing Immediate Start November 285 Immediate 286 Timing DiagramStart/Fixed Pause Signaling November 287 Outgoing Call Processing Fixed Pause Mode November 288 Fixed Pause Outgoing Call Timing Diagram Ground Start Signaling Ground Start SignalingFXO Ground Start Incoming Call Processing November 290 November 291 FXO Ground Start Incoming Call Timing Diagram November 292 Outgoing Call ProcessingCall Teardown Processing 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 November 302 Loop Start SignalingLoop Start Signaling 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 OverviewIsdn 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 November 323 Isdn Call Clearing Initiated by ModuleIsdn Overlapped Dialing November 324 Isdn Call Clearing Initiated by Module November 325 Isdn Call Clearing Initiated by Network November 326 Isdn Call Clearing Initiated by Network November 327 Translating Q.931 to Simple Message InterfaceTranslating Q.931 to Simple Message Interface What is Overlap Receive? Using the overlaprcv feature L4L3mENABLEPROTOCOLUsing 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 Timers921/Q.931 Timers November 332 931 Timers Level 3 Parameters 921 Timers Level 2 ParametersData Type Mnemonic Definition November 333 November 334 Page November 336 Using the Bsmi R2 Signaling Capability November 337 CPE Signaling ModelCPE Signaling Model November 338 Line Signaling Model State CAS Bits Outbound AB Inbound AB November 339 November 340 November 341 Inter-register Signaling November 342 Enabling the R2 ProtocolEnabling the R2 Protocol November 343 R2 Digital Line Signaling Parameters November 344 November 345 Protocol Control November 346 Dnis November 347 IISDNR2MFCPGROUPB Calledlineconditions November 348 IISDNR2MFSIGNALCODES EnumerationProtocol Parameter Mechanics November 349 Forward ChannelIISDNR2MFCFORWARDACTIONS 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 L3L4mSETUPINDL4L3mCLEARREQUEST L3L4mCLEARREQUEST November 360 November 361 Call Tear DownL3L4mDISCONNECT L4L3mCLEARREQUEST Host L3L4mCLEARREQUEST November 362 L4L3mCLEARREQUEST Host L3L4mCLEARREQUEST November 363 Channel BlockingL4L3mCASCHANBLOCK L3L4mCASCHANBLOCKED November 364 Packaging Your Application for Windows November 365 Windows Server 64 bit November 366 Package OptionsPackage Options Installing Modules InstallationInstalling Virtual Modules SR140 Installation Installing the Brooktrout SDK Installing SoftwareOptions for Spawning MSI November 368 November 369 Brooktrout Fax Software System Files November 370 November 371 Install Location File Name Purpose November 372 November 373 Registry EntriesName Value Shortcuts Reboot OptionsName Location November 374 November 375 Installation Configurable Brooktrout SDK Installation Options About the Merge Module FeatureDynamically Linked DLLs dynamicdlls.msm November 376 November 377 Dynamically Linked 64-bit DLLsDynamicdllsx64.msm November 378 Configuration and Protocol Files configdata.msmFile Names 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.msmService Name Default Start Mode November 384 November 385 Installing the Merge Module FeatureIntegrating the Modules November 386 „ dynamicdllsx64.msm independent modules November 387 Case November 388 Merging Modules into a Single Feature November 389 Merging Modules into Multiple Features November 390 About Plug and Play ComponentsAbout Plug and Play Components November 391 Brooktrout Plug and Play Components Plug and Play Installation ScenariosReference Brooktrout Component November 392 User places November 393 November 394 November 395 Structure of the Brooktrout PnP FolderAbout the INF File November 396 About the Dialogic Brooktrout Plug and Play Co-InstallerClass = Computer Telephony Class Guid When Should You Launch the Configuration Tool Should You Launch the Configuration ToolDisplaying the Found New Hardware November 397 November 398 About the Device Property November 399 November 400 Modifying Configuration FilesModifying Configuration Files November 401 User-Defined Configuration File btcall.cfgParameter Description Call Control callctrl.cfg Configuration File Including the Brooktrout Configuration ToolIncluding the Brooktrout Configuration Tool November 402 November 403 Downloading Firmware FilesDownloading Firmware Files November 404 Removing SoftwareRemoving Software 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 November 406 For Version¾ To remove the Plug and Play driver 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 asctog3Asctog3 -imemo.txt -fibmpcps.fnt Ascii to Fax Conversion Utility asctog3 Cut Utility g3chop Cut and Paste UtilitiesG3chop -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 g3combinG3combin -1 lethd.301 sign.301 busrpt.301 November 412 Epstog3 argument-list Where Epson to Fax Conversion Utility epstog3Epson 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 ssFax Display and Edit Utility Supershow ss November 415 November 416 Ss -rv -iletsig.301 G3cvt ifmt ifile ofmt ofile options G3 Conversion Utility g3cvtG3 Conversion Utility g3cvt November 417 November 418 G3cvt MMR fax.mmr MH fax.mh November 419 Print Utility pPrint Utility p November 420 Phsd -xs10 -ys10 -idemo.301Page November 422 Appendix B November 423 Make -f makefile.kerndep November 424 For Red Hat Linux releases ES/AS 4.0 and laterPage External-Telephony ChannelMode Facility Line LapdidLogical channel number Millennium Address T1/E1 span StreamTime slot Unit numberPage 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