Structures and Return Values, Callres | Dialogic 6.2 guide

The Bfv API Functions

	Structures and Return Values
	The Bfv API uses argument structures to pass values to and from
	functions. The application declares the argument structure and
	passes a pointer to it to the function. The argument structure type is
	named args_...; for example, struct args_speech. The same
	argument structure type is used for functions that are related or in
	the same category.
	Contained within the argument structure are structure fields that
	are used for input and/or output. Each function that uses an
	argument structure has marked the fields that are used for each
	purpose. Not all fields are used by all functions taking any particular
	argument structure type.
	Result structures are the most commonly used structures to return
	information to the function. They are:
RES	Returns status information in res.status and some additional
	information in res.line_status.
CALL_RES	Returns information about a call such as its type and destination. If
	applicable, ISDN information such as called party and redirect
	information are returned as well.

November 2009

34

Image 34

Dialogic 6.2 manual Structures and Return Values, Callres

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 Operating System Support Related DocumentsManual Conventions 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 Module Status and Monitoring Functions Debugging, Error Handling, and Return ValuesFunctions Structures and Return Values Callres Miscellaneous Functions and Macros Bfv Call Control Call ControlBSMI-Level 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 Creating an Infopkt Stream Infopkt StreamMkinfopk -o outputfname infopkttype arg Index to prompt file Indexed Prompt File MkpromptEmbedded speech file Simple Speech File Mkinfopk 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 Recording and Playing Voice Developing a Voice ApplicationDeveloping a Voice Application Recording Voice Arguments Using Prompt Files Using Prompt FilesPlaying Back the Voice Message Using the mkprompt Utility Creating a New Prompt File Sending and Receiving a Fax Developing a Fax ApplicationUpdating an Existing Prompt File 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 Bfv API Debug Mode Bfv API Debug ModeBfvDataFSK Dump History BfvLineDumpStructureBfvLineDumpStructure Invoking Dump History Dump History Most recent application corresponding L1A 01 Admin 08 Event 06 Flowcontrolstatus Interpreting the Output Event Logging Lines Status Header LineEvent Logging Line Format Timing Information Parsed Command InformationParsed Command Information Event Descriptions Parsed Command Information Utility Programs for Debugging Bsmi Message Tracing Command SyntaxBsmi Debugging Running a Layer 2 Trace Level 2 Trace Example November 102 Value Meaning Trace Report ValuesNovember 103 Interpreting the I Frame Header Understanding Trace Hexadecimal StringsNovember 104 Bits Interpreting the Message HeaderBits Byte General I Frame Hex November 106 Hex Message Interpreting Information ElementsNovember 107 Hex Information Element IE Formats 931 Information Element IdentifiersNovember 108 November 109 Vtty Tracing Feature November 110 Command Meaning Vtty Console CommandsVtty Commands November 111 ¾ To start the Vtty Tracer, enter Setting Output OptionsVtty Tracer GUI November 112 ¾ Use the File menu to connect to a module Connecting to a ModuleNovember 113 Using the Trace Menu November 114 Using the Memory Menu November 115 Show Menu Information About Options Using the Show MenuNovember 116 Vtty Trace Results November 117 Call Tracer Call TracerNovember 118 Brktcctrace -x 10 -n 5 -oc\Brooktrout\brktlogxxx.txt Command SyntaxArguments November 119 Configuration File Format November 120 November 121 November 122 # OFF November 123 November 124 November 125 Page Boardmon November 127 Boardmon Boardmon -m mod -s span -d -v -hNovember 128 Btver BtverSample boardmon Output November 129 Connlist -m mod ConnlistBtver -m mod Connlist Csend CsendNovember 131 Deact DeactNovember 132 November 133 Debugcontrol DebugcontrolNovember 134 Decode -f filename DecodeExample Decode filename.ips Dfax DfaxDivert November 136 Dlfax DlfaxNovember 137 Dstrip -o outputbasedcxfilename DstripDlfax -l Dlfax options infopkt file Dstrip Eccllvoice EccllvoiceNovember 139 Fax FaxEccllvoice options infopktfile November 140 Faxhl options infopktfile FaxhlFax options infopktfile Faxhl Faxll FaxllNovember 142 November 143 Faxml FaxmlF1 f2 -a f3 -b -g f4 November 144 Faxp options FaxpFaxpml Faxp Faxpml options FeatureFeature -m mod action Actions November 147 Firm FirmFirm -m mod -c confspec -t type firmwarefile November 148 Firmload FirmloadFirmload -c confspec -d -b 01-q -e firmwaredir modulenum November 149 Firmload Brooktrout/boston/fw FontFirmware Type Filename Font -m mod -q -d Ipstrip IpstripIpstrip -h -o outputbase filename November 151 Ivr options IvrMkdcx Mkdcx -o dcxfile pcxfilename Mkinfopk MkinfopkMkinfopk -o outputfname -i inputfname Infopkttype arg November 153 Tag type November 154 Mktiff -o tifffile g3filename MkpromptMktiff Mkprompt Argument ModinfoModinfo -p -c -s -h -H -a mod Modinfo Playp -u unit promptfile phrasenum PlaypRtp Rtp -u unitno -v or Rtp -a Shoparam TelresetArguments Telsave -m mod -v -s Telreset -m modTelsave Telsave Tiffdump -d tifffilename TfaxTiffdump Tfax Tones options TonesTransfer Tones Transfer Transfer options phonenumNovember 162 Transfer.exe -u 0 -m 1 -t bstdialcomplete w110 TransferllExamples Transfer.exe -u 0 -m 1 -t bstalerting w110 Transfer Transferll November 164 Trombone TromboneNovember 165 Trombone options TstripRoot@RedHat9 bapp.src$ make others Tstrip Voice VoiceTstrip -h -o outputbase -r tifffilename November 167 Voice options infopktfile November 168 Voiceraw VoicerawNovember 169 Wave WaveNovember 170 Name November 171 November 172 File Naming Conventions Using Brooktrout FilesNovember 173 ¾ To compile the sample applications Compiling Sample Applications Using MakefilesCompiling Sample Applications Using Makefiles November 174 Compatibility for Compiling Combining the Sample ApplicationsNovember 175 Transferring Calls November 176 Making Call Transfers Using Bfv Making Call Transfers Using BfvNovember 177 High-level Call Transfer using Bfv November 178 Low-level Call Transfer using Bfv November 179 Making Hookflash Transfers Using Bfv ApplicationsMaking Hookflash Transfers November 180 Using Bsmi Applications November 181 Making Two B-Channel Transfers Making Two B-Channel TransfersNovember 182 November 183 Making Call Transfers Using Qsig Making Call Transfers Using QsigSupplementary Services Support November 184 BfvCallReject followed by BfvCallWaitForRelease Enablecalldiversion flagBFfvCallWaitForDivert, and BfvLineDivert. Once the call BfvLineTransferCapabilityQuery. However you must connect Bfv APIs Associated with Qsig November 186 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 Making Two-Channel Call Transfers Tromboning Out TSlot November 192 Connections for a Two-Channel Call Transfer November 193 Actions During a Two-Channel Call Transfer Performing Echo CancellationNovember 194 November 195 Required Connections for Echo Cancellation November 196 Person B Playing Back Voice RecordingsNovember 197 Channel InOut Silence TSlot November 198 Terminating the Two-Channel Call Transfer November 199 Disconnecting Resources November 200 November 201 Transferring Calls Using Release Link Trunk Transfer Transferring Calls Using Release Link Trunk TransferNovember 202 L4L3CALLREQUEST November 203 Network Host Call Control Sequence DiagramsNon-RLT Call Transfer November 204 RLT Call Transfer November 205 November 206 Sample Application November 207 L4L3cntlp L4toL3struct Msg L4L3cntlp = &msg November 208 November 209 Call Hold Values for L4L3mUNIVERSAL messages Placing Calls on Hold Using BsmiPlacing Calls on Hold Using Bsmi November 210 = Mtdlretrieverej November 211 Placing Calls on Hold Using Bsmi November 212 Page Managing Fax and Voice over IP Sessions November 214 Managing Calls Using IP Telephony Managing Calls Using IP TelephonyNovember 215 Adding IP Call Control using the Bfv API November 216 Outgoing IP Calls November 217 Incoming IP Calls November 218 Verifying Dialed Strings Using a SIP Proxy ServerUnderstanding SIP Functionality November 219 November 220 ¾ initiates the following sequence of events November 221 Sample Invite Request November 222 SIP Invite November 223 November 224 Bfv final call Progress code Response Code Call Progress ValuesMapping of SIP responses to Bfv FCP values November 225 Understanding H.323 Functionality November 226 Using H.323 Address Forms November 227 Phone Number November 228 November 229 Common Failures Failover Based on Telephony Cause CodesOverview Failover Based on Telephony Cause Codes November 231 Failover Cause Codes Description Failover ScenariosNovember 232 Known Failover Cause Code Data Known Failures From Various GatewaysSIP November 233 SIP November 234 November 235 SIP to Q.931 Conversion SIP Cause Description SIP to Q.931 ConversionNovember 236 SIP Cause Description November 237 Processing Media Using the T.38 Protocol Processing Media Using the T.38 ProtocolNovember 238 November 239 November 240 Sending and Receiving Faxes November 241 Configuring T.38, RTP and IP Call Control Activities Configuring T.38, RTP and IP Call Control ActivitiesNovember 242 Troubleshooting TroubleshootingNovember 243 Understanding the SIP Protocol Understanding the SIP ProtocolIntroduction to 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 Using Third Party IP Stacks Using Third Party IP StacksNovember 256 Integrating Bfv IP Fax November 257 Components November 258 SR140 Software-Based Integration Linux ConfigurationDisable ECC Component November 259 TR1034 Board-Based Integration Linux November 260 Inbound Call Call NegotiationNovember 261 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 Definition Default Value Robbed Bit Signaling TimersTimer November 269 November 270 November 271 Granularity Definition Default Value November 272 November 273 November 274 Timing Diagrams November 275 Wink Start & Delay Dial Signaling Wink Start & Delay Dial SignalingNovember 276 Incoming Call Processing November 277 Wink Start and Delay Dial Incoming Call Timing November 278 Call Teardown Processing Outgoing Call ProcessingNovember 279 Wink Start and Delay Dial Outgoing Call Timing November 280 Wink Start with Feature Group B & D Wink Start with Feature Group B & DNovember 281 November 282 Iisdn SMI Messages November 283 November 284 Revised 20-Oct-03 Rev1.4 Incoming Call Processing Immediate Start Immediate Start/Fixed Pause SignalingImmediate Start/Fixed Pause Signaling November 285 Start/Fixed Pause Signaling Timing DiagramImmediate 286 Outgoing Call Processing Fixed Pause Mode November 287 Fixed Pause Outgoing Call Timing Diagram November 288 FXO Ground Start Ground Start SignalingGround Start Signaling Incoming Call Processing November 290 FXO Ground Start Incoming Call Timing Diagram November 291 Call Teardown Processing Outgoing Call ProcessingNovember 292 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 Loop Start Signaling Loop Start SignalingNovember 302 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 Isdn Call Processing OverviewMaking an Isdn Incoming Call November 318 L43.data.enable November 319 Isdn Incoming Call November 320 Making an Isdn Outgoing Call November 321 Isdn Outgoing Call November 322 Isdn Overlapped Dialing Isdn Call Clearing Initiated by ModuleNovember 323 Isdn Call Clearing Initiated by Module November 324 Isdn Call Clearing Initiated by Network November 325 Isdn Call Clearing Initiated by Network November 326 Translating Q.931 to Simple Message Interface Translating Q.931 to Simple Message InterfaceNovember 327 Using the overlaprcv feature of L4L3mENABLEPROTOCOL Using the overlaprcv feature L4L3mENABLEPROTOCOLWhat is Overlap Receive? November 328 Bsmi Reference Notes November 329 November 330 Network Brooktrout Controller Host 921/Q.931 Timers 921/Q.931 Timers921 Timers Level 2 Parameters Data Type Mnemonic Definition November 332 Data Type Mnemonic Definition 921 Timers Level 2 Parameters931 Timers Level 3 Parameters November 333 November 334 Page Using the Bsmi R2 Signaling Capability November 336 CPE Signaling Model CPE Signaling ModelNovember 337 Line Signaling Model State CAS Bits Outbound AB Inbound AB November 338 November 339 November 340 Inter-register Signaling November 341 Enabling the R2 Protocol Enabling the R2 ProtocolNovember 342 R2 Digital Line Signaling Parameters November 343 November 344 Protocol Control November 345 Dnis November 346 IISDNR2MFCPGROUPB Calledlineconditions November 347 Protocol Parameter Mechanics IISDNR2MFSIGNALCODES EnumerationNovember 348 IISDNR2MFCFORWARDACTIONS Forward ChannelNovember 349 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 L4L3mCLEARREQUEST L3L4mCLEARREQUEST L3L4mPRESEIZE L3L4mSETUPINDL4L3mCONNECTREQUEST L3L4mCONNACKIND November 360 L3L4mDISCONNECT L4L3mCLEARREQUEST Host L3L4mCLEARREQUEST Call Tear DownNovember 361 L4L3mCLEARREQUEST Host L3L4mCLEARREQUEST November 362 L4L3mCASCHANBLOCK L3L4mCASCHANBLOCKED Channel BlockingNovember 363 Packaging Your Application for Windows November 364 Windows Server 64 bit November 365 Package Options Package OptionsNovember 366 Installing Virtual Modules SR140 InstallationInstalling Modules Installation Options for Spawning MSI Installing SoftwareInstalling the Brooktrout SDK November 368 Brooktrout Fax Software System Files November 369 November 370 Install Location File Name Purpose November 371 November 372 Name Value Registry EntriesNovember 373 Name Location Reboot OptionsShortcuts November 374 Installation November 375 Dynamically Linked DLLs dynamicdlls.msm About the Merge Module FeatureConfigurable Brooktrout SDK Installation Options November 376 Dynamicdllsx64.msm Dynamically Linked 64-bit DLLsNovember 377 File Names Configuration and Protocol Files configdata.msmNovember 378 Firmware firmware.msm November 379 ¾ Depends on the following modules Configuration Tool configtool.msmShortcut Name Target November 380 TECUpdate TECUpdate.msm November 381 License Manager softwarelicense.msm November 382 Utility Programs utilities.msm November 383 Service Name Default Start Mode Boston Host Service bostsrv.msmFile File Name Default Location Number November 384 Integrating the Modules Installing the Merge Module FeatureNovember 385 „ dynamicdllsx64.msm independent modules November 386 Case November 387 Merging Modules into a Single Feature November 388 Merging Modules into Multiple Features November 389 About Plug and Play Components About Plug and Play ComponentsNovember 390 November 391 Reference Brooktrout Component Plug and Play Installation ScenariosBrooktrout Plug and Play Components November 392 November 393 User places 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 Displaying the Found New Hardware Should You Launch the Configuration ToolWhen Should You Launch the Configuration Tool November 397 About the Device Property November 398 November 399 Modifying Configuration Files Modifying Configuration FilesNovember 400 Parameter Description User-Defined Configuration File btcall.cfgNovember 401 Including the Brooktrout Configuration Tool Including the Brooktrout Configuration ToolCall Control callctrl.cfg Configuration File November 402 Downloading Firmware Files Downloading Firmware FilesNovember 403 Removing Software Removing SoftwareNovember 404 ¾ To remove an earlier version of the Plug and Play driver Removing the Plug and Play DriverFor Earlier Versions Prior to Expand the Brooktrout Hardware node ¾ To remove the Plug and Play driver For VersionNovember 406 For 64-bit operating system November 407 Appendix a November 408 Utility Cut and Paste Utilities November 409 Asctog3 -imemo.txt -fibmpcps.fnt Ascii to Fax Conversion Utility asctog3Asctog3 argument-list Where Ascii to Fax Conversion Utility asctog3 G3chop -sx -cy -ifile1.301 -ofile2.301 Where Cut and Paste UtilitiesCut Utility g3chop G3chop -s5 -c20 -isalute.301 -oadvert.301 G3combin -1 lethd.301 sign.301 busrpt.301 Paste Utility g3combinG3combin file1.301 file2.301 file3.301 -l -s -pad November 412 Epson to Fax Conversion Utility epstog3 Epson to Fax Conversion Utility epstog3Epstog3 argument-list Where November 413 Epstog3 -icap001.epc November 414 Fax Display and Edit Utility Supershow ss Fax Display and Edit Utility Supershow ssSs-rhceveava-xs#-ys#-x#-y#-w#-m# -ifilename November 415 Ss -rv -iletsig.301 November 416 G3 Conversion Utility g3cvt G3 Conversion Utility g3cvtG3cvt ifmt ifile ofmt ofile options November 417 G3cvt MMR fax.mmr MH fax.mh November 418 Print Utility p Print Utility pNovember 419 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 Mode ChannelExternal-Telephony Facility Logical channel number LapdidLine Millennium Address Time slot StreamT1/E1 span 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