Dialogic® Brooktrout® Fax Products SDK Developer Guide Release 6.2 November 2009 931-132-06 www.dialogic.
Copyright and Legal Notice Copyright © 1998-2009 Dialogic Corporation. All Rights Reserved. You may not reproduce this document in whole or in part without permission in writing from Dialogic Corporation at the address provided below. All contents of this document are furnished for informational use only and are subject to change without notice and do not represent a commitment on the part of Dialogic Corporation or its subsidiaries ("Dialogic").
Hardware Limited Warranty Warranty for Hardware Products: Dialogic Corporation or its subsidiary that originally sold the hardware product ("Dialogic") warrants to the original purchaser of this hardware product, that at the time of delivery the hardware product supplied hereunder will be free from defects in material and workmanship. This warranty is for the standard period set out on Dialogic's website at http://www.dialogic.
page 4
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 Proce
Contents Chapter 1 – About this Publication . . . . . . . . . . . . . . . . . . . . . . . . . 16 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Related Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Operating System Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Manual Conventions . . . . . . . . . . .
Contents BSMI-Level Call Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Media Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Signal Generation and Tone Detection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Voice Record and Play . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Fax Functions . . . . . . . . . . . . . . . .
Contents Determining Fax Status Information from an Application . . . . . . . . . . . . . . . . . . . . . . . 89 Chapter 4 – Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 This chapter describes how to use the debugging tools. Bfv API Debug Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 BfvDataFSK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents boardmon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . btver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . connlist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . csend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents tones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . transferll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . trombone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Transferring Calls Using Release Link Trunk Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Bfv Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using BSMI Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Call Control Sequence Diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Non-RLT Call Transfer . . . . . . . . . . . . . . .
Contents Introduction to the SIP Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview of SIP Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview of Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Third Party IP Stacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Integrating Bfv IP Fax .
Contents Outgoing Call Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Call Teardown Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FXS Ground Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Incoming Call Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Outgoing Call Processing . . . . . . . . . . . . .
Contents CPE Signaling Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Enabling the R2 Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Protocol Parameter Mechanics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Forward Channel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Removing the Plug and Play Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405 For Earlier Versions (Prior to 5.2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405 For Version 5.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406 Appendix A – G3 Legacy Utilities . . . . . . . . . . . . . . . . . . . . . . . . .
About this Publication Introduction The Dialogic® Brooktrout® Fax Products SDK Developer Guide describes the Bfv API used to create applications to control the features of the Dialogic® Brooktrout® TR1034® Fax Boards, Dialogic® Brooktrout® TruFax® Fax Boards, and the Dialogic® Brooktrout® SR140 Fax Software. The manual gives information about Call Transfer, Automatic Speech Recognition, IP functionality, and BSMI functionality.
R2 signaling Chapter 11 describes how to package software supporting Brooktrout software or SR140 Fax in your product. Appendix A provides instructions for a set of legacy G3 utility programs. Appendix B provides instructions for recompiling the Boston driver to support new kernel patches. A glossary gives definitions for some of the terms used in the manual.
Italics denote the names of variables in the prototype of a function and file names, directory names, and program names within the general text. The Courier font in bold indicates a command sequence entered by the user at the system prompt, for example: cd /Brooktrout/boston/bfv.api The Courier font not bolded indicates system output, for example: C:>Files installed. The Courier font also denotes programming code, such as C, C++, Microsoft® Visual Basic®, and TSL.
Terminology Updated Terminology The current version of this document includes terminology that differs from previous versions. Please note the changes below: Former Terminology Replaced with...
Dialogic® Brooktrout® TR1034 Fax Board Terminology The Dialogic® Brooktrout® TR1034 Fax Board is also referred to herein by one or more of the following terms, or like terms including “TR1034”: November 2009 Brooktrout TR1034 Fax Board Brooktrout TR1034 Board TR1034 Fax Board TR1034 Board TR1034 20
Getting Technical Support Dialogic provides technical services and support for customers who have purchased hardware or software products from Dialogic. If you purchased products from a reseller, please contact that reseller for technical support. To obtain technical support, please use the web site below: www.dialogic.
1 - Introduction to the Dialogic® Brooktrout® Bfv API This chapter describes the Dialogic® Brooktrout® Bfv API and its capabilities.
Bfv API and Associated Libraries Bfv API and Associated Libraries The Bfv Application Programming Interface (API) provides a set of functions that enables applications programmers to write telephony- or packet-network applications that run on Brooktrout’s telecommunications boards or SR140 Fax software products. Using the Bfv API, you can generate sophisticated, multichannel voice, fax, and conferencing applications under Linux, Solaris, and Windows® operating systems.
Bfv API and Associated Libraries By using the Bfv API libraries, the application running on the host processor can communicate through the Boston driver and firmware to one or more Brooktrout boards. Figure 1. Bfv Application Configuration Fax boards have an exact module number of the TR1034 or TruFax® board as indicated on the rotary switch on top of the board, so you can have control over channels on individual boards in a multi-board system.
Bfv API and Associated Libraries Tool. You can also configure H.323 support using the configuration file. See the installation and configuration guide that came with your software for more information about configuring for H.323. The TR1034 Boston modules are driven by the Bfv API. Call control on Boston modules is driven by BSMI. The Bfv API libraries are based on the BTLINE structure, which is a logical abstraction of a physical channel.
The Bfv API Functions The Bfv API Functions The Bfv API functions in all the Bfv API libraries are separated into categories according to the tasks they perform.
The Bfv API Functions Administration, Management, and Configuration Administration and Initialization Functions and Macros The administration and initialization functions allow you to: Attach and detach from a line or a session. Configure the module instead of using a user-defined configuration file such as btcall.cfg. Interrupt a thread or process on an active line. Reset the specified channel. Get information about the module and channel address for the specified channel.
The Bfv API Functions The BTLINE Structure When an application calls the BfvLineAttach (or BfvSessionAttach) function to open and attach a specified channel, the function creates a separate BTLINE structure for a channel and returns a pointer to the line structure. All information about the channel is stored in its BTLINE structure, but only the line state, the line type, and channel number are actually relevant. The BfvLineDetach (or BfvSessionDetach) function deallocates a BTLINE structure.
The Bfv API Functions Hereafter each of the line states is referred to by the descriptive part of its name only (for example, LINE_STATE_IDLE is referred to as IDLE). The current state of the line is stored in the BTLINE structure. A pointer to this structure is passed as an argument to nearly all Bfv API entry points and is provided to the application by the BfvLineAttach function.
The Bfv API Functions Channel Numbering The Bfv API uses two numbering schemes when referencing channels within a system. One is the unit number or ordinal channel number; the other is the logical channel number. The unit number is a number range 0…n-1, where n is the number of channels in the system. The BfvLineAttach function uses the unit number in its argument and returns a pointer to the BTLINE structure, providing a means to reference the channel in future function calls.
The Bfv API Functions Firmware Functions and Macros 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 m
The Bfv API Functions Configuration Files The Bfv API uses several configuration files that let you configure the Bfv API and driver, call control, and country-specific parameters. These files are described below. Sample versions of the files are stored in the directory brooktrout/boston/config. The user-defined configuration file A file that contains configuration parameters for the Bfv API and driver. A sample of this file, called btcall.
The Bfv API Functions Module Status and Monitoring Functions With the module status and monitoring functions, you can: Set and get the state of the module by reading the status LED. Set the module temperature threshold. Get the temperature of the module. Have the module perform a series of self tests and, optionally report the results. Have the module notify the application of events or conditions on the module such as a network alarm, network error, H.100/H.
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.
The Bfv API Functions Miscellaneous Functions and Macros Some administration functions and macros cannot be classified with other functions, but are useful in various ways. For example: November 2009 _dll... functions for use on Windows® operating systems. These functions call standard C library functions such as fopen, fclose, fread, and fwrite; their arguments use the runtime library linked with the DLL. The getopt function parses command line options in a UNIX environment.
The Bfv API Functions Call Control Call control functions enable the application to set up, initiate, connect, disconnect, and perform other tasks related to the telephone network. Three forms of call control are available: Bfv high-level and low-level and BSMI-level. Bfv Call Control High-level Bfv call control functions simplify the process of accessing the telephone system. Some of the high-level functions call the low-level Bfv call control functions to automatically perform the low-level tasks.
The Bfv API Functions Typically, the BSMI is used as one component of a system. Firmware download, for example, is achieved using the call control functions of the Bfv API. Through the Bfv API, you can perform all appropriate configuration and management functions for the Boston series of products. BSMI is used by the Bfv call control functions to perform call processing. BSMI is a level lower than the Bfv API, providing greater flexibility.
The Bfv API Functions Media Processing Media processing refers to the application that is performed on the Brooktrout modules. Depending on the product configuration, it can include: Signal generation and detection Voice play and record Faxing File format manipulation Signal Generation and Tone Detection With the signal generation and tone detection functions, you can: Play call progress signals and generate other tone groups and tone patterns. Get the next call progress code.
The Bfv API Functions Voice Record and Play With the Bfv voice record and play functions, the application can: Open, play, and close a previously recorded prompt file. Record speech into an infopkt stream, a raw speech data buffer, a raw speech file, or a wave file. Play back speech from an infopkt stream, a raw speech data buffer, a raw speech file, or a wave file. Modify the volume and rate of a speech playback while it is in progress.
The Bfv API Functions Fax Functions The Bfv API provides a wealth of fax functions that allow you to control every aspect of sending and receiving V.17 or V.34 faxes. The fax functions are divided into high-, mid-, and low-level functions. Volume 4, Fax Processing, Bfv API Reference Manual provides a detailed description of each Bfv function. Generally, the high-level functions simplify the process of transmitting and receiving facsimiles.
The Bfv API Functions Combining the high-, mid-, and low-level functions within the same application program is valid and useful. Need for the low-level calls depends on the degree of flexibility and functionality an application requires. Table 1 contains a partial list of the high-, mid-, and low-level functions that perform fax tasks. Table 1.
The Bfv API Functions In addition, the fax functions are divided into two subgroups: those that process infopkt-formatted data files and those that process ASCII or G3 data files in other formats. For fax functions that process raw ASCII or G3 data files rather than infopkt-formatted data files, see Volume 4, Fax Processing, Bfv API Reference Manual.
The Bfv API Functions For voice applications, infopkts provide an easy means to build sophisticated interactive voice systems. Using infopkts, a voice application can create a master prompt file that builds all of the system's prompts out of short phrases. This scheme: Reduces the amount of disk space needed for storage. Enables the application to build new prompts as changing demands on the system dictate.
The Bfv API Functions Tag Infopkts Contain speech parameter structures (which describe the sample rate, coding format, and data format of the speech or indicate the end of speech playback), and fax parameter structures (which describe a strip or page of data, the line parameters, or control parameters). They are: INFOPKT_ASCII_STRIP_PARAMETERS Tag containing parameters for ASCII data strip.
The Bfv API Functions Data Infopkts Contain just the header and data, permitting applications to organize large files as a sequence of small data infopkts. They are: INFOPKT_ASCII ASCII data. INFOPKT_G3 G3 data. INFOPKT_PROMPT_MAP Used only in prompt files. Contains information on how to find each of the phrases in the prompt file. INFOPKT_SPEECH Speech data in any of several coding formats.
The Bfv API Functions User-Defined Infopkts Contain a header (the document’s title, the subject of the document, or the total number of pages that the document contains) and user-defined information (document summary and statistics, etc.) useful to an application. When the Bfv API encounters these infopkt types, it ignores them. See the BfvInfopktUser function in Volume 4, Fax Processing, Bfv API Reference Manual. They are: INFOPKT_USER0_USER1....
The Bfv API Functions The Infopkt Stream An infopkt stream is a file or memory buffer containing concatenated individual infopkts. The length of an infopkt stream is limited only by the file size conventions specific to an operating system. The BfvInfopktOpen function opens file-based infopkt streams, and the BfvInfopktOpenMem function opens memory-based infopkt streams. For speech record and play applications, the first infopkt in the infopkt stream depends on the type of speech file.
The Bfv API Functions Indexed Prompt File (mkprompt) Simple Speech File (mkinfopk) _SPCH_PARAMS _PROMPT_MAP smp rate, coding fmt, bitssmp, afe rate, data fmt Index to prompt file _SPEECH Speech Data CVSD, ADPCM, PCM, OKI _SPEECH Speech Data CVSD, ADPCM, PCM, OKI _SPEECH Speech Data CVSD, ADPCM, PCM, OKI embedded speech file _SPCH_PARAMS smp rate, coding fmt, bitssmp, afe rate, data fmt _SPEECH Speech Data CVSD, ADPCM, PCM, OKI _SPEECH Speech Data CVSD, ADPCM, PCM, OKI _SPEECH _END_OF_SPEECH Sp
The Bfv API Functions To create an infopkt stream file to test the fax functionality of your hardware and software: mkinfopk -o fax.ips doc 1 ascii fax.c Where: fax.ips Is the name of the output infopkt stream file that contains the ASCII file fax.c (the sample fax application program included on your distribution CD). doc Is required as the first infopkt in a stream (1 is its argument). See mkinfopk on page 153 for more information about doc. ascii Indicates that the input file fax.
The Bfv API Functions START * optional/conditional _DOC_PARAMS res, len., width * _T.30_PARAMS bit rate, scan time * _PAGE_PARAMS * _STRIP_PARAMS G3, ASCII DATA INDIR_DATA G3, ASCII G3, ASCII, DCX, TIFF _B_O_P Figure 3.
The Bfv API Functions Infopkt Structure Every infopkt consists of a header and data. The 4-byte header consists of a type code and a length. The type code defines the infopkt type, and the length field indicates the total length of the infopkt, including the header. Data consists of raw data, formatting parameters or, in the case of indirect infopkts, pointers to other files. The maximum length of an individual infopkt is 30,000 bytes, but Dialogic recommends limiting the size to approximately 1K.
The Bfv API Functions Fax Infopkt Parameters The T.30 protocol requires two communicating fax machines to agree on several transmission parameters at the beginning of a facsimile transmission. These transmission parameters include the bit rate, scan time, coding scheme, and the basic document format parameters – vertical resolution, page width, and page length. The least capable fax machine determines the values of these parameters; both fax machines adjust to the final values.
The Bfv API Functions The strip parameters infopkts: INFOPKT_ASCII_STRIP_PARAMETERS INFOPKT_G3_STRIP_PARAMETERS define the actual strips of data that make up a page and must precede an ASCII or G3 data type infopkt only to change the default or previously applied strip parameter values (see Volume 6, Appendix E in the Bfv API Reference Manual for default values).
The Bfv API Functions When a single G3 strip consists of multiple G3 infopkts, do not insert an INFOPKT_G3_STRIP_PARAMETERS infopkt between the G3 infopkts. Figure 4 illustrates how an electronic mail document (ASCII), accompanied by a cover sheet, a letterhead, and a signature, could be delivered to a fax machine. Fax Document, Page 1 cover sheet lettrhed.g3 Doc_Parameters G3_Strip_Parameters G3 (data; cover sheet) letterhead Dialogic Corp lettrbod.
The Bfv API Functions This two-page document contains a G3 fax document as a cover page. INFOPKT_G3 (Cover sheet; G3 data) It is followed by a page boundary tag, INFOPKT_BEGINNING_OF_PAGE. The data for the cover sheet is stored in the infopkt stream. INFOPKT_BEGINNING_OF_PAGE (Cover sheet is on its own page) INFOPKT_G3_STRIP_PARAMETERS (Parameter Structure) The second page starts with a G3 document containing the letterhead. It is stored in a separate file.
2 - Developing Applications Using the Bfv API This chapter describes how to develop applications with Brooktrout Fax Software.
Developing a Voice Application Developing a Voice Application Recording and Playing Voice The following steps for recording and playing back speech are demonstrated: How to record voice How to play back previously recorded voice These steps are the same for all supported operating systems. To record and then play speech back, first select the voice channel on which you want to record your message. Then, use the voice.
Developing a Voice Application Recording Voice 1. Prepare channel 2 to record your message: voice -u 2 -r voice.ips The command voice invokes the voice.c program, whose arguments include: Arguments -c num Call the given number, else wait for ring.
Using Prompt Files 2. Dial the phone number of the channel you selected. Make sure the phone line is attached to the selected channel. The voice.c program does not indicate when to begin recording. Begin recording when the line goes off-hook (when you no longer hear ringing). Playing Back the Voice Message ¾ Request that a channel (0 in the example) play back your previously recorded message stored in voice.ips. 1. At the system prompt, type: voice -u 0 -p voice.ips 2.
Using Prompt Files Using the mkprompt Utility The mkprompt utility converts multiple infopkt files into a Brooktrout prompt file and updates an existing Brooktrout prompt file by adding new phrases or modifying existing phrases. When you create a Brooktrout prompt file, the mkprompt utility automatically assigns each infopkt file a phrase number, sequentially, in the order that you enter each file name at the command line.
Developing a Fax Application Updating an Existing Prompt File To update an existing Brooktrout prompt file, at the command line type: mkprompt -u phrase_num prompt_file phrase.pkt: Where: -u Specifies the update command. phrase_num Provides the index number to assign the infopkt-formatted input file. prompt_file Provides the name of the prompt file. phrase.pkt Provides the name of the infopkt-formatted prompt file to add to the prompt file.
Developing a Fax Application Sending a Fax from One Channel to Another ¾ Use the fax sample program to send a fax from one channel to another in your system. 1. Prepare channel 1 to receive a fax: fax -u 1 -r recfile.ips fax invokes the sample fax program with the following arguments: -u Specifies that the following number is the number of the channel that receives a fax (in this case channel 1 is used). -r Places the channel (1) in receive mode. recfile.ips Creates a file, recfile.
Developing a Fax Application Sending a Fax to a Channel from an External Fax Machine Use the fax.c sample program to send a fax from an external fax machine to a channel in your system. Then send the same fax back to the same fax machine from the same channel in your system. 1. Prepare channel 1 to receive a fax as you did in the previous example. Use the same input filename recfile.ips used to send a fax from one channel to another in the same system: fax -u 1 -r recfile.
Developing a Fax Application Using Bfv API Fax Functions The following sections show how to send and receive facsimiles using the high- and low-level function calls, noninfopkt function calls, and TIFF-F function calls. It also shows how to send and receive facsimiles in MR and MMR format, access infopkt streams and TIFF-F fax files from an application, combine data on a single page using TIFF-F fax files, interpret fax status information from an application, and how to use prompt files.
Developing a Fax Application args_admin.config_file_name = "usrcnfig.cfg"; BfvLineReset(lp,&args_admin); Resets the channel and sets the user-configured options selected in the user-defined configuration file named, usrcnfig.cfg. BT_ZERO(args_infopkt); args_infopkt.fname = name; args_infopkt.fmode = "r"; ips = BfvInfopktOpen(&args_infopkt); Opens the infopkt-formatted file called name for reading and transmission. BT_ZERO(args_tel); args_tel.phonenum = "w7814499009"; args_tel.
Developing a Fax Application args_admin.config_file_name = "usrcnfig.cfg"; BfvLineReset(lp,&args_admin); Resets the channel and sets the user-configured options selected in the user-defined configuration file named usrcnfig.cfg. BT_ZERO(args_infopkt); args_infopkt.fname = name; args_infopkt.fmode = "w"; ips = BfvInfopktOpen(&args_infopkt); Opens the infopkt-formatted file called name for writing. BT_ZERO(args_tel); args_tel.
Developing a Fax Application args_admin.config_file_name = "usrcnfig.cfg"; BfvLineReset(lp,&args_admin); Resets the channel and sets the user-configured options selected in the user-defined configuration file named usrcnfig.cfg. BT_ZERO(args_infopkt); args_infopkt.fname = name; args_infopkt.fmode = "r"; ips = BfvInfopktOpen(&args_infopkt); Opens the infopkt-formatted file called name for reading and transmission. BT_ZERO(args_tel); args_tel.
Developing a Fax Application for (;;) { BT_ZERO(args_fax); args_fax.s_ips = ips; if ((ret = BfvFaxNextPage(lp, &args_fax)) <= 0 ) break; BfvFaxSendPage(lp, &args_fax); } Loops through the infopkt stream, getting the next page and transmitting it to the driver. BfvFaxEndOfDocument(lp, &args_fax); Finishes up when the infopkt stream is exhausted. BT_ZERO(args_infopkt); args_infopkt.ips = ips; BfvInfopktClose (&args_infopkt); Closes the infopkt stream file after the file is sent.
Developing a Fax Application args_admin.config_file_name = "usrcnfig.cfg"; BfvLineReset(lp, &args_admin); Resets the channel and sets the user-configured options in the user-defined configuration file usrcnfig.cfg. BT_ZERO(args_infopkt); args_infopkt.fname = name; args_infopkt.fmode = "w"; ips = BfvInfopktOpen(&args_infopkt); Opens the infopkt-formatted file, name, to store the received fax. BT_ZERO(args_tel); args_tel.
Developing a Fax Application BT_ZERO(args_admin); BfvLineDetach (lp, &args_admin); Frees all the memory for the attached line and closes the device. You can replace some low-level functions with a high-level function, for example: BfvFaxBeginReceive BfvFaxGetRemoteInfo BfvFaxSetLocalId BfvFaxWaitForTraining BfvFaxReceivePages These low level functions are replaced with the high level function BfvFaxReceive. See the applications in the sample application directory for more detailed information.
Developing a Fax Application BT_ZERO(args_t30); args_t30.bit_rate = BITRATE_14400; args_t30.scan_time = SCANTIME_0; BfvFaxT30Params(lp,&args_t30); Configures the channel's maximum transmission rate. This function is optional. BT_ZERO(args_page); args_page.top_margin = 0; args_page.bottom_margin = 0; args_page.length = 1143; args_page.ascii_pad = 1; args_page.image_pad = 0; args_page.image_break = 0; args_page.
Developing a Fax Application BT_ZERO(args_strip); args_strip.fmt = DATA_ASCII; args_strip.resolution = RES_200H_100V; args_strip.width = WIDTH_A4; args_strip.left_margin = 5; args_strip.right_margin = 0; args_strip.line_spacing = 2; args_strip.eof_char = 0x1a; BfvFaxStripParams(lp,&args_strip); Sets the ASCII parameters for the ASCII strip main.txt, since it differs from the default. BT_ZERO(args_fax); args_fax.fname = "main.txt"; args_fax.
Developing a Fax Application BT_ZERO(args_fax); args_fax.fname = "memo.txt"; args_fax.fmt = DATA_ASCII; BfvFaxSendFile(lp, &args_fax); Sends the ASCII text file, memo.txt the only file on the second page, to the driver. BfvFaxEndOfDocument(lp, &args_fax); Indicates to the driver that the second page is the last page of the transmission. BT_ZERO(args_admin); BfvLineDetach (lp, &args_admin); Frees all the memory for the attached line and closes the device.
Developing a Fax Application BT_ZERO(args_fax); args_fax.local_id = "Id_string"; BfvFaxSetLocalID(lp,&args_fax); Sets the local ID to transmit to the sending machine. BT_ZERO(args_fax); BfvFaxBeginReceive(lp, &args_fax); Begins the Phase B handshaking procedure. BfvFaxGetRemoteInfo (lp, &args_fax); Waits for the remote to send its ID and capabilities. Note: The previous phone call is terminated by the application if the remote fax machine's ID does not match the expected value.
Developing a Fax Application Sending a Fax Using Calls for TIFF-F Files One way to send a fax using function calls for TIFF-F files is demonstrated below. Each function is presented in sequential order, and the action it performs is described beneath it. BT_ZERO(args_admin); args_admin.unit = unit; lp = BfvLineAttach(&args_admin); Attaches to a free channel and gets a line pointer. args_admin.config_file_name = "usrcnfig.
Developing a Fax Application for (;;) { BT_ZERO(args_fax); args_fax.s_tp = tp; args_fax.combine = 0; if (BfvFaxNextPageTiff(lp,&args_fax) <= 0) break; BT_ZERO(args_fax); args_fax.s_tp = tp; if (BfvFaxSendPageTiff(lp,&args_fax) < 0) break; } Loops through the TIFF-F file, getting the next page and sending it to the driver. BfvFaxEndOfDocument(lp, &args_fax); Finishes up when the TIFF data is exhausted. BT_ZERO(args_tiff); args_tiff.
Developing a Fax Application BT_ZERO(args_tel); args_tel.timeout = 0L; BfvLineWaitForCall (lp, &args_tel); Waits for the detection of an incoming call. BfvLineAnswer (lp, &args_tel); Answers the phone line by going off-hook. BT_ZERO(args_fax); args_fax.local_id = "Id_string"; BfvFaxSetLocalID(lp,&args_fax); Sets the local ID to transmit to the sending machine. BT_ZERO(args_fax); BfvFaxBeginReceive(lp, &args_fax); Begins the Phase B handshaking procedure.
Developing a Fax Application Receiving and Storing a Fax in MMR or MR Format Receiving an Infopkt-Formatted Fax and Storing it in MMR Format A typical way to receive a fax that is made up of infopkts and store it in MMR format is demonstrated below. Each function is presented in sequential order, and the action it performs is described beneath it. When MR or MMR facsimiles are received in infopkt format, the data format type specification is automatically included through the g3strppkt infopkt structure.
Developing a Fax Application BT_ZERO(args_fax); args_fax.fmt = FMT_MMR_ALIGN_MSB; BfvFaxSetReceiveFmt(lp,&args_fax); Sets the format used to pass the received fax data from the channel to the computer. In this example, MMR data format – byte aligned, most significant bit first – is specified. See the fmt parameter description for detailed information on all of the data format types that are available through BfvFaxSetReceiveFmt. BT_ZERO(args_fax); args_fax.r_ips = ips; args_fax.
Developing a Fax Application BT_ZERO(args_fax); args_fax.fmt = FMT_MR_UNALIGN_MSB; BfvFaxSetReceiveFmt(lp,&args_fax); Sets the format used to pass the received fax data from the channel to the computer. In this example, MR data format – byte unaligned, least significant bit first – is specified. See the fmt parameter description for detailed information on all of the data format types that are available through BfvFaxSetReceiveFmt. BT_ZERO(args_fax); args_fax.
Developing a Fax Application BfvFaxEndReception(lp, &args_fax); Call this function when there are no more pages to receive. BT_ZERO(args_admin); BfvLineDetach (lp, &args_admin); Frees all the memory for the attached line and closes the device. Sending a Noninfopkt-Formatted Fax Stored in MMR Format One way to send a fax using function calls for noninfopkt-formatted raw G3 files is demonstrated below. Each function is presented in sequential order, and the action it performs is described beneath it.
Developing a Fax Application args_page.length = 1143; args_page.ascii_pad = 1; BfvFaxPageParams(lp,&args_page); Sets the page parameters: no top or bottom margins, a page length of 1143 (normal) G3 lines, and no padding of short ASCII pages, no padding of short images, no breaking of images, and no margins for images. BT_ZERO(args_fax); args_fax.resolution = RES_200H_100V; args_fax.
Developing a Fax Application Accessing an Infopkt Stream from an Application The function calls BfvFaxSendPage and BfvFaxNextPage are typically used in a loop. Both read infopkts from the infopkt stream for processing. BfvFaxSendPage reads infopkts and processes them in a loop.
Developing a Fax Application Processing, Bfv API Reference Manual for detailed information on how to access user-defined infopkts when using the INDIR_MODE_FOLLOW_NOUSER flag. Sending a TIFF-F Fax File Within an Infopkt Stream Transmitting a fax stored as a TIFF-F file is accomplished using the TIFF-F fax routines, as described earlier in this chapter, or using an infopkt of type INFOPKT_INDIR_TIFF within an infopkt stream. TIFF files contain resolution and width parameters for each page.
Developing a Fax Application The second method uses the normal TIFF sending functions to transmit a TIFF file that is preceded or succeeded by other G3 or ASCII files that are transmitted with either the noninfopkt-formatted raw data fax functions or the TIFF file fax functions.
Developing a Fax Application /* A call to BfvFaxStripParams must be done */ /* here for combination with previous G3 */ /* data (from TIFF file)*/ BT_ZERO(args_strip); args_strip.fmt = DATA_G3; args_strip.resolution = RES_200H_100V; args_strip.width = WIDTH_A4; BfvFaxStripParams(lp,&args_strip); BT_ZERO(args_fax); args_fax.fname = "g3_file"; args_fax.
Developing a Fax Application BT_ZERO(args_strip); args_strip.fmt = DATA_G3; args_strip.resolution = RES_200H_100V; args_strip.width = WIDTH_A4; BfvFaxStripParams(lp,&args_strip); BT_ZERO(args_fax); args_fax.fname = "g3_file"; args_fax.fmt = DATA_G3; BfvFaxSendFile(lp, &args_fax); BfvFaxEndOfDocument(lp, &args_fax); Accessing a TIFF-F File from an Application Although applications can directly read and write TIFF-F files with a set of Bfv library functions, some knowledge of TIFF-F file format is useful.
Developing a Fax Application if ((n = BfvTiffReadImage(&args_tiff)) <= 0) break; process_image(buf,n); } args_tiff.tp = tp; BfvTiffClose(&args_tiff);} my_ifd_func(tp, ifd_ptr, arg) { /* Does nothing,just returns */ return (0); } The BfvTiffWriteImage and BfvTiffWriteIFD functions are used to write a new TIFF file. BfvTiffWriteImage receives data from a user-supplied buffer until the end of the page is reached. The BfvTiffWriteIFD function is called repeatedly with IFD entry information.
Developing a Fax Application BfvTiffWriteImage(&args_tiff); args_tiff.ifd_field = &ifd_field; while (determine_next_ifd(&ifd_field) > 0 && BfvTiffWriteIFD(&args_tiff) == 0); args_tiff.ifd_field = NULL BfvTiffWriteIFD(&args_tiff); args_tiff.tp = tp; BfvTiffClose(&args_tiff); } Determining Fax Status Information from an Application An in-progress fax transmission or reception has a number of attributes that an application might find useful to access.
Developing a Fax Application Transfer Mode The application normally keeps track of its own operation mode (transmitting or receiving), but it can also use the LINE_DCS (see Volume 4, Fax Processing, Bfv API Reference Manual) macro to get this information. Current Page Transmission Parameters The application can use the LINE_DCS macro to access information about the currently transmitting page; this information might change between pages.
3 - Debugging This chapter describes how to use the debugging tools.
Bfv API Debug Mode Bfv API Debug Mode Some components of the Bfv API have their own unique debug functions to produce debug information relevant only to that component. The output from these functions is combined to provide a unified debug output if desired.
BfvLineDumpStructure BfvLineDumpStructure The BfvLineDumpStructure function (Volume 1, Bfv API Reference Manual) dumps the contents of the BTLINE structure into a file. It writes each element of the line structure individually. Use this call to create error report logs (along with the contents of Dump History) and to track changing states of the line.
Dump History Invoking Dump History You can invoke Dump History from within an application or directly from the command line. From within an application, one of: The C system function BfvHistoryDumpModChan (args) See Volume 1 of the Bfv API Reference Manual for detailed information on how to use the BfvHistoryDump... functions. As a stand-alone utility, as follows: dh [-C] [-f] [-r [-b]] [-R file offset] [-P pktver] [-H hdr_dir] module channel -C Clear the history buffer, do not print entries.
Dump History module 0 The most recent application corresponding to channel as an ordinal unit. module FE The fixed application history corresponding to channel as index. Normally all history is collected in a single main history buffer accessible as module 1 channel 1. During driver configuration, you can choose a number of physical history buffers and application history buffers.
Dump History Interpreting the Output The output from Dump History consists of a status header line at the beginning followed by command logging lines. The output looks similar to this: Hist Mod 1/Chan 1 Mon Jun 9 14:02:27 2003, Windows, V4700/B13/P5111/I25: 14:02:20.28.0000827C "PIPR: GDI_PHY_PIPR_MsgReceive (01 01 02 01)" 14:02:20.28.0000827D "PIPR: fnGenericPIPR_MsgReceive (01 01 02 01) NQ = 1 HQ = 0" 14:02:20.28.
Dump History 14:02:20.52.00008291 "M2: Queued incoming packet" Pkt bytes: 17 00 24 02 02 FE 01 01 01 02 01 0C 00 08 03 04 79 01 00 00 04 09 01 00 00 LE (01) ADMIN (08) EVENT (03) FW_DOWNLOAD_FINISHED (79) CURRENT_STREAM [01: Fix Uns Short Unitless] 0000 (09) DOWNLOAD_RESULT [01: Fix Uns Short Unitless] 0000 14:02:20.52.00008292 "PIPR: GDI_PHY_PIPR_MsgSend" 14:02:20.52.00008293 "PIPR: fnPIPR_MsgSend BufID = 51A s(01 01 02 01) d(02 02 FE 01) NQ = 0 HQ = 0" 14:02:20.52.
Parsed Command Information Timing Information Timing information is reported first and usually takes the form: hr:min:sec.fracts.sequence For example: 11:12:25.512934.0000827C The sequence field counts each event added to the history entries and is unique over all history buffers. Gaps in the sequence numbers occur when events occur in other history buffers. Sequence numbers are displayed in hex and wrap at 0xffffffff.
Parsed Command Information First is the facility value in parentheses followed by the name of the facility (01 and ADMIN). Next is the command verb value followed by the name of the command verb (08 and EVENT). Last is the command specifier value followed by the name of the command specifier (03 and FW_DOWNLOAD_FINISHED). The example command contains 2 tags directly within it. Looking at the first one, the line describing a tag starts with the tag ID value and tag name (79 and CURRENT_STREAM).
Utility Programs for Debugging Utility Programs for Debugging The following sample applications/utilities are available to help you in debugging your applications by giving you information about modules in the system such as the firmware, driver, connections, etc. btver btver gives you version information for the driver, Bfv API, boot ROM firmware, control processor firmware, and DSP firmware. See btver on page 129 for more information.
BSMI Debugging BSMI Debugging The debug output is controlled using the regular mechanisms provided with the Bfv API. Included in the debug output are diagnostic strings including BSMI message tracing and network layer tracing. BSMI Message Tracing vtty The vtty program displays layer 2, 3, and 4 messages (depending on user settings).
BSMI Debugging The trace information is embedded within the Bfv API debug output, see Figure 5 for a sample output.
BSMI Debugging Table 2. Trace Report Values Value Meaning Ch# Lapdid number. This is an even number where 0=Port A 2=Port B Time Hexadecimal timestamp incremented at 1 ms intervals. Direct Direction of frame; possible values are Xmit (transmitted by module) and Rcvd (received by module). SAPI Service Access Point Identifier which identifies the type of D-channel signaling performed; possible values are 00 (ISDN call control) or 63 (management procedures).
BSMI Debugging Understanding Trace Hexadecimal Strings The hexadecimal string displayed in the trace consists of the following components: Information (I) Frame header Note: A trace displays hexadecimal strings for I Frame messages only. Supervisory (S Frame) messages, such as Receiver Ready (RR), and Unnumbered (U Frame) messages, such as SABME and UA, are not displayed in hexadecimal format.
BSMI Debugging Bits Bits 8 7 6 5 4 3 2 1 Byte 0 1 1 1 1 1 1 0 1 8 7 6 5 4 Example 3 2 0 0 0 0 0 0 0 0 00 TEI 1 3 1 1 0 0 0 0 0 1 C1 N(s) 0 4 0 0 0 0 0 0 0 0 00 N(r) P/F 5 0 0 0 0 0 0 0 0 00 See See Figure Figure 77 - - - - - - - - - - - - - FCS - - - - - - - - - - - - - n-2 n-1 Not Shown in Trace n Not Shown in Trace 1 1 - Not Shown in Trace Message 1 1 0 C/R SAPI 0 2 1 1 1 0 General I Frame Example SETUP I Fram
BSMI Debugging The Message type value 0x05 identifies the D-channel message as a SETUP; refer to Table 3 on page 106 for possible Q.931 message type values.
BSMI Debugging Table 3. Q.931 Message Types (Continued) Message Type Bits Hex Message 0 1 1 1 1 0 1 1 7B Information 0 1 1 0 1 1 1 0 6E Notify 0 1 1 1 1 1 0 1 7D Status 0 1 1 1 0 1 0 1 75 Status Enquiry Interpreting Information Elements For Q.931 call control messages, the first Information Element (IE) starts at byte offset 9 in the hexadecimal string. Each message can contain several IEs of either fixed (single byte) or variable length.
BSMI Debugging p 8 7 6 Byte 8 7 6 5 4 3 2 1 IE Identifier 1 0 0 0 0 0 1 0 0 04 Length of IE (in bytes) 2 0 0 0 0 0 0 1 0 02 3 1 0 0 0 1 0 0 0 0 5 4 3 2 1 - Contents of IE 88 Transfer capability 1 0 0 1 0 0 0 0 Transfer mode and rate 90 Figure 8. IE Formats Table 4. Q.
BSMI Debugging Table 4. Q.
BSMI Debugging VTTY Tracing Feature The VTTY tracing provides access to control processor internals and diagnostic tracing information. Two VTTY applications are provided: VTTY Console Commands on page 111 VTTY Tracer GUI on page 112 (Windows® operating systems only) These applications allow users to enter commands that enable tracing capabilities or retrieve any saved information blocks.
BSMI Debugging VTTY Console Commands Specifically, you can use the VTTY commands to show argument information, tracing information, access memory locations and get help. Table 5 shows the command syntax and describes the action that is performed. (See Table 2 on page 103 for a definition of “lapdid”. Table 5. VTTY Commands Command Meaning > help Returns a menu of supported commands with syntax. Same as help.
BSMI Debugging VTTY Tracer GUI The VTTY Tracer graphical user interface provides access to control processor internals and diagnostic tracing information from a Windows® environment. ¾ To start the VTTY Tracer, enter: vtty_tracer.exe The VTTY Tracer screen is displayed. Setting Output Options From the main screen, you can change the tracer output options.
BSMI Debugging 1. Click Settings|Options. The Tracing Options dialog is displayed. Set where the trace output is saved, either screen or file. The maximum file size is set in MBytes. Once a file reaches its maximum size, the tracing output loops back to the beginning of the file. The user always has the number of MBytes of information entered. You can change these options any time during execution (while tracing or before connecting to a module). 2. Click OK to save your tracing options.
BSMI Debugging 3. Click OK. The connection confirmation is displayed in the VTTY Tracer screen: Using the Trace Menu When you choose options from the Trace menu, multiple items are selected.
BSMI Debugging In this example the Command 12 turns on Layer 2 tracing. This feature allows support of new tracing options without additional coding or installation. Using the Memory Menu Click the Memory menu to read and write predefined sizes of memory. Using the Memory menu requires extreme care. Reading or writing memory to the module can cause irreparable harm. This menu should never be used unless explicitly directed to do so by Dialogic Technical Services and Support.
BSMI Debugging Using the Show Menu The Show menu causes a set of predefined variables to be displayed: Show Menu Options Information About tmr Timer structure in the call control protocols lapdid The specified D-channel lap The LAP-D (Q.921) protocol q931 The Q.931 ISDN call control protocol dass The DASS-2 call control protocol dpnss The DPNSS-1 call control protocol pump Internal operations Each menu choice produces a dialog box where another selection is made from a drop down box.
BSMI Debugging VTTY Trace Results Figure 9 shows the results of a VTTY trace. Figure 9. VTTY Trace Example Each trace message (for both screen and trace file output) is prefixed with a time stamp in the same format used for the call control trace files and the Bfv API application debug log files. The time reference for this time stamp is the local host time.
Call Tracer Call Tracer Dialogic provides a Call Tracer command line utility that collects call trace information in an active system. The output is intended for Dialogic Technical Services and Support, but it is important that all users know how to use Call Tracer to create the output file, if Dialogic Technical Services and Support personnel request it. The Call Tracer utility can be started before or after starting the client application.
Call Tracer Command Syntax brktcctrace [-o ] [-i ] [-t ] [-x ] [-n ] [-h] Arguments -o Fully qualified path of the output file/log file including the log filename. example: c:\Brooktrout\brktlog_xxx.txt, where xxx is the client port number. The path containing spaces should be added between double quotes. This is a mandatory parameter. -i Path of the input filter configuration file including the file name.
Call Tracer Configuration File Format This section describes the filter configuration file format. Because the configuration file is optional, there is no default. Lines that start with a ‘#’ character are comments only. The filter settings are not case sensitive. All the settings are printed in upper case for uniformity. If the configuration file has multiple entries for the same filter settings, the first setting is used.
Call Tracer ######################################################## Filter Settings Configuration File ######################################################## #------------------------------------------------------# CONFIG Legal Values # ON # # OFF # - Default value will be set when a filter setting is not listed in the filtersettings.cfg file. - Filter settings which are not listed in the filtersettings.cfg file will be disabled.
Call Tracer #------------------------------------------------------# ECC Legal Values # NONE # ERROR # WARNING # BASIC # VERBOSE #------------------------------------------------------ECC.ECC_API = NONE ECC.ECC_HOST_MODULE = NONE ECC.ECC_INTERNAL = NONE ECC.ECC_IP_STACK = NONE ECC.ECC_L3L4 = NONE ECC.ECC_L4L3 = NONE #------------------------------------------------------# QSIG Legal Values # ON # OFF #------------------------------------------------------QSIG.QSIG_STACK.LAYER4_IN = OFF QSIG.
Call Tracer #------------------------------------------------------# VTTY Legal Values # ON # OFF # # The listed filters below use Module ID 0x02 as an example. # Update the module ID before using the VTTY filters. # Add separate entries for multiple modules. # # There are 3 keywords that can be used in a VTTY filter name: # MODULE, SPAN, and CHAN. The index for each of the keywords # is base 0. The table below shows which keywords are available # for which filters.
Call Tracer # # So to trace SMI for module 2 add: # VTTY_MODULE.MODULE02.VTTY_MAIN.SMI = ON # # To trace CAS L3L4 for module 2 on span1, channel 1 add: # VTTY_CHAN.MODULE02.SPAN01.CHAN01.VTTY_CAS.L3L4 = ON # # Refer to the developer guide for additional usage # information. #------------------------------------------------------VTTY_MODULE.MODULE02.VTTY_MAIN.LAP = OFF VTTY_MODULE.MODULE02.VTTY_MAIN.SMI = OFF VTTY_MODULE.MODULE02.VTTY_CAS.CALLERID = OFF VTTY_MODULE.MODULE02.VTTY_CAS.
Call Tracer VTTY_MODULE.MODULE02.VTTY_LE58.CONFIG = OFF VTTY_MODULE.MODULE02.VTTY_LE58.CURRENT_TIME = OFF VTTY_MODULE.MODULE02.VTTY_LE58.DEVICE_MGMT = OFF VTTY_MODULE.MODULE02.VTTY_LE58.EXCEPTION = OFF VTTY_MODULE.MODULE02.VTTY_LE58.HW_ACCESS = OFF VTTY_MODULE.MODULE02.VTTY_LE58.LINE_STATUS = OFF VTTY_MODULE.MODULE02.VTTY_LE58.RING_COUNT = OFF VTTY_MODULE.MODULE02.VTTY_LE58.
4 - Sample Applications and Utilities This chapter describes the sample applications and utilities that come as part of the Dialogic® Brooktrout® SDK. Dialogic includes a large collection of sample application programs and utilities with the Bfv API modules. Sources for the sample applications are located in either boston/bfv.api/app.src or boston/bfv.api/bapp.src, except for a few applications whose directories are stated in the text.
boardmon the state of the signaling bits and alarms. It also counts the errors (e.g., framing errors, CRC errors, clock slips, BPVs) on each span. It only works with spans that are configured for robbed-bit signaling and where telephony connections have been made. The spans are numbered starting from 1 which is the first interface on a module. The btcall.cfg file is the user configuration file. The boardmon application is found in the bapp.src directory.
btver Sample boardmon Output Board Temperature: 105.8F Ethernet link 0: UP Mod 0x03 Span 1 41.0C No Alarms FRM 000000 Ch: 1 In: a.aa b.bb c.cc d.dd 5 .aaa .bbb .ccc .ddd 9 13 17 21 aaaa .aaa aa.a aaa. bbbb .bbb bb.b bbb. cccc .ccc cc.c ccc. dddd .ddd dd.d ddd. Out: A.AA B.BB C.CC D.DD .AAA .BBB .CCC .DDD AAAA BBBB CCCC DDDD .AAA .BBB .CCC .DDD AA.A BB.B CC.C DD.D .... .... .... .... .... .... .... .... .... .... .... .... .... .... .... ....
connlist Command Syntax btver [-m ] [-v] Arguments -m Display version info for specified module only. Otherwise display for all. -v Turn on Bfv API debug mode. The firmware must be downloaded on a module to obtain its control processor and DSP information. connlist The connlist program lists currently established call switching connections.
csend csend This application uses low-level, noninfopkt, raw-data, fax-sending routines to send facsimiles. It allows sending a single fax page either in standard fax format from an MH/MSB G3 data file or in an enhanced fax format (e.g. JPEG, JBIG) from an EFF data file. T.30 holdup is used to check on the receiver's capabilities before deciding which type of file to send. Turn on the Bfv API debug program from the command line. The btcall.cfg file is the configuration file.
deact Arguments -c Color or other enhanced fax file, default: c1.jpg -e Enhanced Fax Format (EFF) options, default: 3 OR together the following hex values: 1 = JPEG Enable 2 = Full Color 4 = Default tables 8 = 12-bit (vs. 8-bit) 10 = No Subsampling 20 = Custom Illuminant 40 = Custom Gamut 100 = JBIG 200 = JBIG L0 400 = Lossless Color 800 = MRC 1000 = MRC 2000 = MRC 4000 = Plane Interleave 8000 = Page Length Strip -g Black and white MH file, default: eagle.
deact Command Syntax deact [-a] [-s] Arguments November 2009 -a Deactivate all modules on the board containing . -s The value of is interpreted as a cPCI slot number. Module to deactivate.
debug_control debug_control The debug_control utility allows a user to selectively turn on logging remotely in an application. The application gives the user the ability to control all the debug options available in the BfvDebugModeSetAdv function. Command Syntax debug_control [-v] [-u chan] [-d debug_mode [-f file1 [-f file2 [-m max_size]]]] [-F 0|1 [-a]] [-c debug_type[,...] [-l level] [-L file]] Arguments -d = Set Bfv API debug mode, optionally with file or files with limit.
decode decode The decode program reads a specified infopkt stream file and lists the individual infopkts that comprise the stream. The decode program is found in the app.src directory. Command Syntax decode [-f] Arguments -f Directs decode to follow indirect infopkts and decode the contents, instead of listing file names. The name of the infopkt stream file to read. Example decode filename.
dfax dfax The dfax program uses the low-level Intel DCX fax transmitting and receiving routines to send and receive facsimiles. Turn on the Bfv API debug program from the command line. The btcall.cfg file is the user configuration file. The dfax program is found in the app.src directory. Command Syntax dfax [-u ] [-v] -s or dfax [-u ] [-v] -r Arguments The name of the file to send or receive. -r Receive mode.
dlfax 3. If the incoming call is accepted, the divert program uses the speed_infopkt_file recording and playing routines to record and play speech. Command Syntax divert [-d ] [-e ] -j [-u ] [-s ] -p -r Arguments -d Divert to a given number, or else wait for a diverted-to call. -e If -d, then -e specifies the redir_reason (default is DIVERT_UNCONDITIONAL). -j If waiting for a diverted-to call, reject the diverted-to call.
dstrip Bfv API debug mode is turned on. The btcall.cfg file is the user configuration file. The dlfax program is found in the app.src directory. Command Syntax dlfax -l or dlfax [options] Arguments -c Use the dialing restrictions for the country specified by ccode. This value must be one of the numeric values listed in ccode.h. The name of the infopkt file to send. -l List contents of the dialing database. -s Send to given phone number.
eccllvoice eccllvoice The eccllvoice program is used to record and play speech for ISDN calls. It uses the speech-infopkt-file recording and playing routines to record and play speech. Recording continues for a maximum of ten seconds or the time specified in the -n option. eccllvoice uses low-level call control function calls as shown in the following table.
fax Command Syntax eccllvoice [options] infopktfile Arguments -c -f Call given number, else wait for ring. Specify record coding format1; use the number of the format or one of the following names. If there is no number specified, you must use the name. adpcm adpcm32 adpcm24 pcm_ulaw pcm_ulaw64 pcm_ulaw48 pcm_ulaw88 pcm_alaw pcm_alaw64 pcm_alaw48 pcm_alaw88 1 2 3 -l Loop forever, sending or receiving. -n Specify recording time in seconds. -p Play. -r Record (default 10 seconds).
faxhl Command Syntax fax [options] Arguments Name of the file to send or receive. -l Set local ID. -L Loop for testing. -r Receive a fax. -s Send to given phone number. -u Use specific channel number. -w On receive, do not wait for ring. Requires one -s or -r argument. faxhl The faxhl program uses the highest level infopkt file fax sending and receiving routines to send or receive facsimiles.
faxll faxll The faxll program uses the low-level non-infopkt raw data fax sending and receiving routines to send or receive facsimiles. This application uses the BfvFaxSendFile function, so 128-byte Brooktrout headers are not permitted. It also uses the user function feature of BfvLineOriginateCall to print call progress values. Use the -g or -a argument to specify that the next raw data file contains G3 or ASCII data, respectively. If a file contains fine resolution data, use the -F argument.
faxll Command Syntax faxll [-u ] [-v] [-h] [-H] -s [-F] [-E #] [-g] [-a] [-p] [-b] ... or faxll [-u ] [-v] [-p] -r ... Arguments -a The following files are raw ASCII text. -b Beginning of page. -E # The next page is an enhanced fax format page. # specifies the format, which is created by ORing the following hex values: 1 = JPEG Enable 2 = Full Color 4 = Default tables 8 = 12bit (vs.
faxml When sending, the application can mix G3 and ASCII files. Example -g f1 f2 -a f3 -b -g f4 When receiving, each filename in the list receives a page of G3 data, so make sure that enough filenames appear in the list to accommodate all pages of incoming data. faxml The faxml program uses the mid-level infopkt file fax sending and receiving routines to send or receive facsimiles. Turn on the Bfv API debug program from the command line. The btcall.cfg file is the user configuration file.
faxp faxp The faxp program uses the highest level infopkt file fax polling routines to send and/or receive facsimiles. You must specify if the program is going to call (-c) or answer (-a) and one send file (-s), one receive file (-r), or one of both. This program performs the ordinary sending and receiving functions and all possible polling variations. The local ID is specified from the command line. Bfv API debug mode is turned on. The btcall.cfg file is the user configuration file.
feature Command Syntax faxpml [options] Arguments -a Answer. -c Dial given phone number. -L Loop for testing. -r File to receive, if permitted. -s File to send, if permitted. -u Use specified channel number. Requires one -s or one -r argument or one of each, and one -c or one -a argument. feature The feature program manipulates feature set data on the product. It can query or download feature set data.
feature feature downloads ASCII license (feature) files by default, and can also accept binary data if you use the -b option.
firm firm The firm program is used to download firmware. The firmware consists of several types, by number, which must be downloaded in the proper sequence. firmload automatically takes care of identifying the proper files and downloading them in the correct sequence. The sequence is as follows: Type 2 (PROC_APP) = Control processor firmware Type 1 (DSP_APP) = DSP firmware Bfv API debug mode is turned on. The btcall.cfg file is the user configuration file. The firm program is found in the bapp.
firmload firmload The firmload program is used to download a complete set of standard firmware files to all hardware modules on all boards in a system. The standard firmware files are listed in Chapter 9 in the installation and configuration guide that came with your software and in the Release Notes. Downloads, by default, are attempted for all hardware modules in the range 2 through 0xFD. The firmware consists of several types, by number, that must be downloaded in the proper sequence.
font The firmload program ensures that the required firmware files exist in the specified directory before beginning a download. There are multiple possibilities for some of the firmware filenames. These are listed in the following list in search order. firmload looks for the following: Firmware Type Filename PROC_APP cp.bin DSP_APP dsp1000.hex, dsp1000_ld.hex, dsp1000_v34.
ipstrip ipstrip The ipstrip program removes the infopkt header from the G3 or speech data in a specified infopkt stream file and writes each page of the converted data to a file, g3data.30x. The first page of converted data is written to the file g3data.301, the second to the file g3data.302, the third to the file g3data.303, and so on until the entire infopkt stream file is converted. All speech data is placed in a single file.
ivr ivr The ivr program is a small, interactive, voice-response system that permits users to receive a fax, send a fax, record a message and play a message. It uses the speech infopkt-file recording and playing routines and the highest level infopkt-file fax receiving and sending routines. The ivr_msg subdirectory contains all prerecorded files, and all new files are created in that subdirectory. Bfv API debug mode is turned on. The btcall.cfg file is the user configuration file.
mkinfopk mkinfopk The mkinfopk program builds an infopkt stream file. The mkinfopk program is found in the app.src directory. Command Syntax mkinfopk -o [-i ] {infopkt_type arg}... Arguments -o The name of the output file. -i Infopkt type specifications are included in the file input_fname instead of the command line. infopkt_type The type of infopkt that follows. arg An argument value for the infopkt.
mkinfopk Tag type doc, g3_strip, ascii_strip, page, t30, bop, spi, eos, fax_hdr, eff. For tag (parameter setting) infopkts, the argument value is not normally used, and mkinfopk inserts a dummy value. When you do not specify an argument value, mkinfopk uses hard-coded default parameter values. If, however, arg is the @ character, mkinfopk prompts you to enter parameter values for this infopkt. (The bop type does not have parameters, so the @ character has no effect on it.
mkprompt mkprompt The mkprompt program creates or updates a prompt file from infopkt files that contain individual phrases. When updating, you can specify an existing phrase number or a new phrase number. The mkprompt program is found in the app.src directory. Command Syntax mkprompt []... or mkprompt -u Arguments Name of the prompt file to create or update.
modinfo If a raw G3 file has a 128-byte Brooktrout header (it is a btG3 file), mktiff uses the resolution, width, and number of scan lines from the header when storing the information for that page in the new TIFF file. If it does not encounter a header or if the number of scan lines is 0, mktiff counts the actual number of scan lines in the G3 input file. modinfo The modinfo program lists information about active hardware and software modules maintained within the driver.
playp For example, a module with 48 work channels is listed as having 49 channels, and a module with no work channels (no firmware downloaded) is listed as having one channel. playp The playp program waits for a call, then plays the specified sequence of phrases from the specified prompt file until the sequence completes or until the user presses the # key. Bfv API debug mode is turned on. The btcall.cfg file is the user configuration file. The playp program is found in the app.src directory.
shoparam Arguments -a All Channels -u Channel number. -v Turn on Bfv API debug mode. shoparam The shoparam program displays the contents of the line structure and the parameter values set in a user configuration file and the read-only parameters taken from the country configuration file. shoparam does not work unless a module is present in the system, the driver is installed and running, and the firmware is loaded and running on the module. The shoparam program is found in the app.
telsave Command Syntax telreset [-m ] Arguments -m Use the specified module (default 2). telsave The telsave program writes telephony parameters to a module’s Non-Volatile RAM (NVRAM). Bfv API debug mode is turned on. The btcall.cfg file is the user configuration file. The file callctrl.cfg is the call control configuration file. The telsave program is found in the bapp.src directory.
tfax tfax The tfax program uses the low-level TIFF-F file fax sending and receiving routines to send and receive facsimiles. Turn on the Bfv API debug program from the command line. The btcall.cfg file is the configuration file. The tfax program is found in the app.src directory. Command Syntax tfax [-u ] [-v] -s or tfax [-u ] [-v] -r Arguments -r Receive mode. -s Send mode. Name of the file to send or receive.
tones tones The tones program uses DTMF detection routines to detect and display incoming touchtones and DTMF generation and single frequency tone generation routines to produce touchtones and other tones. Turn on the Bfv API debug program from the command line. The btcall.cfg file is the configuration file. The tones program is found in the app.src directory. Command Syntax tones [options] Arguments -c Call given number, else wait for ring. -g Get tones and display them.
transfer Command Syntax transfer [options] phonenum Arguments phonenum Caller C’s telephone number. options -u unit_num The unit number to use. Value: 0 to (max channels-1) -m b_channel_mode The channel mode used if the protocol can do 1 or 2 B-channel transfer. If the protocol supports both, transfer capability is LINE_XFER_ALL. Different protocols support different modes: Hookflash supports 1 B-channel transfers. RLT supports 2 B-channel transfers.
transferll Examples ¾ Assume that 110 is phone number of caller C. 1. Transfer using 1 B-channel and complete transfer at the state BST_DIAL_COMPLETE: transfer.exe -u 0 -m 1 -t bst_dial_complete w110 2. Transfer using 1 B-channel and complete transfer at the state BST_ALERTING: transfer.exe -u 0 -m 1 -t bst_alerting w110 3. Transfer using 2 B-channels and complete transfer at the state BST_DIAL_COMPLETE: transfer.exe -u 0 -m 2 -t bst_dial_complete w110 4.
transferll The following list shows the call control functions used by transfer and transferll. transfer transferll BfvLineTransfer BfvCallHold and BfvCallWaitForHold BfvCallSetup and BfvCallWaitForComplete BfvCallTransferComplete and BfvCallWaitTransferComplete BfvLineHold BfvCallHold and BfvCallWaitForHold BfvLineRetrieve BfvCallRetrieve and BfvCallWaitForRetrieve Command Syntax transfer [options] phonenum Arguments phonenum Caller C’s telephone number.
trombone -m b_channel_mode The channel mode used if the protocol can do 1 or 2 B-channel transfer. If the protocol supports both, transfer capability is LINE_XFER_ALL. Different protocols support different modes: Hookflash supports 1 B-channel transfers. RLT supports 2 B-channel transfers. ETSI BRI, ETSI PRI, T1-ISDN, NTT BRI, and NTT PRI support both 1 and 2 B-channel transfers. Values: 1, 2 Note: This option does not support the LINE_XFER_TWO_CHAN_NEEDS_NAILUP transfer capability.
tstrip welcome prompt, the program dials an outbound call on the secondary channel. When the outbound call on the secondary channel is answered, the program connects the two parties together with a full duplex connection and records speech from the primary caller. The program terminates the tromboned call when either the recording session reaches a maximum timeout value or either of the callers hangs up. The trombone program is found in the app.src directory.
voice The tstrip program is found in the app.src directory. Bfv API debug mode is turned on. Command Syntax tstrip [-h] [-o ] [-r] Arguments -h Adds a 128-byte Brooktrout header to the beginning of each file. This header includes the resolution, width, and number of scan lines. -o Uses supplied output filename base to form filenames instead of “g3data”. -r Instructs tstrip to leave the data format as is.
voice Pressing the following keys on the telephone keypad affect the speed and volume at which the application plays back speech: 1 = increases the gain 2 = decreases the gain 3 = increases the speed 4 = decreases the speed Bfv API debug mode is turned on. The btcall.cfg file is the user configuration file. The voice program is found in the app.src directory. Command Syntax voice [options] Arguments -c Call given number, else wait for ring.
voiceraw voiceraw The voiceraw program uses the raw speech data file recording and playing routines to record and play speech. Recording begins when you start speaking. Recording continues for a maximum of ten seconds or the time specified in the -n option. Pressing # on the telephone keypad immediately terminates playback or recording.
wave Command Syntax voiceraw [options] Arguments -c Call given number, else wait for ring. -f Specify coding format; use the number of the format or one of the following names. If there is no number specified, you must use the name. adpcm adpcm32 adpcm24 pcm_ulaw pcm_ulaw64 pcm_ulaw48 pcm_ulaw88 pcm_alaw pcm_alaw64 pcm_alaw48 pcm_alaw88 1 2 3 -l Loop forever, sending or receiving. -n Specify recording time in seconds. -p Play. -r Record (default 10 seconds).
wave Pressing the following keys on the telephone keypad affect the speed and volume at which the application plays back speech: 1 = increases the gain 2 = decreases the gain 3 = increases the speed 4 = decreases the speed Bfv API debug mode is turned on. The btcall.cfg file is the user configuration file. The wave program is found in the app.src directory. Command Syntax wave [options] Arguments (Options) -c Call given number, else wait for ring.
Compiling Sample Applications Using Microsoft® Developer Studio Project Files Compiling Sample Applications Using Microsoft® Developer Studio Project Files The Brooktrout SDK CD includes Microsoft® Developer Studio Project files for all samples in the bfv.api\app.src samples directory, including project files for the following versions of Visual Studio®: Visual Studio® 6.0 (not recommended) Visual Studio® .
Compiling Sample Applications Using Microsoft® Developer Studio Project Files Using Brooktrout Files Dialogic has created a Microsoft Visual Studio® Workspace/Solution dsp file and vcproj file for each Brooktrout SDK sample in the boston\bfv.api\winnt\app.src directory in the Brooktrout SDK InstallShield package. You can see all the samples from a single workspace/solution by opening these files from the compiler application. Table 6.
Compiling Sample Applications Using Makefiles Compiling Sample Applications Using Makefiles The sample applications are distributed in source form and are compiled using the supplied makefile(s). The makefile(s) come set up to link the application programs with the Brooktrout Bfv API library. ¾ To compile the sample applications: 1. Change to the /boston/bfv.api//app.src directory.
Compiling Sample Applications Using Makefiles Combining the Sample Applications The sample applications provided with the Brooktrout SDK are combined or modified in a variety of ways to demonstrate key capabilities. Typically, combining these applications can require modifications to configuration files, such as callctrl.cfg. Compatibility for Compiling The current Brooktrout SDK is compatible with all prior Brooktrout SDK versions - 3.2 and later.
5 - Transferring Calls This chapter describes transferring calls using the Bfv API-level and BSMI-level call control functionality. Note: The Dialogic® Brooktrout® SR140 Fax Software does not support this functionality. Call transfer is a method of redirecting an incoming call to an internal line or “transferring” it from one channel to another channel. The phone network can also manage and disconnect the call. Call transfer functionality is supported on the board and inside a public switch.
Making Call Transfers Using Bfv Making Call Transfers Using Bfv The diagram in Figure 10 illustrates a transfer using the BfvLineTransfer high level call transfer function. The application issues a BfvLineTransfer function call to transfer a call. BfvLineTransferCapabilityQuery checks the transfer capability through LINE_XFER_ queries.
Making Call Transfers Using Bfv BfvLineTransfer LINE_XFER_ False SINGLE BfvLineTransferCapabilityQuery LINE_XFER_ False ALL True LINE_XFER_ TWO_CHAN LINE_XFER_NONE True True 2nd Channel Specified BfvCallSetup (Enquiry) BfvCallWaitFor Hold BST_DIAL_COMPLETE False BfvCallHold transfer_line_ state BST_ALERTING BST_CONNECTED BfvCallWaitFor Alerting supervised Yes BfvCallWaitFor Complete Successful BfvCallWaitFor Complete where CP is ring or connected No False BfvLineTransfer Complete
Making Call Transfers Using Bfv BfvLineTransfer Complete BfvLineTransfer Cancel BfvCallTransfer Complete BfvCallRetrieve BfvCallWait TransferComplete BfvCallWaitFor Retrieve BfvCallWaitFor Release End End Figure 11.
Making Hookflash Transfers Making Hookflash Transfers You can make hookflash call transfers using either the Bfv- level API or BSMI-level API. There are two types of hookflash transfers: Analog loop start signaling Transfers using loop start signaling commonly use hookflash. Hookflash allows for both blind and attended transfers using the same channel. In a blind transfer, the application drops out of the call before the transfer completes.
Making Hookflash Transfers To configure using configuration files: Set the port configuration for T1 RBS using the callctrl.cfg configuration file: port_config=t1_robbed_bit or for Analog, set: port_config=analog Set the protocol file for T1 Robbed Bit using the callctrl.cfg configuration file: protocol_file=C:\Brooktrout\Boston\config\winkstart.lec and for Analog, the protocol file is: protocol_file=C:\Brooktrout\Boston\config\analog_loopstart_us.lec Set the transfer_variant using the callctrl.
Making Two B-Channel Transfers Making Two B-Channel Transfers When making a two B-channel transfer, the central office connects two outside calls through the central office, freeing the B-channels to take more calls. You can only transfer calls using two B-channels on T1 ISDN PRI configurations. Bfv maintains a maximum of two calls per B-channel. Of these two calls, only one call is on hold at a time.
Making Two B-Channel Transfers For more information on the BfvCallHold function, refer to Volume 2, Bfv API Reference Manual. For more information on the Brooktrout Configuration Tool, refer to the chapter on using the configuration tool in the installation and configuration guide that came with your software.
Making Call Transfers Using QSIG Making Call Transfers Using QSIG ISDN QSIG QSIG is an ISO standard that defines the ISDN signaling and control methods used to link PBXs in private ISDN networks. The standard extends the “Q” point in the ISDN logical reference model, which was established by the ITU-T in its Q.93x series of recommendations that defined the basic functions of ISDN switching systems. QSIG is an ISDN based protocol for signaling between nodes of a Private Integrated Services Network (PISN).
Making Call Transfers Using QSIG Call Diversion Call Diversion (Unconditional, Busy and Not Responding) contains three scenarios: Originating - the board places a call and the far end attempts to divert the call to a different destination. You can set Originating to enable or disable through the call configuration file using enable_call_diversion flag. Served - the board receives an incoming call and attempts to divert it.
Making Call Transfers Using QSIG Name Identification This feature allows the Bfv API to see the text name of the user similar to Caller ID on an analog phone line. Therefore, if the network provides the calling party, the calling party’s name is reported through BfvLineWaitForCall/BfvCallWaitForSetup functions located in the res.calling_party_subaddress field of the args structures.
Making Call Transfers Using Active Redirection (Japan) Making Call Transfers Using Active Redirection (Japan) To transfer calls in Japan, use Active Redirection, a call transfer method that uses the central office or a PBX to transfer calls. Active redirecting is only available for T1 ISDN PRI and ISDN BRI. To configure using the Brooktrout Configuration Tool (Windows® only): Set port’s Protocol Options to T1 ISDN or BRI. Set the network Protocol to JATE (Japan) INS-1500.
Making Explicit Call Transfers (ECT) With E1 ISDN and BRI Making Explicit Call Transfers (ECT) With E1 ISDN and BRI Explicit call transfer (ECT) with E1 ISDN transfers calls using either a single B-channel or two B-channels using switch resources in the central office or PBX. Explicit call transfer is only used with the Bfv API, and is available on ISDN PRI (E1) and ISDN BRI. To configure using the Brooktrout Configuration Tool (Windows® only): Set each port’s Protocol Options to E1 ISDN or BRI.
Making Explicit Call Transfers (ECT) With E1 ISDN and BRI Set the transfer_variant using the callctrl.cfg configuration file: transfer_Variant=etsi_exp_link for explicit link transfer. You can also choose an implicit link by setting: transfer_Variant=etsi_imp_link Set the country code using the btcall.cfg configuration file, leave as default: country_code = 0010. Country codes are listed in: C:\Brooktrout\Boston\bfv.api\inc\ccode.
Making Two-Channel Call Transfers (Tromboning) Making Two-Channel Call Transfers (Tromboning) This section provides information about creating a two-channel call transfer (trombone call transfer). A two-channel call transfer occurs when an application connects a calling party to a called party with a full duplex connection, while maintaining control of both calls. For some applications, this method of transfer provides redundancy with no added benefits.
Making Two-Channel Call Transfers (Tromboning) Setting up the Two-Channel Call Transfer In the typical two way call transfer application, the application detects an incoming call and answers the call. The application then performs voice playback and voice recognition functions as needed, responding to the caller's spoken utterances. For example, a caller might speak someone's name and the application then accesses that person's phone number.
Making Two-Channel Call Transfers (Tromboning) Channel 0 Channel 1 In Ref In Out In Ref In Out Out In Out In TSlot 0 TSlot 1 Figure 12. Connections for Standard (non-transfer) Operation In Figure 12 the output slot of Channel_0 transmits to the input slot of network timeslot 0, while the output slot of network timeslot 0 transmits to the input slot of Channel_0. The connections between Channel 0 and network timeslot 0 create a full duplex voice session.
Making Two-Channel Call Transfers (Tromboning) variable where it is easily accessed and restored when disconnecting the two-channel call transfer (see Terminating the Two-Channel Call Transfer on page 199). When connecting and disconnecting resources, the application should primarily use the BfvCallSWConnect() function. The application must provide all connections with a source and destination resource.
Making Two-Channel Call Transfers (Tromboning) The application created a new connection from the output of network timeslot 0 to the input of network timeslot 1 and another new connection from the output of network timeslot 1 to the input of network timeslot 0 (see Figure 13 on page 193). Using this model, Channel 0 can record the data that is being transmitted from the network timeslot 0 and Channel 1 can record the data that is being transmitted from network timeslot 1.
Making Two-Channel Call Transfers (Tromboning) When the application creates a two-channel call transfer, the two callers become sources of the reflected data. The application must configure the echo cancellation portion of the channel resource to remove repeated input from two sources by using its reference signal slot (the channel’s reference number is 1). The application must also call the BfvSpeechEchoCancelControl() function to configure the channel to accept an input reference signal on slot #1.
Making Two-Channel Call Transfers (Tromboning) Figure 14 on page 196 shows the connections required to configure the echo canceller on a channel during a two-channel call transfer while recording from person A. The application sends the final echo cancelled data up to the host for recording. Host Channel 1 In Out Ref_In Channel 1 Ref_Out In Out Ref_In Out In In Out TSlot 0 TSlot 1 Person A Person B Ref_Out Figure 14.
Making Two-Channel Call Transfers (Tromboning) Playing Back Voice Recordings Voice playback during a two-channel call transfer can take one of two forms. The voice application plays voice data to both callers. In this example, the channel playing the voice data is the source resource and the network timeslots are the destination resources.
Making Two-Channel Call Transfers (Tromboning) channel provides silence generation on its output). After playback is completed, the application can re-establish the full duplex connection. The following series of illustrations demonstrate the changes. In Figure 16, there is a full duplex connection between channel 0 and TSlot 0, and another full duplex connection between channel 1 and TSlot 1. Channel 0 Channel 1 In Ref In Out In Ref In Out Out In Out In TSlot 0 TSlot 1 Figure 16.
Making Two-Channel Call Transfers (Tromboning) In Figure 18, the application places the caller on TSlot 1 on hold and generates silence from channel 1 to the caller. There is a full duplex connection between channel 0 and TSlot 0. Channel 0 is playing a voice prompt to the caller on TSlot 0 while recording. To take the caller on TSlot 1 off hold, re-establish the connections as they were in Figure 17. Channel 0 Ref In In Out Channel 1 Ref In In Out (Silence) Out TSlot 0 In Out In TSlot 1 Figure 18.
Making Two-Channel Call Transfers (Tromboning) Disconnecting Resources When disconnecting resources, invert the source and destination resources so that the firmware responds appropriately. Due to firmware requirements, when disconnecting resources, invert the source and destination resources.
Making Two-Channel Call Transfers (Tromboning) If the application configured the echo canceller in the channel to get an input reference signal from slot #1, then the application must remove this configuration to return the echo canceller to its default behavior. To do this the application must call the BfvSpeechEchoCancelControl() function (See Volume 3 of the Bfv API Reference Manual). For example: BT_ZERO(speech_args); speech_args.
Transferring Calls Using Release Link Trunk Transfer Transferring Calls Using Release Link Trunk Transfer Release Link Trunk is an explicit call transfer method for Nortel DMS-250 switches and is only available for Nortel switches. The host application initiates the Release Link Trunk (RLT) action, but the call transfer is completed within the public switch network. Calls come into the network on two B-channels. Each channel maintains its call and both channels are busy.
Transferring Calls Using Release Link Trunk Transfer Set the switch type using the callctrl.cfg configuration file: switch_type=nti_dms250 Set the transfer_variant using the callctrl.cfg configuration file, set: transfer_Variant=rlt Set the country code using the btcall.cfg configuration file: country_code = 0010(US). Country codes are listed in: C:\Brooktrout\Boston\bfv.api\inc\ccode.
Transferring Calls Using Release Link Trunk Transfer For more information on L4L3mENABLE_PROTOCOL and L3L4mALERTING, please refer to Volume 5, Bfv API Reference Manual. For more information on the Brooktrout Configuration Tool, refer to the chapter on using the configuration tool in the installation and configuration guide that came with your software.
Transferring Calls Using Release Link Trunk Transfer Network Host ALERTING <=== L4L3mALERTING (B1) CONNECT <=== L4L3mCONNECT (B1) Now that B-channel #2 is set up, continue with normal call setup on B1, sending alerting and connect. The call is transferred by the board, but it must maintain active call setup on both B-channels for the duration of the call. RLT Call Transfer SETUP ===> L3L4mSETUP_IND (B1) The host receives an incoming call on B-channel #1.
Transferring Calls Using Release Link Trunk Transfer Once the network establishes a direct connection between the originator of the first call and the final destination of the second call, it sends DISCONNECT messages for both B1 and B2. The calls are released on the board (and the board does not need to keep two B-channels established), but the switch maintains the actual connections between the originator and the reroute destination.
Transferring Calls Using Release Link Trunk Transfer Sample Application The following code fragments show the relevant BSMI control messages used in RLT transfer.
Transferring Calls Using Release Link Trunk Transfer /***********************************************************************/ /********** Send alerting ****/ /***********************************************************************/ void send_alert(int spy_chan, int call_ref) { L4_to_L3_struct *L4L3cntlp; L4_to_L3_struct msg; L4L3cntlp = &msg; zero_msg(L4L3cntlp); L4L3cntlp->lapdid = spy_chan; L4L3cntlp->L4_ref = 0; L4L3cntlp->call_ref = call_ref; printf("%d: Snd L4L3mALERTING_REQUEST \n", spy_chan); L4L3c
Transferring Calls Using Release Link Trunk Transfer /***********************************************************************/ /************** Send facility ****/ /***********************************************************************/ /* Send L4L3mFACILITY */ void send_facility(int spy_chan, int call_ref) { L4_to_L3_struct *L4L3cntlp; L4_to_L3_struct msg; unsigned char*ieptr; L4L3cntlp = &msg; zero_msg(L4L3cntlp); L4L3cntlp->lapdid = spy_chan; L4L3cntlp->L4_ref = 0; L4L3cntlp->call_ref = call_ref; L4L3cn
Placing Calls on Hold Using BSMI Placing Calls on Hold Using BSMI When you invoke hold functions in BSMI, the host sends an L4L3mUNIVERSAL message to the board with the data.universal.msg_id field set to a value in Table 8, also detailed in Example 1. The board accepts messages from either the host (using an L4L3mUNIVERSAL message) and passes them to the network, or takes network messages and passes them to the host (in an L3L4mUNIVERSAL message).
Placing Calls on Hold Using BSMI Example 1 memset(&l43msg,0,sizeof(L4_to_L3_struct)); l43msg->msgtype = L4L3mUNIVERSAL; l43msg->data.universal.msg_id = MT_DL_RETRIEVE; Example 2 #define IEID_CAUSE 0x08 //CAUSE IE ID code #define EXTENSION_BIT 0x80 //extension bit for an octet memset(&l43msg,0,sizeof(L4_to_L3_struct)); l43msg->msgtype = L4L3mUNIVERSAL; l43msg->data.universal.msg_id = MT_DL_RETRIEVE_REJ; l43msg->data.universal.ie_count = 1; //must equal all IEs l43msg->data.universal.ie.
Placing Calls on Hold Using BSMI November 2009 212
6 - Managing Fax and Voice over IP Sessions This chapter describes how to develop applications that use the internet for fax and voice media. To establish Internet Protocol (IP) sessions, Dialogic uses the Session Initiation Protocol (SIP) and the H.323 Protocol. To manage fax and voice media, Dialogic uses T.38 and RTP protocols. This chapter has the following sections: November 2009 Managing Calls Using IP Telephony Failover Based on Telephony Cause Codes Configuring T.
Managing Calls Using IP Telephony Managing Calls Using IP Telephony The Bfv API supports fax functionality over IP networks using the Session Initiation Protocol (SIP) and the H.323 protocol as well as the PSTN network (using ISDN, RBS, R2 MFC, and analog loop start call control protocols) through a common and consistent programming interface. This flexibility helps you to develop fax applications that can place and receive calls over traditional PSTN and IP transports using modules or the SR140.
Managing Calls Using IP Telephony T1/E1 Gateway PSTN to SIP/T.38 LAN Ethernet Switch or Hub Host (with fax application) Ethernet Ethernet (IP) Host NIC (SIP) TR1034 (T.38) Figure 19. SIP Configuration Model With dual-purpose modules in place, end-users can choose between PSTN or IP mode. Your applications can determine whether the module supports the IP or PSTN mode either at runtime or installation.
Managing Calls Using IP Telephony Outgoing IP Calls Your application manages outgoing calls if it performs the following: Uses the function calls from the table below Does not do syntax validation of the dial string Relies on the return status from the BfvLineOriginateCall function to determine call completion success. In this case the application is unaware of the mode of transport (PSTN or IP): BfvCallDisconnect Starts the process of terminating a telephone call.
Managing Calls Using IP Telephony Incoming IP Calls Your application can receive incoming IP calls if it uses function calls from the table below In this case the application is unaware of the mode of transport (PSTN or IP): Starts answering an incoming telephone call. BfvCallDisconnect Starts the process of terminating a telephone call. BfvCallReject Rejects an incoming telephone call. BfvCallRingDetect Enables or disables the detection of incoming phone calls.
Managing Calls Using IP Telephony Understanding SIP Functionality The following section provides information about SIP functionality and processes. For a detailed introduction to the SIP protocol, see Introduction to the SIP Protocol on page 244. Using a SIP Proxy Server To make an outgoing connection using the IP, your application must know the IP address of a local proxy server which is responsible for forwarding the SIP call towards its final destination.
Managing Calls Using IP Telephony SIP/T38://+01-781-555-1212 ISDN://+01-781-449-9009 When the current FAX.C sample program is compiled, it takes command line parameters to define the number dialed. With no changes to the source code, you can replace the number with a URI to allow it to take advantage of T.38. The sample program is effectively IP-enabled purely by virtue of the dial string it uses. In a SIP environment, the following command: fax –u 0 –s xxxxx@brooktrout.com foo.
Managing Calls Using IP Telephony The following are valid dial string examples for a SIP channel. Comments are shown in italics. sip:Joe Smith sip:800-555-1212@somewhere.com sip:800-555-1212@myproxy.com Joe Smith 800-555-1212@Somewhere.com 800-555-1212@myproxy.com 800-555-1212 +1 (800) 555-1212 192.168.1.45 Joe@192.168.1.1 sip:somewhere.com sip:joe@somewhere.com:9876 sip:011442871234@somewhere.com;user=phone SIP endpoint address. Endpoint gateway specified.
Managing Calls Using IP Telephony Sample INVITE Request The following sample uses the Bfv API to send the INVITE request. CALL CONTROL CONFIGURATION FILE l3l4_trace=none l4l3_trace=none api_trace=none internal_trace=none host_module_trace=none ip_stack_trace=none trace_file=c:\brooktrout\boston\config\ecc.log [module.2] [module.2/clock_config] clock_mode=master clock_source=internal [module.2/ethernet.1] dhcp=disabled ip_address=208.129.52.105 ip_netmask=255.255.255.0 ip_gateway=208.129.52.
Managing Calls Using IP Telephony [host_module.1/t38parameters] t38_max_bit_rate=14400 t38_fax_fill_bit_removal=false t38_fax_transcoding_MMR=false 38_fax_transcoding_JBIG=false t38_fax_rate_management=transferredTCF t38_fax_udp_EC=t38UDPRedundancy t38_UDPTL_redundancy_depth_image=2 t38_UDPTL_redundancy_depth_control=1 t38_t30_fast_notify=false BFV APPLICATION BT_ZERO(args); args.phonenum = “john.brooktrout.com” args.
Managing Calls Using IP Telephony 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 29 Defined by the current domain of the UAC. Generated internally. Defined by the IP of the primary NIC (network interface controller). Defined by the sip_Contact setting in the call control configuration file (default is the IP address of the primary NIC). Defined by the sip_Max-Forwards setting in the call control configuration file. Generated internally. Generated internally. Generated internally.
Managing Calls Using IP Telephony Call Progress Values Brooktrout Bfv API has mapped all possible IP call INVITE responses to Bfv call progress values. See Table 9 for values for functions that provide a final call progress value: Table 9.
Managing Calls Using IP Telephony Understanding H.323 Functionality This Brooktrout SDK supports the H.323 protocol (version 4 and Annex D), providing end point functionality only. Our current H.323 implementation does not operate as a gateway or H.323 Gatekeeper, but you can configure your application to communicate with a gateway or H.323 Gatekeeper. The H.323 implementation supports both a primary and alternate H.323 Gatekeeper.
Managing Calls Using IP Telephony Using H.323 Address Forms To allow applications to work for both SIP and H.323, the dialstring field for BfvLineOriginateCall and BfvCallSetup accepts a format of phone_number@ip_address (a current SIP format). The phone number is an optional field as is the port in the ip_address. The existing H.323 dialstrings remain unchanged and are still supported as described below. This option provides a unified way of placing a non-gatekeeper call that works for both SIP and H.323.
Managing Calls Using IP Telephony E.164 Alias (Phone Number) This Called Party Address can start with the optional identifier “TEL:”, followed by one or more E.164 address destinations. Turn on H.323 Gatekeeper support when using E.164 aliases. An E.164 alias is a phone number that is up to 128 characters long and includes the characters 0 – 9, *, #. You can set the terminal’s E.164 alias using the h323_e164alias parameter in the call control configuration file.
Managing Calls Using IP Telephony TA:198.133.219.
Failover Based on Telephony Cause Codes Failover Based on Telephony Cause Codes Overview Identifying call failures within an IP telephony network allows an application to re-route calls depending on the failure. In many cases, the failover to other network devices occurs seamlessly when the network has the following: H.323 Gatekeepers SIP Registrar Servers or SIP Redirect Servers In cases where the network does not have these components, the failover responsibility falls on the application.
Failover Based on Telephony Cause Codes Gateway failure during an active call by disconnecting the PSTN cable. Applications needing specific information about a call failure can use the cause codes reported by BfvLineTerminateCall(). However, using cause codes to determine failover scenarios is complicated. In most cases, the cause codes supplied by the gateway are manufacturer-specific and depend on the protocol being used.
Failover Based on Telephony Cause Codes Failover Scenarios Refer to Table 10 to determine failover scenarios. The table shows cause codes that have been found uniformly consistent with conditions requiring re-routing. Note that cause codes 18 and 1000 are for cases where the gateway is unreachable or inoperative. The cause codes in this table are suggested based on data collected from various Gateways (shown in Table 11). Entries with “-” specify scenarios for which no data was collected. Table 10.
Failover Based on Telephony Cause Codes Known Failures From Various Gateways H.323 and SIP In Table 11, the entries are divided between H.323 and SIP. In the case of H.323, cause codes are sent by the gateway as values corresponding to Q.931 error codes. These are returned unaltered by BfvLineTerminateCall(). In the case of SIP, the gateway sends SIP error codes which are then translated by BfvLineTerminateCall() into Q.931 error codes before being returned.
Failover Based on Telephony Cause Codes Scenario SR140 Protocol GnuGK Alcatel Avaya SIP Control Cisco 2821 CCM6.01 CCM6.1 Quintum IM1010 Gateway with H.323 responding SIP/H323 and PSTN down (no PSTN cable connected) 1000 27 34 - 1000 1 1 17 - Gateway with H.323 responding SIP/H.323 and PSTN down due to an alarm 17 27 34 - - - - 0 - Gateway SIP/H.323 channels exceeded H.323 1000 34 1000 - 1000 63, 41 44 1000 - Gateway PSTN channels exceeded H.
Failover Based on Telephony Cause Codes Scenario GnuGK Alcatel Avaya SIP Control Cisco 2821 CCM6.01 CCM6.1 Quintum IM1010 Gateway with SIP responding SIP/H.323 and PSTN down (no PSTN cable connected) - 41 - 41 1 1 1 17 41 Gateway with SIP responding SIP/H.323 and PSTN down due to an alarm - 41 - - - - - - 41 Gateway SIP/H.
Failover Based on Telephony Cause Codes SIP to Q.931 Conversion Table 12 shows the translation performed to create Q.931 codes from SIP error codes. Table 12. SIP to Q.931 Conversion November 2009 SIP Cause Code Description Q.
Failover Based on Telephony Cause Codes November 2009 SIP Cause Code Description Q.
Processing Media Using the T.38 Protocol Processing Media Using the T.38 Protocol The Brooktrout SDK supports real-time sending and receiving faxes over IP following the T.38 protocol for exchanging messages and data through IP fax gateways or IAF devices over an IP network. Because Brooktrout’s Bfv Call Control API uniformly supports a wide set of transports including IP, you can use the same fax functions for fax over IP as when sending faxes over the PSTN.
Processing Media Using the T.38 Protocol Brooktrout Fax Server T.30 / V.34 T.30 / V.34 PSTN Receiving Fax Machine Scaling/ transcoding While the method of transport is different, IP environments support the functionality of these elements. There are two types of devices used to implement T.38: an endpoint and a T.38-aware gateway. TR1034-based applications form endpoints. The following diagram shows how they support a likely IP fax scenario: T.30 / T.38 T.30 / T.
Processing Media Using the T.38 Protocol In endpoint facsimile devices, such as a network fax server, the T.38 protocol provides the equivalent to the modem in traditional faxing. In a gateway, the T.38 protocol is used to translate T.30 protocol and image data from the modems in the gateway to and from the IP endpoint connection, using the following procedure. 1. With T.38 in an endpoint, the application connects a T.38 fax server to an IP network and transmits the T.
Processing Media Using the T.38 Protocol This diagram shows how the protocols work together during the call: IP T.30 protocol stack T38 UDP or TCP PSTN T38 Demodulation Remodulation V.17 T.30 protocol stack End-to-end T.30 Protocol management In all cases the application must establish the call first using the IP call control protocol. The call control protocol is responsible for the initial call set up and tear down.
Configuring T.38, RTP and IP Call Control Activities Configuring T.38, RTP and IP Call Control Activities If your application runs on Windows® systems, you can use the Brooktrout Configuration Tool to configure call control. Use the IP Call Control Module Configuration Window to modify values for: General information IP parameters for both SIP and H.323 T.
Troubleshooting Troubleshooting You can use any existing Bfv problem solving tools to troubleshoot your T.38 application. Use the log files created by these tools to understand what is happening and modify your application. See Chapter , Debugging on page 91 for more information about these tools. Dialogic has provided a debug_control mode for T.38 problem solving (use under guidance of Dialogic Technical Services and Support). See Volume 1 of the Bfv API Reference Manual for more information.
Understanding the SIP Protocol Understanding the SIP Protocol You can use the Session Initiation Protocol (SIP), an application-layer control (signaling) protocol, to create, modify, and terminate sessions with one or more participants. These sessions include internet telephone calls, multimedia distribution, and multimedia conferences. SIP invitations used to create sessions carry session descriptions that allow participants to agree on a set of compatible media types.
Understanding the SIP Protocol Numerous protocols carry various forms of real-time multimedia session data such as voice, video, or text messages. The Session Initiation Protocol (SIP) works in concert with these protocols by enabling internet endpoints (called user agents) to discover one another and to agree on a characterization of a session they would like to share.
Understanding the SIP Protocol SIP is not a vertically integrated communications system. SIP is rather a component that is used with other IETF protocols to build a complete multimedia architecture.
Understanding the SIP Protocol Overview of Operation This section introduces the basic operations of SIP using simple examples. This section is tutorial in nature and does not contain any normative statements.
Understanding the SIP Protocol contains a number of header fields. Header fields are named attributes that provide additional information about a message. The ones present in an INVITE include the following: Unique identifier for the call Destination address Caller A's address Information about the type of session that Caller A wishes to establish with Caller B. The INVITE (message F1 in Figure 20) might look like this: . atlanta.com proxy . . . biloxi.com proxy . . . A's . . . . . . .
Understanding the SIP Protocol INVITE sip:b@biloxi.com SIP/2.0 Via: SIP/2.0/UDP pc33.atlanta.com;branch=z9hG4bK776asdhds Max-Forwards: 70 To: b From: A ;tag=1928301774 Call-ID: a84b4c76e66710@pc33.atlanta.com CSeq: 314159 INVITE Contact: Content-Type: application/sdp Content-Length: 142 (A's SDP not shown) INVITE Message Note: Caller A's SDP not shown The first line of the text-encoded message contains the method name (INVITE).
Understanding the SIP Protocol Contact Contains a SIP or SIPS URI that represents a direct route to contact Caller A, usually composed of a username at a fully qualified domain name (FQDN). While an FQDN is preferred, many end systems do not have registered domain names, so IP addresses are permitted. While the Via header field tells other elements where to send the response, the Contact header field tells other elements where to send future requests.
Understanding the SIP Protocol of the biloxi.com proxy server and forwards, or proxies, the INVITE request there. Before forwarding the request, the atlanta.com proxy server adds an additional Via header field value that contains its own address (the INVITE already contains Caller A's address in the first Via). The biloxi.com proxy server receives the INVITE and responds with a 100 (Trying) response back to the atlanta.
Understanding the SIP Protocol In this example, Caller B decides to answer the call. When he picks up the handset, the SIP phone sends a 200 (OK) response to indicate that the call has been answered. The 200 (OK) contains a message body with the SDP media description of the type of session that Caller B is willing to establish with Caller A. As a result, there is a two-phase exchange of SDP messages: Caller A sent one to Caller B, and Caller B sent one back to Caller A.
Understanding the SIP Protocol could proxy the INVITE to Caller B's voicemail server. A proxy server can also send an INVITE to a number of locations at the same time. This type of parallel search is known as forking (see below). In this case, the 200 (OK) is routed back through the two proxies and is received by Caller A's softphone, which then stops the ringback tone and indicates that the call has been answered.
Understanding the SIP Protocol forking. For this reason, request handling in SIP is often classified as either INVITE or non- INVITE, referring to all other methods besides INVITE. In some cases, it may be useful for proxies in the SIP signaling path to see all the messaging between the endpoints for the duration of the session. For example, if the biloxi.
Understanding the SIP Protocol Registrations are one way to create this information, but not the only way. Arbitrary mapping functions are configured at the discretion of the administrator. Finally, it is important to note that in SIP, registration is used for routing incoming SIP requests and has no role in authorizing outgoing requests. Authorization and authentication are handled in SIP either on a request-by-request basis with a challenge/response mechanism, or by using a lower layer scheme.
Using Third Party IP Stacks Using Third Party IP Stacks The Bfv Fax can be integrated with systems that have their own IP call control stacks. The primary IP stacks are SIP and H.323. These stacks negotiate an RTP and a T.38 port to perform fax. With the use of the SR140 software, a pure fax software solution can be integrated on systems that have VoIP features.
Using Third Party IP Stacks Integrating Bfv IP Fax Figure 21 shows the individual components that an application interacts with via the Bfv API. Although other facilities exist in the Bfv, only the fax-related facilities are shown below. Figure 21.
Using Third Party IP Stacks Components The following figure shows the components included in this configuration. Note that you must disable the functionality of the following: ECC Component H.323 Stack SIP Stack Refer to Disable ECC Component on page 259 which disables the stacks too. Figure 22.
Using Third Party IP Stacks Configuration You can configure the Bfv with the ConfigTool on Windows® or by creating the callctrl.cfg files manually. The ConfigTool is a full-solution configuration because the call control is included in the configuration along with the IP Stack which has been integrated with BFV. It can be used to create the initial callctrl.cfg and btcall.cfg. However, for this setup, you must edit the callctrl.cfg manually.
Using Third Party IP Stacks # [module.41] vb_firm=/usr/sys/brooktrout/boston/fw/bostvb.so # This parameter should be set to the number of channels licensed for the SR140 product channels=30 [module.41/ethernet.1] ip_interface=eth0 TR1034 Board-Based Integration - Linux The following callctrl.cfg configuration is an example for a TR1034 board based integration for Linux in the default installation directory. # callctrl.cfg # # Sample Call Control configuration file for Boston Bfv API with Tr1034.
Using Third Party IP Stacks # Specify an IP mask such as 255.255.255.0 ip_netmask=0.0.0.0 # Specify an IP address such as 192.168.0.1 ip_gateway=0.0.0.0 ip_broadcast=0.0.0.0 ethernet_speed=auto ip_arp_timeout=10 Call Negotiation Inbound Call The following section uses SIP to demonstrate the interaction between the third party stack in the application and the Bfv API for negotiating RTP and T.38 for an inbound call.
Using Third Party IP Stacks Figure 23.
Using Third Party IP Stacks Outbound Call The following section uses SIP to demonstrate the interaction between the third party stack in the application and Bfv for negotiating RTP and T.38 for an outbound call. Systems that will perform RTP can generate the CNG tone and avoid setting the RTP on the Bfv.
7 - Robbed Bit Signaling This chapter describes robbed bit signaling as used with BSMI-level call control.
General Information These protocols apply either to digital (T1 or E1) or analog lines. The different types of lines simply provide a different mechanism for conveying the signal-electric signals (loop current and ring voltage) on analog lines and bits on digital lines. On digital lines, these protocols are sometimes referred to as Channel Associated Signaling (CAS) or Robbed-Bit Signaling (RBS) due to the nature of the signaling.
General Information The protocols describe the value and meaning of the signaling bits and the timing between changes in their value. Brooktrout modules support the following LEC protocols: E&M Wink Start E&M Immediate Start E&M Delay Dial FXO Loop Start FXS Loop Start FXO Ground Start FXS Ground Start All signaling modes support pulsed (10 pulses per second), DTMF and MF dialing. However, detection of digits must be handled by the host.
General Information the B-channel number on that trunk (also 0-based). Some of the data structures associated with the message will have a specific field for specifying the B-channel, which must also be set. Enabling a channel and selecting the protocol to run is done through message L4L3mENABLE_CAS, while message L4L3mDISABLE_ CAS is used to disable a channel. It is possible to have different channels on the same T1 trunk running different protocols.
General Information Timer Definitions The LEC structure (named IISDN_ROBBED_BIT_DATA for historical reasons) contains a series of 16-bit values used to configure the various timing parameters associated with the protocols. Table 13 lists the timers in alphabetical order and contains each timer's unit, meaning, and default value.
General Information Table 13. Robbed Bit Signaling Timers (Continued) Timer Granularity Definition delayed_on_ hook_timer 50 ms Default Value Delayed on hook timer. If set to a IISDN56_DELAYED_ON_ value greater than 0, the HOOKTIMER_DEFAULT (20) amount of time it waits for the 1 second host to set the line onhook (message L4L3mCLEAR_ REQUEST) after the protocol has detected termination of the call. If this timer expires, the protocol sets the line onhook automatically.
General Information Table 13. Robbed Bit Signaling Timers (Continued) Timer Granularity Definition Default Value dptimer_ interdigit 10 ms IISDN56_DPINTERDGT_TIMER_ DEFAULT (30) dptimer_make 10 ms Dial Pulse Interdigit. Time between digits when performing digit outpulsing. Dial Pulse Make. Off-hook (make) time for outdialing a dial pulse digit.
General Information Table 13. Robbed Bit Signaling Timers (Continued) Timer Granularity Definition Default Value glare_ detection_ timer 10 ms Glare Detection. IISDN56_GLARE_TIMER_ Timer started at the beginning DEFAULT (5) of outseizure that determines if 50 ms a wink start or delay dial was returned too quickly to be an acknowledgment of the outseizure, but should be treated as glare. guard_ interval_timer 50 ms Guard Interval Timer.
General Information Table 13. Robbed Bit Signaling Timers (Continued) Timer Granularity Definition hooktimer_ 10 ms offhook_inseize hooktimer_ offhook_ answer 10 ms hooktimer_ min_wink 10 ms hooktimer_ maxmake 10 ms hooktimer_ maxbreak hooktimer_ minmake November 2009 Inseizure Filter. Time that the receive signal bit must be in-use to be considered an inseizure from the connected equipment. Answer Filter.
General Information Table 13. Robbed Bit Signaling Timers (Continued) Timer Granularity Definition Default Value hooktimer_ minbreak 10 ms Minimum Dial Pulse Break Time. IISDN56_MINBREAK_TIMER_ DEFAULT (1) Shortest break region that is counted as a dial pulse break region. Anything shorter should be ignored. 1 ms Ignore Inseize After Release Timer. IISDN56_IGNINSZ_TIMER_ DEFAULT (5) Time after the interface has idled before Instant ISDN will allow an inseizure from the connected equipment.
General Information Table 13. Robbed Bit Signaling Timers (Continued) Timer Granularity Definition Default Value outseize_ack_ timer 50 ms CO Outseize Acknowledge Timer. IISDN56_OUTS_ACK_TIMER_ DEFAULT (60) Time to continue looking for the outgoing start dial signal from the connected equipment on outseizure before declaring an outseizure failure. 3 seconds Duration of ring signal during the ring cycle on outbound calls (FXS Loop Start and FXS Ground Start calls only).
General Information Timing Diagrams To aid in the development process, timing diagrams that illustrate call setup and call teardown signaling in the various supported protocols are provided in the sections that follow. The diagrams consist of four parts: IISDN SMI Messages: Indicates the Bfv API messages sent to and received from the card during the call scenario.
Wink Start & Delay Dial Signaling Wink Start & Delay Dial Signaling In the Wink Start protocol, the device seizing the line expects a wink signal (a short-duration - 140 to 290ms - offhook signal) to be sent back as acknowledgment before sending the address digits. In the Delay Dial, the device seizing the line expects an off-hook response from the far end for at lest 140ms, and waits for the far end to return to on-hook state before sending the address digits.
Wink Start & Delay Dial Signaling The remaining settings are described in the context of incoming and outgoing calls in the subsections that follow. Brooktrout modules process calls in the same manner on both wink start and delay dial trunks. Incoming Call Processing During an incoming call, the host receives an L3L4mPRE_SEIZE message if send_preseize_event = 1 in the IISDN_ROBBED_BIT_ DATA structure. This message is sent when the module detects an incoming seizure (off hook).
November 2009 L3L4mPRE_SEIZE DP Digit "2" DP Digit "1" L3L4mSETUP_IND L4L3mALERTING_REQUEST or L4L3mPROGRESS_REQUEST NOTE: This diagram is designed to give the reader a general understanding of the sequence of events for this robbed bit protocol over time. The timers and spacing on this graph are not proportional to the actual events that occur.
Wink Start & Delay Dial Signaling Outgoing Call Processing During an outgoing call, the host receives an L3L4mPROGRESS in response to the L4L3mCALL_REQUEST to start the call. The host then receives an L3L4mSEIZE_COMP message if send_seize_comp_ event = 1 in the IISDN_ROBBED_BIT_DATA structure. This message is sent when the module detects a wink from the network, indicating the network is ready to receive digits.
November 2009 L3L4mPROGRESS L4L3mCALL_REQUEST DP Digit "2" L3L4mSEIZE_COMP DP Digit "1" NOTE: This diagram is designed to give the reader a general understanding of the sequence of events for this robbed bit protocol over time. The timers and spacing on this graph are not proportional to the actual events that occur.
Wink Start with Feature Group B & D Wink Start with Feature Group B & D To configure a Brooktrout module for wink start with Feature Group B and D signaling, the host must issue an L4L3mENABLE_CAS with an IISDN_ROBBED_BIT_DATA structure that contains the following settings: send_glare_err_event = 0 (not used for wink start) in_trunk_type = IISDNttWINK_START (the default value) out_trunk_type = IISDNttWINK_START (the default value) fgb_fgd_mode = 1 (enabling Feature Group B and D) The remain
November 2009 L3L4mPRE_SEIZE DP Digit "2" DP Digit "1" L3L4mSETUP_IND Revised 20-Oct-03 Revised 10-Nov-98 Revision 1.3 L3L4mTXWINK_END L4L3mCONNECT_REQUEST L4L3mALERTING_REQUEST or L4L3mPROGRESS_REQUEST L4L3mTX_WINK NOTE: This diagram is designed to give the reader a general understanding of the sequence of events for this robbed bit protocol over time. The timers and spacing on this graph are not proportional to the actual events that occur.
Wink Start with Feature Group B & D Outgoing Call Processing The host receives an L3L4mPROGRESS in response to the L4L3mCALL_REQUEST to start the call. The host then receives an L3L4mRX_WINK message when the module detects a wink from the network. The module waits a period of time (determined by the fixed pause timer) before sending digits. When the timer expires, the host receives an L3L4mSEIZE_COMP message if send_seize_comp_ event = 1 in the IISDN_ROBBED_BIT_DATA structure.
November 2009 DP Digit "2" L3L4mSEIZE_COMP DP Digit "1" NOTE: This diagram is designed to give the reader a general understanding of the sequence of events for this robbed bit protocol over time. The timers and spacing on this graph are not proportional to the actual events that occur.
Immediate Start/Fixed Pause Signaling Immediate Start/Fixed Pause Signaling Immediate Start signaling applies to incoming calls only; Fixed Pause signaling applies to outgoing calls only. Since these signaling types functionally complement each other, they are handled together by Brooktrout modules. The exact protocol to be used for a call is automatically selected depending on whether an incoming or outgoing call is being handled.
November 2009 L3L4mPRE_SEIZE DP Digit "2" DP Digit "1" L3L4mSETUP_IND L4L3mALERTING_REQUEST or L4L3mPROGRESS_REQUEST NOTE: This diagram is designed to give the reader a general understanding of the sequence of events for this robbed bit protocol over time. The timers and spacing on this graph are not proportional to the actual events that occur.
Immediate Start/Fixed Pause Signaling Outgoing Call Processing (Fixed Pause Mode) During an outgoing call, the host receives an L3L4mPROGRESS in response to the L4L3mCALL_REQUEST to start the call. The module waits a period of time (determined by the fixed pause timer) before sending digits. When the timer expires, the host receives an L3L4mSEIZE_COMP message if send_seize_comp_event = 1 in the IISDN_ROBBED_BIT_DATA structure.
November 2009 L3L4mPROGRESS L4L3mCALL_REQUEST DP Digit "2" L3L4mSEIZE_COMP DP Digit "1" NOTE: This diagram is designed to give the reader a general understanding of the sequence of events for this robbed bit protocol over time. The timers and spacing on this graph are not proportional to the actual events that occur.
Ground Start Signaling Ground Start Signaling Brooktrout modules support two types of ground start signaling: Foreign Exchange - Office (FXO) Foreign Exchange - Subscriber (FXS) When operating in FXO mode, the module assumes the far end of the connection is an FXS termination. When operating in FXS mode, the module assumes the far end is an FXO termination.
Ground Start Signaling Figure 31 shows how a Brooktrout module processes an incoming call received over an FXO ground start trunk.
November 2009 L3L4mPRE_SEIZE DP Digit "2" DP Digit "1" L3L4mSETUP_IND L4L3mALERTING_REQUEST or L4L3mPROGRESS_REQUEST NOTE: This diagram is designed to give the reader a general understanding of the sequence of events for this robbed bit protocol over time. The timers and spacing on this graph are not proportional to the actual events that occur.
Ground Start Signaling Outgoing Call Processing If send_glare_err_event = 0 in the IISDN_ROBBED_BIT_DATA structure, the host receives an L3L4mERROR message containing the value L3L4errGLARE if the outgoing call attempt fails due to glare. Glare occurs when the module attempts to make an outgoing call on a channel at the same time an incoming call arrives on the channel. The call attempt fails because the network always wins channel contention.
November 2009 L3L4mPROGRESS L4L3mCALL_REQUEST L3L4mCONNECT NOTE: No digits are collected on the far end in this mode. L3L4mSEIZE_COMP NOTE: This diagram is designed to give the reader a general understanding of the sequence of events for this robbed bit protocol over time. The timers and spacing on this graph are not proportional to the actual events that occur.
November 2009 L3L4mCLEAR_REQUEST L4L3mCLEAR_REQUEST NOTE: This diagram is designed to give the reader a general understanding of the sequence of events for this robbed bit protocol over time. The timers and spacing on this graph are not proportional to the actual events that occur.
November 2009 NOTE: This diagram is designed to give the reader a general understanding of the sequence of events for this robbed bit protocol over time. The timers and spacing on this graph are not proportional to the actual events that occur.
Ground Start Signaling FXS Ground Start To configure a Brooktrout module for FXS ground start signaling, the host must issue an L4L3mENABLE_CAS with an IISDN_ ROBBED_BIT_DATA structure that contains the following settings: in_trunk_type = IISDNtt5ESS_GDSTART out_trunk_type = IISDNtt5ESS_GDSTART max_incoming_digit_count = 0 (no digits collected) timed_answer_supervision = 1 (timer expiration indicates far end answer) fgb_fgd_mode = 0 (not used) The remaining settings are described in the
November 2009 NOTE: This diagram is designed to give the reader a general understanding of the sequence of events for this robbed bit protocol over time. The timers and spacing on this graph are not proportional to the actual events that occur. B Bit A Bit L4L3mCONNECT_REQUEST NOTE: No digits are collected on the near end in this mode.
Ground Start Signaling Outgoing Call Processing If send_glare_err_event = 0 in the IISDN_ROBBED_BIT_DATA structure, the host receives an L3L4mERROR message containing the value L3L4errGLARE if the outgoing call attempt fails due to glare. Glare occurs when the module attempts to make an outgoing call on a channel at the same time an incoming call arrives on the channel. The call attempt fails because the network always wins channel contention.
November 2009 L3L4mPROGRESS DP Digit "2" DP Digit "1" NOTE: This diagram is designed to give the reader a general understanding of the sequence of events for this robbed bit protocol over time. The timers and spacing on this graph are not proportional to the actual events that occur.
November 2009 L3L4mCLEAR_REQUEST L4L3mCLEAR_REQUEST NOTE: This diagram is designed to give the reader a general understanding of the sequence of events for this robbed bit protocol over time. The timers and spacing on this graph are not proportional to the actual events that occur.
November 2009 NOTE: This diagram is designed to give the reader a general understanding of the sequence of events for this robbed bit protocol over time. The timers and spacing on this graph are not proportional to the actual events that occur.
Loop Start Signaling Loop Start Signaling Brooktrout modules support two types of loop start signaling: FXO Loop Start FXS Loop Start When operating in FXO mode, the module assumes the far end of the connection is an FXS termination. When operating in FXS mode, the module assumes the far end is an FXO termination. FXS Loop Start is the protocol used for Brooktrout's analog modules. The sequence of events and timings is the same for both analog or digital line interfaces.
Loop Start Signaling FXO Loop Start To configure a Brooktrout module for FXO loop start signaling, the host must issue an L4L3mENABLE_CAS with an IISDN_ROBBED_ BIT_DATA structure that contains the following settings: send_glare_err_event = 0 (not used for loop start) in_trunk_type = IISDNttFXO_LPSTART out_trunk_type = IISDNttFXO_LPSTART timed_answer_supervision = 0 (answer supervision required) fgb_fgd_mode = 0 (not used) The remaining settings are described in the context of incoming a
Loop Start Signaling Incoming Call Processing During an incoming call, the host receives an L3L4mPRE_SEIZE message if send_preseize_event = 1 in the IISDN_ROBBED_BIT_ DATA structure. This message is sent when the module detects an incoming seize from the far end (FXS end). The module then collects dial pulse digits from the network; the maximum number of digits the module expects to receive must be specified in the max_ incoming_digit_count field.
November 2009 L3L4mPRE_SEIZE DP Digit "2" DP Digit "1" L3L4mSETUP_IND L4L3mALERTING_REQUEST or L4L3mPROGRESS_REQUEST NOTE: This diagram is designed to give the reader a general understanding of the sequence of events for this robbed bit protocol over time. The timers and spacing on this graph are not proportional to the actual events that occur.
November 2009 L3L4mPROGRESS L4L3mCALL_REQUEST NOTE: No digits are collected on the far end in this mode. L3L4mCONNECT NOTE: This diagram is designed to give the reader a general understanding of the sequence of events for this robbed bit protocol over time. The timers and spacing on this graph are not proportional to the actual events that occur.
November 2009 NOTE: This diagram is designed to give the reader a general understanding of the sequence of events for this robbed bit protocol over time. The timers and spacing on this graph are not proportional to the actual events that occur.
November 2009 L3L4mCLEAR_REQUEST L4L3mCLEAR_REQUEST NOTE: This diagram is designed to give the reader a general understanding of the sequence of events for this robbed bit protocol over time. The timers and spacing on this graph are not proportional to the actual events that occur.
Loop Start Signaling FXS Loop Start To configure a Brooktrout module for FXS loop start signaling, the host must issue an L4L3mENABLE_CAS with an IISDN_ROBBED_ BIT_DATA structure that contains the following settings: in_trunk_type = IISDNtt5ESS_LPSTART out_trunk_type = IISDNtt5ESS_LPSTART max_incoming_digit_count = 0 (no digits collected) timed_answer_supervision = 1 (timer expiration indicates far end answer) fgb_fgd_mode = 0 (not used) The remaining settings are described in the conte
Loop Start Signaling event = 1 in the IISDN_ROBBED_BIT_DATA structure. This message is sent after the fixed pause timer expires. When the timer expires, the host receives an L3L4mSEIZE_COMP message if send_ seize_comp_event = 1 in the IISDN_ROBBED_BIT_DATA structure. FXS ground start supports transmitting digits other than dial pulse digits. If called_party_digits = 0 in the L4L3mCALL_REQUEST that started the call, the module waits in outdialing state indefinitely.
November 2009 NOTE: No digits are collected on the near end in this mode. L4L3mCONNECT_REQUEST NOTE: This diagram is designed to give the reader a general understanding of the sequence of events for this robbed bit protocol over time. The timers and spacing on this graph are not proportional to the actual events that occur.
November 2009 L3L4mPROGRESS L4L3mCALL_REQUEST DP Digit "2" L3L4mSEIZE_COMP DP Digit "1" NOTE: This diagram is designed to give the reader a general understanding of the sequence of events for this robbed bit protocol over time. The timers and spacing on this graph are not proportional to the actual events that occur.
November 2009 NOTE: For FXS Loop Start Mode, there is no manner using the signalling bits in which to detect that the remote side has hung up. The only way to do this is to detect a lack of data on the connection, and then initate call teardown from the local side. NOTE: This diagram is designed to give the reader a general understanding of the sequence of events for this robbed bit protocol over time. The timers and spacing on this graph are not proportional to the actual events that occur.
November 2009 L3L4mCLEAR_REQUEST L4L3mCLEAR_REQUEST NOTE: This diagram is designed to give the reader a general understanding of the sequence of events for this robbed bit protocol over time. The timers and spacing on this graph are not proportional to the actual events that occur.
November 2009 L3L4mCLEAR_REQUEST L4L3mCLEAR_REQUEST NOTE: This diagram is designed to give the reader a general understanding of the sequence of events for this robbed bit protocol over time. The timers and spacing on this graph are not proportional to the actual events that occur.
8 - ISDN Call Processing and Management This chapter describes ISDN call processing using BSMI-level call control. The chapter has the following sections: ISDN Call Processing Overview Translating Q.931 to Simple Message Interface Using the overlap_rcv feature of L4L3mENABLE_ PROTOCOL Q.921/Q.931 Timers Brooktrout modules provide multipurpose platforms for fully integrated network access.
BSMI interprets undecoded Q.931 packets from the network, removing information not needed by most applications and making it available via an L3L4m message. If you need specific Q.931 information not delivered with the message but that is documented as contained in a Q.
ISDN Call Processing Overview ISDN Call Processing Overview This subsection presents an overview of ISDN incoming and outgoing call setup and tear down and overlapped dialing. Switched 56 calls use a similar mechanism. Making an ISDN Incoming Call A typical incoming ISDN call is illustrated in Figure 48. In this call scenario, the Brooktrout module is answering a call. The following message exchange is relative to the module: 1.
ISDN Call Processing Overview Notification of incoming calls comes via a SETUP_IND message which contains the B-channel number the network would like to set the call up on. By turning on negotiation, you can specify a different (specific) B-channel on which to establish rather than the one requested by the network.
ISDN Call Processing Overview It is also possible to configure BSMI to generate a SETUP_ACK rather than a CALL_PROCEEDING message upon arrival of a setup message. Network Module Host SETUP CALL PROCEEDING L3L4mSETUP_IND L4L3mALERTING_REQUEST ALERTING L4L3mCONNECT_REQUEST CONNECT CONNECT ACKNOWLEDGE Figure 48. ISDN Incoming Call As in the case of a call, BSMI also handles the call model where a SETUP_ACK generated instead of a call proceeding.
ISDN Call Processing Overview Making an ISDN Outgoing Call A typical outgoing ISDN call is illustrated in Figure 49. In this call scenario, the module is making an outgoing call. During an outgoing call, if the phone number is more than 20 digits long, the application automatically sends the number using overlapped dialing (See ISDN Overlapped Dialing on page 323 for more information). The following message exchange is relative to the module: 1.
ISDN Call Processing Overview Network Module Host L4L3mCALL_REQUEST SETUP CALL PROCEEDING ALERTING CONNECT CONNECT ACKNOWLEDGE L3L4mALERTING L3L4mCONNECT Figure 49. ISDN Outgoing Call Call Proceeding (L3L4mCALL_PROCEEDING) is reported to the module but is not automatically reported to the host via the Bfv API. In order to retrieve this message, set the field below to 1 in your ENABLE_PROTOCOL message: 143.data.enable_protocol.level3.cnfg.q931.
ISDN Call Processing Overview ISDN Overlapped Dialing The Euro-ISDN protocol only allows 20 digits to be sent as a group (en-block) when placing a call. For longer phone numbers, the application must use overlapped dialing— the process of sending extra digits after the initial call setup.
ISDN Call Processing Overview 3. The network responds to the DISCONNECT with a RELEASE message. 4. The module generates two messages upon receipt of the RELEASE: RELEASE COMPLETE message to the network, indicating the call has been cleared L3L4mCLEAR_REQUEST message to the host, indicating the call has been disconnected Network Module Host L4L3mCLEAR_REQUEST DISCONNECT RELEASE RELEASE COMPLETE L3L4mCLEAR_REQUEST Figure 50.
ISDN Call Processing Overview If you want manual control over the sending of RELEASE COMPLETE, set the field below to 1: l43.data.enable_protocol.level3.cnfg.q931.release_complete_control = 1 An L4L3mCLEAR_REQUEST message will then send the RELEASE COMPLETE message. The host cannot consider a call disconnected and the channel available for another call until the L3L4mCLEAR_REQUEST message has been received from the module.
ISDN Call Processing Overview If the call is made using Switched 56 robbed bit signaling (not ISDN), there is an additional waiting period between sending the L4L3mCLEAR_REQUEST and receiving the L3L4mCLEAR_ REQUEST indicating the channel is available. This interval is equal to the value of the guard_interval_timer and is usually 100 ms. Refer to Chapter , Robbed Bit Signaling on page 264 for more information on robbed bit signaling timers.
Translating Q.931 to Simple Message Interface Translating Q.931 to Simple Message Interface Table 14 translates Q.931 messages to the appropriate Simple Message Interface (SMI) message and compares them to their corresponding message. Table 14. Q.931 Message Comparison Table Q.
Using the overlap_rcv feature of L4L3mENABLE_PROTOCOL Table 14. Q.931 Message Comparison Table (Continued) Q.
Using the overlap_rcv feature of L4L3mENABLE_PROTOCOL BSMI Reference Notes Support for Overlap Receive mode are enabled using the overlap_rcv flag in the BSMI_Q931_CNFG structure of L4L3mENABLE_ PROTOCOL messages. If the Host application expects to support Overlap Receive calling models (more typical of E1 and EURO-based BRI installations than domestic T1 installations), it should set the overlap_rcv flag to “1” when enabling the Q.931 D-channel.
Using the overlap_rcv feature of L4L3mENABLE_PROTOCOL How Overlap Receive Mode Changes Call Control Events Presentation Volume 5, Bfv API Reference Manual describes the normal call control events associated with ISDN Call Processing and Management. These events occur when incoming SETUP messages contain all the appropriate CALLED_PARTY information elements and SENDING_COMPLETE information elements.
Using the overlap_rcv feature of L4L3mENABLE_PROTOCOL Network Brooktrout Controller Setup (no sending complete or called party #IE) Host overlap_rcv ENABLED L3L4mSETUP_IND SETUP ACKNOWLEDGE INFORMATION L3L4mINFO If no SENDING_COMPLETE IE is present, or when Module cannot determine if CALLED_PARTY info is complete, Module issues request for further info.
Q.921/Q.931 Timers Q.921/Q.931 Timers An application can change the default behavior in Instant ISDN Software Level 2 and Level 3 parameters by issuing ENABLE_ PROTOCOL. L4L3mENABLE_PROTOCOL contains an IISDN_L2_CONST structure that defines Level 2 parameters and an IISDN_Q931_ TIMERS structure that configure Level 3 timers. The IISDN_Q931_ TIMERS structure is only valid when the Level 3 mode (l3_mode) value in the message is IISDNl3modQ931. Table 15 and Table 16 list the parameters for both structures.
Q.921/Q.931 Timers Table 15. Q.921 Timers (Level 2 Parameters) (Continued) Data Type Mnemonic Definition unsigned short n200 Maximum number of retransmissions. value is 3. unsigned short n201 Maximum number of octets in an I frame. Currently the maximum is 240. unsigned short n202 Maximum number of transmissions of a TEI request message. Default value is 3. unsigned short K Maximum transmit window. Default value is 7; maximum value is 127. BRI default is 1. Default Table 16. Q.
Q.921/Q.931 Timers Table 16. Q.931 Timers (Level 3 Parameters) (Continued) Data Type Mnemonic Definition unsigned short t318 Q.931 Resume Request state timer. Default value is 1200 (120 seconds). unsigned short t319 Q.931 Suspend Request state timer. Default value is 1200 (120 seconds). unsigned short t3m1 Q.931 Maintenance SERVICE ACK timer. Default value is 1200 (120 seconds). Default value must be used for NFAS configurations. unsigned short t321 Q.931 NFAS D-channel backup timer.
9 - Using the BSMI R2 Signaling Capability This chapter describes R2 signaling as used with BSMI-level call control. The chapter has the following sections: CPE Signaling Model Enabling the R2 Protocol Brooktrout boards offer E1 CAS signaling for customer premise equipment (CPE).
CPE Signaling Model Line Signaling) and MF compelled (MFC) (R2 Inter-register Signaling). Signaling is controlled via the BSMI interface in a manner similar to Q.931 and LEC protocols. Note: This chapter applies only to BSMI (low-level call control) users. Bfv call control users cannot use this information. The LEC protocols are described in Chapter , Robbed Bit Signaling on page 264. Please contact Dialogic Technical Services and Support for a list of supported variants of the R2 protocol.
CPE Signaling Model Table 17. Line Signaling Model State CAS Bits Notes Outbound AB Inbound AB Idle 10 10 Both outbound and inbound channels are sending idle signal. Seize 00 10 Outbound channel seizes the line. Seize Acknowledge 00 11 Inbound channel initializes MFC inter-register signaling and sends the seize acknowledgment. When the seize acknowledgment is recognized by the outbound channel, inter-register signaling begins with the transmission of the first DNIS digit.
CPE Signaling Model Table 17. Line Signaling Model (Continued) State Idle CAS Bits Notes Outbound AB Inbound AB 10 10 Inbound side sends the idle signal. Disconnection initiated by the outbound side. Clear forward 10 01 Outbound side sends the clear forward signal. Release guard 10 11 This state is optional. The inbound side responds to the clear forward with a clear back signal and holds it for a specified length of time. 10 10 Inbound side sends the idle signal.
CPE Signaling Model Information passed from the inbound side to the outbound side is: Called line condition (for example, free with change, busy, etc.) Network congestion ITU recommendations specify a set of 6 frequencies to be used for forward signals, and another 6 for backward signals. Each signal consists of 2 frequencies, thus providing 15 forward signals and 15 backward signals.
CPE Signaling Model Figure 52 illustrates an example inter-register exchange in which the inbound protocol is configured to collect DNIS digits first, followed by collection of ANI information, and concluding with the exchange of DNIS category and called line condition. However, variations on this exchange are possible, resulting from different settings of the inbound protocol control parameters and the absence of certain signals in a given variant.
Enabling the R2 Protocol Enabling the R2 Protocol Using the R2 protocol is similar to using the LEC protocols. Each individual channel is enabled using an L4L3mENABLE_CAS message. When the module receives this message, it will initialize all timers and data structures associated with the specified channel, put the line in idle state “onhook” and respond with an L3L4mCAS_ STATUS message. The application must select the following signaling type: l43msg.data.cas_data.
Enabling the R2 Protocol BSMI does not support varying any parameter settings from channel to channel on a single trunk. Trunk level configuration is performed upon receipt of the first L4L3mENABLE_CAS message on that trunk. However, L4L3mENABLE_CAS must be sent for every channel in order for the channel to initialize and go on-hook. Therefore, the IISDN_E1_CAS_R2_DATA structure should be filled out identically for each channel's L4L3mENABLE_CAS.
Enabling the R2 Protocol Table 18. R2 Digital Line Signaling Parameters (Continued) Name Description c_d_cas_bits Specification of the CAS C bit and D bit settings. Units Range 0: CD=00 1: CD=01 2: CD=10 3: CD=11 ClearbackControl Used by the outbound side to determine whether the network will use a release guard (AB=11) or a forced release (AB=00) signal to tear down a call, The selected signal is handled accordingly, while the other is simply ignored.
Enabling the R2 Protocol Table 19. R2 MFC Inter-register Signaling Parameters (Continued) Name Description Units Range pulseToneDuration Duration of a backward pulse signal (Ref. ITU Q.442). ms Typically [100 - 200] Outbound MFC Timers forwardToneMaxOnTime Time associated with the outbound Seconds This is typically in the “T1” timer that supervises the range [12-18], but refer interval between start of a forward to network tone and cessation of the forward specification. tone (Ref. ITU Q.476).
Enabling the R2 Protocol Table 19. R2 MFC Inter-register Signaling Parameters (Continued) Name Description Units Range Backward Channel Signal Definitions sendNextDigitDNIS Signal request for next DNIS digit (state DNIS). Table 20 sendLastButOneDigitDNIS Signal request for last-but-one DNIS digit (state DNIS). This signal is not currently used.
Enabling the R2 Protocol Table 19. R2 MFC Inter-register Signaling Parameters (Continued) Name Description groupB_LineConditions Structure of Group B called line conditions indexed by enumeration IISDN_R2MFCP_GROUP_B_ CALLED_LINE_CONDITIONS. Units Range Refer to Table 22 Only a subset of these signals are used in a given protocol variant. Set those that are not used to the “invalid” tone code.
Enabling the R2 Protocol Protocol Parameter Mechanics The set of protocol parameters is specified according to a simple procedure. Individual signal meanings are set to the appropriate MF tone code. R2 MF tone codes for both forward and backward channels are defined according to the enumeration in Table 20. If a signal is not defined for a particular variant, its value is set to zero. Table 20.
Enabling the R2 Protocol Forward Channel The set of forward channel actions to backward channel signals is defined in Table 21. Actions #2 - #8 might be used when processing DNIS or ANI digits according to a particular protocol variant. The processing changes state according to the current state and the particular event. For instance, when in the ANI state, if a backward signal event requires processing action PROCESS_NEXT_DNIS_DIGIT_REQUEST, then that action occurs with a return to the DNIS state.
Enabling the R2 Protocol Table 21. IISDN_R2MFC_FORWARD_ACTIONS (Continued) Name Description State PROCESS_CONGESTION_SIGNAL Process congestion signal. DNIS or ANI PROCESS_NEXT_ANI_DIGIT_REQUEST Process request for next ANI digit. ANI PROCESS_CALLING_PARTY_CATEGORY_ REQUEST Process request for calling party (ANI) information. DNIS PROCESS_CALL_ACCEPTED_NO_GROUP_B Process call accepted without need for Group B line condition.
Enabling the R2 Protocol Table 22 identifies the enumeration of Group B called line conditions. This enumeration forms the set of indices to array groupB_LineConditions (Table 19). This allows the mapping of the invariant enumeration values to and from the corresponding backward signal codes that vary from trunk to trunk. A number of user defined spares are provided. Table 22.
Enabling the R2 Protocol Table 23 identifies the set of backward channel actions to forward signals. Table 23. IISDN_R2MFCP_BACKWARD_ACTIONS Name Description Valid State PROCESS_INVALID_FORWARD_SIGNAL This action is performed when the protocol cannot recover and the register must immediately release. This action is used in any protocol state. Any PROCESS_DNIS_DIGIT Process received DNIS digit. DNIS PROCESS_DNIS_END_OF_PULSING Process end-of-pulsing (DNIS) signal.
Enabling the R2 Protocol Inbound calls require generation of call progress tones. If a call has been accepted, BSMI will generate a finite number of RING tone cycles before entering the answered state. If a call has been rejected, BSMI will generate the BUSY signal until the call is cleared by the outbound side. Table 24 identifies the IISDN_CPGEN_MF_ PARAMS structure that contains the parameters required to define a call progress signal for generation by a DSP resource. Table 24.
Enabling the R2 Protocol Table 24. IISDN_CPGEN_MF_PARAMS (Continued) Name Description makeTime3 See makeTime1; not used if numCadences = 2 breakTime3 See breakTime1; not used if numCadences = 2 numCycles Number of cadence cycles to generate.
Enabling the R2 Protocol R2 Call Control This section presents an overview of R2 outbound and inbound call setup and tear down. LEC protocols and ISDN use a similar mechanism. Once the trunk is configured, a particular channel that is enabled is ready to dial an outbound call or process an inbound call from the network. The R2 protocol stack automatically selects a DSP channel (Boston channel) to perform the tone detection/generation operations.
Enabling the R2 Protocol Outbound Call Setup An outbound call request sequence that results in call acceptance by the remote side is illustrated in Figure 53. The Host application issues the module an L4L3mCALL_REQUEST message with the following R2 payload entries: l43msg.msgtype = L4L3mCALL_REQUEST; l43msg.lapdid = 0x1; l43msg.data.call_req_data.bchannel = 1; l43msg.data.call_req_data.called_party.num_digits l43msg.data.call_req_data.called_party.
Enabling the R2 Protocol Call acceptance by the remote end is determined by BSMI during MFC inter-register signaling. At this point, BSMI issues an L3L4mALERTING message to the Host containing the IISDN_R2_ CALL_STATUS structure. The structure element l34msg.data.al_con_data.r2_call_status.
Enabling the R2 Protocol An outbound call request sequence that results in call rejection by the remote side is illustrated in Figure 54. In this case, BSMI determines that the call has been rejected during inter-register signaling and automatically clears the call request. BSMI then provides the Host indication of the failed call attempt with the L3L4mCLEAR_REQUEST message.
Enabling the R2 Protocol Inbound Call Setup Inbound call setup is illustrated in Figure 55. The host optionally receives an L3L4mPRE_SEIZE message when BSMI detects an incoming seizure. When all DNIS and ANI address information has been collected, BSMI issues an L3L4mSETUP_IND message. After examination of the address information, the host application might wish to accept or reject the call.
Enabling the R2 Protocol In the event that a failure occurs after the optional L3L4mPRE_ SEIZE message, but before the L3L4mSETUP_IND message, BSMI will issue an L3L4mSTATUS_IND message containing the IISDN_ R2_CALL_STATUS structure that identifies the reason for the call failure. No host action is required in this case, but the status indication is logged for informational purposes. (1) L3L4mPRE_SEIZE (2) L3L4mSETUP_IND If call is accepted ...
Enabling the R2 Protocol Call Tear Down Figure 56 illustrates a call disconnection initiated by the network. BSMI issues an L3L4mDISCONNECT message. The host responds with a clear request that is followed with an L3L4mCLEAR_ REQUEST message when the channel has returned to the idle state. (1) L3L4mDISCONNECT (2) L4L3mCLEAR_REQUEST Host (3) L3L4mCLEAR_REQUEST Figure 56.
Enabling the R2 Protocol Figure 57 illustrates a call disconnection initiated by the host application. The host issues an L4L3mCLEAR_REQUEST message. BSMI responds with an L3L4mCLEAR_REQUEST message when the channel has returned to the idle state. (1) L4L3mCLEAR_REQUEST Host (2) L3L4mCLEAR_REQUEST Figure 57.
Enabling the R2 Protocol Channel Blocking BSMI provides a mechanism for the Host application to block and unblock individual channels as well as to receive indication that the far end has blocked or unblocked a particular channel. Although the R2 protocol remains “enabled”, a blocked channel is not available for outbound or inbound calls. The BSMI message sequences for local blocking and blocking by the network are illustrated in Figure 58.
10 - Packaging Your Application for Windows® This chapter describes how to package Dialogic® Brooktrout® software so that you can deliver it to your customers as part of your product.
Brooktrout SDK consists of a collection of software components in a simple installation package known as boston.msi that installs the basic drivers and other required runtime components to support Brooktrout modules.
Package Options A merge module consists of a component such as a .dll file and its related files, resources, registry entries, and setup logic.
Installation Installation The paragraphs in this section provide instructions for: Installing modules and virtual modules (SR140) Installing software Installing Modules Your customers can install either the software first or the module first. Brooktrout’s application supports both methods. In your instructions to customers, tell them to do the following if they install the module before installing software: 1. Turn off the computer. 2. Install the module. 3. Restart the computer. 4.
Installation Installing Software Depending on how you choose to deliver your package to your customers, Brooktrout provides its software as an MSI package (boston.msi) or as selectable modules that you can merge into an existing MSI package. This section discusses these options and provides instructions to implement them.
Installation msiexec \I boston.msi \qn INSTALLDIR=D:\ProductFolder SHOWLAUNCHPROGRAM=0 SHOWLAUNCHREADME=1. If you use your own installation program instead of boston.msi and the Brooktrout INF file to install Brooktrout files, check for the presence of Brooktrout Fax Software by examining the registry entries (see page 373). Remove the entries before installing the new Brooktrout version. The boston.
Installation Table 25. Brooktrout Fax Software System Files (Continued) Install Location File Name Purpose bin\ axis_notice.txt License notice text file bin\ bostvb.dll Host based firmware dll bin\ brktcctrace.exe Call Tracer utility file bin\ BrktLicMgr.exe License Manager file bin\ BrktLicMgrHelp.zip License Manager Help files bin\ btver.exe Brooktrout Fax Software and firmware version information bin\ confighelp.zip Help files for the configuration tool bin\ configtool.
Installation Table 25. Brooktrout Fax Software System Files (Continued) Install Location File Name Purpose config\ btcall.cfg User-defined configuration file config\ BT_CPARM.CFG Country-specific configuration parameters file config\ callctrl.cfg Call control configuration file config\ ctr21.qslac Protocol file config\ epsonec.fnt Font file config\ epsonec.fz8 Font file config\ epsones.fnt Font file config\ epsones.fz8 Font file config\ epsonpc.fnt Font file config\ epsonpc.
Installation Table 25. Brooktrout Fax Software System Files (Continued) Install Location File Name Purpose driver\pnp\ brooktrout.cat Security catalog file for the pnp driver components driver\pnp\ trxstream.inf INF file for installing pnp boston driver\pnp\ TRxStream\x86\ boston.pdb Driver symbol file for 32-bit OS driver\pnp\ TRxStream\x86 boston.sys Plug and Play driver for 32-bit OS driver\pnp\ TRxStream\x86 brktBdevco.
Installation In addition to copying the files to the destination folders, this option registers (service installation) bostsrv.exe with the host system. The bostsrv.exe service registers with a dependency on the boston.sys device driver. Because the boston.msi also installs the plug and play boston device driver, you do not have to manually install the pnp driver using the Found New Hardware Wizard. This installation occurs automatically.
Installation Shortcuts The installation creates the following shortcut under Start –> Programs: Name Location Brooktrout Configuration Tool The Brooktrout Configuration Tool is a utility that is used to create and modify the configuration files, edit and update the driver parameters, and configure and initialize both physical and virtual modules. The Brooktrout Configuration tool [INSTALLDIR]\bin\configtool.exe where INSTALLDIR is the directory that you selected to install the configuration tool.
Installation During the full installation of the User Interface, a dialog appears indicating that a reboot is necessary. However, if you are running a quiet installation, all dialog boxes are suppressed including the reboot dialog box. You will have to refer to the reboot values above stored in the registry to know if a reboot is necessary.
Installation Configurable Brooktrout SDK Installation Options The first time install Finish page provides an option to: Launch Configuration Tool: The installation program provides this option to launch the configuration tool as a default. Refer to Options for Spawning MSI on page 368 for details on how to use this option. About the Merge Module Feature A Microsoft® Software Merge (MSM) module file consists of a simplified MSI database created to deliver components to an MSI application package.
Installation Files Installed The module contains the following files: File Name bostdlld.dll brkth323.dll brktsip.dll osidlld.dll bsmidlld.dll Registry Entries None Environment Variables None Shortcuts None Services None Dependency None Dynamically Linked 64-bit DLLs (dynamic_dlls_x64.msm) Merge this module to install the dynamically linked version of the 64-bit Bfv API DLLs and supporting files. Files Installed The module contains the following files: File Name bostdlld.dll osidlld.
Installation Configuration and Protocol Files (configdata.msm) Merge this module to install the configuration, protocol, and font files. Files Installed The module contains the following files: File Names analog_loopstart_europe.lec fxo_loopstart.lec analog_loopstart_us.lec fxs_groundstart.lec btcall.cfg fxs_loopstart.lec BT_CPARM.CFG ibmpcps.fnt callctrl.cfg ibmpcps.fz8 ctr21.qslac immediatedial.lec epsonec.fnt itu_argentina.r2 epsonec.fz8 itu_brazil.r2 epsones.fnt itu_china.r2 epsones.
Installation Firmware (firmware.msm) Merge this module to install the firmware files. Files Installed The module contains the following files: File Name bostvb.dll cp.bin dsp1000.hex dsp1000_ld.hex dsp1000_ud.hex dsp1000_v34.hex dsp1034_ud.
Installation Configuration Tool (configtool.msm) Merge this module to install the configuration tool and its help files. Files Installed The module contains the following files: File Name configtool.exe confighelp.zip Registry Entries RuntimeConfigtoolPath configtool.exe Environment Variables None Shortcuts Creates an advertised shortcut under Start Menu –> Program files. Shortcut Name Target Brooktrout Configuration Tool configtool.
Installation TECUpdate (TECUpdate.msm) Distribute TECUpdate to your end users even if you do not plan to distribute the Configuration Tool so that your customers can update their systems as needed. Merge this module to install TECUpdate utility files. Files Installed The module contains the following files: File Name bostdlld210.dll bostdlld301.dll bostdlld303.dll bostdlld310.dll bostdlld320.dll bostdlld330.dll TECUpdate.exe TECUpdate_Guide.pdf TECUpdateHelp.
Installation License Manager (softwarelicense.msm) Distribute the License Manager to all end users so that your customers can activate a software license on a system. The License Manager validates the license activated by the customer and turns on the Brooktrout product functionality. Merge this module to install the license program files. Files Installed The module contains the following files: File Name axis_notice.txt AxisClient.dll AxisTransport.dll AxisXMLParser.dll brktlicmgr.exe brktlicmgrhelp.
Installation Utility Programs (utilities.msm) Merge this module to install the utility programs used for querying hardware and software information, downloading firmware and performing other related tasks. Files Installed The module contains the following files: File Name AccuCall.exe AccuCallHelp.zip brktcctrace.exe btver.exe filtersettings.cfg firm.exe firmload.exe modinfo.exe vtty_tracer.
Installation Boston Host Service (bostsrv.msm) Merge this module to install and register the Boston Host Service. Files Installed Registry Entries The module contains the following files: File Number File Name Default Location 1 bostsrv.exe System Folder (Windows\System32) 2 bostsrv.dll System Folder The bostsrv.msm module creates the following registry entry.
Installation Installing the Merge Module Feature The Brooktrout SDK (sdk_windows.exe) includes the Merge Module feature that installs all the *.msm files. When you launch sdk_windows.exe, the files (merge modules) install under [INSTALLDIR]\mergemodules where INSTALLDIR identifies the location that you select for storing the Brooktrout SDK package. The mergemodules folder also includes a readme.txt file that briefly describes the merge modules.
Installation The Brooktrout merge modules consist of: dynamic_dlls.msm (independent module) dynamic_dlls_x64.msm (independent modules) configdata.msm (independent module) firmware.msm (independent module) configtool.msm (module with dependencies) softwarelicense.msm (independent module) utilities.msm (module with dependencies) bostsrv.msm (module with dependencies) TECUpdate.
Installation linking to the DLLs. With the system variable set, you can simply append the absolute path to these files to the Path environment variable. You can also add the destination location of *.exe files within the merge modules to the system path so that they are executed from anywhere on your system. Rather than relying on the Path variable, it is strongly recommended that the destination of dynamic_dlls.msm and bostsrv.msm be set to [SystemFolder], and the destination of dynamic_dlls_x64.
Installation Figure 59.
Installation Figure 60.
About Plug and Play Components About Plug and Play Components Plug and Play happens outside the process of the application that uses the drivers. The Brooktrout SDK includes Plug and Play compatible drivers and the INF file. The INF file contains essential information needed for the Windows® Class Installers to correctly identify components in an INF file and install them.
About Plug and Play Components Note: Existing Dialogic® Brooktrout® Fax Products SDK Developers: You cannot start or stop the Plug and Play driver using commands like the net start/stop commands that you might be using in your application. The user cannot restart the driver since it is now a Windows® Device Manager Plug and Play driver.
About Plug and Play Components Table 26. Brooktrout Plug and Play Components Reference Brooktrout Component Device Brooktrout hardware Function Driver boston.sys INF File trxstream.inf Device Co-Installer brktBdevco.dll Device Property Page brktBdevpp.dll Brooktrout Catalog File brooktrout.cat Driver Symbol File boston.
About Plug and Play Components Scenario 1 shows the install process beginning with installing the module. At the end of the process you have created a customized install process for Brooktrout product components. User places Board in server User opts to search for driver files on CD-ROM Drive or HDD. [Browses / places CD in drive] Plug and Play Manager calls trxstream.inf Plug and Play Manager creates "Brooktrout Hardware" class Plug and Play Manager installs boston.
About Plug and Play Components Scenario 2 shows the install process beginning with installing the software and then installing the module. User places Board in server User installs Brooktrout software Plug and Play Manager finds board Plug and Play Manager creates "Brooktrout Hardware" class Device Co-installer (brktBdevco.dlll) receives the call November 2009 User opts to search for driver files on CD-ROM Drive or HDD. [Browses / places CD in drive] Plug and Play Manager installs boston.
About Plug and Play Components Structure of the Brooktrout PnP Folder The Brooktrout PnP folder has the following structure: PnP | brooktrout.cat | trxstream.inf |- TRxStream | |- x86 | | boston.sys | | boston.pdb | | brktBdevpp.dll | | brktBdevco.dll | |- x64 | | boston.sys | | boston.pdb | | brktBdevpp.dll | | brktBdevco.dll Note: It is very important for this folder structure to be maintained when installed or copied for the Plug and Play to work correctly.
About Plug and Play Components ¾ Once you identify the INF file (specifically trxstream.inf), the following actions occur. For an authoritative description of the Plug and Play install process always use information from Microsoft (available at MSDN). 1. During the hardware installation, Windows® creates a new device under Computer Telephony Hclass.
About Plug and Play Components Automatically launches the Brooktrout Configuration Tool For details about the install package and the configuration tool, see the installation and configuration guide that came with your software. Use the next paragraphs to understand the role that the co-installer page plays in Plug and Play operating systems.
About Plug and Play Components displayed, and it instead signals the process level event. The configuration tool (upon getting unblocked because the event got signaled rather than timing out) resets the timer and waits for the event again. This process continues until the co-installer does not signal anymore; finally, the configuration tool waiting for the event times out and then launches the functional user interface.
About Plug and Play Components The Brooktrout Device Manager Property Page is a custom DLL (brktBdevpp.dll) that provides basic integration with Microsoft® Management Console. Its primary function displays feature information and its secondary function provides the option to launch the Brooktrout Configuration Tool.
Modifying Configuration Files Modifying Configuration Files This section describes each of the configuration files. You can edit the configuration files with a standard text editor or you can use the Brooktrout Configuration Tool to make changes (see the installation and configuration guide that came with your software). Assuming the default installation, the configuration files are located in Brooktrout\Boston\config. Sample configuration files are located in Brooktrout\Boston\config\samples.cfg.
Modifying Configuration Files User-Defined Configuration File (btcall.cfg) The user-defined configuration file contains parameters that set values such as specific fax formatting. The Brooktrout SDK supplies a default configuration file named btcall.cfg. If you have a btcall.cfg file created for a previous release of the Bfv API, delete the following parameters from the file.
Including the Brooktrout Configuration Tool Call Control (callctrl.cfg) Configuration File This file contains configuration parameters that define how you want the Bfv API to configure the modules for call control. For details about parameters and valid values, see the Bfv API Reference Manual, Volume 6, Appendix A, Configuration Files.
Downloading Firmware Files Downloading Firmware Files In addition to installing the software, you must: Update the boot ROM flash memory Download the firmware files Optionally configure the call control parameters. The Configuration Tool can only be used to start the Boston Host Service and to configure the call control parameters; this utility cannot be used to update the boot ROM flash memory.
Removing Software Removing Software The Add/Remove Programs selection on the Windows® Control Panel screen provides options to initiate the following on the installed components for the package (see Uninstalling or Modifying the Software in the installation and configuration guide that came with your software): Modify – Selecting this option displays a custom setup dialog that allows the user to select the features to be installed or removed.
Removing the Plug and Play Driver Removing the Plug and Play Driver Installing a Brooktrout device using the Plug and Play Manager (Found New Hardware Wizard) creates some backup files and registry entries. The Windows® Plug and Play Manager uses this information to automatically install the device on rebooting. To completely remove the Plug and Play driver from the system, you must perform a complete cleanup after you remove the device from the Device Manager.
Removing the Plug and Play Driver This value contains the name of the backup copy of the trxstream.inf file that Windows® created during device installation under C:\WINNT\INF. 8. Delete the INF file of this name from C:\WINNT\INF along with the corresponding PNF file. Except for the extension, the INF file and the PNF file have the same names. For example, if the INF file is oem11.inf, the name of the PNF file is oem11.pnf. 9.
Removing the Plug and Play Driver 7. Examine the registry value InfPath located under HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\ Control\Class\{8CF4CA66-A2CC-48FA-BC1D6A64E47F6D27}. 8. Search for the first key which contains the following values: DriverDesc=Brooktrout TRxStream Board This key should contain the name of the backup copy of the trxstream.inf file that Windows® created during the device installation under C:\winnt\INF 9.
Appendix A G3 Legacy Utilities This appendix describes legacy utilities that help manipulate raw G3 fax files. The utilities described in this chapter permit you to manipulate raw G3 fax files (rather than infopkt-formatted files) from the command line. These are legacy utilities that are provided to users who need to manipulate raw G3 files. They have been tested with previous versions of the Bfv API and are expected to work, but they are no longer tested/supported.
The G3 utilities include: ASCII to Fax Conversion Utility Converts ASCII text files to Brooktrout G3 fax image files. Cut and Paste Utilities Used in conjunction, removes parts of fax images and stores them in a separate file and recombines them into another file. Epson to Fax Conversion Utility Converts Epson print files to Brooktrout G3 fax image files. Fax Display and Edit Utility Displays fax files and provides a visual interface to the cut utility.
ASCII to Fax Conversion Utility (asctog3) ASCII to Fax Conversion Utility (asctog3) Converts ASCII text files to Brooktrout Group 3 fax image files. Although this utility is included, in most cases ASCII file transmission is better accomplished utilizing the ability of the Brooktrout fax modules to convert ASCII to G3 on-the-fly. This is a legacy utility. Command Syntax asctog3 argument-list Where: -i (input file) Specifies the input file to convert to Group 3.
Cut and Paste Utilities Cut and Paste Utilities The next two utility commands, g3chop and g3combin, permit cutting and pasting of fax images at the command line. These two commands are most commonly used to create letterhead and signature files. Cut Utility (g3chop) Removes portions of Brooktrout Group 3 fax files and stores them in a separate file. Command Syntax g3chop -sx -cy -ifile1.301 -ofile2.
Cut and Paste Utilities Paste Utility (g3combin) Combines portions of Brooktrout Group 3 fax files, and, although it is most commonly used to create letterhead and signature files, it can combine all types of fax files. Although this utility is included, in most cases combining fax files is better accomplished using infopkt files. To attach a letterhead, specify the letterhead file as file1. To attach a signature file, specify the signature file as file2.
Epson to Fax Conversion Utility (epstog3) Epson to Fax Conversion Utility (epstog3) Converts Epson print files to Brooktrout Group 3 fax images and provides complete emulation of the Epson-LX80 printer (including bold, italics and graphics). Command Syntax epstog3 argument-list Where: November 2009 -i (input file) Specifies the input printer file (Epson-format) and optional path name. -o (output file) Specifies the output fax image filename and optional pathname.
Epson to Fax Conversion Utility (epstog3) The epstog3 utility displays help information on converting graphics files to fax image files, on the command line. Note: Fonts must be located in the current directory for all platforms except those platforms that use MS-DOS executables (Windows® NT, Windows® 2000). For these cases, the fonts must be located either in the font subdirectory of the directory named by the FMAIL environment variable, if it is set, or in the boston\bfv.api\fonts directory.
Fax Display and Edit Utility: Supershow (ss) Fax Display and Edit Utility: Supershow (ss) Displays a fax file on screen for viewing and editing. Editing options include scaling, rotating, and reversing video. Note: Supershow does not scale images automatically to maintain aspect ratios or to fit images on the screen. Each pixel in the file corresponds to one pixel on the screen. Supershow does support manual scaling with the commands described on the help screen.
Fax Display and Edit Utility: Supershow (ss) -x Specifies the X-offset. Units are in tenths of an inch. -y Specifies the Y-offset. Units are in tenths of an inch. -xs Specifies the X scale factor. Values are 1, 2, or 3. -ys Specifies the Y scale factor. Values are 1, 2, or 3. -w Specifies the width (0 = A4, 1 = B4, 2 = A3) and overrides the header. -m Specifies the number of kilobytes of memory to use for an image. The default is 512K. Using large values might slow response times.
G3 Conversion Utility (g3cvt) G3 Conversion Utility (g3cvt) Converts a raw fax file between any of these formats—MH, MR, MMR, PCX, and bitmap. It accepts files that use either MSB or LSB bit order, and (optionally) skips past a Brooktrout 128-byte header. Output from this utility does not contain a 128-byte Brooktrout header. As it proceeds, g3cvt displays dots across the screen. If it detects an error in the input file, g3cvt displays an error message.
G3 Conversion Utility (g3cvt) -h Causes g3cvt to copy the first 128 bytes of the input file to the output file, with no conversion. -f Specifies fine resolution input. Used with MR or PCX output only. MR output—The program represents the data slightly differently and more efficiently when it knows the input is in fine resolution. PCX output—Since PCX format is always in fine resolution, the program must know whether the input file is in fine or normal resolution.
Print Utility (p) Print Utility (p) Prints the fax file to any one of several printers.
Print Utility (p) -yYOFF -xsXSCALE -ysYSCALE -ifiles -ooutfile -paper -w[width] A4 LET (y offset) Selects a Y direction offset in tenths of inches. Only the portion of the image below this position is displayed. (x scale factor) Selects an X direction scale factor in 5% increments. The image is scaled to this factor of its original size in the X direction. (y scale factor) Selects a Y direction scale factor in 5% increments. The image is scaled to this factor of its original size in the Y direction.
Appendix B Recompiling On Linux Platforms This appendix provides instructions for recompiling the Boston driver to support new kernel patches. Use the instructions below to recompile the Boston driver on supported Linux platforms so that the driver can operate with any kernel patch for supported Linux versions. The Boston driver supports only official kernel patches as released by Red Hat.
Each of these directories also contains a file named bostbase.a, which is a library containing precompiled object files compiled for that same kernel version, variant, and architecture. The driver/linux/kernel directory contains files named kerndep.c, kerndep.h, and makefile.kerndep. Before building a Brooktrout driver for a patch version, install the kernel source, the compiler, and other standard development tools on the system.
For Red Hat Linux releases ES/AS 4.0 and later: The kernel source itself is not required; instead, a development kit is required. This kit is in the package whose name is of the form kernel-devel-, in the file kernel-devel-.i686.rpm or kernel-smp-devel-.i686.rpm. This kit is automatically installed if you tell the Linux installation program to install everything.
Glossary API Application Programming Interface ASR Automatic Speech Recognition Channel A logical channel of operations provided by a Boston module. See logical channel number, ordinal channel number, work channel. EC Echo cancellation External-Telephony Mode Using the Bfv API directly instead of a speech engine API to perform call control (Mixed Mode) Facility A software entity responsible for a set of related functions that provide services to the host, e.g., fax facility and voice facility.
lapdid The term lapdid has its origins with the LAP-D protocol used for call control, but has an extended meaning for Brooktrout products. For call control for all protocols, trunk 1 = lapdid 0, trunk 2 = lapdid 2, trunk 3 = lapdid 4 and trunk 4 = lapdid 6. LEC Local Exchange Carrier Line A T1/E1 slot or a single analog slot. Lines are numbered starting at 1. Logical channel number A number used with the hardware module number to reference a channel in a system.
Stream A logical data entity that corresponds to a physical data line on a TDM bus. T1/E1 span The set of slots that comprises one T1 (24) or one E1 (30) line. The spans are numbered starting at 1. TCP Transmission Control Protocol Time slot A logical entity that corresponds to one telephone call. Unit number 1.
Index A About merge modules 376 Accessing the telephone system 36 Active redirecting for Japan (call transfer) 187 Add/Remove Programs Removing packaged software 404 Administration, management and configuration Bfv functions 26 Administrative channels 30 ALERTING Q.931 message 318, 321 API debug mode 92 parsed commands in output 98 app.
Checking for presence of 369 BSMI API Boston Simple Message Interface 23 call control 36 control messages 37 BT_CPARM.CFG file 32 btcall.cfg configuration files 32 Modifying for packaging software 401 BTLINE structure 25, 28 btver program debugging tool 100 using 129 C call clearing initiated by the board 323 initiated by the network 325 Call control 36 Bfv API 36 BSMI API 36 call progress signals 38 CALL PROCEEDING Q.
dfax program 136 Diagnostic utilities, tracing messages 101 Dialing restrictions 137 dialing ISDN overlapped 323 Dialing database functions 137 digits dial pulse 269, 270 timers 268 DISCONNECT Q.
full duplex call transfer, see Two-channel call transfers Functions administration and initialization 27 board status and monitoring 33 configuration 31 debugging and error handling 33 fax 40 file format manipulation 42 firmware 31 high-level 40 high-level fax 41 low-level 40 low-level fax 41 mid-level 40 mid-level fax 41 miscellaneous 35 FXO signaling 289 FXS signaling 289 G G3 Conversion Utility 417 G3 utilities 408 ASCII to fax conversion utility(asctog3) 410 cut (g3chop) 411 Epson to fax conversion uti
Installing merge modules 385 Instant ISDN Software, Layer 2 and Layer 3 parameters 332 Integrating Brooktrout software with your software 368 Integrating merge modules 385–389 IP Receiving IP Calls 218 Sending IP Calls 217 ipstrip program 151 ISDN calls call clearing 323 dialing long numbers 323 incoming call handling 318 outgoing call handling 321 Overlapped dialing 323 ivr program 152 K Kernel patches for Linux, recompiling for new patches 422 L L3L4mALERTING outgoing call example 321 L3L4mCLEAR_REQUEST
firmware 31 miscellaneous 35 Making registry entries 384 Maximum transmit window (K) 333 Media processing Bfv functions 26 types of applications 38 Merge modules About the feature 376 Defining file locations 384 Dependent 386 Feature content 376 Independent 386 Installing 385 Integrating 385–389 Merging examples 387–389 msm files 376–384 Registry entry 384 Messages header 105 recording and playing 152 MF tone detection 38 generation 38 Mid-level fax functions 41 Miscellaneous functions 35 Miscellaneous macr
Installation flowcharts 392 Installation package 364 InstallHome Path 373 Instructions for installing boards 367 Instructions for Plug and play drivers. 367 Integrating software 368 isdn parameter 401 Launching the Configuration Tool 397 Making registry entries 373 Merge module 366, 376 modifying btcall.
Release Link Trunk 202 RELEASE Q.
Spawning Installation package 364 Speech infopkt parameters 51 recording and playing 139, 167, 169, 170 recording and playing wave files 170 Status information, fax 89 Storing information about a channel 28 Streams, definition 428 Structures 34 Supershow (ss) display and edit utility 415 Switched 56 calls, guard timing 325 Syntax, defining boston.msi properties 368 System Packaging requirements 365 Packaging software files 369 Packaging Software Installation Options 376 T T.
BfvCallSWConnect 192 BfvCallSWGetConns 192 BfvCallSWGetInfo 192 Conditions for termination 199 Configuring echo cancellation 195 Connecting resources 191 Connection type 191 Defining source and destination resources 191 Disconnecting resources 194, 200 Echo cancellation 194 Noise when terminating the full duplex connection 197 Removing conflicting connections 193 Resources 191 Restoring echo canceler defaults after termination 201 Setting up 191 Source code for disconnecting resources 200 Source code for ec
November 2009 440
