Firmware Functions and Macros

The Bfv API Functions

With the specialized firmware functions, you can:

Download firmware to the module from a file or a buffer

Get information about a module’s firmware configuration options

With the firmware macros, you can determine:

Version number, build number, and date of the control processor firmware

Version number, build number, and date of the boot ROM firmware

Version number, build number, date of each DSP firmware, and the number of DSPs on the module

Configuration Functions

The Bfv API provides functions that allow you to get the current information about the telephony configuration, reset the telephony state, and save telephony parameters to Non-Volatile RAM (NVRAM).

You can also establish a connection between source and destination telephony resources; get information about the connections, their ports and classes; and clear all switching connections for a module.

November 2009

Page 31

Image 31

Dialogic 6.2 manual Firmware Functions and Macros, Configuration Functions

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 Operating System Support Related DocumentsManual 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 ValuesFunctions Callres Structures and Return Values Miscellaneous Functions and Macros Bfv Call Control Call ControlBSMI-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 StreamMkinfopk -o outputfname infopkttype arg Smp rate, coding fmt, bits Smp, afe rate, data fmt Indexed Prompt File MkpromptEmbedded 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 Recording and Playing Voice Developing a Voice ApplicationDeveloping a Voice Application Arguments Recording Voice Using Prompt Files Using Prompt FilesPlaying Back the Voice Message Creating a New Prompt File Using the mkprompt Utility Developing a Fax Application Developing a Fax ApplicationUpdating 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 ModeBfvDataFSK Dump History BfvLineDumpStructureBfvLineDumpStructure Dump History Invoking Dump History Most recent application corresponding Interpreting the Output L1A 01 Admin 08 Event 06 Flowcontrolstatus Event Logging Lines Status Header LineEvent Logging Line Format Event Descriptions Parsed Command InformationParsed Command Information Timing Information Parsed Command Information Utility Programs for Debugging Running a Layer 2 Trace Command SyntaxBsmi Debugging Bsmi Message Tracing November 102 Level 2 Trace Example Value Meaning Trace Report ValuesNovember 103 Interpreting the I Frame Header Understanding Trace Hexadecimal StringsNovember 104 General I Frame Interpreting the Message HeaderBits Byte Bits November 106 Hex Hex Message Interpreting Information ElementsNovember 107 Hex Information Element IE Formats 931 Information Element IdentifiersNovember 108 November 109 November 110 Vtty Tracing Feature November 111 Vtty Console CommandsVtty Commands Command Meaning November 112 Setting Output OptionsVtty Tracer GUI ¾ To start the Vtty Tracer, enter ¾ Use the File menu to connect to a module Connecting to a ModuleNovember 113 November 114 Using the Trace Menu November 115 Using the Memory Menu Show Menu Information About Options Using the Show MenuNovember 116 November 117 Vtty Trace Results Call Tracer Call TracerNovember 118 November 119 Command SyntaxArguments 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 Boardmon -m mod -s span -d -v -hNovember 128 November 129 BtverSample boardmon Output Btver Connlist ConnlistBtver -m mod Connlist -m mod Csend CsendNovember 131 Deact DeactNovember 132 November 133 Debugcontrol DebugcontrolNovember 134 Decode filename.ips DecodeExample Decode -f filename November 136 DfaxDivert Dfax Dlfax DlfaxNovember 137 Dstrip DstripDlfax -l Dlfax options infopkt file Dstrip -o outputbasedcxfilename Eccllvoice EccllvoiceNovember 139 November 140 FaxEccllvoice options infopktfile Fax Faxhl FaxhlFax options infopktfile Faxhl options infopktfile Faxll FaxllNovember 142 November 143 November 144 FaxmlF1 f2 -a f3 -b -g f4 Faxml Faxp FaxpFaxpml Faxp options Actions FeatureFeature -m mod action Faxpml options November 147 November 148 FirmFirm -m mod -c confspec -t type firmwarefile Firm November 149 FirmloadFirmload -c confspec -d -b 01-q -e firmwaredir modulenum Firmload Font -m mod -q -d FontFirmware Type Filename Firmload Brooktrout/boston/fw November 151 IpstripIpstrip -h -o outputbase filename Ipstrip Mkdcx -o dcxfile pcxfilename IvrMkdcx Ivr options November 153 MkinfopkMkinfopk -o outputfname -i inputfname Infopkttype arg Mkinfopk November 154 Tag type Mkprompt MkpromptMktiff Mktiff -o tifffile g3filename Modinfo ModinfoModinfo -p -c -s -h -H -a mod Argument Rtp -u unitno -v or Rtp -a PlaypRtp Playp -u unit promptfile phrasenum Shoparam TelresetArguments Telsave Telreset -m modTelsave Telsave -m mod -v -s Tfax TfaxTiffdump Tiffdump -d tifffilename Tones TonesTransfer Tones options Transfer Transfer options phonenumNovember 162 Transfer.exe -u 0 -m 1 -t bstalerting w110 TransferllExamples Transfer.exe -u 0 -m 1 -t bstdialcomplete w110 November 164 Transfer Transferll Trombone TromboneNovember 165 Tstrip TstripRoot@RedHat9 bapp.src$ make others Trombone options November 167 VoiceTstrip -h -o outputbase -r tifffilename Voice November 168 Voice options infopktfile Voiceraw VoicerawNovember 169 Wave WaveNovember 170 November 171 Name November 172 File Naming Conventions Using Brooktrout FilesNovember 173 November 174 Compiling Sample Applications Using MakefilesCompiling Sample Applications Using Makefiles ¾ To compile the sample applications Compatibility for Compiling Combining the Sample ApplicationsNovember 175 November 176 Transferring Calls Making Call Transfers Using Bfv Making Call Transfers Using BfvNovember 177 November 178 High-level Call Transfer using Bfv November 179 Low-level Call Transfer using Bfv November 180 Using Bfv ApplicationsMaking Hookflash Transfers Making Hookflash Transfers November 181 Using Bsmi Applications Making Two B-Channel Transfers Making Two B-Channel TransfersNovember 182 November 183 November 184 Making Call Transfers Using QsigSupplementary Services Support Making Call Transfers Using Qsig BfvLineTransferCapabilityQuery. However you must connect Enablecalldiversion flagBFfvCallWaitForDivert, 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 JapanNovember 187 Making Explicit Call Transfers ECT With E1 Isdn and BRI Making Explicit Call Transfers ECT With E1 Isdn and BRINovember 188 November 189 Making Two-Channel Call Transfers Tromboning Making Two-Channel Call Transfers TromboningNovember 190 Connecting Resources Setting up the Two-Channel Call TransferNovember 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 CancellationNovember 194 November 195 November 196 Required Connections for Echo Cancellation Person B Playing Back Voice RecordingsNovember 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 TransferNovember 202 November 203 L4L3CALLREQUEST November 204 Call Control Sequence DiagramsNon-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 BsmiPlacing 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 TelephonyNovember 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 ServerUnderstanding 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 ValuesMapping 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 CodesOverview Common Failures November 231 Failover Cause Codes Description Failover ScenariosNovember 232 November 233 Known Failures From Various GatewaysSIP Known Failover Cause Code Data November 234 SIP November 235 SIP to Q.931 Conversion SIP Cause Description SIP to Q.931 ConversionNovember 236 November 237 SIP Cause Description Processing Media Using the T.38 Protocol Processing Media Using the T.38 ProtocolNovember 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 ActivitiesNovember 242 Troubleshooting TroubleshootingNovember 243 November 244 Understanding the SIP ProtocolIntroduction 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 StacksNovember 256 November 257 Integrating Bfv IP Fax November 258 Components November 259 ConfigurationDisable ECC Component SR140 Software-Based Integration Linux November 260 TR1034 Board-Based Integration Linux Inbound Call Call NegotiationNovember 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 TimersTimer 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 SignalingNovember 276 November 277 Incoming Call Processing November 278 Wink Start and Delay Dial Incoming Call Timing Call Teardown Processing Outgoing Call ProcessingNovember 279 November 280 Wink Start and Delay Dial Outgoing Call Timing Wink Start with Feature Group B & D Wink Start with Feature Group B & DNovember 281 Iisdn SMI Messages November 282 November 283 Revised 20-Oct-03 Rev1.4 November 284 November 285 Immediate Start/Fixed Pause SignalingImmediate Start/Fixed Pause Signaling Incoming Call Processing Immediate Start Start/Fixed Pause Signaling Timing DiagramImmediate 286 November 287 Outgoing Call Processing Fixed Pause Mode November 288 Fixed Pause Outgoing Call Timing Diagram Incoming Call Processing Ground Start SignalingGround Start Signaling FXO Ground Start November 290 November 291 FXO Ground Start Incoming Call Timing Diagram Call Teardown Processing Outgoing Call ProcessingNovember 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 SignalingNovember 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 OverviewMaking 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 Overlapped Dialing Isdn Call Clearing Initiated by ModuleNovember 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 InterfaceNovember 327 November 328 Using the overlaprcv feature L4L3mENABLEPROTOCOLWhat 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 Timers921 Timers Level 2 Parameters Data Type Mnemonic Definition 921/Q.931 Timers November 333 921 Timers Level 2 Parameters931 Timers Level 3 Parameters Data Type Mnemonic Definition November 334 Page November 336 Using the Bsmi R2 Signaling Capability CPE Signaling Model CPE Signaling ModelNovember 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 ProtocolNovember 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 EnumerationNovember 348 IISDNR2MFCFORWARDACTIONS Forward ChannelNovember 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 L3L4mSETUPINDL4L3mCONNECTREQUEST L3L4mCONNACKIND L4L3mCLEARREQUEST L3L4mCLEARREQUEST L3L4mDISCONNECT L4L3mCLEARREQUEST Host L3L4mCLEARREQUEST Call Tear DownNovember 361 November 362 L4L3mCLEARREQUEST Host L3L4mCLEARREQUEST L4L3mCASCHANBLOCK L3L4mCASCHANBLOCKED Channel BlockingNovember 363 November 364 Packaging Your Application for Windows November 365 Windows Server 64 bit Package Options Package OptionsNovember 366 Installation InstallationInstalling Modules Installing Virtual Modules SR140 November 368 Installing SoftwareInstalling 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 Name Value Registry EntriesNovember 373 November 374 Reboot OptionsShortcuts Name Location November 375 Installation November 376 About the Merge Module FeatureConfigurable Brooktrout SDK Installation Options Dynamically Linked DLLs dynamicdlls.msm Dynamicdllsx64.msm Dynamically Linked 64-bit DLLsNovember 377 File Names Configuration and Protocol Files configdata.msmNovember 378 November 379 Firmware firmware.msm November 380 Configuration Tool configtool.msmShortcut 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.msmFile File Name Default Location Number Service Name Default Start Mode Integrating the Modules Installing the Merge Module FeatureNovember 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 ComponentsNovember 390 November 391 November 392 Plug and Play Installation ScenariosBrooktrout Plug and Play Components Reference Brooktrout Component User places November 393 November 394 About the INF File Structure of the Brooktrout PnP FolderNovember 395 Class = Computer Telephony Class Guid About the Dialogic Brooktrout Plug and Play Co-InstallerNovember 396 November 397 Should You Launch the Configuration ToolWhen Should You Launch the Configuration Tool Displaying the Found New Hardware November 398 About the Device Property November 399 Modifying Configuration Files Modifying Configuration FilesNovember 400 Parameter Description User-Defined Configuration File btcall.cfgNovember 401 November 402 Including the Brooktrout Configuration ToolCall Control callctrl.cfg Configuration File Including the Brooktrout Configuration Tool Downloading Firmware Files Downloading Firmware FilesNovember 403 Removing Software Removing SoftwareNovember 404 Expand the Brooktrout Hardware node Removing the Plug and Play DriverFor Earlier Versions Prior to ¾ To remove an earlier version of the Plug and Play driver ¾ To remove the Plug and Play driver For VersionNovember 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 asctog3Asctog3 argument-list Where Asctog3 -imemo.txt -fibmpcps.fnt G3chop -s5 -c20 -isalute.301 -oadvert.301 Cut and Paste UtilitiesCut Utility g3chop G3chop -sx -cy -ifile1.301 -ofile2.301 Where November 412 Paste Utility g3combinG3combin file1.301 file2.301 file3.301 -l -s -pad G3combin -1 lethd.301 sign.301 busrpt.301 November 413 Epson to Fax Conversion Utility epstog3Epstog3 argument-list Where Epson to Fax Conversion Utility epstog3 November 414 Epstog3 -icap001.epc November 415 Fax Display and Edit Utility Supershow ssSs-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 g3cvtG3cvt ifmt ifile ofmt ofile options G3 Conversion Utility g3cvt November 418 G3cvt MMR fax.mmr MH fax.mh Print Utility p Print Utility pNovember 419 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 Facility ChannelExternal-Telephony Mode Millennium Address LapdidLine Logical channel number Unit number StreamT1/E1 span Time slotPage 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