Api | Dialogic 6.2 instruction

2 - Developing

Applications Using the Bfv

API

This chapter describes how to develop applications with Brooktrout Fax Software.

The chapter has the following sections:

Developing a Voice Application

Using Prompt Files

Developing a Fax Application

November 2009

56

Image 56

Dialogic 6.2 manual Api

Contents

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 Manual Conventions Related DocumentsOperating System Support 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 Functions Debugging, Error Handling, and Return ValuesModule Status and Monitoring Functions Structures and Return Values Callres Miscellaneous Functions and Macros BSMI-Level Call Control Call ControlBfv 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 Mkinfopk -o outputfname infopkttype arg Infopkt StreamCreating an Infopkt Stream Indexed Prompt File Mkprompt Embedded speech file Simple Speech File MkinfopkIndex 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 Developing a Voice ApplicationRecording and Playing Voice Recording Voice Arguments Playing Back the Voice Message Using Prompt FilesUsing Prompt Files Using the mkprompt Utility Creating a New Prompt File Developing a Fax Application Updating an Existing Prompt FileSending 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 BfvDataFSK Bfv API Debug ModeBfv API Debug Mode BfvLineDumpStructure BfvLineDumpStructureDump History Invoking Dump History Dump History Most recent application corresponding L1A 01 Admin 08 Event 06 Flowcontrolstatus Interpreting the Output 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 Command Syntax Bsmi DebuggingBsmi Message Tracing Running a Layer 2 Trace Level 2 Trace Example November 102 November 103 Trace Report ValuesValue Meaning November 104 Understanding Trace Hexadecimal StringsInterpreting the I Frame Header Interpreting the Message Header Bits ByteBits General I Frame Hex November 106 November 107 Interpreting Information ElementsHex Message November 108 IE Formats 931 Information Element IdentifiersHex Information Element November 109 Vtty Tracing Feature November 110 Vtty Console Commands Vtty CommandsCommand Meaning November 111 Setting Output Options Vtty Tracer GUI¾ To start the Vtty Tracer, enter November 112 November 113 Connecting to a Module¾ Use the File menu to connect to a module Using the Trace Menu November 114 Using the Memory Menu November 115 November 116 Using the Show MenuShow Menu Information About Options Vtty Trace Results November 117 November 118 Call TracerCall Tracer Command Syntax ArgumentsBrktcctrace -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 November 128 Boardmon -m mod -s span -d -v -hBoardmon Btver Sample boardmon OutputBtver November 129 Connlist Btver -m modConnlist -m mod Connlist November 131 CsendCsend November 132 DeactDeact November 133 November 134 DebugcontrolDebugcontrol Decode ExampleDecode -f filename Decode filename.ips Dfax DivertDfax November 136 November 137 DlfaxDlfax Dstrip Dlfax -l Dlfax options infopkt fileDstrip -o outputbasedcxfilename Dstrip November 139 EccllvoiceEccllvoice Fax Eccllvoice options infopktfileFax November 140 Faxhl Fax options infopktfileFaxhl options infopktfile Faxhl November 142 FaxllFaxll November 143 Faxml F1 f2 -a f3 -b -g f4Faxml November 144 Faxp FaxpmlFaxp options Faxp Feature Feature -m mod actionFaxpml options Actions November 147 Firm Firm -m mod -c confspec -t type firmwarefileFirm November 148 Firmload Firmload -c confspec -d -b 01-q -e firmwaredir modulenumFirmload November 149 Font Firmware Type FilenameFirmload Brooktrout/boston/fw Font -m mod -q -d Ipstrip Ipstrip -h -o outputbase filenameIpstrip November 151 Ivr MkdcxIvr options Mkdcx -o dcxfile pcxfilename Mkinfopk Mkinfopk -o outputfname -i inputfname Infopkttype argMkinfopk November 153 Tag type November 154 Mkprompt MktiffMktiff -o tifffile g3filename Mkprompt Modinfo Modinfo -p -c -s -h -H -a modArgument Modinfo Playp RtpPlayp -u unit promptfile phrasenum Rtp -u unitno -v or Rtp -a Arguments TelresetShoparam Telreset -m mod TelsaveTelsave -m mod -v -s Telsave Tfax TiffdumpTiffdump -d tifffilename Tfax Tones TransferTones options Tones November 162 Transfer options phonenumTransfer Transferll ExamplesTransfer.exe -u 0 -m 1 -t bstdialcomplete w110 Transfer.exe -u 0 -m 1 -t bstalerting w110 Transfer Transferll November 164 November 165 TromboneTrombone Tstrip Root@RedHat9 bapp.src$ make othersTrombone options Tstrip Voice Tstrip -h -o outputbase -r tifffilenameVoice November 167 Voice options infopktfile November 168 November 169 VoicerawVoiceraw November 170 WaveWave Name November 171 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 Transferring Calls November 176 November 177 Making Call Transfers Using BfvMaking Call Transfers Using Bfv High-level Call Transfer using Bfv November 178 Low-level Call Transfer using Bfv November 179 Using Bfv Applications Making Hookflash TransfersMaking Hookflash Transfers November 180 Using Bsmi Applications November 181 November 182 Making Two B-Channel TransfersMaking Two B-Channel Transfers November 183 Making Call Transfers Using Qsig Supplementary Services SupportMaking Call Transfers Using Qsig November 184 Enablecalldiversion flag BFfvCallWaitForDivert, and BfvLineDivert. Once the callBfvCallReject followed by BfvCallWaitForRelease BfvLineTransferCapabilityQuery. However you must connect Bfv APIs Associated with Qsig November 186 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 Making Two-Channel Call Transfers Tromboning Out TSlot November 192 Connections for a Two-Channel Call Transfer November 193 November 194 Performing Echo CancellationActions During a Two-Channel Call Transfer November 195 Required Connections for Echo Cancellation November 196 November 197 Playing Back Voice RecordingsPerson B Channel InOut Silence TSlot November 198 Terminating the Two-Channel Call Transfer November 199 Disconnecting Resources November 200 November 201 November 202 Transferring Calls Using Release Link Trunk TransferTransferring Calls Using Release Link Trunk Transfer L4L3CALLREQUEST November 203 Call Control Sequence Diagrams Non-RLT Call TransferNetwork 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 BsmiCall 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 November 215 Managing Calls Using IP TelephonyManaging Calls Using IP Telephony 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 FunctionalityVerifying 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 valuesBfv 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 OverviewCommon Failures Failover Based on Telephony Cause Codes November 231 November 232 Failover ScenariosFailover Cause Codes Description Known Failures From Various Gateways SIPKnown Failover Cause Code Data November 233 SIP November 234 November 235 November 236 SIP to Q.931 ConversionSIP to Q.931 Conversion SIP Cause Description SIP Cause Description November 237 November 238 Processing Media Using the T.38 ProtocolProcessing Media Using the T.38 Protocol November 239 November 240 Sending and Receiving Faxes November 241 November 242 Configuring T.38, RTP and IP Call Control ActivitiesConfiguring T.38, RTP and IP Call Control Activities November 243 TroubleshootingTroubleshooting Understanding the SIP Protocol Introduction to the SIP ProtocolUnderstanding 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 November 256 Using Third Party IP StacksUsing Third Party IP Stacks Integrating Bfv IP Fax November 257 Components November 258 Configuration Disable ECC ComponentSR140 Software-Based Integration Linux November 259 TR1034 Board-Based Integration Linux November 260 November 261 Call NegotiationInbound Call 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 TimerDefinition Default Value November 269 November 270 November 271 Granularity Definition Default Value November 272 November 273 November 274 Timing Diagrams November 275 November 276 Wink Start & Delay Dial SignalingWink Start & Delay Dial Signaling Incoming Call Processing November 277 Wink Start and Delay Dial Incoming Call Timing November 278 November 279 Outgoing Call ProcessingCall Teardown Processing Wink Start and Delay Dial Outgoing Call Timing November 280 November 281 Wink Start with Feature Group B & DWink Start with Feature Group B & D November 282 Iisdn SMI Messages November 283 November 284 Revised 20-Oct-03 Rev1.4 Immediate Start/Fixed Pause Signaling Immediate Start/Fixed Pause SignalingIncoming Call Processing Immediate Start November 285 Immediate 286 Timing DiagramStart/Fixed Pause Signaling Outgoing Call Processing Fixed Pause Mode November 287 Fixed Pause Outgoing Call Timing Diagram November 288 Ground Start Signaling Ground Start SignalingFXO Ground Start Incoming Call Processing November 290 FXO Ground Start Incoming Call Timing Diagram November 291 November 292 Outgoing Call ProcessingCall Teardown Processing 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 November 302 Loop Start SignalingLoop Start Signaling 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 CallIsdn 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 November 323 Isdn Call Clearing Initiated by ModuleIsdn Overlapped Dialing Isdn Call Clearing Initiated by Module November 324 Isdn Call Clearing Initiated by Network November 325 Isdn Call Clearing Initiated by Network November 326 November 327 Translating Q.931 to Simple Message InterfaceTranslating Q.931 to Simple Message Interface 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 Definition921/Q.931 Timers November 332 921 Timers Level 2 Parameters 931 Timers Level 3 ParametersData Type Mnemonic Definition November 333 November 334 Page Using the Bsmi R2 Signaling Capability November 336 November 337 CPE Signaling ModelCPE Signaling Model Line Signaling Model State CAS Bits Outbound AB Inbound AB November 338 November 339 November 340 Inter-register Signaling November 341 November 342 Enabling the R2 ProtocolEnabling the R2 Protocol R2 Digital Line Signaling Parameters November 343 November 344 Protocol Control November 345 Dnis November 346 IISDNR2MFCPGROUPB Calledlineconditions November 347 November 348 IISDNR2MFSIGNALCODES EnumerationProtocol Parameter Mechanics November 349 Forward ChannelIISDNR2MFCFORWARDACTIONS 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 L3L4mCONNACKINDL4L3mCLEARREQUEST L3L4mCLEARREQUEST November 360 November 361 Call Tear DownL3L4mDISCONNECT L4L3mCLEARREQUEST Host L3L4mCLEARREQUEST L4L3mCLEARREQUEST Host L3L4mCLEARREQUEST November 362 November 363 Channel BlockingL4L3mCASCHANBLOCK L3L4mCASCHANBLOCKED Packaging Your Application for Windows November 364 Windows Server 64 bit November 365 November 366 Package OptionsPackage Options Installation Installing ModulesInstalling Virtual Modules SR140 Installation Installing Software Installing the Brooktrout SDKOptions for Spawning MSI November 368 Brooktrout Fax Software System Files November 369 November 370 Install Location File Name Purpose November 371 November 372 November 373 Registry EntriesName Value Reboot Options ShortcutsName Location November 374 Installation November 375 About the Merge Module Feature Configurable Brooktrout SDK Installation OptionsDynamically Linked DLLs dynamicdlls.msm November 376 November 377 Dynamically Linked 64-bit DLLsDynamicdllsx64.msm November 378 Configuration and Protocol Files configdata.msmFile Names 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 NumberService Name Default Start Mode November 384 November 385 Installing the Merge Module FeatureIntegrating the Modules „ dynamicdllsx64.msm independent modules November 386 Case November 387 Merging Modules into a Single Feature November 388 Merging Modules into Multiple Features November 389 November 390 About Plug and Play ComponentsAbout Plug and Play Components November 391 Plug and Play Installation Scenarios Brooktrout Plug and Play ComponentsReference Brooktrout Component November 392 November 393 User places 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 Should You Launch the Configuration Tool When Should You Launch the Configuration ToolDisplaying the Found New Hardware November 397 About the Device Property November 398 November 399 November 400 Modifying Configuration FilesModifying Configuration Files November 401 User-Defined Configuration File btcall.cfgParameter Description Including the Brooktrout Configuration Tool Call Control callctrl.cfg Configuration FileIncluding the Brooktrout Configuration Tool November 402 November 403 Downloading Firmware FilesDownloading Firmware Files November 404 Removing SoftwareRemoving Software 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 November 406 For Version¾ To remove the Plug and Play driver 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 WhereAsctog3 -imemo.txt -fibmpcps.fnt Ascii to Fax Conversion Utility asctog3 Cut and Paste Utilities Cut Utility g3chopG3chop -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 -padG3combin -1 lethd.301 sign.301 busrpt.301 November 412 Epson to Fax Conversion Utility epstog3 Epstog3 argument-list WhereEpson 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# -ifilenameFax Display and Edit Utility Supershow ss November 415 Ss -rv -iletsig.301 November 416 G3 Conversion Utility g3cvt G3cvt ifmt ifile ofmt ofile optionsG3 Conversion Utility g3cvt November 417 G3cvt MMR fax.mmr MH fax.mh November 418 November 419 Print Utility pPrint Utility p Phsd -xs10 -ys10 -idemo.301 November 420Page Appendix B November 422 Make -f makefile.kerndep November 423 For Red Hat Linux releases ES/AS 4.0 and later November 424Page Channel External-TelephonyMode Facility Lapdid LineLogical channel number Millennium Address Stream T1/E1 spanTime slot Unit numberPage 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