Voice API For Windows Operating Systems Programming Guide 6.2 Win V1
User Manual: 6.2
Open the PDF directly: View PDF 
.
Page Count: 190
| Download | |
| Open PDF In Browser | View PDF |
Voice API for Windows Operating Systems Programming Guide November 2002 05-1831-001 INFORMATION IN THIS DOCUMENT IS PROVIDED IN CONNECTION WITH INTEL® PRODUCTS. NO LICENSE, EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, TO ANY INTELLECTUAL PROPERTY RIGHTS IS GRANTED BY THIS DOCUMENT. EXCEPT AS PROVIDED IN INTEL'S TERMS AND CONDITIONS OF SALE FOR SUCH PRODUCTS, INTEL ASSUMES NO LIABILITY WHATSOEVER, AND INTEL DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY, RELATING TO SALE AND/OR USE OF INTEL PRODUCTS INCLUDING LIABILITY OR WARRANTIES RELATING TO FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR INFRINGEMENT OF ANY PATENT, COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT. Intel products are not intended for use in medical, life saving, or life sustaining applications. Intel may make changes to specifications and product descriptions at any time, without notice. This Voice API for Windows Operating Systems Programming Guide as well as the software described in it is furnished under license and may only be used or copied in accordance with the terms of the license. The information in this manual is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Intel Corporation. Intel Corporation assumes no responsibility or liability for any errors or inaccuracies that may appear in this document or any software that may be provided in association with this document. Except as permitted by such license, no part of this document may be reproduced, stored in a retrieval system, or transmitted in any form or by any means without express written consent of Intel Corporation. Copyright © 2002, Intel Corporation AlertVIEW, AnyPoint, AppChoice, BoardWatch, BunnyPeople, CablePort, Celeron, Chips, CT Media, Dialogic, DM3, EtherExpress, ETOX, FlashFile, i386, i486, i960, iCOMP, InstantIP, Intel, Intel logo, Intel386, Intel486, Intel740, IntelDX2, IntelDX4, IntelSX2, Intel Create&Share, Intel GigaBlade, Intel InBusiness, Intel Inside, Intel Inside logo, Intel NetBurst, Intel NetMerge, Intel NetStructure, Intel Play, Intel Play logo, Intel SingleDriver, Intel SpeedStep, Intel StrataFlash, Intel TeamStation, Intel Xeon, Intel XScale, IPLink, Itanium, LANDesk, LanRover, MCS, MMX, MMX logo, Optimizer logo, OverDrive, Paragon, PC Dads, PC Parents, PDCharm, Pentium, Pentium II Xeon, Pentium III Xeon, Performance at Your Command, RemoteExpress, Shiva, SmartDie, Solutions960, Sound Mark, StorageExpress, The Computer Inside., The Journey Inside, TokenExpress, Trillium, VoiceBrick, Vtune, and Xircom are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries. * Other names and brands may be claimed as the property of others. Publication Date: November 2002 Document Number: 05-1831-001 Intel Converged Communications, Inc. 1515 Route 10 Parsippany, NJ 07054 For Technical Support, visit the Intel Telecom Support Resources website at: http://developer.intel.com/design/telecom/support/ For Products and Services Information, visit the Intel Communications Systems Products website at: http://www.intel.com/network/csp/ For Sales Offices and other contact information, visit the Intel Telecom Building Blocks Sales Offices page at: http://www.intel.com/network/csp/sales/ Voice API for Windows Operating Systems Programming Guide – November 2002 Contents About This Publication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Intended Audience. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How to Use This Publication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Related Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Product Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 1.1 1.2 1.3 1.4 1.5 1.6 1.7 1.8 1.9 1.10 2 15 15 16 16 16 17 17 17 17 18 18 18 18 19 19 19 19 20 Standard Runtime Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Asynchronous Programming Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Synchronous Programming Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Device Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 3.1 3.2 4 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . R4 API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Call Progress Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Tone Generation and Detection Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.4.1 Global Tone Detection (GTD) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.4.2 Global Tone Generation (GTG) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.4.3 Cadenced Tone Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Dial Pulse Detection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Play and Record Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.6.1 Play and Record Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.6.2 Speed and Volume Control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.6.3 Transaction Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.6.4 Silence Compressed Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.6.5 Echo Cancellation Resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Send and Receive FSK Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Caller ID. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . R2/MF Signaling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TDM Bus Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Programming Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 2.1 2.2 2.3 3 11 11 11 11 13 Device Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Voice Device Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Event Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 4.1 4.2 Overview of Event Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Event Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 5 Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 6 Application Development Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 6.1 General Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.1.1 Busy and Idle States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.1.2 I/O Terminations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.1.3 Clearing Structures Before Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Voice API for Windows Operating Systems Programming Guide – November 2002 31 31 31 34 3 Contents 6.2 6.3 6.4 6.5 7 Call Progress Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 7.1 7.2 7.3 7.4 7.5 7.6 7.7 7.8 7.9 7.10 7.11 4 Fixed and Flexible Routing Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 Fixed Routing Configuration Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 Additional DM3 Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 6.4.1 Call Control Through Global Call API Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 6.4.2 Multi-Threading and Multi-Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 6.4.3 DM3 Interoperability. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 6.4.4 DM3 Media Loads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 6.4.5 Device Discovery for DM3 and Springware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 6.4.6 Device Initialization Hint. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 6.4.7 TDM Bus Time Slot Considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 Using Wink Signaling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 6.5.1 Setting Delay Prior to Wink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 6.5.2 Setting Wink Duration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 6.5.3 Receiving an Inbound Wink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Call Progress Analysis Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 Call Progress and Call Analysis Terminology. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 Call Progress Analysis Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 Using Call Progress Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 7.4.1 Overview of Steps to Initiate Call Progress Analysis . . . . . . . . . . . . . . . . . . . . . . . 46 7.4.2 Enabling Call Progress Analysis Features in DX_CAP . . . . . . . . . . . . . . . . . . . . . 46 7.4.3 Enabling Call Progress Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 7.4.4 Executing a Dial Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 7.4.5 Determining the Outcome of a Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 7.4.6 Obtaining Additional Call Outcome Information. . . . . . . . . . . . . . . . . . . . . . . . . . . 49 R4 on DM3 Call Progress Analysis Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Tone Detection in Call Progress Analysis. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 7.6.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 7.6.2 Types of Tones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 7.6.3 Dial Tone Detection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 7.6.4 Ringback Detection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 7.6.5 Busy Tone Detection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 7.6.6 Positive Voice Detection (PVD) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 7.6.7 Positive Answering Machine Detection (PAMD) . . . . . . . . . . . . . . . . . . . . . . . . . . 56 7.6.8 Fax or Modem Tone Detection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 7.6.9 Disconnect Tone Supervision . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 7.6.10 Loop Current Detection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 PBX Expert Tone Set Files and Call Progress Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Default Tone Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Modifying Default Tone Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 SIT Frequency Detection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 7.10.1 Tri-Tone SIT Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 7.10.2 Setting Tri-Tone SIT Frequency Detection Parameters. . . . . . . . . . . . . . . . . . . . . 62 7.10.3 Obtaining Tri-Tone SIT Frequency Information . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 7.10.4 Global Tone Detection Tone Memory Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 7.10.5 Frequency Detection Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 7.10.6 Setting Single Tone Frequency Detection Parameters . . . . . . . . . . . . . . . . . . . . . 66 7.10.7 Obtaining Single Tone Frequency Information . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 Call Progress Analysis Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 Voice API for Windows Operating Systems Programming Guide – November 2002 Contents 7.12 8 8.9 Overview of Recording and Playback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Digital Recording and Playback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Play and Record Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Play and Record Convenience Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Voice Encoding Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G.726 Voice Coder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Transaction Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Silence Compressed Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.8.1 Overview of Silence Compressed Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.8.2 Enabling Silence Compressed Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.8.3 Encoding Methods Supported in Silence Compressed Record . . . . . . . . . . . . . . Echo Cancellation Resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.9.1 Overview of Echo Cancellation Resource. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.9.2 Echo Cancellation Resource Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.9.3 Modes of Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.9.4 Echo Cancellation Resource Application Models . . . . . . . . . . . . . . . . . . . . . . . . . 77 77 78 78 79 80 81 81 81 82 83 84 84 84 86 88 Speed and Volume Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 9.1 9.2 9.3 9.4 9.5 9.6 9.7 10 67 68 68 69 70 71 75 Recording and Playback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 8.1 8.2 8.3 8.4 8.5 8.6 8.7 8.8 9 Cadence Detection in Basic Call Progress Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.12.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.12.2 Typical Cadence Patterns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.12.3 Elements of a Cadence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.12.4 Outcomes of Cadence Detection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.12.5 Setting Selected Cadence Detection Parameters. . . . . . . . . . . . . . . . . . . . . . . . . 7.12.6 Obtaining Cadence Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Speed and Volume Control Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Speed and Volume Convenience Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Speed and Volume Adjustment Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 Speed and Volume Modification Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 Play Adjustment Digits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 Setting Play Adjustment Conditions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 Explicitly Adjusting Speed and Volume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 Send and Receive FSK Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 10.1 10.2 10.3 10.4 10.5 10.6 10.7 Overview of ADSI and Two-Way FSK Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ADSI Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ADSI Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . One-Way ADSI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Two-Way ADSI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10.5.1 Transmit to On-Hook CPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10.5.2 Two-Way FSK. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ADSI and Two-Way FSK Voice Library Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10.6.1 Support on DM3 Boards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10.6.2 Support on Springware Boards. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Developing ADSI Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10.7.1 Technical Overview of One-Way ADSI Data Transfer . . . . . . . . . . . . . . . . . . . . 10.7.2 Implementing One-Way ADSI Using dx_TxIottData( ) . . . . . . . . . . . . . . . . . . . . 10.7.3 Technical Overview of Two-Way ADSI Data Transfer . . . . . . . . . . . . . . . . . . . . 10.7.4 Implementing Two-Way ADSI Using dx_TxIottData( ) . . . . . . . . . . . . . . . . . . . . Voice API for Windows Operating Systems Programming Guide – November 2002 105 106 107 107 108 108 108 109 109 110 110 110 111 112 113 5 Contents 10.8 11 Caller ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 11.1 11.2 11.3 11.4 11.5 11.6 12 12.3 13.2 13.3 Global Tone Detection (GTD) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 13.1.1 Overview of Global Tone Detection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 13.1.2 Defining Global Tone Detection Tones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 13.1.3 Building Tone Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 13.1.4 Working with Tone Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 13.1.5 Retrieving Tone Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 13.1.6 Setting GTD Tones as Termination Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . 133 13.1.7 Maximum Amount of Memory Available for User-Defined Tone Templates . . . . 133 13.1.8 Estimating Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 13.1.9 Guidelines for Creating User-Defined Tones. . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 13.1.10 Global Tone Detection Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 Global Tone Generation (GTG) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 13.2.1 Using GTG. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 13.2.2 GTG Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 13.2.3 Building and Implementing a Tone Generation Template . . . . . . . . . . . . . . . . . . 139 Cadenced Tone Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 13.3.1 Using Cadenced Tone Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 13.3.2 How To Generate a Custom Cadenced Tone . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 13.3.3 How To Generate a Non-Cadenced Tone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 13.3.4 TN_GENCAD Data Structure - Cadenced Tone Generation. . . . . . . . . . . . . . . . 143 13.3.5 How To Generate a Standard PBX Call Progress Signal . . . . . . . . . . . . . . . . . . 143 13.3.6 Predefined Set of Standard PBX Call Progress Signals . . . . . . . . . . . . . . . . . . . 144 13.3.7 Important Considerations for Using Predefined Call Progress Signals . . . . . . . . 149 Global Dial Pulse Detection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 14.1 14.2 14.3 14.4 6 Overview of Cached Prompt Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 Using Cached Prompt Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 12.2.1 Discovering Cached Prompt Capability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 12.2.2 Downloading Cached Prompts to a Board. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 12.2.3 Playing Cached Prompts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 12.2.4 Recovering from Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 12.2.5 Cached Prompt Management Hints and Tips . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 Cached Prompt Management Example Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 Global Tone Detection and Generation, and Cadenced Tone Generation. . . . . . . . . . . . . . 129 13.1 14 Overview of Caller ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 Caller ID Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 Accessing Caller ID Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 Enabling Channels to Use the Caller ID Feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 Error Handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 Caller ID Technical Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 Cached Prompt Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 12.1 12.2 13 10.7.5 Implementing Two-Way ADSI Using dx_TxRxIottData( ) . . . . . . . . . . . . . . . . . . 114 Modifying Older One-Way ADSI Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 Key Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 Global DPD Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 Enabling Global DPD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 Global DPD Programming Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 Voice API for Windows Operating Systems Programming Guide – November 2002 Contents 14.5 14.6 14.7 14.8 15 R2/MF Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Direct Dialing-In Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . R2/MF Multifrequency Combinations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . R2/MF Signal Meanings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . R2/MF Compelled Signaling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . R2/MF Voice Library Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . R2/MF Tone Detection Template Memory Requirements . . . . . . . . . . . . . . . . . . . . . . . . 157 158 158 159 165 167 168 Syntellect License Automated Attendant. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 16.1 16.2 16.3 17 153 154 154 154 R2/MF Signaling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 15.1 15.2 15.3 15.4 15.5 15.6 15.7 16 Dial Pulse Detection Digit Type Reporting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Defines for Digit Type Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Global DPD Programming Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Global DPD Example Code (Synchronous Model) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview of Automated Attendant Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 Syntellect License Automated Attendant Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 How to Use the Automated Attendant Function Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 Building Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 17.1 17.2 Voice and SRL Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Compiling and Linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17.2.1 Include Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17.2.2 Required Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17.2.3 Run-time Linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17.2.4 Variables for Compiling and Linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 172 172 172 173 173 Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 Voice API for Windows Operating Systems Programming Guide – November 2002 7 Contents Figures 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 8 Cluster Configurations for Fixed and Flexible Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 Multiple Devices Listening to the Same TDM Bus Time Slot . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 Basic Call Progress Analysis Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 PerfectCall Call Progress Analysis Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 Call Outcomes for Call Progress Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 A Standard Busy Signal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 A Standard Single Ring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 A Type of Double Ring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 Cadence Detection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 Elements of Established Cadence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 No Ringback Due to Continuous No Signal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 No Ringback Due to Continuous Nonsilence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 Cadence Detection Salutation Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Silence Compressed Record Parameters Illustrated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Echo Canceller with Relevant Input and Output Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Echo Canceller Operating over a TDM bus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 ECR Bridge Example Diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 An ECR Play Over the TDM bus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 Example of Custom Cadenced Tone Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 Standard PBX Call Progress Signals (Part 1) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 Standard PBX Call Progress Signals (Part 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 Forward and Backward Interregister Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 Multiple Meanings for R2/MF Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 R2/MF Compelled Signaling Cycle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 Example of R2/MF Signals for 4-digit DDI Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 Voice and SRL Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 Voice API for Windows Operating Systems Programming Guide – November 2002 Contents Tables 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 Voice Device Inputs for Event Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Voice Device Returns from Event Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 API Function Restrictions in a Fixed Routing Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 Call Progress Analysis Support with dx_dial( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Default Call Progress Analysis Tone Definitions (DM3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Default Call Progress Analysis Tone Definitions (Springware) . . . . . . . . . . . . . . . . . . . . . . . . . 60 Special Information Tone Sequences (Springware) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 Voice Encoding Methods (DM3 Boards) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Voice Encoding Methods (Springware Boards) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Default Speed Modification Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 Default Volume Modification Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 Supported CLASS Caller ID Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 Standard Bell System Network Call Progress Tones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 Asynchronous/Synchronous Tone Event Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 Maximum Memory Available for User-Defined Tone Templates . . . . . . . . . . . . . . . . . . . . . . . 134 Maximum Memory Available for Tone Templates for Tone-Creating Voice Features . . . . . . . 134 Maximum Memory and Tone Templates (for Dual Tones) . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 Standard PBX Call Progress Signals. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 TN_GENCAD Definitions for Standard PBX Call Progress Signals . . . . . . . . . . . . . . . . . . . . 148 Forward Signals, CCITT Signaling System R2/MF tones . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158 Backward Signals, CCITT Signaling System R2/MF tones . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 Purpose of Signal Groups and Changeover in Meaning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 Meanings for R2/MF Group I Forward Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 Meanings for R2/MF Group II Forward Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 Meanings for R2/MF Group A Backward Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 Meanings for R2/MF Group B Backward Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 Voice API for Windows Operating Systems Programming Guide – November 2002 9 Contents 10 Voice API for Windows Operating Systems Programming Guide – November 2002 About This Publication The following topics provide information about this publication: • Purpose • Intended Audience • How to Use This Publication • Related Information Purpose This publication describes voice processing features and provides guidelines for building computer telephony applications using the voice API on Windows* operating systems. Such applications include, but are not limited to, call routing, voice messaging, interactive voice response, and call center applications. This publication is a companion guide to the Voice API Library Reference, which provides details on the functions and parameters in the voice library. Intended Audience This information is intended for: • Distributors • System Integrators • Toolkit Developers • Independent Software Vendors (ISVs) • Value Added Resellers (VARs) • Original Equipment Manufacturers (OEMs) • End Users How to Use This Publication This document assumes that you are familiar with and have prior experience with Windows* operating systems and the C programming language. Use this document together with the following: the Voice API Programming Guide, the Standard Runtime Library API Programming Guide, and the Standard Runtime Library API Library Reference. Voice API for Windows Operating Systems Programming Guide — November 2002 11 About This Publication The information in this guide is organized as follows: • Chapter 1, “Product Description” introduces the key features of the voice library and provides a brief description of each feature. • Chapter 2, “Programming Models” provides a brief overview of supported programming models. • Chapter 3, “Device Handling” discusses topics related to devices such as device naming concepts, how to open and close devices, and how to discover whether a device is Springware or DM3. • Chapter 4, “Event Handling” provides information on functions used to handle events. • Chapter 5, “Error Handling” provides information on handling errors in your application. • Chapter 6, “Application Development Guidelines” provides programming guidelines and techniques for developing an application using the voice library. This chapter also discusses fixed and flexible routing configurations. • Chapter 7, “Call Progress Analysis” describes the components of call progress analysis in detail. This chapter also covers differences between Basic Call Progress Analysis and PerfectCall Call Progress Analysis. • Chapter 8, “Recording and Playback” discusses playback and recording features, such as encoding algorithms, play and record API functions, transaction record, and silence compressed record. • Chapter 9, “Speed and Volume Control” explains how to control speed and volume of playback recordings through API functions and data structures. • Chapter 10, “Send and Receive FSK Data” describes the two-way frequency shift keying (FSK) feature, the Analog Display Services Interface (ADSI), and API functions for use with this feature. • Chapter 11, “Caller ID” describes the caller ID feature, supported formats, and how to enable it. • Chapter 12, “Cached Prompt Management” provides information on cached prompts and how to use cached prompt management in your application. • Chapter 13, “Global Tone Detection and Generation, and Cadenced Tone Generation” describes these tone detection and generation features in detail. • Chapter 14, “Global Dial Pulse Detection” discusses the Global DPD feature, the API functions for use with this feature, programming guidelines, and example code. • Chapter 15, “R2/MF Signaling” describes the R2/MF signaling protocol, the API functions for use with this feature, and programming guidelines. • Chapter 16, “Syntellect License Automated Attendant” describes Intel® Dialogic® hardware and software that include a license for the Syntellect Technology Corporation (STC) patent portfolio. • Chapter 17, “Building Applications” discusses compiling and linking requirements such as include files and library files. 12 Voice API for Windows Operating Systems Programming Guide — November 2002 About This Publication Related Information You can download Intel® Dialogic® documentation (known as the online bookshelf) as part of the system release software installation or from the Telecom Support Resources website at http://resource.intel.com/telecom/support/documentation/releases/index.htm. See the following for more information: • For details on all voice functions, parameters and data structures in the voice library, see the Voice API Library Reference. • For details on the Standard Runtime Library (SRL), supported programming models, and programming guidelines for building all applications, see the Standard Runtime Library API Programming Guide. The SRL is a device-independent library that consists of event management functions and standard attribute functions. • For details on all functions and data structures in the Standard Runtime Library (SRL) library, see the Standard Runtime Library API Library Reference. • For information on the system release, system requirements, software and hardware features, supported hardware, and release documentation, see the Release Guide for the system release you are using. • For details on compatibility issues, restrictions and limitations, known problems, and late- breaking updates or corrections to the release documentation, see the Release Update. Be sure to check the Release Update for the system release you are using for any updates or corrections to this publication. Release Updates are available on the Telecom Support Resources website at http://resource.intel.com/telecom/support/releases/index.html. • For details on installing the system software, see the System Release Installation Guide. • For guidelines on building applications using Global Call software (a common signaling interface for network-enabled applications, regardless of the signaling protocol needed to connect to the local telephone network), see the Global Call API Programming Guide. • For details on all functions and data structures in the Global Call library, see the Global Call API Library Reference. • For details on configuration files (including FCD/PCD files) and instructions for configuring products, see the Configuration Guide for your product or product family. • For technical support, see http://developer.intel.com/design/telecom/support/. This Technical Support Web site contains developer support information, downloads, release documentation, technical notes, application notes, a user discussion forum, and more. Voice API for Windows Operating Systems Programming Guide — November 2002 13 About This Publication 14 Voice API for Windows Operating Systems Programming Guide — November 2002 Product Description 1. 1 This chapter provides information on key voice library features and capability. The following topics are covered: • Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 • R4 API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 • Call Progress Analysis. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 • Tone Generation and Detection Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 • Dial Pulse Detection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 • Play and Record Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 • Send and Receive FSK Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 • Caller ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 • R2/MF Signaling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 1.1 Overview The voice software provides a high-level interface to telecom media processing boards from Intel and is a building block for creating computer telephony applications. It offers a comprehensive set of features such as dual-tone multifrequency (DTMF) detection, tone signaling, call progress analysis, caller ID detection, playing and recording that supports a number of encoding methods, and much more. The voice software consists of a C language library of functions, device drivers, and firmware. The voice library is well integrated with other technology libraries provided by Intel such as fax, conferencing, and continuous speech processing. This architecture enables you to add new capability to your voice application over time. For an up-to-date list of products and features supported, see the latest system release guide. For a list of voice features by product, see http://www.intel.com/design/network/products/telecom/boards/index.htm. 1.2 R4 API The term R4 API (“System Software Release 4 Application Programming Interface”) describes the direct interface used for creating computer telephony application programs. The R4 API is a rich set of proprietary APIs for building computer telephony applications tailored to hardware products from Intel. These APIs encompass technologies that include voice, network interface, fax, and speech. This document describes the voice API. Voice API for Windows Operating Systems Programming Guide — November 2002 15 Product Description In addition to original Springware products (also known as earlier-generation products), the R4 API supports a new generation of hardware products that are based on the DM3 mediastream architecture. Feature differences between these two categories of products are noted. DM3 boards is a collective name used in this document to refer to products that are based on the Intel® Dialogic® DM3 mediastream architecture. DM3 board names typically are prefaced with “DM,” such as the Intel® NetStructure™ DM/V2400A-PCI. Springware boards refer to boards based on earlier-generation architecture. Springware boards typically are prefaced with “D,” such as the Intel® Dialogic® D/240JCT-T1. In this document, the term voice API is used to refer to the R4 voice API. The term “R4 for DM3” or “R4 on DM3” is used to refer to specific aspects of the R4 API interface that relate to support for DM3 boards. 1.3 Call Progress Analysis Call progress analysis monitors the progress of an outbound call after it is dialed into the Public Switched Telephone Network (PSTN). There are two forms of call progress analysis: basic and PerfectCall. PerfectCall call progress analysis uses an improved method of signal identification and can detect fax machines and answering machines. Basic call progress analysis provides backward compatibility for older applications written before PerfectCall call progress analysis became available. Note: PerfectCall call progress analysis was formerly called enhanced call analysis. See Chapter 7, “Call Progress Analysis” for detailed information about this feature. 1.4 Tone Generation and Detection Features In addition to DTMF and MF tone detection and generation, the following signaling features are provided by the voice library: • Global Tone Detection (GTD) • Global Tone Generation (GTG) • Cadenced Tone Generation 1.4.1 Global Tone Detection (GTD) Global tone detection allows you to define single- or dual-frequency tones for detection on a channel-by-channel basis. Global tone detection and GTD tones are also known as user-defined tone detection and user-defined tones. Use global tone detection to detect single- or dual-frequency tones outside the standard DTMF range of 0-9, a-d, *, and #. The characteristics of a tone can be defined and tone detection can be enabled using GTD functions and data structures provided in the voice library. 16 Voice API for Windows Operating Systems Programming Guide — November 2002 Product Description See Chapter 13, “Global Tone Detection and Generation, and Cadenced Tone Generation” for detailed information about global tone detection. 1.4.2 Global Tone Generation (GTG) Global tone generation allows you to define a single- or dual-frequency tone in a tone generation template and to play the tone on a specified channel. See Chapter 13, “Global Tone Detection and Generation, and Cadenced Tone Generation” for detailed information about global tone generation. 1.4.3 Cadenced Tone Generation Cadenced tone generation is an enhancement to global tone generation. It allows you to generate a tone with up to 4 single- or dual-tone elements, each with its own on/off duration, which creates the signal pattern or cadence. You can define your own custom cadenced tone or take advantage of the built-in set of standard PBX call progress signals, such as dial tone, ringback, and busy. See Chapter 13, “Global Tone Detection and Generation, and Cadenced Tone Generation” for detailed information about cadenced tone generation. 1.5 Dial Pulse Detection Dial pulse detection (DPD) allows applications to detect dial pulses from rotary or pulse phones by detecting the audible clicks produced when a number is dialed, and to use these clicks as if they were DTMF digits. Global dial pulse detection, called global DPD, is a software-based dial pulse detection method that can use country-customized parameters for extremely accurate performance. See Chapter 14, “Global Dial Pulse Detection” for more information about this feature. 1.6 Play and Record Features The following play and record features are provided by the voice library: • Play and Record Functions • Speed and Volume Control • Transaction Record • Silence Compressed Record • Echo Cancellation Resource Voice API for Windows Operating Systems Programming Guide — November 2002 17 Product Description 1.6.1 Play and Record Functions The voice library includes several functions and data structures used for recording and playing audio data. These allow you to digitize and store human voice, then retrieve, convert and play this digital information. For more information about the play and record feature, see Chapter 8, “Recording and Playback”. For detailed information about play and record functions, see the Voice API Library Reference. Telecom media processing boards from Intel support many well-known voice encoding methods or algorithms. For more information about these voice encoding methods or algorithms, see Section 8.5, “Voice Encoding Methods”, on page 79. 1.6.2 Speed and Volume Control The speed and volume control feature allows you to control the speed and volume of a message being played on a channel, for example, by entering a DTMF tone. Several functions and data structures can be used to control speed and volume of play on a channel. For more information, see Chapter 9, “Speed and Volume Control”. 1.6.3 Transaction Record The transaction record feature allows voice activity on two channels to be summed and stored in a single file, or in a combination of files, devices, and memory. This feature is useful in call center applications where it is necessary to archive a verbal transaction or record a live conversation. See Chapter 8, “Recording and Playback” for more information on the transaction record feature. 1.6.4 Silence Compressed Record The silence compressed record (SCR) feature enables recording with silent pauses eliminated. This results in smaller recorded files with no loss of intelligibility. When the audio level is at or falls below the silence threshold for a minimum duration of time, silence compressed record begins. If a short burst of noise (glitch) is detected, the compression does not end unless the glitch is longer than a specified period of time. See Chapter 8, “Recording and Playback” for more information. 18 Voice API for Windows Operating Systems Programming Guide — November 2002 Product Description 1.6.5 Echo Cancellation Resource The echo cancellation resource (ECR) feature enables a voice channel to dynamically perform echo cancellation on any external TDM bus time slot signal. Note: The ECR feature has been replaced with continuous speech processing (CSP). Although the CSP API is related to the voice API, it is provided as a separate product. The continuous speech processing software is a significant enhancement to ECR. The continuous speech processing library provides many features such as high-performance echo cancellation, voice energy detection, barge-in, voice event signaling, pre-speech buffering, full-duplex operation and more. For more information on this API, see the Continuous Speech Processing documentation. See Chapter 8, “Recording and Playback” for a detailed description of the ECR feature. 1.7 Send and Receive FSK Data The send and receive frequency shift keying (FSK) data interface is used for Analog Display Services Interface (ADSI). Frequency shift keying is a frequency modulation technique to send digital data over voiced band telephone lines. ADSI allows information to be transmitted for display on a display-based telephone connected to an analog loop-start line, and to store and forward SMS messages in the Public Switched Telephone Network (PSTN). The telephone must be a true ADSI-compliant device. See Chapter 10, “Send and Receive FSK Data” for a summary of the ADSI protocol and directions for implementing ADSI support using voice library functions. 1.8 Caller ID An application can enable the caller ID feature on specific channels to process caller ID information as it is received with an incoming call. Caller ID information can include the calling party’s directory number (DN), the date and time of the call, and the calling party’s subscriber name. See Chapter 11, “Caller ID” for more information about this feature. 1.9 R2/MF Signaling R2/MF signaling is an international signaling system that is used in Europe and Asia to permit the transmission of numerical and other information relating to the called and calling subscribers’ lines. R2/MF signaling is typically accomplished through the Global Call API. For more information, see the Global Call documentation set. Chapter 15, “R2/MF Signaling” is provided for reference only. for more information about R2/MF signaling and how to use it with Springware boards. Voice API for Windows Operating Systems Programming Guide — November 2002 19 Product Description 1.10 TDM Bus Routing A time division multiplexing (TDM) bus is a technique for transmitting a number of separate digitized signals simultaneously over a communication medium. TDM bus includes the CT Bus and SCbus. The CT Bus is an implementation of the computer telephony bus standard developed by the Enterprise Computer Telephony Forum (ECTF) and accepted industry-wide. The H100 hardware specification covers CT Bus implementation using the PCI form factor. The H110 hardware specification covers CT Bus implementation using the CompactPCI (cPCI) form factor. The CT Bus has 4096 bi-directional time slots. The SCbus or signal computing bus connects Signal Computing System Architecture (SCSA) resources. The SCbus has 1024 bi-directional time slots. A TDM bus connects voice, telephone network interface, fax, and other technology resource boards together. TDM bus boards are treated as board devices with on-board voice and/or telephone network interface devices that are identified by a board and channel (time slot for digital network channels) designation, such as a voice channel, analog channel, or digital channel. For information on TDM routing functions, see the Voice API Library Reference. Note: 20 When you see a reference to the SCbus or SCbus routing, the information also applies to the CT Bus on DM3 products. That is, the physical interboard connection can be either SCbus or CT Bus. The SCbus protocol is used and the TDM routing API (previously called the SCbus routing API) applies to all the boards regardless of whether they use an SCbus or CT Bus physical interboard connection. Voice API for Windows Operating Systems Programming Guide — November 2002 Programming Models 2. 2 This chapter briefly discusses the Standard Runtime Library and supported programming models: • Standard Runtime Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 • Asynchronous Programming Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 • Synchronous Programming Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 2.1 Standard Runtime Library The Standard Runtime Library (SRL) provides a set of common system functions that are device independent and are applicable to all Intel® Dialogic® devices. The SRL consists of a data structure, event management functions, device management functions (called standard attribute functions), and device mapper functions. You can use the SRL to simplify application development, such as by writing common event handlers to be used by all devices. When developing voice processing applications, refer to the Standard Runtime Library documentation in tandem with the voice library documentation. For more information on the Standard Runtime Library, see the Standard Runtime Library API Library Reference and Programming Guide. 2.2 Asynchronous Programming Models Asynchronous programming enables a single program to control multiple voice channels within a single process. This allows the development of complex applications where multiple tasks must be coordinated simultaneously. The asynchronous programming model uses functions that do not block thread execution; that is, the function continues processing under the hood. A Standard Runtime Library (SRL) event later indicates function completion. Generally, if you are building applications that use any significant density, you should use the asynchronous programming model to develop field solutions. For complete information on asynchronous programming models, see the Standard Runtime Library API Programming Guide. 2.3 Synchronous Programming Model The synchronous programming model uses functions that block application execution until the function completes. This model requires that each channel be controlled from a separate process. This allows you to assign distinct applications to different channels dynamically in real time. Voice API for Windows Operating Systems Programming Guide — November 2002 21 Programming Models Synchronous programming models allow you to scale an application by simply instantiating more threads or processes (one per channel). This programming model may be easy to encode and manage but it relies on the system to manage scalability. Applying the synchronous programming model can consume large amounts of system overhead, which reduces the achievable densities and negatively impacts timely servicing of both hardware and software interrupts. Using this model, a developer can only solve system performance issues by adding memory or increasing CPU speed or both. The synchronous programming models may be useful for testing or very low-density solutions. For complete information on synchronous programming models, see the Standard Runtime Library API Programming Guide. 22 Voice API for Windows Operating Systems Programming Guide — November 2002 Device Handling 3. 3 This chapter describes the concept of a voice device and how voice devices are named and used. • Device Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 • Voice Device Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 3.1 Device Concepts The following concepts are key to understanding devices and device handling: device A device is a computer component controlled through a software device driver. A resource board, such as a voice resource, fax resource, and conferencing resource, and network interface board contain one or more logical board devices. Each channel or time slot on the board is also considered a device. device channel A device channel refers to a data path that processes one incoming or outgoing call at a time (equivalent to the terminal equipment terminating a phone line). The first two numbers in the product naming scheme identify the number of device channels for a given product. For example, there are 24 voice device channels on a D/240JCT-T1 board, 30 on a D/300JCT-E1. device name A device name is a literal reference to a device, used to gain access to the device via an xx_open( ) function, where “xx” is the prefix defining the device to be opened. For example, “dx” is the prefix for voice device, “fx” for fax device, “ms” for modular station interface (MSI) device, and so on. device handle A device handle is a numerical reference to a device, obtained when a device is opened using xx_open( ), where “xx” is the prefix defining the device to be opened. The device handle is used for all operations on that device. physical and virtual boards The APIs functions distinguish between physical boards and virtual boards. The device driver views a single physical voice board with more than four channels as multiple emulated D/4x boards. These emulated boards are called virtual boards. For example, a D/120JCT-LS with 12 channels of voice processing contains 3 virtual boards. A DM/V480A-2T1 board with 48 channels of voice processing and 2 T-1 trunk lines contains 12 virtual voice boards and 2 virtual network interface boards. 3.2 Voice Device Names The Intel® Dialogic® system software assigns a device name to each device or each component on a board. A voice device is named dxxxBn, where n is the device number assigned in sequential Voice API for Windows Operating Systems Programming Guide — November 2002 23 Device Handling order down the list of sorted voice boards. A device corresponds to a grouping of two or four voice channels. For example, a D/240JCT-T1 board employs 24 voice channels; the Intel® Dialogic® system software therefore divides the D/240JCT into 6 voice board devices, each device consisting of 4 channels. Examples of board device names for voice boards are dxxxB1 and dxxxB2. A device name can be appended with a channel or component identifier. A voice channel device is named dxxxBnCy, where y corresponds to one of the voice channels. Examples of channel device names for voice boards are dxxxB1C1 and dxxxB1C2. For complete information on device handling, see the Standard Runtime Library API Programming Guide. 24 Voice API for Windows Operating Systems Programming Guide — November 2002 Event Handling 4. 4 This chapter provides information on functions used to retrieve and handle events. Topics include: • Overview of Event Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 • Event Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 4.1 Overview of Event Handling An event indicates that a specific activity has occurred on a channel. The voice driver reports channel activity to the application program in the form of events, which allows the program to identify and respond to a specific occurrence on a channel. Events provide feedback on the progress and completion of functions and indicate the occurrence of other channel activities. Voice library events are defined in the dxxxlib.h header file. For a list of events that may be returned by the voice software, see the Voice API Library Reference. 4.2 Event Management Functions Event management functions are used to retrieve and handle events being sent to the application from the firmware. These functions are contained in the Standard Runtime Library (SRL) and defined in srllib.h. The SRL provides a set of common system functions that are device independent and are applicable to all Intel® Dialogic® devices. For more information on event management and event handling, see the Standard Runtime Library API Programming Guide. Event management functions include: • sr_enbhdlr( ) • sr_dishdlr( ) • sr_getevtdev( ) • sr_getevttype( ) • sr_getevtlen( ) • sr_getevtdatap( ) For details on SRL functions, see the Standard Runtime Library API Library Reference. The event management functions retrieve and handle voice device termination events for functions that run in asynchronous mode, such as dx_dial( ) and dx_play( ). For complete function reference information, see the Voice API Library Reference. Voice API for Windows Operating Systems Programming Guide — November 2002 25 Event Handling Each of the event management functions applicable to the voice boards are listed in the following tables. Table 1 lists values that are required by event management functions. Table 2 list values that are returned for event management functions that are used with voice devices. Table 1. Voice Device Inputs for Event Management Functions Event Management Function sr_enbhdlr( ) Enable event handler sr_dishdlr( ) Disable event handler Voice Device Input evt_type evt_type Valid Value Related Voice Functions TDX_PLAY dx_play( ) TDX_PLAYTONE dx_playtone( ) TDX_RECORD dx_rec( ) TDX_GETDIG dx_getdig( ), dx_getdigEx( ) TDX_DIAL dx_dial( ) TDX_CALLP dx_dial( ) TDX_SETHOOK dx_sethook( ) TDX_WINK dx_wink( ) TDX_ERROR All asynchronous functions As above As above Table 2. Voice Device Returns from Event Management Functions Event Management Function 26 Return Description Returned Value Related Voice Functions sr_getevtdev( ) Get device handle device voice device handle sr_getevttype( ) Get event type event type TDX_PLAY dx_play( ) TDX_PLAYTONE dx_playtone( ) TDX_RECORD dx_rec( ) TDX_GETDIG dx_getdig( ), dx_getdigEx( ) TDX_DIAL dx_dial( ) TDX_CALLP dx_dial( ) TDX_CST dx_setevtmsk( ) TDX_SETHOOK dx_sethook( ) TDX_WINK dx_wink( ) TDX_ERROR All asynchronous functions sr_getevtlen( ) Get event data length event length sizeof (DX_CST) sr_getevtdatap( ) Get pointer to event data event data pointer to DX_CST structure Voice API for Windows Operating Systems Programming Guide — November 2002 Event Handling Voice API for Windows Operating Systems Programming Guide — November 2002 27 Event Handling 28 Voice API for Windows Operating Systems Programming Guide — November 2002 Error Handling 5. 5 This chapter discusses how to handle errors that can occur when running an application. All voice library functions return a value to indicate success or failure of the function. A return value of zero or a non-negative number indicates success. A return value of -1 indicates failure. If a voice library function fails, call the standard attribute functions ATDV_LASTERR( ) and ATDV_ERRMSGP( ) to determine the reason for failure. For more information on these functions, see the Standard Runtime Library API Library Reference. If an extended attribute function fails, two types of errors can be generated. An extended attribute function that returns a pointer will produce a pointer to the ASCIIZ string “Unknown device” if it fails. An extended attribute function that does not return a pointer will produce a value of AT_FAILURE if it fails. Extended attribute functions for the voice library are prefaced with “ATDX_”. Notes: 1. The dx_open( ) and dx_close( ) functions are exceptions to the above error handling rules. If these functions fail, the return code is -1. Use dx_fileerrno( ) to obtain the system error value. 2. If ATDV_LASTERR( ) returns the EDX_SYSTEM error code, an operating system error has occurred. Use dx_fileerrno( ) to obtain the system error value. For a list of errors that can be returned by a voice library function, see the Voice API Library Reference. You can also look up the error codes in the dxxxlib.h file. Voice API for Windows Operating Systems Programming Guide — November 2002 29 Error Handling 30 Voice API for Windows Operating Systems Programming Guide — November 2002 Application Development Guidelines 6. 6 This chapter provides programming guidelines and techniques for developing an application using the voice library. The following topics are discussed: • General Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 • Fixed and Flexible Routing Configurations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 • Fixed Routing Configuration Restrictions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 • Additional DM3 Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 • Using Wink Signaling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 6.1 General Considerations The following considerations apply to all applications written using the voice API: • Busy and Idle States • I/O Terminations • Clearing Structures Before Use See feature chapters for programming guidelines specific to a feature, such as Call Progress Analysis, Caller ID, and so on. 6.1.1 Busy and Idle States The operation of some library functions are dependent on the state of the device when the function call is made. A device is in an idle state when it is not being used, and in a busy state when it is dialing, stopped, being configured, or being used for other I/O functions. Idle represents a single state; busy represents the set of states that a device may be in when it is not idle. State-dependent functions do not make a distinction between the individual states represented by the term busy. They only distinguish between idle and busy states. For more information on categories of functions and their description, see the Voice API Library Reference. 6.1.2 I/O Terminations When an I/O function is issued, you must pass a set of termination conditions as one of the function parameters. Termination conditions are events monitored during the I/O process that will cause an I/O function to terminate. When the termination condition is met, a termination reason is returned by ATDX_TERMMSK( ). If the I/O function is running in synchronous mode, the Voice API for Windows Operating Systems Programming Guide — November 2002 31 Application Development Guidelines ATDX_TERMMSK( ) function returns a termination reason after the I/O function has completed. If the I/O function is running in asynchronous mode, the ATDX_TERMMSK( ) function returns a termination reason after the function termination event has arrived. I/O functions can terminate under several conditions as described later in this section. You can predict events that will occur during I/O (such as a digit being received or the call being disconnected) and set termination conditions accordingly. The flow of control in a voice application is based on the termination condition. Setting these conditions properly allows you to build voice applications that can anticipate a caller's actions. To set the termination conditions, values are placed in fields of a DV_TPT structure. If you set more than one termination condition, the first one that occurs will terminate the I/O function. The DV_TPT structures can be configured as a linked list or array, with each DV_TPT specifying a single terminating condition. For more information on the DV_TPT structure, which is defined in srllib.h, see the Voice API Library Reference. The termination conditions are described in the following paragraphs. byte transfer count This termination condition applies when playing or recording a file with dx_play( ) or dx_rec( ). The maximum number of bytes is set in the DX_IOTT structure. This condition will cause termination if the maximum number of bytes is used before one of the termination conditions specified in the DV_TPT occurs. For information about setting the number of bytes in the DX_IOTT, see the Voice API Library Reference. dx_stopch( ) occurred The dx_stopch( ) function will terminate any I/O function except dx_dial( ), dx_dialtpt( ), or dx_wink( ), and stop the device. See the dx_stopch( ) function description for more detailed information about this function. end of file reached This termination condition applies when playing a file. This condition will cause termination if -1 has been specified in the io_length field of the DX_IOTT, and no other termination condition has occurred before the end of the file is reached. For information about setting the DX_IOTT, see the Voice API Library Reference. When this termination condition is met, a TM_EOD termination reason is returned from ATDX_TERMMSK( ). loop current drop (DX_LCOFF) This termination condition is not supported on DM3 boards. In some central offices, switches, and PBXs, a drop in loop current indicates disconnect supervision. An I/O function can terminate if the loop current drops for a specified amount of time. The amount of time is specified in the tp_length field of a DV_TPT structure. The amount of time can be specified in 100 msec units (default) or 10 msec units. 10 msec can be specified in the tp_flags field of the DV_TPT. When this termination condition is met, a TM_LCOFF termination reason is returned from ATDX_TERMMSK( ). maximum delay between digits (DX_IDDTIME) This termination condition monitors the length of time between the digits being received. A specific length of time can be placed in the tp_length field of a DV_TPT. If the time between receiving digits is more than this period of time, the function terminates. The amount of time can be specified in 100 msec units (default) or 10 msec units. 10 msec units can be specified in 32 Voice API for Windows Operating Systems Programming Guide — November 2002 Application Development Guidelines the tp_flags field of the DV_TPT. When this termination condition is met, a TM_IDDTIME termination reason is returned from ATDX_TERMMSK( ). maximum digits received (DX_MAXDTMF) This termination condition counts the number of digits in the channel's digit buffer. If the buffer is not empty before the I/O function is called, the digits that are present in the buffer when the function is initiated are counted as well. The maximum number of digits to receive is set by placing a number from 1 to 31 in the tp_length field of a DV_TPT. This value specifies the number of digits allowed in the buffer before termination. When this termination condition is met, a TM_MAXDTMF termination reason is returned from ATDX_TERMMSK( ). maximum length of non-silence ((DX_MAXNOSIL) Non-silence is the absence of silence: noise or meaningful sound, such as a person speaking. This condition is enabled by setting the tp_length field of a DV_TPT to a specific period of time. When non-silence is detected for this length of time, the I/O function will terminate. This termination condition is frequently used to detect dial tone, or the howler tone that is used by central offices to indicate that a phone has been off-hook for an extended period of time. The amount of time can be specified in 100 msec units (default) or 10 msec units. 10 msec units can be specified in the tp_flags field of the DV_TPT. When this termination condition is met, a TM_MAXNOSIL termination reason is returned from ATDX_TERMMSK( ). maximum length of silence (DX_MAXSIL) This termination condition is enabled by setting the tp_length field of a DV_TPT. The specified value is the length of time that continuous silence will be detected before it terminates the I/O function. The amount of time can be specified in 100 msec units (default) or 10 msec units. 10 msec units can be specified in the tp_flags field of the DV_TPT. When this termination condition is met, a TM_MAXSIL termination reason is returned from ATDX_TERMMSK( ). pattern of silence and non-silence (DX_PMON and DX_PMOFF) This termination condition is not supported on DM3 boards. A known pattern of silence and non-silence can terminate a function. A pattern can be specified by using DX_PMON and DX_PMOFF in the tp_termno field in two separate DV_TPT structures, where one represents a period of silence and one represents a period of non-silence. When this termination condition is met, a TM_PATTERN termination reason is returned from ATDX_TERMMSK( ). DX_PMOFF and DX_PMON termination conditions must be used together. The DX_PMON terminating condition must directly follow the DX_PMOFF terminating condition. A combination of both DV_TPT structures using these conditions is used to form a single termination condition. For more information, see the DV_TPT structure in the Voice API Library Reference. specific digit received (DX_DIGMASK) Digits received during an I/O function are collected in a channel's digit buffer. If the buffer is not empty before an I/O function executes, the digits in the buffer are treated as being received during the I/O execution. This termination condition is enabled by specifying a digit bit mask in the tp_length field of a DV_TPT structure. If any digit specified in the bit mask appears in the digit buffer, the I/O function will terminate. When this termination condition is met, a TM_DIGIT termination reason is returned from ATDX_TERMMSK( ). maximum function time (DX_MAXTIME) A time limit may be placed on the execution of an I/O function. The tp_length field of a DV_TPT can be set to a specific length of time in 100 msec units. The I/O function will Voice API for Windows Operating Systems Programming Guide — November 2002 33 Application Development Guidelines terminate when it executes longer than this period of time. The amount of time can be specified in 100 msec units (default) or 10 msec units. 10 msec units can be specified in the tp_flags field of the DV_TPT. When this termination condition is met, a TM_MAXTIME termination reason is returned from ATDX_TERMMSK( ). user-defined digit received (DX_DIGTYPE) User-defined digits received during an I/O function are collected in a channel's digit buffer. If the buffer is not empty before an I/O function executes, the digits in the buffer are treated as being received during the I/O execution. This termination condition is enabled by specifying the digit and digit type in the tp_length field of a DV_TPT structure. If any digit specified in the bit mask appears in the digit buffer, the I/O function will terminate. When this termination condition is met, a TM_DIGIT termination reason is returned from ATDX_TERMMSK( ). user-defined tone on/off event detected (DX_TONE) This termination condition is used with Global Tone Detection. Before specifying a userdefined tone as a termination condition, the tone must first be defined using the GTD dx_bld...( ) functions, and tone detection on the channel must be enabled using the dx_addtone( ) or dx_enbtone( ) function. To set tone on/off to be a termination condition, specify DX_TONE in the tp_termno field of the DV_TPT. You must also specify DX_TONEON or DX_TONEOFF in the tp_data field. When this termination condition is met, a TM_TONE termination reason is returned from ATDX_TERMMSK( ). The DV_TPT structure may be cleared using dx_clrtpt( ) before initializing the structure and passing a pointer to it as a function parameter. 6.1.3 Clearing Structures Before Use Two library functions are provided to clear structures. dx_clrcap( ) clears DX_CAP structures and dx_clrtpt( ) clears DV_TPT structures. See the Voice API Library Reference for details. It is good practice to clear the field values of any structure before using the structure in a function call. Doing so will help prevent unintentional settings or terminations. 6.2 Fixed and Flexible Routing Configurations On DM3 boards, the voice library supports two types of routing configuration as follows: fixed routing configuration This configuration is primarily for backward compatibility with DNA 3.3 and System Release 5.0. The fixed routing configuration applies only to DM3 boards. With fixed routing, the resource devices (voice/fax) and network interface devices are permanently coupled together in a fixed configuration. Only the network interface time slot device has access to the TDM bus. For example, on a DM/V960A-4T1 board, each voice resource channel device is permanently routed to a corresponding network interface time slot device on the same physical board. The routing of these resource and network interface devices is predefined and static. The resource device also does not have access to the TDM bus and so cannot be routed independently on the TDM bus. No off-board sharing or exporting of voice/fax resources is allowed. 34 Voice API for Windows Operating Systems Programming Guide — November 2002 Application Development Guidelines flexible routing configuration This configuration is compatible with R4 API routing on Springware boards; that is, Springware boards use flexible routing. Flexible routing is available for DM3 boards starting in System Release 5.01. With flexible routing, the resource devices (voice/fax) and network interface devices are independent, which allows exporting and sharing of the resources. All resources have access to the TDM bus. For example, on a DM/V960A-4T1 board, each voice resource channel device and each network interface time slot device can be independently routed on the TDM bus. Flexible routing is the configuration of choice for application development. These routing configurations are also referred to as cluster configurations, because the routing capability is based upon the contents of the DM3 cluster. The fixed routing configuration is one that uses permanently coupled resources, while the flexible routing configuration uses independent resources. From a DM3 perspective, the fixed routing cluster is restricted by its coupled resources and the flexible routing cluster allows more freedom by nature of its independent resources, as shown in Figure 1. You select the routing configuration at configuration time by downloading the appropriate media load to the board. See the Configuration Guide for your product family for information about which media load files support flexible or fixed routing for your board. Figure 1. Cluster Configurations for Fixed and Flexible Routing Flexible Routing (Independent Resources) Fixed Routing (Coupled Resources) Voice Fax Network Interface Network Interface Voice Fax TDM bus TDM bus TDM bus Notes: 1. The R4 Voice Resource includes the DM3 Player, Recorder, Tone Generator, and Signal Detector resources. TDM bus 2. The Fax Resource is an optional component. 3. The Network Interface is referred to in DM3 terms as the Telephony Service Channel (TSC). Voice API for Windows Operating Systems Programming Guide — November 2002 35 Application Development Guidelines 6.3 Fixed Routing Configuration Restrictions Flexible routing configuration is the configuration of choice for applications using R4 on DM3. This documentation assumes that the flexible routing configuration is in use unless otherwise stated. The following restrictions apply when using fixed routing configuration: • TDM bus voice resource routing is not supported • TDM bus fax resource routing restricted • voice, fax, and Global Call resource/device management restricted Table 3 shows the voice API function restrictions in a fixed routing configuration. For Fax API restrictions, see the Fax Software Reference. For Global Call API restrictions, see the Global Call API Programming Guide. Table 3. API Function Restrictions in a Fixed Routing Configuration Function Name 6.4 Notes dx_close( ) Limitations: Although dx_open( ) and dx_close( ) are operational on DM3 voice devices in a fixed routing configuration, their purpose is extremely limited by nature of the voice resource membership in a DM3 cluster. Instead, you must use the gc_OpenEx( ), gc_GetResourceH( ), and gc_Close( ) functions. See the Global Call API Library Reference for information on these functions. dx_getxmitslot( ) Not supported. The function fails with error code EDX_SH_MISSING, indicating “Switching Handler is not present”. dx_listen( ) Not supported. The function fails with error code EDX_SH_MISSING, indicating “Switching Handler is not present”. dx_open( ) Limitations: Although dx_open( ) and dx_close( ) are operational on DM3 voice devices in a fixed routing configuration, their purpose is extremely limited by nature of the voice resource membership in a DM3 cluster. Instead, you must use the gc_OpenEx( ), gc_GetResourceH( ), and gc_Close( ) functions. See the Global Call API Library Reference for information on these functions. dx_unlisten( ) Not supported. The function fails with error code EDX_SH_MISSING, indicating “Switching Handler is not present”. nr_scroute( ) Limitations: Does not support voice, fax, analog network interface devices (LSI), or MSI devices. Supports DTI devices only. nr_scunroute( ) Limitations: Does not support voice, fax, analog network interface devices (LSI), or MSI devices. Supports DTI devices only. Additional DM3 Considerations The following information provides programming guidelines and considerations for developing applications on DM3 boards: • Call Control Through Global Call API Library • Multi-Threading and Multi-Processing • DM3 Interoperability • DM3 Media Loads 36 Voice API for Windows Operating Systems Programming Guide — November 2002 Application Development Guidelines • Device Discovery for DM3 and Springware • Device Initialization Hint • TDM Bus Time Slot Considerations 6.4.1 Call Control Through Global Call API Library Call state functions such as dx_wink( ) and board-level parameters such as DXBD_R_ON and DXBD_R_OFF which are used in digital connections do not apply in DM3 applications. Similarly, hook state functions such as dx_sethook( ) and dx_wtring( ) and settings such as DM_RINGS which are used in analog connections do not apply in DM3 applications. Instead, these call control type functions are typically performed by the Global Call API Library. For more information on setting up call control, see the Global Call API Programming Guide and the Global Call API Library Reference. 6.4.2 Multi-Threading and Multi-Processing The voice API supports multi-threading and multi-processing, with some restrictions on the latter. The restrictions on multi-processing are outlined below. First, one particular channel can only be opened in one process at a time. There can, however, be multiple processes accessing different sets of channels. In other words, ensure that each process is provided with a unique set of devices to manipulate. Second, if a channel was opened in process A and then closed, process B is then allowed to open the same channel. However, since closing a channel is an asynchronous operation on DM3 boards, there is a small gap between the time when the xx_close( ) function returns in process A and the time when process B is allowed to open the same channel. If process B opens the channel too early, things could go wrong. For this reason, this type of sequence should be avoided. Third, there is a restriction on use of firmware tones in case of multi-processing in the voice API. Multiple processes that define tones (GTD or GTG) do not share tone definitions in the firmware. That is, if you define tone A in process #1 for channel dxxxB1C1 on DM3 board X and the same tone A in process #2 for channel dxxxB1C1 on the same DM3 board X, two firmware tones are consumed on board X. In other words, the same tone defined from different processes is not shared in the firmware; hence this limits the number of tones that can be created overall. Fourth, with the Audio Conferencing API, multiple processes cannot access the same conference. 6.4.3 DM3 Interoperability The following rules apply when using R4 for DM3 in a computer with existing R4 API voice applications: • R4 for DM3 can be installed and operated in a computer with existing R4 applications without affecting those applications. Use SRL device mapper functions to return information about the Voice API for Windows Operating Systems Programming Guide — November 2002 37 Application Development Guidelines structure of the system. For details on these functions, see the Standard Runtime Library API Library Reference. • A single R4 application program can be written or modified to use both DM3 and Springware devices together in one system. 6.4.4 DM3 Media Loads Different configurations for DM3 products are supported in the form of media loads. For instance, a specific media load is available for users who need to implement continuous speech processing (CSP) and conferencing in their applications. See the appropriate Configuration Guide for specific media loads that are available. 6.4.5 Device Discovery for DM3 and Springware Applications that use both Springware and DM3 devices must have a way of differentiating what type of device is to be opened. The TDM bus routing device information functions such as dx_getctinfo( ) provide a programming solution. DM3 hardware is identified by the CT_DFDM3 value in the ct_devfamily field of the CT_DEVINFO structure. Only DM3 devices will have this field set to CT_DFDM3. For more information on the dx_getctinfo( ) function and the CT_DEVINFO structure, see the Voice API Library Reference. Note: Use SRL device mapper functions to return information about the structure of the system. For information on these functions, see the Standard Runtime Library API Library Reference. The following procedure shows how to initialize an application and perform device discovery when the application supports both DM3 and Springware boards. 1. Open the first voice channel device on the first voice board in the system with dx_open( ). 2. Call dx_getctinfo( ) and check the CT_DEVINFO.ct_devfamily value. 3. If ct_devfamily is CT_DFDM3, then flag all the voice channel devices associated with the board as DM3 type. 4. Close the voice channel with dx_close( ). 5. Repeat steps 1 to 4 for each voice board. For information on initializing the Global Call API on DM3 devices, see the Global Call API Programming Guide. 6.4.6 Device Initialization Hint The xx_open( ) functions for the voice (dx), Global Call (gc), network (dt), and fax (fx) APIs are asynchronous in R4 on DM3, unlike the standard R4 versions, which are synchronous. This should usually have no impact on an application, except in cases where a subsequent function calls on a device that is still initializing, that is, is in the process of opening. In such cases, the initialization must be finished before the follow-up function can work. The function won’t return an error, but it is blocked until the device is initialized. 38 Voice API for Windows Operating Systems Programming Guide — November 2002 Application Development Guidelines For instance, if your application called dx_open( ) and dx_getfeaturelist( ), the dx_getfeaturelist( ) is blocked until the initialization of the device is completed internally, even though dx_open( ) has already returned success. In other words, the initialization (dx_open( )) may appear to be complete, but, in truth, it is still going on in parallel. With some applications, this may cause slow device-initialization performance. Fortunately, you can avoid this particular problem quite simply by reorganizing the way the application opens and then configures devices. The recommendation is to do all xx_open( ) functions for all channels before proceeding with the next function. For example, you would have one loop through the system devices to do all the xx_open( ) functions first, and then start a second loop through the devices to configure them, instead of doing one single loop where a xx_open( ) is immediately followed by other API functions on the same device. With this method, by the time all xx_open( ) commands are completed, the first channel will be initialized, so you won't experience problems. This change is not necessary for all applications, but if you experience poor initialization performance, you can gain back speed by using this hint. 6.4.7 TDM Bus Time Slot Considerations When multiple devices are listening to the same TDM bus time slot, take into account the application considerations discussed in this section. Specifically, these considerations should be taken into account whenever a resource device such as voice, continuous speech processing (CSP), or other listens to the same TDM bus time slot device as a local, on-board network interface device (dtiBnTm). Note: There is NO restriction when listening to a TDM bus time slot device to which the network interface device is currently transmitting. Figure 2 represents the cases discussed below. Figure 2. Multiple Devices Listening to the Same TDM Bus Time Slot External Tx device dt_listen( ) TS=120 dx_listen( ) or ec_listen( ) CT Bus dtiBwTz dxxxBnCm dxxxBxCy DM3 Board Voice API for Windows Operating Systems Programming Guide — November 2002 39 Application Development Guidelines In a configuration where a DM3 network interface device shares (listens) the same TDM bus time slot device with a local, on-board voice device (CSP or fax device), these considerations apply: • If an application calls dt_listen( ) or gc_Listen( ) on a DM3 network interface device (dtiBwTz) to listen to an external TDM bus time slot device (TS=120 in the figure), followed by one or more dx_listen( ), ec_listen( ), fx_listen( ), or other related functions to a local, on board voice device (dxxxBnCm) to listen to the same external TDM bus time slot device, then the application MUST break (unlisten) the TDM bus voice connection(s) first, using dx_unlisten( ), ec_unlisten( ), or fx_unlisten( ), etc.), prior to calling dt_unlisten( ) or gc_Unlisten( ) to the local network interface device referred above. Failure to do so causes the latter call or subsequent voice calls to fail. This scenario could arise during recording (or transaction recording) of an external source, during a two party hair-pinning connection. • In the same scenario, if an application calls dx_listen( ), ec_listen( ), or fx_listen( ), etc. first, then there is no particular sequencing order that must be followed during TDM bus time slot device tear-down. However, full density (up to 120 channels) of CSP or Transaction Record might not be possible. • If multiple local, on-board network interface devices are all listening to the same external TDM bus time slot device (in this case tslot = 120), the network interface devices must undo the TDM bus connections—that is, call dt_unlisten( ) or gc_Unlisten( )—so that the first network interface to listen to the TDM bus time slot device is the last one to unlisten. This scenario could arise during broadcasting of an external source to several local network interface channels. For information on Fax and CSP, see the Fax documentation set and Continuous Speech Processing documentation set respectively. 6.5 Using Wink Signaling The information in this section does not apply to DM3 boards. The following topics provide information on wink signaling which is available through the dx_wink( ) function: • Setting Delay Prior to Wink • Setting Wink Duration • Receiving an Inbound Wink 6.5.1 Setting Delay Prior to Wink The information in this section does not apply to DM3 boards. The default delay prior to generating the outbound wink is 150 msec. To change the delay, use the dx_setparm( ) function to enter a value for the DXCH_WINKDLY parameter where: delay = the value entered x 10 msec The syntax of the function is: 40 Voice API for Windows Operating Systems Programming Guide — November 2002 Application Development Guidelines int delay; delay = 15; dx_setparm(dev,DXCH_WINKDLY,(void*)&delay) If delay = 15, then DXCH_WINKDLY = 15 x 10 or 150 msec. 6.5.2 Setting Wink Duration The information in this section does not apply to DM3 boards. The default outbound wink duration is 150 msec. To change the wink duration, use the dx_setparm( ) function to enter a value for the DXCH_WINKLEN parameter where: duration = the value entered x 10 msec The syntax of the function is: int duration; duration = 15; dx_setparm(dev,DXCH_WINKLEN,(void*)&duration) If duration = 15, then DXCH_WINKLEN = 15 x 10 or 150 msec. 6.5.3 Receiving an Inbound Wink The information in this section does not apply to DM3 boards. Note: The inbound wink duration must be between the values set for DXCH_MINRWINK and DXCH_MAXRWINK. The default value for DXCH_MINRWINK is 100 msec, and the default value for DXCH_MAXRWINK is 200 msec. Use the dx_setparm( ) function to change the minimum and maximum allowable inbound wink duration. To receive an inbound wink on a channel: 1. Using the dx_setparm( ) function, set the off-hook delay interval (DXBD_OFFHDLY) parameter to 1 so that the channel is ready to detect an incoming wink immediately upon going off hook. 2. Using the dx_setevtmsk( ) function, enable the DM_WINK event. Note: If DM_WINK is not specified in the mask parameter of the dx_setevtmsk( ) function, and DM_RINGS is specified, a wink will be interpreted as an incoming call. A typical sequence of events for an inbound wink is: 1. The application calls the dx_sethook( ) function to initiate a call by going off hook. 2. When the incoming call is detected by the Central Office, the CO responds by sending a wink to the board. 3. When the wink is received successfully, a DE_WINK event is sent to the application. Voice API for Windows Operating Systems Programming Guide — November 2002 41 Application Development Guidelines 42 Voice API for Windows Operating Systems Programming Guide — November 2002 Call Progress Analysis 7. 7 This chapter provides detailed information on the call progress analysis feature. The following topics are discussed: • Call Progress Analysis Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 • Call Progress and Call Analysis Terminology. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 • Call Progress Analysis Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 • Using Call Progress Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 • R4 on DM3 Call Progress Analysis Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 • Tone Detection in Call Progress Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 • PBX Expert Tone Set Files and Call Progress Analysis . . . . . . . . . . . . . . . . . . . . . . . . 59 • Default Tone Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 • Modifying Default Tone Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 • SIT Frequency Detection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 • Call Progress Analysis Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 • Cadence Detection in Basic Call Progress Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 7.1 Call Progress Analysis Overview Call progress analysis monitors the progress of an outbound call after it is dialed into the Public Switched Telephone Network (PSTN). By using call progress analysis (CPA) you can determine for example: • whether the line is answered and, in many cases, how the line is answered • whether the line rings but is not answered • whether the line is busy • whether there is a problem in completing the call The outcome of the call is returned to the application when call progress analysis has completed. There are two forms of call progress analysis: PerfectCall call progress analysis Uses an improved method of signal identification and can detect fax machines and answering machines. You should design all new applications using PerfectCall call progress analysis. DM3 boards support PerfectCall call progress analysis only. Note: In this document, the term call progress analysis refers to PerfectCall call progress analysis unless stated otherwise. Voice API for Windows Operating Systems Programming Guide — November 2002 43 Call Progress Analysis Basic call progress analysis Provides backward compatibility for older applications written before PerfectCall call progress analysis became available. It is strongly recommended that you do not design new applications using basic call progress analysis. Caution: 7.2 If your application also uses the Global Call API, see the Global Call documentation set for call progress analysis considerations specific to Global Call. The Global Call API is a common signaling interface for network-enabled applications, regardless of the signaling protocol needed to connect to the local telephone network. Call progress analysis support varies with the protocol used. Call Progress and Call Analysis Terminology On DM3 boards, a distinction is made between activity that occurs before a call is connected and after a call is connected. The following terms are used: call progress (pre-connect) This term refers to activity that occurs before a call is connected, such as busy, ringback, dial tone, SIT, and so on. call analysis (post-connect) This term refers to activity that occurs after a call is connected, such as voice detection, answering machine detection, fax tone detection, modem, and so on. call progress analysis This term refers to the feature set that encompasses both call progress and call analysis. 7.3 Call Progress Analysis Components Call progress analysis uses the following techniques or components to determine the progress of a call: • cadence detection (part of call progress or pre-connect) • frequency detection (part of call progress or pre-connect) • loop current detection (part of call progress or pre-connect) • positive voice detection (part of call analysis or post-connect) • positive answering machine detection (part of call analysis or post-connect) Figure 3 illustrates the components of basic call progress analysis. Figure 4 illustrates the components of PerfectCall call progress analysis. These components can all operate simultaneously. In basic call progress analysis, cadence detection is the sole means of detecting a no ringback, busy, or no answer. PerfectCall call progress analysis uses cadence detection plus frequency detection to identify all of these signals plus fax machine tones. A connect can be detected through the complementary methods of cadence detection, frequency detection, loop current detection, positive voice detection, and positive answering machine detection. 44 Voice API for Windows Operating Systems Programming Guide — November 2002 Call Progress Analysis Figure 3. Basic Call Progress Analysis Components Incoming Signal Intercept (SIT) Loop Current Detection Cadence Detection Frequency Detection No Ringback Positive Voice Detection No Answer Busy Connect Figure 4. PerfectCall Call Progress Analysis Components Incoming Signal Frequency Detection Intercept (SIT) 7.4 No Dialtone Cadence Detection Fax Tone Busy Positive Voice or Answering Machine Detection Loop Current Detection No Answer No Ringback Connect Using Call Progress Analysis The following topics provide information on how to use call progress analysis when making an outbound call: • Overview of Steps to Initiate Call Progress Analysis • Enabling Call Progress Analysis Features in DX_CAP Voice API for Windows Operating Systems Programming Guide — November 2002 45 Call Progress Analysis • Enabling Call Progress Analysis • Executing a Dial Function • Determining the Outcome of a Call • Obtaining Additional Call Outcome Information 7.4.1 Overview of Steps to Initiate Call Progress Analysis Perform the following procedure to initiate an outbound call with call progress analysis: 1. Set up the call analysis parameter structure (DX_CAP), which contains parameters to control the operation of call progress analysis, such as frequency detection, cadence detection, loop current, positive voice detection, and positive answering machine detection. 2. On Springware boards, enable call progress analysis on a specified channel using dx_initcallp( ). Modify tone definitions as appropriate. On DM3 boards, the dx_initcallp( ) is not used and tone definitions cannot be modified. Call progress analysis can be enabled directly through the dx_dial( )function (see step 3). DM3 applications that use the ISDN protocol can enable call progress analysis using dx_dial( ). For all other protocols, such as analog protocols and digital CAS protocols, use the Global Call API for call progress analysis. See the Global Call documentation set for more information. 3. Call dx_dial( ) to start an outbound call. 4. Use the ATDX_CPTERM( ) extended attribute function to determine the outcome of the call. 5. Obtain additional termination, frequency, or cadence information (such as the length of the salutation) as desired using extended attribute functions. Each of these steps is described in more detail next. For a full description of the functions and data structures described in this chapter, see the Voice API Library Reference. 7.4.2 Enabling Call Progress Analysis Features in DX_CAP The call progress analysis parameters structure, DX_CAP, is used by dx_dial( ). It contains parameters to control the operation of call progress analysis features, such as frequency detection, positive voice detection (PVD), and positive answering machine detection (PAMD). To customize the parameters for your environment, you must set up the call progress analysis parameter structure before calling a dial function. To set up the DX_CAP structure for call progress analysis: 1. Execute the dx_clrcap( ) function to clear the DX_CAP and initialize the parameters to 0. The value 0 indicates that the default value will be used for that particular parameter. dx_dial( ) can also be set to run with default call progress analysis parameter values, by specifying a NULL pointer to the DX_CAP structure. 2. Set the parameter to another value if you do not want to use the default value for a given parameter. 46 Voice API for Windows Operating Systems Programming Guide — November 2002 Call Progress Analysis The ca_intflg field (intercept mode flag) of DX_CAP enables and disables the following call progress analysis components: SIT frequency detection, positive voice detection (PVD), and positive answering machine detection (PAMD). The defines for ca_intflg field are as follows: DX_OPTDIS Disables Special Information Tone (SIT) frequency detection, PAMD, and PVD. On DM3 boards, provides call progress without SIT frequency detection. DX_OPTNOCON Enables SIT frequency detection and returns an “intercept” immediately after detecting a valid frequency. On DM3 boards, provides call progress with SIT frequency detection. DX_PVDENABLE Enables PVD. On DM3 boards, provides PVD call analysis only (no call progress). DX_PVDOPTNOCON Enables PVD and DX_OPTNOCON. On DM3 boards, provides call progress with SIT frequency detection and PVD call analysis. DX_PAMDENABLE Enables PAMD and PVD. On DM3 boards, provides PAMD and PVD call analysis only (no call progress). DX_PAMDOPTEN Enables PAMD, PVD, and DX_OPTNOCON. On DM3 boards, provides full call progress and call analysis. Note: DX_OPTEN and DX_PVDOPTEN are obsolete. Use DX_OPTNOCON and DX_PVDOPTNOCON instead. For more information on adjusting DX_CAP parameters, see Section 7.10, “SIT Frequency Detection”, on page 61, and Section 7.6, “Tone Detection in Call Progress Analysis”, on page 51. 7.4.3 Enabling Call Progress Analysis Call progress analysis is activated on a per-channel basis. On DM3 boards, applications that use the ISDN protocol can enable call progress analysis using dx_dial( ). For all other protocols, such as analog protocols and digital CAS protocols, use the Global Call API for call progress analysis. See the Global Call documentation set for more information. On Springware boards, initiate call progress analysis using the dx_initcallp( ) function. Voice API for Windows Operating Systems Programming Guide — November 2002 47 Call Progress Analysis On Springware boards, to enable call progress analysis on a specified channel, perform the following steps. This procedure needs to be followed only once per channel; thereafter, any outgoing calls made using a dial function will benefit from call progress analysis. 1. Make any desired modifications to the default dial tone, busy tone, fax tone, and ringback signal definitions using the dx_chgfreq( ), dx_chgdur( ), and dx_chgrepcnt( ) functions. 2. Call dx_deltones( ) to clear all tone templates remaining on the channel. Note that this function deletes all global tone definition (GTD) tones for the given channel, and not just those involved with call progress analysis. 3. Execute the dx_initcallp( ) function to activate call progress analysis. Call progress analysis stays active until dx_deltones( ) is called. The dx_initcallp( ) function initializes call progress analysis on the specified channel using the current tone definitions. Once the channel is initialized with these tone definitions, this initialization cannot be altered. The only way to change the tone definitions in effect for a given channel is to issue a dx_deltones( ) call for that channel, then invoke another dx_initcallp( ) with different tone definitions. 7.4.4 Executing a Dial Function To use call progress analysis, call dx_dial( ) with the mode function argument set to DX_CALLP. Termination of dialing with call progress analysis is indicated differently depending on whether the function is running asynchronously or synchronously. If running asynchronously, use Standard Runtime Library (SRL) Event Management functions to determine when dialing with call progress analysis is complete (TDX_CALLP termination event). If running synchronously, wait for the function to return a value greater than 0 to indicate successful completion. On DM3 boards, applications that use the ISDN protocol can use dx_dial( ) for call progress analysis. For all other protocols, such as analog protocols and digital CAS protocols, use the Global Call API for call progress analysis. See the Global Call documentation set for more information. 7.4.5 Determining the Outcome of a Call Once dx_dial( ) with call progress analysis has terminated, use the extended attribute function ATDX_CPTERM( ) to determine the outcome of the call. ATDX_CPTERM( ) will return one of the following call progress analysis termination results: CR_BUSY Called line was busy. CR_CEPT Called line received operator intercept (SIT). Extended attribute functions provide information on detected frequencies and duration. CR_CNCT Called line was connected. Use ATDX_CONNTYPE( ) to return the connection type for a completed call. 48 Voice API for Windows Operating Systems Programming Guide — November 2002 Call Progress Analysis CR_ERROR Call progress analysis error occurred. Use ATDX_CPERROR( ) to return the type of error. CR_FAXTONE Called line was answered by fax machine or modem. CR_NOANS Called line did not answer. CR_NODIALTONE Timeout occurred while waiting for dial tone. CR_NORB No ringback on called line. CR_STOPD Call progress analysis stopped due to dx_stopch( ). Figure 5 illustrates the possible outcomes of call progress analysis. Figure 5. Call Outcomes for Call Progress Analysis Incoming Signal Frequency Detection No Intercept (SIT) Dialtone Cadence Detection Faxtone Busy Loop Current Detection No Answer CR_NOCR_CEPT DIALTONE CR_FAXTONE CR_BUSY CR_NOANS Connect Reason Positive Voice or Answering Machine Detection No Ringback Connect CR_NORB CR_CNCT CR_CAD CON_LPC CON_PVD CON_PAMD Termination Reason Termination Reason: From ATDX_CPTERM( ). Connect Reason: From ATDX_CONNTYPE( ). 7.4.6 Obtaining Additional Call Outcome Information To obtain additional call progress analysis information, use the following extended attribute functions: ATDX_ANSRSIZ( ) Returns duration of answer. This function is not supported on DM3 boards. Voice API for Windows Operating Systems Programming Guide — November 2002 49 Call Progress Analysis ATDX_CPERROR( ) Returns call analysis error. ATDX_CPTERM( ) Returns last call analysis termination. ATDX_CONNTYPE( ) Returns connection type ATDX_CRTNID( ) Returns the identifier of the tone that caused the most recent call progress analysis termination. This function is not supported on DM3 boards. ATDX_DTNFAIL( ) Returns the dial tone character that indicates which dial tone call progress analysis failed to detect. This function is not supported on DM3 boards. ATDX_FRQDUR( ) Returns duration of first frequency detected. This function is not supported on DM3 boards. ATDX_FRQDUR2( ) Returns duration of second frequency detected. This function is not supported on DM3 boards. ATDX_FRQDUR3( ) Returns duration of third frequency detected. This function is not supported on DM3 boards. ATDX_FRQHZ( ) Returns frequency detected in Hz of first detected tone. This function is not supported on DM3 boards. ATDX_FRQHZ2( ) Returns frequency of second detected tone. This function is not supported on DM3 boards. ATDX_FRQHZ3( ) Returns frequency of third detected tone. This function is not supported on DM3 boards. ATDX_LONGLOW( ) Returns duration of longer silence. This function is not supported on DM3 boards. ATDX_FRQOUT( ) Returns percent of frequency out of bounds. This function is not supported on DM3 boards. ATDX_SHORTLO( ) Returns duration of shorter silence. This function is not supported on DM3 boards. ATDX_SIZEHI( ) Returns duration of non-silence. This function is not supported on DM3 boards. As indicated, not all functions are supported on DM3 boards. See each function reference description in the Voice API Library Reference for more information. For a discussion of how frequency and cadence information returned by these extended attribute functions relate to the DX_CAP parameters, see Section 7.10, “SIT Frequency Detection”, on page 61 and Section 7.6, “Tone Detection in Call Progress Analysis”, on page 51. 50 Voice API for Windows Operating Systems Programming Guide — November 2002 Call Progress Analysis 7.5 R4 on DM3 Call Progress Analysis Scenarios Table 4, “Call Progress Analysis Support with dx_dial( )”, on page 51 provides information on what specific call progress analysis scenarios are supported with the dx_dial( ) function. To invoke dx_dial( ) under channel associated signaling (CAS), your application must wait for the connected event. This method is available regardless of the protocol being used; however, some restrictions apply when using DM3 CAS protocols. The restrictions are due to the fact that the voice capability is shared between the network device and the voice channel during the call setup time. Notes: 1. The information in this section also applies to DI products, which are considered to use CAS protocols. 2. For information on using the Global Call API for call progress analysis, see the Global Call documentation set. Call progress analysis support varies with the protocol used. Table 4. Call Progress Analysis Support with dx_dial( ) CPA Feature 7.6 dx_dial( ) support on Springware dx_dial( ) support on DM3 Comments Busy Yes Yes CAS protocols: not supported No ringback Yes Yes CAS protocols: not supported SIT frequency detection Yes Yes CAS protocols: not supported No answer Yes Yes CAS protocols: not supported Cadence break Yes Yes CAS protocols: not supported Loop current detection Yes No Dial tone detection Yes No Fax tone detection Yes Yes CAS protocols: wait for Global Call GCEV_CONNECTED event Positive Voice Detection (PVD) Yes Yes CAS protocols: wait for Global Call GCEV_CONNECTED event Positive Answering Machine Detection (PAMD) Yes Yes CAS protocols: wait for Global Call GCEV_CONNECTED event Tone Detection in Call Progress Analysis Tone detection in PerfectCall call progress analysis differs from the one in basic call progress analysis. The following topics discuss tone detection used in PerfectCall call progress analysis: • Overview • Types of Tones • Dial Tone Detection • Ringback Detection • Busy Tone Detection • Positive Voice Detection (PVD) Voice API for Windows Operating Systems Programming Guide — November 2002 51 Call Progress Analysis • Positive Answering Machine Detection (PAMD) • Fax or Modem Tone Detection • Disconnect Tone Supervision • Loop Current Detection 7.6.1 Overview PerfectCall call progress analysis uses a combination of cadence detection and frequency detection to identify certain signals during the course of an outgoing call. Cadence detection identifies repeating patterns of sound and silence, and frequency detection determines the pitch of the signal. Together, the cadence and frequency of a signal make up its “tone definition”. Unlike basic call progress analysis, which uses fields in the DX_CAP structure to store signal cadence information, PerfectCall call progress analysis uses tone definitions which are contained in the voice driver itself. Functions are available to modify these default tone definitions. 7.6.2 Types of Tones Tone definitions are used to identify several kinds of signals. DM3 boards support the following defined tones and tone identifiers. For information on default tone templates and definitions, see Section 7.8, “Default Tone Definitions”, on page 59. BUSY Busy signal BUSY_FAST Alternate busy signal DIALTONE1 Local dial tone Dm3_DIALTONE2 International dial tone FAX_CNG1 CED (called station) fax tone or modem tone RINGING1 Ringback RINGING2 TS0 Ringback RINGING2 TS1 Ringback 52 Voice API for Windows Operating Systems Programming Guide — November 2002 Call Progress Analysis Springware boards support the following defined tones and tone identifiers. For information on default tone templates and definitions, see Section 7.8, “Default Tone Definitions”, on page 59. Tone identifiers are returned by the ATDX_CRTNID( ) function. TID_BUSY1 Busy signal (detected as single tone) TID_BUSY2 Alternate busy signal (detected as dual tone) TID_DIAL_INTL International dial tone TID_DIAL_LCL Local dial tone TID_DIAL_XTRA Special (extra) dial tone TID_DISCONNECT Disconnect tone (post-connect) TID_FAX1 CED (called station) fax tone or modem tone TID_FAX2 CNG (calling) fax tone or modem tone TID_RNGBK1 Ringback (detected as single tone) TID_RNGBK2 Ringback (detected as dual tone) On Springware boards, the tone identifiers are used in calls to the functions dx_chgfreq( ), dx_chgdur( ), and dx_chgrepcnt( ) to change the tone definitions. For function reference information, see the Voice API Library Reference. For more information, see Section 7.4.3, “Enabling Call Progress Analysis”, on page 47. 7.6.3 Dial Tone Detection The dx_dial( ) function does not support dial tone detection on DM3 boards. Wherever call progress analysis is in effect, a dial string for an outgoing call may specify special ASCII characters that instruct the system to wait for a certain kind of dial tone. The following additional special characters may appear in a dial string: L wait for a local dial tone I wait for an international dial tone X wait for a special (“extra”) dial tone Voice API for Windows Operating Systems Programming Guide — November 2002 53 Call Progress Analysis The tone definitions for each of these dial tones is set for each channel at the time of the dx_initcallp( ) function. In addition, the following DX_CAP fields identify how long to wait for a dial tone, and how long the dial tone must remain stable. ca_dtn_pres Dial Tone Present: the length of time that the dial tone must be continuously present (in 10 msec units). If a dial tone is present for this amount of time, dialing of the dial string proceeds. Default value: 100 (one second). ca_dtn_npres Dial Tone Not Present: the length of time to wait before declaring the dial tone not present (in 10 msec units). If a dial tone of sufficient length (ca_dtn_pres) is not found within this period of time, call progress analysis terminates with the reason CR_NODIALTONE. The dial tone character (L, I, or X) for the missing dial tone can be obtained using ATDX_DTNFAIL( ). Default value: 300 (three seconds). ca_dtn_deboff Dial Tone Debounce: the maximum duration of a break in an otherwise continuous dial tone before it is considered invalid (in 10 msec units). This parameter is used for ignoring short drops in dial tone. If a drop longer than ca_dtn_deboff occurs, then dial tone is no longer considered present, and another dial tone must begin and be continuous for ca_dtn_pres. Default value: 10 (100 msec). 7.6.4 Ringback Detection Call progress analysis uses the tone definition for ringback to identify the first ringback signal of an outgoing call. At the end of the first ringback (that is, normally, at the beginning of the second ringback), a timer goes into effect. The system continues to identify ringback signals (but does not count them). If a break occurs in the ringback cadence, the call is assumed to have been answered, and call progress analysis terminates with the reason CR_CNCT (connect); the connection type returned by the ATDX_CONNTYPE( ) function will be CON_CAD (cadence break). However, if the timer expires before a connect is detected, then the call is deemed unanswered, and call progress analysis terminates with the reason CR_NOANS. To enable ringback detection, turn on SIT frequency detection in the DX_CAP ca_intflg field. For details, see Section 7.4.3, “Enabling Call Progress Analysis”, on page 47. The following DX_CAP fields govern ringback behavior: ca_stdely This field is not supported on DM3 boards. Start Delay: the delay after dialing has been completed before starting cadence detection, frequency detection, and positive voice detection (in 10 msec units). Default: 25 (0.25 seconds). ca_cnosig Continuous No Signal: the maximum length of silence (no signal) allowed immediately after the ca_stdely period (in 10 msec units). If this duration is exceeded, call progress analysis is terminated with the reason CR_NORB (no ringback detected). Default value: 4000 (40 seconds). 54 Voice API for Windows Operating Systems Programming Guide — November 2002 Call Progress Analysis ca_noanswer No Answer: the length of time to wait after the first ringback before deciding that the call is not answered (in 10 msec units). If this duration is exceeded, call progress analysis is terminated with the reason CR_NOANS (no answer). Default value: 3000 (30 seconds). ca_maxintering This field is not supported on DM3 boards. Maximum Inter-ring: the maximum length of time to wait between consecutive ringback signals (in 10 msec units). If this duration is exceeded, call progress analysis is terminated with the reason CR_CNCT (connected). Default value: 800 (8 seconds). 7.6.5 Busy Tone Detection On DM3 boards, call progress analysis specifies two busy tones: BUSY and BUSY_FAST. If either of them is detected while frequency detection is active, then call progress is terminated with the reason CR_BUSY. On Springware boards, call progress analysis specifies two busy tones: TID_BUSY1 and TID_BUSY2. If either of them is detected while frequency detection and cadence detection are active, then call progress is terminated with the reason CR_BUSY. ATDX_CRTNID( ) identifies which busy tone was detected. To enable busy tone detection, turn on SIT frequency detection in the DX_CAP ca_intflg field. For details, see Section 7.4.3, “Enabling Call Progress Analysis”, on page 47. 7.6.6 Positive Voice Detection (PVD) Positive voice detection (PVD) can detect when a call has been answered by determining whether an audio signal is present that has the characteristics of a live or recorded human voice. This provides a very precise method for identifying when a connect occurs. The ca_intflg field in DX_CAP enables/disables PVD. For information on enabling PVD, see Section 7.4.2, “Enabling Call Progress Analysis Features in DX_CAP”, on page 46. PVD is especially useful in those situations where answer supervision is not available for loop current detection to identify a connect, and where the cadence is not clearly broken for cadence detection to identify a connect (for example, when the nonsilence of the cadence is immediately followed by the nonsilence of speech). If the ATDX_CONNTYPE( ) function returns CON_PVD, the connect was due to positive voice detection. Note: When a connect is detected through positive voice detection or loop current detection, the DX_CAP parameters ca_hedge, ca_ansrdgl, and ca_maxansr are ignored. These fields are not supported on DM3 boards. Voice API for Windows Operating Systems Programming Guide — November 2002 55 Call Progress Analysis 7.6.7 Positive Answering Machine Detection (PAMD) Whenever PAMD is enabled, positive voice detection (PVD) is also enabled. The ca_intflg field in DX_CAP enables/disables PAMD and PVD. For information on enabling PAMD, see Section 7.4.2, “Enabling Call Progress Analysis Features in DX_CAP”, on page 46. When enabled, detection of an answering machine will result in the termination of call analysis with the reason CR_CNCT (connected); the connection type returned by the ATDX_CONNTYPE( ) function will be CON_PAMD. To distinguish between a greeting by a live human and one by an answering machine, one of the following methods is used: PAMD_QUICK The quick method examines only the events surrounding the connect time and makes a rapid judgment as to whether or not an answering machine is involved. PAMD_FULL The long method looks at the full greeting to determine whether it came from a human or a machine. Using PAMD_FULL gives a very accurate determination; however, in situations where a fast decision is more important than accuracy, PAMD_QUICK might be preferred. PAMD_ACCU The most accurate detection. Provides the same accuracy as PAMD_FULL for detecting live voice, but is more accurate (though slightly slower) than PAMD_FULL for detecting an answering machine. Use this setting when accuracy is more important than speed. The recommended setting for the call analysis parameter structure (DX_CAP) ca_pamd_spdval field is PAMD_ACCU. This setting provides the most accurate evaluation. It detects live voice as accurately as PAMD_FULL but is more accurate than PAMD_FULL (although slightly slower) in detecting an answering machine. Use the setting PAMD_ACCU when accuracy is more important than speed. The following DX_CAP fields govern positive answering machine detection: ca_pamd_spdval PAMD Speed Value: whether to make a quick decision on positive answering machine detection. Possible values: • PAMD_FULL – look at greeting (long method) • PAMD_QUICK – look at connect only (quick method) • PAMD_ACCU – look at greeting (long method) and use most accuracy for detecting an answering machine Default value: PAMD_FULL This field is not supported on DM3 boards. ca_pamd_qtemp PAMD Qualification Template: the algorithm to use in PAMD. At present there is only one template: PAMD_QUAL1TMP. This parameter must be set to this value. This field is not supported on DM3 boards. 56 Voice API for Windows Operating Systems Programming Guide — November 2002 Call Progress Analysis ca_pamd_failtime maximum time to wait for positive answering machine detection or positive voice detection after a cadence break. Default Value: 400 (in 10 msec units). ca_pamd_minring minimum allowable ring duration for positive answering machine detection. Default Value: 190 (in 10 msec units). This field is not supported on DM3 boards. 7.6.8 Fax or Modem Tone Detection On DM3 boards, one tone is defined: FAX_CNG1. If this tone is detected while frequency detection is active, then call progress is terminated with the reason CR_FAXTONE. On Springware boards, two tones are defined: TID_FAX1 and TID_FAX2. If either of them is detected while frequency detection and cadence detection are active, then call progress is terminated with the reason CR_FAXTONE. ATDX_CRTNID( ) identifies which fax or modem tone was detected. To enable fax or modem tone detection, turn on SIT frequency detection in the DX_CAP ca_intflg field. For details, see Section 7.4.3, “Enabling Call Progress Analysis”, on page 47. 7.6.9 Disconnect Tone Supervision On DM3 boards, disconnect tone supervision is not supported. On Springware boards, one tone is defined: TID_DISCONNECT. See Table 6, “Default Call Progress Analysis Tone Definitions (Springware)”, on page 60 for the tone definition. Call progress analysis provides positive disconnect supervision by detecting either a loop current drop or the disconnect tone that occurs after a party hangs up to end a connected call. In both cases, when a disconnect is detected, a loop current drop event is generated. In this way, disconnect tones can be used easily in an application that processes loop current drop events. To enable disconnect tone supervision and use it with call progress analysis, follow these instructions: 1. If your application uses a tone set file that defines a disconnect tone (non-default value), you must enable support for this tone set file in the Intel Dialogic Configuration Manager (DCM). In the Misc tab, set TSFFileSupport parameter to Yes. In the File tab, set TSFFileName to the tone set file you wish to be downloaded to the board. If you are not using a tone set file, skip this step. 2. To enable disconnect tone supervision on your board, use the Intel Dialogic Configuration Manager (DCM). In the Misc tab, set the DisconnectTone parameter to Yes. The setting of this parameter is stored in the Registry, and any change to it takes effect when the application is executed rather than when the boards are started. When enabled, the default disconnect tone Voice API for Windows Operating Systems Programming Guide — November 2002 57 Call Progress Analysis definition is used. For information on the default tone definition, see Section 7.8, “Default Tone Definitions”, on page 59. You can customize the disconnect tone through the API functions provided for that purpose: dx_chgfreq( ), dx_chgdur( ), and dx_chgrepcnt( ). 3. Use dx_initcallp( ) to initialize call progress analysis in your application as normal. 4. Use the dx_setevtmsk( ) function with the DM_LCOFF parameter to enable detection of loop current drop events. This step is essential to obtain disconnect supervision. 5. Use the dx_dial( ) function with call progress analysis enabled to establish a connected call as normal. The TID_DISCONNECT tone is not used during call progress analysis; it is automatically disabled until call progress analysis ends. If a fast busy tone occurs during call progress analysis, it is detected by the TID_BUSY2 tone and will terminate call progress analysis. If the party hangs up and a disconnect tone is present within the parameters of the TID_DISCONNECT tone definition, call progress analysis detects the tone and generates a single loop current drop event (DX_LCOFF). Note: If you enable the disconnect tone and loop current drop events as described above and perform a dial without call progress analysis, a loop current drop event occurs if a fast busy tone is encountered during the dial. For more information on disconnect tone supervision, see Section 13.1.10.1, “Detecting Disconnect Tone”, on page 138. 7.6.10 Loop Current Detection The dx_dial( ) function does not support loop current detection on DM3 boards. Some telephone systems return a momentary drop in loop current when a connection has been established (answer supervision). Loop current detection returns a connect when a transient loop current drop is detected. In some environments, including most PBXs, answer supervision is not provided. In these environments, Loop current detection will not function. Check with your Central Office or PBX supplier to see if answer supervision based on loop current changes is available. In some cases, the application may receive one or more transient loop current drops before an actual connection occurs. This is particularly true when dialing long-distance numbers, when the call may be routed through several different switches. Any one of these switches may be capable of generating a momentary drop in loop current. To disable loop current detection, set DX_CAP ca_lcdly to -1. 7.6.10.1 Loop Current Detection Parameters Affecting a Connect To prevent detecting a connect prematurely or falsely due to a spurious loop current drop, you can delay the start of loop current detection by using the parameter ca_lcdly. 58 Voice API for Windows Operating Systems Programming Guide — November 2002 Call Progress Analysis Loop current detection returns a connect after detecting a loop current drop. To allow the person who answered the phone to say “hello” before the application proceeds, you can delay the return of the connect by using the parameter ca_lcdly1. ca_lcdly Loop Current Delay: the delay after dialing has been completed and before beginning Loop Current Detection. To disable loop current detection, set to -1. Default: 400 (10 msec units). ca_lcdly1 Loop Current Delay 1: the delay after loop current detection detects a transient drop in loop current and before call progress analysis returns a connect to the application. Default: 10 (10 msec units). If the ATDX_CONNTYPE( ) function returns CON_LPC, the connect was due to loop current detection. Note: 7.7 When a connect is detected through positive voice detection or loop current detection, the DX_CAP parameters ca_hedge, ca_ansrdgl, and ca_maxansr are ignored. PBX Expert Tone Set Files and Call Progress Analysis PBX Expert is a utility designed to facilitate the management of unique call progress tones produced by PBXs, key systems (KSU), and PSTNs. A tone set file, or TSF, is the way in which PBX Expert stores call progress tone definitions. To select and activate a TSF that will be used by your voice board for call progress analysis, you must enable support for this tone set file in the Intel Dialogic Configuration Manager (DCM). In the Misc tab, set TSFFileSupport parameter to Yes. In the File tab, set TSFFileName to the tone set file you wish to be downloaded to the board. When a TSF is active, its tone definitions replace the default tone definitions already in the voice DLL, where they are automatically used by any applications using call progress analysis. The dx_TSFstatus( ) function enables your application to determine the outcome of when activating a TSF, such as whether the TSF was successfully loaded. 7.8 Default Tone Definitions Table 5 provides call progress analysis default tone definitions for DM3 boards. Springware tone IDs are listed for reference. Amplitudes are given in dBm, frequencies in Hz, and duration in 10 msec units. Notes: 1. The Dm3_DIALTONE2 name must be specified as shown, with the mix of uppercase and lowercase characters. A dash in a table cell means not applicable. A space in a table cell means not available on DM3 boards. 2. Tone definitions on DM3 boards are not modifiable. Voice API for Windows Operating Systems Programming Guide — November 2002 59 Call Progress Analysis Table 5. Default Call Progress Analysis Tone Definitions (DM3) Springware Tone ID DM3 Signal ID Freq1 Freq2 On Time Off Time Reps TID_BUSY1 BUSY 480 ± 30 620 ± 30 650 ± 350 650 ± 350 2 TID_BUSY2 BUSY_FAST 480 ± 30 620 ± 30 250 ± 150 250 ± 150 2 TID_DIAL_LCL DIALTONE1 350 ± 40 440 ± 40 100 - 1 TID_DIAL_INTL Dm3_DIALTONE2 340 ± 40 440 ± 40 100 - 1 FAX_CNG1 1100 ± 50 350 ± 250 - 1 TID_RNGBK1 RINGING1 450 ± 150 450 ± 150 1875 ± 1125 4000 ± 4000 1 TID_RNGBK2 RINGING2 TS0 450 ± 150 450 ± 150 600 ± 400 600 ± 400 1 RINGING2 TS1 450 ± 150 450 ± 150 600 ± 400 3500 ± 2500 1 TID_DIAL_XTRA TID_DISCONNECT TID_FAX1 TID_FAX2 Table 6 provides call progress analysis default tone definitions for Springware boards. Frequencies are specified in Hz, durations in 10 msec units, and repetitions in integers. Table 6. Default Call Progress Analysis Tone Definitions (Springware) Springware Tone ID 7.9 Freq1 Freq2 On Time Off Time TID_BUSY1 500 ± 200 TID_BUSY2 500 ± 200 TID_DIAL_LCL 400 ± 125 TID_DIAL_INTL 402 ± 125 TID_DIAL_XTRA 401 ± 125 TID_DISCONNECT 500 ± 200 TID_FAX1 2150 ± 50 250 ± 250 TID_FAX2 1100 ± 50 250 ± 250 TID_RNGBK1 438 ± 138 1300 ± 1050 5800 ± 4150 TID_RNGBK2 438 ± 138 1300 ± 1050 5800 ± 4150 Reps 550 ± 400 550 ± 400 4 525 ± 175 550 ± 400 550 ± 400 4 525 ± 175 550 ± 400 550 ± 400 4 438 ± 138 Modifying Default Tone Definitions On DM3 boards, modifying default tone definitions is not supported. Call progress analysis makes use of global tone detection (GTD) tone definitions for three different types of dial tones, two busy tones, one ringback tone, and two fax tones. The tone definitions 60 Voice API for Windows Operating Systems Programming Guide — November 2002 Call Progress Analysis specify the frequencies, durations, and repetition counts necessary to identify each of these signals. Each signal may consist of a single tone or a dual tone. The voice driver contains default definitions for each of these tones. The default definitions will allow applications to identify the tones correctly in most countries and for most switching equipment. However, if a situation arises in which the default tone definitions are not adequate, three functions are provided to modify the standard tone definitions. dx_chgfreq( ) specifies frequencies and tolerances for one or both frequencies of a single- or dual-frequency tone dx_chgdur( ) specifies the cadence (on time, off time, and acceptable deviations) for a tone dx_chgrepcnt( ) specifies the repetition count required to identify a tone These functions only change the tone definitions; they do not alter the behavior of call progress analysis itself. When the dx_initcallp( ) function is invoked to activate call progress analysis on a particular channel, it uses the current tone definitions to initialize that channel. Multiple calls to dx_initcallp( ) may therefore use varying tone definitions, and several channels can operate simultaneously with different tone definitions. For information on default tone templates, see Table 6, “Default Call Progress Analysis Tone Definitions (Springware)”, on page 60. For more information on tones and tone detection, see Section 7.6, “Tone Detection in Call Progress Analysis”, on page 51. 7.10 SIT Frequency Detection Special Information Tone (SIT) frequency detection is a component of call progress analysis. The following topics provide more information on this component: • Tri-Tone SIT Sequences • Setting Tri-Tone SIT Frequency Detection Parameters • Obtaining Tri-Tone SIT Frequency Information • Global Tone Detection Tone Memory Usage • Frequency Detection Errors • Setting Single Tone Frequency Detection Parameters • Obtaining Single Tone Frequency Information 7.10.1 Tri-Tone SIT Sequences SIT frequency detection operates simultaneously with all other call progress analysis detection methods. The purpose of frequency detection is to detect the tri-tone special information tone (SIT) Voice API for Windows Operating Systems Programming Guide — November 2002 61 Call Progress Analysis sequences and other single-frequency tones. Detection of a SIT sequence indicates an operator intercept or other problem in completing the call. SIT frequency detection can detect virtually any single-frequency tone below 2100 Hz and above 300 Hz. Table 7 provides tone information for the four SIT sequences on Springware boards. The frequencies are represented in Hz and the length of the signal is in 10 msec units. The length of the first tone is not dependable; often it is shortened or cut. Table 7. Special Information Tone Sequences (Springware) SIT Name 7.10.2 Description 1st Tone Freq. Len. 2nd Tone Freq. Len. 3rd Tone Freq. Len. NC No Circuit Found 985 38 1429 38 1777 38 IC Operator Intercept 914 27 1371 27 1777 38 VC Vacant Circuit 985 38 1370 27 1777 38 RO Reorder (system busy) 914 27 1429 38 1777 38 Setting Tri-Tone SIT Frequency Detection Parameters The parameters described in this section are not supported on DM3 boards. Frequency detection on voice boards is designed to detect all three tones in a tri-tone SIT sequence. To detect all three tones in a SIT sequence, you must specify the frequency detection parameters in the DX_CAP for all three tones in the sequence. To detect all four tri-tone SIT sequences: 1. Set an appropriate frequency detection range in the DX_CAP to detect each tone across all four SIT sequences. Set the first frequency detection range to detect the first tone for all four SIT sequences (approximately 900 to 1000 Hz). Set the second frequency detection range to detect the second tone for all four SIT sequences (approximately 1350 to 1450 Hz). Set the third frequency detection range to detect the third tone for all four SIT sequences (approximately 1725 to 1825 Hz). 2. Set an appropriate detection time using the ca_timefrq and ca_mxtimefrq parameters to detect each tone across all four SIT sequences. For each tone, set ca_timefrq to 5 and ca_mxtimefrq to 50 to detect all SIT tones. The tones range in length from 27 to 38 (in 10 msec units), with some tones occasionally cut short by the Central Office. Note: Occasionally, the first tone can also be truncated by a delay in the onset of call progress analysis due to the setting of ca_stdely. 3. After an SIT sequence is detected, ATDX_CPTERM( ) will return CR_CEPT to indicate an operator intercept, and you can determine which SIT sequence was detected by obtaining the actual detected frequency and duration for the tri-tone sequence using extended attribute functions. These functions are described in detail in the Voice API Library Reference. 62 Voice API for Windows Operating Systems Programming Guide — November 2002 Call Progress Analysis The following fields in the DX_CAP are used for Frequency Detection on voice boards. Frequencies are specified in Hertz, and time is specified in 10 msec units. To enable detection of the second and third tones, you must set the frequency detection range and time for each tone. General The following field in the DX_CAP is used for Frequency Detection on voice boards. ca_stdely Start Delay. The delay after dialing has been completed and before starting Frequency Detection. This parameter also determines the start of cadence detection and Positive Voice Detection. Note that this can affect detection of the first element of an operator intercept tone. Default: 25 (10 msec units). First Tone The following fields in the DX_CAP are used for Frequency Detection for the first tone. Frequencies are specified in Hertz, and time is specified in 10 msec units. ca_lowerfrq Lower bound for first tone in Hz. Default: 900. ca_upperfrq Upper bound for first tone in Hz. Adjust higher for additional operator intercept tones. Default: 1000. ca_timefrq Minimum time for first tone to remain in bounds. The minimum amount of time required for the audio signal to remain within the frequency detection range for it to be detected. The audio signal must not be greater than ca_upperfrq or lower than ca_lowerfrq for at least the time interval specified in ca_timefrq. Default: 5 (10 msec units). ca_mxtimefrq Maximum allowable time for first tone to be present. Default: 0 (10 msec units). Second Tone The following fields in the DX_CAP are used for Frequency Detection for the second tone. Frequencies are specified in Hertz, and time is specified in 10 msec units. To enable detection of the second and third tones, you must set the frequency detection range and time for each tone. Note: This tone is disabled initially and must be activated by the application using these variables. ca_lower2frq Lower bound for second tone in Hz. Default: 0. ca_upper2frq Upper bound for second tone in Hz. Default: 0. Voice API for Windows Operating Systems Programming Guide — November 2002 63 Call Progress Analysis ca_time2frq Minimum time for second tone to remain in bounds. Default: 0 (10 msec units). ca_mxtime2frq Maximum allowable time for second tone to be present. Default: 0 (10 msec units). Third Tone The following fields in the DX_CAP are used for Frequency Detection for the third tone. Frequencies are specified in Hertz, and time is specified in 10 msec units. To enable detection of the second and third tones, you must set the frequency detection range and time for each tone. Note: This tone is disabled initially and must be activated by the application using these variables. ca_lower3frq Lower bound for third tone in Hz. Default: 0. ca_upper3frq Upper bound for third tone in Hz. Default: 0. ca_time3frq Minimum time for third tone to remain in bounds. Default: 0 (10 msec units). ca_mxtime3frq Maximum allowable time for third tone to be present. Default: 0 (10 msec units). 7.10.3 Obtaining Tri-Tone SIT Frequency Information The functions described in this section are not supported on DM3 boards. Upon detection of the specified sequence of frequencies, you can use extended attribute functions to provide the exact frequency and duration of each tone in the sequence. The frequency and duration information will allow exact determination of all four SIT sequences. The following extended attribute functions are used to provide information on the frequencies detected by call progress analysis. ATDX_FRQHZ( ) Frequency in Hz of the tone detected in the tone detection range specified by the DX_CAP ca_lowerfrq and ca_upperfrq parameters; usually the first tone of an SIT sequence. This function can be called on non-DSP boards. ATDX_FRQDUR( ) Duration of the tone detected in the tone detection range specified by the DX_CAP ca_lowerfrq and ca_upperfrq parameters; usually the first tone of an SIT sequence (10 msec units). ATDX_FRQHZ2( ) Frequency in Hz of the tone detected in the tone detection range specified by the DX_CAP ca_lower2frq and ca_upper2frq parameters; usually the second tone of an SIT sequence. 64 Voice API for Windows Operating Systems Programming Guide — November 2002 Call Progress Analysis ATDX_FRQDUR2( ) Duration of the tone detected in the tone detection range specified by the DX_CAP ca_lower2frq and ca_upper2frq parameters; usually the second tone of an SIT sequence (10 msec units). ATDX_FRQHZ3( ) Frequency in Hz of the tone detected in the tone detection range specified by the DX_CAP ca_lower3frq and ca_upper3frq parameters; usually the third tone of an SIT sequence. ATDX_FRQDUR3( ) Duration of the tone detected in the tone detection range specified by the DX_CAP ca_lower3frq and ca_upper3frq parameters; usually the third tone of an SIT sequence (10 msec units). 7.10.4 Global Tone Detection Tone Memory Usage The information in this section does not apply to DM3 boards. If you use call progress analysis to identify the tri-tone SIT sequences, call progress analysis will create tone detection templates internally, and this will reduce the number of tone templates that can be created using Global Tone Detection functions. See Chapter 13, “Global Tone Detection and Generation, and Cadenced Tone Generation” for information relating to memory usage for Global Tone Detection. Call progress analysis will create one tone detection template for each single-frequency tone with a 100 Hz detection range. For example, if detecting the set of tri-tone SIT sequences (three frequencies) on each of four channels, the number of allowable user-defined tones will be reduced by three per channel. If you initiate call progress analysis and there is not enough memory to create the SIT tone detection templates internally, you will get a CR_MEMERR error. This indicates that you are trying to exceed the maximum number of tone detection templates. The tone detection range should be limited to a maximum of 100 Hz per tone to reduce the chance of exceeding the available memory. 7.10.5 Frequency Detection Errors The information in this section does not apply to DM3 boards, as the DX_CAP fields mentioned in this section are not supported on DM3 boards. The frequency detection range specified by the lower and upper bounds for each tone cannot overlap; otherwise, an error will be produced when the driver attempts to create the internal tone detection templates. For example, if ca_upperfrq is 1000 and ca_lower2frq is also 1000, an overlap occurs and will result in an error. Also, the lower bound of each frequency detection range must be less than the upper bound (for example, ca_lower2frq must be less than ca_upper2frq). Voice API for Windows Operating Systems Programming Guide — November 2002 65 Call Progress Analysis 7.10.6 Setting Single Tone Frequency Detection Parameters The information in this section does not apply to DM3 boards, as the DX_CAP fields mentioned in this section are not supported on DM3 boards. The following paragraphs describe how to set single tone frequency detection on Springware boards. Setting single tone frequency detection parameters allows you to identify that a SIT sequence was encountered because one of the tri-tones in the SIT sequence was detected. But Frequency Detection cannot determine exactly which SIT sequence was encountered, because it is necessary to identify two tones in the SIT sequence to distinguish among the four possible SIT sequences. The default frequency detection range is 900-1000 Hz, which is set to detect the first tone in any SIT sequence. Because the first tone is often truncated, you may want to increase ca_upperfrq to 1800 Hz so that it includes the third tone. If this results in too many false detections, you can set Frequency Detection to detect only the third tone by setting ca_lowerfrq to 1750 and ca_upperfrq to 1800. The following fields in the DX_CAP are used for Frequency Detection. Frequencies are specified in Hertz, and time is specified in 10 msec units. ca_stdely Start Delay: the delay after dialing has been completed and before starting Frequency Detection. This parameter also determines the start of cadence detection. Default: 25 (10 msec units). ca_lowerfrq lower bound for tone in Hz. Default: 900. ca_upperfrq upper bound for tone in Hz. Default: 1000. ca_timefrq time frequency. Minimum time for 1st tone in an SIT to remain in bounds. The minimum amount of time required for the audio signal to remain within the frequency detection range specified by ca_upperfrq and ca_lowerfrq for it to be considered valid. Default: 5 (10 msec units) 7.10.7 Obtaining Single Tone Frequency Information The information in this section does not apply to DM3 boards, as the DX_CAP fields mentioned in this section are not supported on DM3 boards. Upon detection of a frequency in the specified range, you can use the ATDX_FRQHZ( ) extended attribute function to return the frequency in Hz of the tone detected in the range specified by the DX_CAP ca_lowerfrq and ca_upperfrq parameters. The frequency returned is usually the first tone of an SIT sequence. 66 Voice API for Windows Operating Systems Programming Guide — November 2002 Call Progress Analysis 7.11 Call Progress Analysis Errors If ATDX_CPTERM( ) returns CR_ERROR, you can use ATDX_CPERROR( ) to determine the call progress analysis error that occurred. CR_MEMERR Out of memory trying to create temporary Special Information Tone (SIT) templates (exceeds maximum number of templates) CR_TMOUTON Time-out waiting for a SIT CR_TMOUTOFF SIT too long (exceeds a ca_mxtimefrq parameter) CR_UNEXPTN Unexpected SIT (the sequence of detected tones did not correspond to the SIT sequence) CR_MXFRQERR Invalid ca_mxtimefrq field in DX_CAP. If the ca_mxtimefrq parameter for each SIT is nonzero, it must have a value greater than or equal to the ca_timefrq parameter for the same SIT CR_UPFRQERR Invalid upper frequency selection. This value must be nonzero for detection of any SIT. CR_LGTUERR Lower frequency greater than upper frequency CR_OVRLPERR Overlap in selected SITs 7.12 Cadence Detection in Basic Call Progress Analysis Cadence detection is a component of basic call progress analysis. The following topics discuss cadence detection and some of the most commonly adjusted cadence detection parameters in basic call progress analysis: • Overview • Typical Cadence Patterns • Elements of a Cadence • Outcomes of Cadence Detection • Setting Selected Cadence Detection Parameters • Obtaining Cadence Information Voice API for Windows Operating Systems Programming Guide — November 2002 67 Call Progress Analysis 7.12.1 Overview The cadence detection algorithm has been optimized for use in the United States standard network environment. Caution: This discussion of cadence detection in basic call progress analysis is provided for backward compatibility purposes only. You should not develop new applications based on basic call progress analysis. Instead you should use PerfectCall call progress analysis. For information on cadence detection in PerfectCall call progress analysis, see Section 7.6, “Tone Detection in Call Progress Analysis”, on page 51. If your system is operating in another type of environment (such as behind a PBX), you can customize the cadence detection algorithm to suit your system through the adjustment of the cadence detection parameters. Cadence detection analyzes the audio signal on the line to detect a repeating pattern of sound and silence, such as the pattern produced by a ringback or a busy signal. These patterns are called audio cadences. Once a cadence has been established, it can be classified as a single ring, a double ring, or a busy signal by comparing the periods of sound and silence to established parameters. Notes: 1. Sound is referred to as nonsilence. 2. The algorithm used for cadence detection is disclosed and protected under U.S. patent 4,477,698 of Melissa Electronic Labs, and other patents pending. 7.12.2 Typical Cadence Patterns Figure 6, Figure 7, and Figure 8 show some typical cadence patterns for a standard busy signal, a standard single ring, and a double ring. Figure 6. A Standard Busy Signal 50 50 50 50 nonsilence silence 50 50 50 The timings are given in units of 10ms. 68 Voice API for Windows Operating Systems Programming Guide — November 2002 Call Progress Analysis Figure 7. A Standard Single Ring 200 200 ≈ ≈ nonsilence 400 ≈ silence The timings are given in units of 10ms. Figure 8. A Type of Double Ring 50 50 50 nonsilence 225 25 silence ≈ The timings are given in units of 10ms. 7.12.3 Elements of a Cadence From the preceding cadence examples, you can see that a given cadence may contain two silence periods with different durations, such as for a double ring; but in general, the nonsilence periods have the same duration. To identify and distinguish between the different types of cadences, the voice driver must detect two silence and two nonsilence periods in the audio signal. Figure 9 illustrates cadence detection. Figure 9. Cadence Detection Dialing Complete Period Used to Establish Cadence Periods Compared to the Established Cadence nonsilence silence Voice API for Windows Operating Systems Programming Guide — November 2002 69 Call Progress Analysis Once the cadence is established, the cadence values can be retrieved using the following extended attribute functions: ATDX_SIZEHI( ) length of the nonsilence period (in 10 msec units) for the detected cadence ATDX_SHORTLOW( ) length of the shortest silence period for the detected cadence (in 10 msec units) ATDX_LONGLOW( ) length of the longest silence period for the detected cadence (in 10 msec units). Only one nonsilence period is used to define the cadence because the nonsilence periods have the same duration. Figure 10 shows the elements of an established cadence. Figure 10. Elements of Established Cadence ATDX_LONGLOW ATDX_SIZEHIGH ATDX_SHORTLOW 50 50 nonsilence 225 ≈ silence 25 The timings are given in units of 10ms. The durations of subsequent states are compared with these fields to see if the cadence has been broken. 7.12.4 Outcomes of Cadence Detection Cadence detection can identify the following conditions during the period used to establish the cadence or after the cadence has been established: • No Ringback • Connect • Busy • No Answer Although Loop Current Detection and Positive Voice Detection provide complementary means of detecting a connect, cadence detection provides the only way in basic call progress analysis to detect a no ringback, busy, or no answer. 70 Voice API for Windows Operating Systems Programming Guide — November 2002 Call Progress Analysis Cadence detection can identify the following conditions during the period used to establish the cadence: No Ringback While the cadence is being established, cadence detection determines whether the signal is continuous silence or nonsilence. In this case, cadence detection returns a no ringback, indicating there is a problem in completing the call. Connect While the cadence is being established, cadence detection determines whether the audio signal departs from acceptable network standards for busy or ring signals. In this case, cadence detection returns a connect, indicating that there was a “break” from general cadence standards. Cadence detection can identify the following conditions after the cadence has been established: Connect After the cadence has been established, cadence detection determines whether the audio signal departs from the established cadence. In this case, cadence detection returns a connect, indicating that there was a break in the established cadence. No Answer After the cadence has been established, cadence detection determines whether the cadence belongs to a single or double ring. In this case, cadence detection can return a no answer, indicating there was no break in the ring cadence for a specified number of times. Busy After the cadence has been established, cadence detection determines whether the cadence belongs to a slow busy signal. In this case, cadence detection can return a busy, indicating that the busy cadence was repeated for a specified number of times. To determine whether the ring cadence is a double or single ring, compare the value returned by the ATDX_SHORTLOW( ) function to the DX_CAP field ca_lo2rmin. If the ATDX_SHORTLOW( ) value is less than ca_lo2rmin, the cadence is a double ring; otherwise, it is a single ring. 7.12.5 Setting Selected Cadence Detection Parameters Only the most commonly adjusted cadence detection parameters are discussed here. For a complete listing and description of the DX_CAP data structure, see the Voice API Library Reference. You should only need to adjust cadence detection parameters for network environments that do not conform to the U.S. standard network environment (such as behind a PBX). Voice API for Windows Operating Systems Programming Guide — November 2002 71 Call Progress Analysis 7.12.5.1 General Cadence Detection Parameters The following are general cadence detection parameters in DX_CAP: ca_stdely Start Delay: the delay after dialing has been completed and before starting cadence detection. This parameter also determines the start of Frequency Detection and Positive Voice Detection. Default: 25 (10 msec units) = 0.25 seconds. Be careful with this variable. Setting this variable too small may allow switching transients or, if too long, miss critical signaling. ca_higltch High Glitch: the maximum nonsilence period to ignore. Used to help eliminate spurious nonsilence intervals. Default: 19 (in 10 msec units). To eliminate audio signal glitches over the telephone line, the parameters ca_logltch and ca_higltch are used to determine the minimum acceptable length of a valid silence or nonsilence duration. Any silence interval shorter than ca_logltch is ignored, and any nonsilence interval shorter than ca_higltch is ignored. ca_logltch Low Glitch: the maximum silence period to ignore. Used to help eliminate spurious silence intervals. Default: 15 (in 10 msec units). 7.12.5.2 Cadence Detection Parameters Affecting a No Ringback After cadence detection begins, it waits for an audio signal of nonsilence. The maximum waiting time is determined by the parameter ca_cnosig (continuous no signal). If the length of this period of silence exceeds the value of ca_cnosig, a no ringback is returned. Figure 11 illustrates this. This usually indicates a dead or disconnected telephone line or some other system malfunction. ca_cnosig Continuous No Signal: the maximum time of silence (no signal) allowed immediately after cadence detection begins. If exceeded, a no ringback is returned. Default: 4000 (in 10 msec units), or 40 seconds. Figure 11. No Ringback Due to Continuous No Signal Dialing Complete nonsilence No Ringback Returned CA_STDELY 250 CA_CNOSIG 4000 ≈ silence The timings are given in units of 10ms. 72 Voice API for Windows Operating Systems Programming Guide — November 2002 Call Progress Analysis If the length of any period of nonsilence exceeds the value of ca_cnosil (continuous nonsilence), a no ringback is returned, shown in Figure 12. ca_cnosil Continuous Nonsilence: the maximum length of nonsilence allowed. If exceeded, a no ringback is returned. Default: 650 (in 10 msec units), or 6.5 seconds. Figure 12. No Ringback Due to Continuous Nonsilence CA_CNOSIL 650 nonsilence No Ringback Returned silence The timings are given in units of 10ms. 7.12.5.3 Cadence Detection Parameters Affecting a No Answer or Busy By using the ca_nbrdna parameter, you can set the maximum number of ring cadence repetitions that will be detected before returning a no answer. By using the ca_nbrdna and ca_nsbusy parameters, you can set the maximum number of busy cadence repetitions. ca_nbrdna Number of Rings Before Detecting No Answer: the number of single or double rings to wait before returning a no answer. Default: 4. ca_nsbusy Nonsilence Busy: the number of nonsilence periods in addition to ca_nbrdna to wait before returning a busy. Default: 0. ca_nsbusy is added to ca_nbrdna to give the actual number of busy cadences at which to return busy. Note that even though ca_nsbusy is declared as an unsigned variable, it can be a small negative number. Do not allow ca_nbrdna + ca_nsbusy to equal 2. This is a foible of the 2’s complement bit mapping of a small negative number to an unsigned variable. 7.12.5.4 Cadence Detection Parameters Affecting a Connect You can cause cadence detection to measure the length of the salutation when the phone is answered. The salutation is the greeting when a person answers the phone, or an announcement when an answering machine or computer answers the phone. By examining the length of the greeting or salutation you receive when the phone is answered, you may be able to distinguish between an answer at home, at a business, or by an answering machine. Voice API for Windows Operating Systems Programming Guide — November 2002 73 Call Progress Analysis The length of the salutation is returned by the ATDX_ANSRSIZ( ) function. By examining the value returned, you can estimate the kind of answer that was received. Normally, a person at home will answer the phone with a brief salutation that lasts about 1 second, such as “Hello” or “Smith Residence.” A business will usually answer the phone with a longer greeting that lasts from 1.5 to 3 seconds, such as “Good afternoon, Intel Corporation.” An answering machine or computer will usually play an extended message that lasts more than 3 or 4 seconds. This method is not 100% accurate, for the following reasons: • The length of the salutation can vary greatly. • A pause in the middle of the salutation can cause a premature connect event. • If the phone is picked up in the middle of a ringback, the ringback tone may be considered part of the salutation, making the ATDX_ANSRSIZ( ) return value inaccurate. In the last case, if someone answers the phone in the middle of a ring and quickly says “Hello”, the nonsilence of the ring will be indistinguishable from the nonsilence of voice that immediately follows, and the resulting ATDX_ANSRSIZ( ) return value may include both the partial ring and the voice. In this case, the return value may deviate from the actual salutation by 0 to +1.8 seconds. The salutation would appear to be the same as when someone answers the phone after a full ring and says two words. Note: A return value of 180 to 480 may deviate from the actual length of the salutation by 0 to +1.8 seconds. Cadence detection will measure the length of the salutation when the ca_hedge (hello edge) parameter is set to 2 (the default). ca_hedge Hello Edge: the point at which a connect will be returned to the application, either the rising edge (immediately when a connect is detected) or the falling edge (after the end of the salutation). 1 = rising edge. 2 = falling edge. Default: 2 (connect returned on falling edge of salutation). Try changing this if the called party has to say “Hello” twice to trigger the answer event. Because a greeting might consist of several words, call progress analysis waits for a specified period of silence before assuming the salutation is finished. The ca_ansrdgl (answer deglitcher) parameter determines when the end of the salutation occurs. This parameter specifies the maximum amount of silence allowed in a salutation before it is determined to be the end of the salutation. To use ca_ansrdgl, set it to approximately 50 (in 10 msec units). ca_ansrdgl Answer Deglitcher: the maximum silence period (in 10 msec units) allowed between words in a salutation. This parameter should be enabled only when you are interested in measuring the length of the salutation. Default: -1 (disabled). 74 Voice API for Windows Operating Systems Programming Guide — November 2002 Call Progress Analysis The ca_maxansr (maximum answer) parameter determines the maximum allowable answer size before returning a connect. ca_maxansr Maximum Answer: the maximum allowable length of ansrsize. When ansrsize exceeds ca_maxansr, a connect is returned to the application. Default: 1000 (in 10 msec units), or 10 seconds. Figure 13 shows how the ca_ansrdgl parameter works. Figure 13. Cadence Detection Salutation Processing Connection Detected nonsilence Connect Event Returned Here Salutation "Good Afternoon," "Intel Corporation" silence CA_ANSRDGL CA_ANSRDGL When ca_hedge = 2, cadence detection waits for the end of the salutation before returning a connect. The end of the salutation occurs when the salutation contains a period of silence that exceeds ca_ansrdgl or the total length of the salutation exceeds ca_maxansr. When the connect event is returned, the length of the salutation can be retrieved using the ATDX_ANSRSIZ( ) function. After call progress analysis is complete, call ATDX_ANSRSIZ( ). If the return value is less than 180 (1.8 seconds), you have probably contacted a residence. A return value of 180 to 300 is probably a business. If the return value is larger than 480, you have probably contacted an answering machine. A return value of 0 means that a connect was returned because excessive silence was detected. This can vary greatly in practice. Note: 7.12.6 When a connect is detected through Positive Voice Detection or Loop Current Detection, the DX_CAP parameters ca_hedge, ca_ansrdgl, and ca_maxansr are ignored. Obtaining Cadence Information The functions described in this section are not supported on DM3 boards. To return cadence information, you can use the following extended attribute functions: ATDX_SIZEHI( ) duration of the cadence non-silence period (in 10 msec units) ATDX_SHORTLOW( ) duration of the cadence shorter silence period (in 10 msec units) Voice API for Windows Operating Systems Programming Guide — November 2002 75 Call Progress Analysis ATDX_LONGLOW( ) duration of the cadence longer silence period (in 10 msec units) ATDX_ANSRSIZ( ) duration of answer if a connect occurred (in 10 msec units) ATDX_CONNTYPE( ) connection type. If ATDX_CONNTYPE( ) returns CON_CAD, the connect was due to cadence detection. 76 Voice API for Windows Operating Systems Programming Guide — November 2002 Recording and Playback 8. 8 This chapter discusses playback and recording features in the voice library. The following topics are discussed: • Overview of Recording and Playback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 • Digital Recording and Playback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 • Play and Record Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 • Play and Record Convenience Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 • Voice Encoding Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 • G.726 Voice Coder. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 • Transaction Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 • Silence Compressed Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 • Echo Cancellation Resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 8.1 Overview of Recording and Playback The primary voice processing operations provided by a voice board include: • recording: digitizing and storing human voice • playback: retrieving, converting, and playing the stored, digital information to reconstruct the human voice. The following features related to voice recording and playback operation are documented in other chapters in this document: • Controlling when a playback or recording terminates using I/O termination conditions is documented in Section 6.1.2, “I/O Terminations”, on page 31. • Controlling the speed and volume when messages are played back is documented in Chapter 9, “Speed and Volume Control”. • A method for increasing access speed for retrieving and storing voice prompts is documented in Chapter 12, “Cached Prompt Management”. 8.2 Digital Recording and Playback In digital speech recording, the voice board converts the human voice from a continuous sound wave, or analog signal, into a digital representation. The voice board does this by frequently sampling the amplitude of the sound wave at individual points in the speech signal. Voice API for Windows Operating Systems Programming Guide — November 2002 77 Recording and Playback The accuracy, and thus the quality, of the digital recording is affected by: • the sampling rate (number of samples per second), also called digitization rate • the precision, or resolution, of each sample (the amount of data that is used to represent 1 sample). If the samples are taken at a greater frequency, the digital representation will be more accurate and the voice quality will be greater. Likewise, if more bits are used to represent the sample (higher resolution), the sample will be more accurate and the voice quality will be greater. In digital speech playback, the voice board reconstructs the speech signal by converting the digitized voice back into analog voltages. If the voice data is played back at the same rate at which it was recorded, an approximation of the original speech will result. 8.3 Play and Record Functions The C language function library includes several functions for recording and playing audio data, such as dx_rec( ), dx_reciottdata( ), dx_play( ), and dx_playiottdata( ). Recording takes audio data from a specified channel and encodes it for storage in memory, in a file on disk, or on a custom device. Playing decodes the stored audio data and plays it on the specified channel. The storage location is one factor in determining which record and play functions should be used. The storage location affects the access speed for retrieving and storing audio data. One or more of the following data structures are used in conjunction with certain play and record functions: DV_TPT to specify a termination condition for the function, DX_IOTT to identify a source or destination for the data, and DX_XPB to specify the file format, data format, sampling rate, and resolution. For detailed information about play and record functions, which are also known as I/O functions, see the Voice API Library Reference. 8.4 Play and Record Convenience Functions Several convenience functions are provided to make it easier to implement play and record functionality in an application. Some examples are: dx_playf( ), dx_playvox( ), dx_playwave( ), dx_recf( ), and dx_recvox( ). These functions are specific cases of the dx_play( ) and dx_rec( ) functions and run in synchronous mode. For example, dx_playf( ) performs a playback from a single file by specifying the filename. The same operation can be done using dx_play( ) and specifying a DX_IOTT structure with only one entry for that file. Using dx_playf( ) is more convenient for a single file playback because you do not have to set up a DX_IOTT structure for the one file and the application does not need to open the file. dx_recf( ) provides the same single file convenience for the dx_rec( ) function. For a complete list of I/O convenience functions and function reference information, see the Voice API Library Reference. 78 Voice API for Windows Operating Systems Programming Guide — November 2002 Recording and Playback 8.5 Voice Encoding Methods A digitized audio recording is characterized by several parameters as follows: • the number of samples per second, or sampling rate • the number of bits used to store a sample, or resolution • the rate at which data is recorded or played There are many encoding and storage schemes available for digitized voice. For DM3 boards, the voice encoding methods supported are listed in Table 8. Table 8. Voice Encoding Methods (DM3 Boards) Sampling Rate (kHz) Digitizing Method Note: Resolution (Bits) Bit Rate (Kbps) File Format OKI ADPCM 6 4 24 VOX, WAVE OKI ADPCM 8 4 32 VOX, WAVE G.711 PCM A-law and mu-law 6 8 48 VOX, WAVE G.711 PCM A-law and mu-law 8 8 64 VOX, WAVE G.721 8 4 32 VOX, WAVE Linear PCM 11 8 88 VOX, WAVE Linear PCM 11 16 176 VOX, WAVE TrueSpeech 8 16 8.5 VOX, WAVE GSM 6.10 full rate (Microsoft format) 8 (value ignored) 13 VOX, WAVE GSM 6.10 full rate (TIPHON format) 8 (value ignored) 13 VOX G.726 bit exact 8 2 16 VOX, WAVE G.726 bit exact 8 3 24 VOX, WAVE G.726 bit exact 8 4 32 VOX, WAVE G.726 bit exact 8 5 40 VOX, WAVE On DM3 boards, voice coders listed here are not available in all situations on all boards. For example, speed control is supported only at 8 kHz sampling rate using PCM A-law or mu-law, or OKI ADPCM. Whenever a restriction exists, it will be noted. Voice API for Windows Operating Systems Programming Guide — November 2002 79 Recording and Playback For Springware boards, the voice encoding methods supported are listed in Table 9. Table 9. Voice Encoding Methods (Springware Boards) Digitizing Method Note: 8.6 Sampling Rate (kHz) Resolution (Bits) Bit Rate (Kbps) File Format OKI ADPCM 4 6 24 VOX, WAVE OKI ADPCM 4 8 32 VOX, WAVE G.711 PCM A-law and mu-law 8 6 48 VOX, WAVE G.711 PCM A-law and mu-law 8 8 64 VOX, WAVE Linear PCM 8 11 88 VOX, WAVE Linear PCM 16 11 176 VOX, WAVE GSM 6.10 full rate (Microsoft format) (value ignored) 8 13 WAVE GSM 6.10 full rate (TIPHON format) (value ignored) 8 13 WAVE G.726 bit exact 4 8 32 VOX On Springware boards, voice coders listed here are not available in all situations on all boards. For example, speed can be controlled on playbacks using 24 kbps or 32 kbps ADPCM only. Volume can be controlled on all playbacks regardless of the encoding algorithm. Whenever a restriction exists, it will be noted. G.726 Voice Coder G.726 is an ITU-T recommendation that specifies an adaptive differential pulse code modulation (ADPCM) technique for recording and playing back audio files. It is useful for applications that require speech compression, encoding for noise immunity, and uniformity in transmitting voice and data signals. The voice library provides support for a G.726 bit exact voice coder that is compliant with the ITU-T G.726 recommendation. Audio encoded in the G.726 bit exact format complies with Voice Profile for Internet Messaging (VPIM), a communications protocol that makes it possible to send and receive messages from disparate messaging systems over the Internet. G.726 bit exact is the audio encoding and decoding standard supported by VPIM. The G.726 voice coder is enabled on a per-board basis. To specify the G.726 voice coder, use the DX_XPB structure in conjunction with the dx_playiottdata( ) and dx_reciottdata( ) functions. To determine the voice resource handles to be used with dx_playiottdata( ) and dx_reciottdata( ), call functions such as sr_getboardcnt( ), ATDV_SUBDEVS( ), ATDX_CHNAMES( ) or SRL device mapper functions to return the number of boards of a particular type, the number of subdevices for the device, and the channel device names. 80 Voice API for Windows Operating Systems Programming Guide — November 2002 Recording and Playback See the Voice API Library Reference for more information on voice functions and data structure. See the Standard Runtime Library API Library Reference for more information on SRL functions and standard attribute functions. 8.7 Transaction Record Transaction record enables the recording of a two-party conversation by allowing two timedivision multiplexing (TDM) bus time slots from a single channel to be recorded. This feature is useful for call center applications where it is necessary to archive a verbal transaction or record a live conversation. A live conversation requires two time slots on the TDM bus, but Intel Dialogic voice boards today can only record one time slot at a time. No loss of channel density is realized with this feature. For example, a D/160SC-LS can still record 16 simultaneous conversations. Voice activity on two channels can be summed and stored in a single file, or in a combination of files, devices, and/or memory. Note: Transaction record is not supported on all boards. For example, it is not supported on D/41ESC, VFX/40ESC, and VFX/40ESCplus boards. For a list of board support, see the Release Guide. Use the following function for transaction record: dx_mreciottdata( ) records voice data from two channels to a data file, memory, or custom device See the Voice API Library Reference for a full description of functions. 8.8 Silence Compressed Record The silence compressed record (SCR) feature is discussed in more detail in the following topics: • Overview of Silence Compressed Record • Enabling Silence Compressed Record • Encoding Methods Supported in Silence Compressed Record 8.8.1 Overview of Silence Compressed Record The silence compressed record feature (SCR) enables recording with silent pauses eliminated. This results in smaller recorded files with no loss of intelligibility. On Springware boards, when the audio level is at or falls below the silence threshold for a minimum duration of time, SCR begins. When a short burst of noise (glitch) is detected, the compression does not end unless the glitch is longer than a specified period of time. On DM3 boards, the SCR algorithm is based on energy detection and zero crossing. This SCR uses different parameters than the standard SCR. Specifically, the Pre-Compensation and De-Glitch parameters are no longer needed, and there are additional new parameters. [where is this docu Voice API for Windows Operating Systems Programming Guide — November 2002 81 Recording and Playback The SCR algorithm operates on one msec blocks of speech and uses a two-fold approach to determine whether a sample is speech or silence. Two probability of speech values are calculated using a zero crossing algorithm and an energy detection algorithm. These values are put together to calculate a combined probability of speech. The energy detection algorithm allows you to modify the background noise threshold range. Signals above the high threshold are declared speech, and signals below the low threshold are declared silence. Speech or silence is declared based on the previous sample, the current combined probability of speech in relation to the speech probability threshold and silence probability threshold parameters and the trailing silence parameter. 8.8.2 Enabling Silence Compressed Record On DM3 boards, use dx_setparm( ) and the DXCH_SCRFEATURE define to turn SCR on and off. Once enabled, voice record functions automatically record with SCR. For more information on modifying SCR parameters, see the Configuration Guide for your product or product family. On Springware boards, you enable SCR in the voice.prm file which is downloaded to the board during initialization. You must edit this file and set appropriate values for the SCR parameters for use in your working environment before initializing the board. You cannot enable this feature through the voice API. After SCR is enabled in the voice.prm file, it is automatically activated by the use of voice record functions such as dx_rec( ). On Springware boards, the SCR parameters specify the silence threshold, the duration of silence at the end of speech before silence compression begins, the duration of a glitch in the line which does not stop silence compression, and more. Figure 14 illustrates how these parameters work. See the appropriate Configuration Guide for details of the parameters and information on how to enable and configure this feature. 82 Voice API for Windows Operating Systems Programming Guide — November 2002 Recording and Playback Figure 14. Silence Compressed Record Parameters Illustrated Speech Detected Compression Ends Begin Compression End of Speech Noise Spike (Glitch) Compression Continues Silence Less Than SCR_T Compression Not Enabled Begin Compression SCR_PC (bytes) SCR_THRES (dB) SCR_T SCR_PC (10 ms Unit) (Bytes) SCR_T (10 ms Unit) SCR_DG (10 ms Unit) 8.8.3 Encoding Methods Supported in Silence Compressed Record On DM3 boards, the following encoding algorithms and sampling rates are supported in SCR: • OKI ADPCM 6 kHz with 4-bit samples (24 kbps) and 8 kHz with 4-bit samples (32 kbps), VOX and WAVE file formats • G.711 PCM at 6 kHz with 8-bit samples (48 kbps) and 8 kHz with 8-bit samples (64 kbps) using A-law or mu-law coding, VOX and WAVE file formats • G.721 at 8 kHz with 4-bit samples (32 kbps), VOX and WAVE file formats • G.726 bit-exact voice coder at 8 kHz with 2-, 3-, 4-, or 5-bit samples (16, 24, 32, 40 kbps), VOX and WAVE file formats On Springware boards, the following encoding algorithms and sampling rates are supported in SCR: • 6 kHz and 8 kHz OKI ADPCM • 8 kHz and 11 kHz linear PCM • 8 kHz and 11 kHz A-law PCM • 8 kHz and 11 kHz Mu-law PCM Voice API for Windows Operating Systems Programming Guide — November 2002 83 Recording and Playback 8.9 Echo Cancellation Resource The echo cancellation resource (ECR) feature is not supported on DM3 boards. The echo cancellation resource (ECR) feature is a functional component of a voice channel. ECR is discussed in more detail in the following topics: • Overview of Echo Cancellation Resource • Echo Cancellation Resource Operation • Modes of Operation • Echo Cancellation Resource Application Models 8.9.1 Overview of Echo Cancellation Resource The ECR feature lets you use echo cancellation on signals external to the voice channel. The echo cancellation capability becomes a system-wide resource that may be applied to any time-division multiplexing (TDM) bus PCM stream. The addition of the ECR feature allows the application to dynamically configure a voice channel as either an echo cancellation device (ECR mode) or as a standard voice processing channel (SVP mode). In ECR mode, the voice channel can dynamically perform echo cancellation on any TDM bus time slot signal external to the voice channel. In ECR mode, a portion of the standard voice functionality remains available while another portion of it becomes unavailable. Note: The ECR feature has been replaced with the continuous speech processing (CSP) API. CSP is the preferred method for echo cancellation and should be used where available. For more information, see the Continuous Speech Processing API Programming Guide and Continuous Speech Processing API Library Reference. Prior to the implementation of the ECR feature in the voice library, each voice channel device had a single transmit (TX) TDM bus time slot assigned to it for data communication across the TDM bus. To connect one device to another across the TDM bus, an application would call xx_listen( ) (where xx_ is ag_, dt_, dx_, or ms_) on one voice or network device to connect to a second device’s transmit channel. Any signal transmitted by the second device on its transmit channel (TX channel) would be received by the first device’s receive channel (RX channel). For a full-duplex connection, the second device would then call xx_listen( ) to connect its receive channel to the first device’s transmit channel. Throughout this section, reference is made to echo cancellation-specific terminology. See the glossary for definitions of ECR terminology. 8.9.2 Echo Cancellation Resource Operation The echo canceller accepts two TDM bus input data streams. One stream contains data that is identical to that which was transmitted to the echo-producing circuit (Transmit Signal in Figure 15). The second stream, referred to as the echo-carrying stream, contains received data from this circuit. The received data typically contains a signal with two time-varying signals superimposed upon one another. One signal consists of a filtered version of the transmitted data (referred to as echo) and the other signal originates at the far end (referred to as far-end speech). 84 Voice API for Windows Operating Systems Programming Guide — November 2002 Recording and Playback Figure 15. Echo Canceller with Relevant Input and Output Signals Echo Canceller EchoCarrying Signal RX ECR_TX EchoCancelled Signal Echo-Carrying Signal Echo Analog Device Echo Producing Circuit Echo-Subtractor (Echo-Carrying) — (Echo-Estimate) = Echo-Cancelled ECR_RX Echo-Estimator and other control circuitry TX (Disabled in ECR Mode) Echo Reference Signal Transmit Signal of Another Device The purpose of the echo canceller is to sufficiently reduce the magnitude of the echo component, such that it does not interfere with further processing or analysis of the echo-canceled data stream. The echo canceller performs this function by computing a model of the impulse response of the echo path using information in the echo-carrying signal. Then, given the impulse response model and access to the echo reference signal, the echo canceller forms an estimate of the echo. This estimate is then subtracted from the echo-carrying signal, forming a third, echo-canceled signal. Figure 16 illustrates the signals used in the echo canceller. For echo cancellation, an extra TDM bus time slot is assigned to each voice device for use by the ECR feature. To activate ECR mode, the application must route two receive time slots to the voice channel. Figure 16. Echo Canceller Operating over a TDM bus Echo RX Telephone Network Signaling Analog Device TX VOX_RX E C R ECR_RX ECR_TX VOX_TX Voice Device Switching Handler Echo-Generating Signal SCbus Echo-Carrying Signal Echo-Carrying Signal Echo-Reference Signal Enabled in ECR Mode Disabled in ECR Mode SCbus Voice API for Windows Operating Systems Programming Guide — November 2002 85 Recording and Playback Once the ECR feature is enabled on a board, each voice channel is also permanently assigned two TDM bus transmit time slots. These time slots are referred to as the voice-transmit time slot and the echo-cancellation transmit time slot. You can retrieve the time slot numbers for each via the dx_getxmitslot( ) and dx_getxmitslotecr( ) functions, respectively. If the ECR feature is not enabled, the channels are not assigned the echo cancellation TDM bus transmit time slots, and ECR mode is not possible on any voice channel of that board. The function dx_listen( ) routes the echo-carrying signal to the voice device. A call to dx_listenecr( ) or dx_listenecrex( ) routes the echo reference signal to the voice channel and simultaneously activates ECR mode. The resulting echo canceller uses the echo reference signal to estimate the echo component in the echo-carrying signal, and subtracts that estimate from the echocarrying signal. This process results in an echo-canceled signal with a greatly reduced echo component. For another device to receive the echo-canceled signal output by the echo canceller, it calls dx_getxmitslotecr( ) to retrieve the echo canceller’s transmit time-slot number, and calls xx_listen( ) (where xx_ is ag_, dt_, dx_, or ms_) to connect its receive channel to the echocanceled signal. To return the voice channel to standard voice processing (SVP) mode, the application calls dx_unlistenecr( ) on the voice channel to stop the echo canceller, disable ECR mode, and disconnect the echo canceller’s receive channel. For technical information on ECR functions, see the Voice API Library Reference. For examples of echo cancellation configurations, see Section 8.9.4, “Echo Cancellation Resource Application Models”, on page 88. 8.9.3 Modes of Operation The echo cancellation resource feature has two modes of operation as discussed in the following topics: • Overview of Modes • Standard Voice Processing (SVP) Mode • Echo Cancellation Resource (ECR) Mode 8.9.3.1 Overview of Modes When the ECR feature is enabled at initialization time on a supported board, there are two possible modes of operation: SVP and ECR. Until ECR mode is activated, the board operates in the Standard Voice Processing (SVP) mode, which offers default echo cancellation. The ECR mode, which provides high-performance echo cancellation, can be dynamically activated or deactivated on any voice channel of the enabled board. To enable ECR mode, set EC_Resource to ON in the .cfg file or in DCM when configuring the board. 86 Voice API for Windows Operating Systems Programming Guide — November 2002 Recording and Playback 8.9.3.2 Standard Voice Processing (SVP) Mode All voice channels are initially in the SVP mode with the default echo cancellation for ECR feature-enabled boards. The SVP mode utilizes a 48 tap (6 ms) echo canceller. In SVP mode, all Dialogic voice functions operate as usual, with one exception. If a channel in SVP mode is playing a file and listening (via a dx_listen( ) function), then playback transmits data on both the standard voice-transmit time slot and the echo-cancellation transmit time slot. The standard voice-transmit time slot carries the play signal. The echo cancellation time slot carries an echo-canceled version of the signal from the receive time slot. This echo-canceled signal is derived from the original play signal (the echo reference) and the signal from the receive time slot specified in the dx_listen( ) function (the echo carrying signal). 8.9.3.3 Echo Cancellation Resource (ECR) Mode Any voice channel can be placed into ECR mode via the dx_listenecr( ) or dx_listenecrex( ) function on an ECR feature-enabled board. When a voice channel is placed in ECR mode, the echo reference TDM bus time slot is specified and the high performance echo canceller is activated. The ECR mode supplies 128 tap (16 ms) echo cancellation. When an echo carrying signal is provided as an input to the ECR by an associated dx_listen( ) function, an echo-canceled version of that signal is produced on the echo-cancellation TDM bus time slot. If no echo carrying signal is defined, the contents of the echo-cancellation transmit time slot are undefined and unpredictable. Other characteristics of the echo canceller can be set if the ECR mode is activated using the dx_listenecrex( ) function.For technical information on ECR functions, see the Voice API Library Reference. Note: dx_listen( ) may precede or follow the dx_listenecr( ) or dx_listenecrex( ) function. If multiple dx_listen( ) and dx_listenecr( ) or dx_listenecrex( ) function calls are issued against a single channel, the echo cancellation operates on the last two issued. Successive dx_listenecr( ) or dx_listenecrex( ) functions can be issued without requiring any dx_unlistenecr( ) between them. While a channel is in ECR mode, a number of standard voice operations are not available. The unavailable operations include the following: • play • record (8 kHz PCM record is the only supported record encoding when a channel is in the ECR mode. Any such 8 kHz PCM record is a recording of the echo-canceled signal.) • dial • tone generation • R2/MF • transaction record If a channel is actively performing any of the above operations, a dx_listenecr( ) or dx_listenecrex( ) function is not performed, and the function returns an error to the application. Conversely, if a channel is in ECR mode, a request for any of these operations is not honored, except for the record noted. A channel may be returned to SVP mode dynamically via the dx_unlistenecr( ) function. Voice API for Windows Operating Systems Programming Guide — November 2002 87 Recording and Playback 8.9.4 Echo Cancellation Resource Application Models Two application models are provided in this section to illustrate building an echo-canceled connection via the TDM bus: • How to Set Up the ECR Bridge • How to Set Up an ECR Play Over the TDM bus 8.9.4.1 How to Set Up the ECR Bridge This application model uses two Modular Station Interface (MSI/SC) station devices connected via the TDM bus to two voice channel devices. The voice channel devices are operating in ECR mode. Two telephones (Figure 17, “ECR Bridge Example Diagram”, on page 89) are connected to the MSI/SC stations for providing input and for listening to the echo-canceled output of each voice device. Perform the following to set up an ECR bridge: 1. Get TDM bus transmit time slots of both MSI/SC devices and the ECR transmit time slots of the two voice channel devices. ms_getxmitslot (MS1, &MS1_TX); ms_getxmitslot (MS2, &MS2_TX); dx_getxmitslotecr (CH1, &CH1_ECR_TX); dx_getxmitslotecr (CH2, &CH2_ECR_TX); 2. Have both MSI/SC stations listen to the ECR transmit of the opposite voice channel. ms_listen (MS1, &CH2_ECR_TX); ms_listen (MS2, &CH1_ECR_TX); 3. Have both voice channel devices listen to their corresponding MSI/SC station device. dx_listen (CH1, &MS1_TX); dx_listen (CH2, &MS2_TX); 4. Have each voice channel connect its echo canceller’s receive time slot to the opposite echo canceller’s ECR transmit. These signals are used as echo reference signals. dx_listenecr (CH1, & CH2_ECR_TX); dx_listenecr (CH2, & CH1_ECR_TX); 88 Voice API for Windows Operating Systems Programming Guide — November 2002 Recording and Playback Figure 17. ECR Bridge Example Diagram CH1 CH2 ECR TX TX ECR TX EC EC RX TX ECR RX ECR RX RX CH2_ECR_TX S C b u s S C CH1_ECR_TX b u MS1_TX s MS2_TX Example #include #include #include #include #includemain() { int chdev1, chdev2; /* Voice channel device handles */ int msdev1, msdev2; /* MSI/SC station device handles */ SC_TSINFO sc_tsinfo; /* TDM bus time slot information structure */ long scts; /* Pointer to TDM bus time slot */ long ms1txts, ms2txts, /* Transmit time slots of stations 1 & 2 */ ch1ecrtxts, ch2ecrtxts; /* Transmit time slots of echo-cancellers on voice channels 1 & 2 */ /* Open voice board 1 channel 1 device */ if ((chdev1 = dx_open("dxxxB1C1", 0)) == -1) { printf("Cannot open channel dxxxB1C1. errno = %d", errno); exit(1); } /* Open voice board 1 channel 2 device */ if ((chdev2 = dx_open("dxxxB1C2", 0)) == -1) { printf("Cannot open channel dxxxB1C2. errno = %d", errno); exit(1); } /* Open MSI/SC board 1 station 1 device */ if ((msdev1 = ms_open("msiB1C1", 0)) == -1) { printf("Cannot open station msiB1C1. errno = %d", errno); exit(1); } Voice API for Windows Operating Systems Programming Guide — November 2002 89 Recording and Playback /* Open MSI/SC board 1 station 2 device */ if ((msdev2 = ms_open("msiB1C2", 0)) == -1) { printf("Cannot open station msiB1C2. errno = %d", errno); exit(1); } /* Initialize a TDM bus time slot information */ sc_tsinfo.sc_numts = 1; sc_tsinfo.sc_tsarrayp = &scts; /* Get TDM bus time slot connected to transmit of MSI/SC station 1 on board 1 */ if (ms_getxmitslot(msdev1, &sc_tsinfo) == -1) { printf("Error message = %s, on %s", ATDV_ERRMSGP(msdev1), ATDV_NAMEP(msdev1)); exit(1); } ms1txts = scts; /* Get TDM bus time slot connected to transmit of MSI/SC station 2 on board 1 */ if (ms_getxmitslot(msdev2, &sc_tsinfo) == -1) { printf("Error message = %s, on %s", ATDV_ERRMSGP(msdev2), ATDV_NAMEP(msdev2)); exit(1); } ms2txts = scts; /* Get TDM bus time slot connected to transmit of voice channel 1 on board 1 */ if (dx_getxmitslotecr(chdev1, &sc_tsinfo) == -1) { printf("Error message = %s, on %s", ATDV_ERRMSGP(chdev1), ATDV_NAMEP(chdev1)); exit(1); } ch1ecrtxts = scts; /* Get TDM bus time slot connected to transmit of voice channel 2 on board 1 */ if (dx_getxmitslotecr(chdev2, &sc_tsinfo) == -1) { printf("Error message = %s, on %s", ATDV_ERRMSGP(chdev2), ATDV_NAMEP(chdev2)); exit(1); } ch2ecrtxts = scts; /* Have MSI/SC station 1 listen to channel 2's echo-cancelled transmit */ if (ms_listen(msdev1, &sc_tsinfo) == -1) { printf("Error message = %s, on %s", ATDV_ERRMSGP(msdev1), ATDV_NAMEP(msdev1)); exit(1); } scts = ch1ecrtxts; /* Have MSI/SC station 2 listen to channel 1's echo-cancelled transmit */ if (ms_listen(msdev2, &sc_tsinfo) == -1) { printf("Error message = %s, on %s", ATDV_ERRMSGP(msdev2), ATDV_NAMEP(msdev2)); exit(1); } scts = ms1txts; /* Have channel 1 listen to station 1's transmit */ if (dx_listen(chdev1, &sc_tsinfo) == -1) { printf("Error message = %s, on %s", ATDV_ERRMSGP(chdev1), ATDV_NAMEP(chdev1)); exit(1); } scts = ms2txts; /* Have channel 2 listen to station 2's transmit */ if (dx_listen(chdev2, &sc_tsinfo) == -1) { printf("Error message = %s, on %s", ATDV_ERRMSGP(chdev2), ATDV_NAMEP(chdev2)); exit(1); } 90 Voice API for Windows Operating Systems Programming Guide — November 2002 Recording and Playback scts = ch2ecrtxts; /* Have channel 1's echo-canceller listen to channel 2's echo-cancelled transmit */ if (dx_listenecr(chdev1, &sc_tsinfo) == -1) { printf("Error message = %s, on %s", ATDV_ERRMSGP(chdev1), ATDV_NAMEP(chdev1)); exit(1); } scts = ch1ecrtxts; /* Have channel 2's echo-canceller listen to channel 1's echo-cancelled transmit */ if (dx_listenecr(chdev2, &sc_tsinfo) == -1) { printf("Error message = %s, on %s", ATDV_ERRMSGP(chdev2), ATDV_NAMEP(chdev2)); exit(1); } /* Bridge connected, both stations receive echo-cancelled signal */ /* * * Continue * */ /* Then perform xx_unlisten() and dx_unlistenecr(), plus all necessary xx_close()s */ if (ms_unlisten(msdev2) == -1) { printf("Error message = %s, on exit(1); } if (ms_unlisten(msdev1) == -1) { printf("Error message = %s, on exit(1); } if (dx_unlistenecr(chdev2) == -1) printf("Error message = %s, on exit(1); } if (dx_unlistenecr(chdev1) == -1) printf("Error message = %s, on exit(1); } if (dx_unlisten(chdev2) == -1) { printf("Error message = %s, on exit(1); } if (dx_unlisten(chdev1) == -1) { printf("Error message = %s, on exit(1); } if (dx_close(chdev1) == -1) { printf("Error message = %s, on exit(1); } if (dx_close(chdev2) == -1) { printf("Error message = %s, on exit(1); } if (ms_close(msdev1) == -1) { printf("Error message = %s, on exit(1); } if (ms_close(msdev2) == -1) { printf("Error message = %s, on exit(1); } return(0); %s", ATDV_ERRMSGP(msdev2), ATDV_NAMEP(msdev2)); %s", ATDV_ERRMSGP(msdev1), ATDV_NAMEP(msdev1)); { %s", ATDV_ERRMSGP(chdev2), ATDV_NAMEP(chdev2)); { %s", ATDV_ERRMSGP(chdev1), ATDV_NAMEP(chdev1)); %s", ATDV_ERRMSGP(chdev2), ATDV_NAMEP(chdev2)); %s", ATDV_ERRMSGP(chdev1), ATDV_NAMEP(chdev1)); %s", ATDV_ERRMSGP(chdev1), ATDV_NAMEP(chdev1)); %s", ATDV_ERRMSGP(chdev2), ATDV_NAMEP(chdev2)); %s", ATDV_ERRMSGP(chdev1), ATDV_NAMEP(chdev1)); %s", ATDV_ERRMSGP(msdev2), ATDV_NAMEP(msdev2)); } Voice API for Windows Operating Systems Programming Guide — November 2002 91 Recording and Playback 8.9.4.2 How to Set Up an ECR Play Over the TDM bus In this model, two MSI/SC station devices are connected via the TDM bus to two voice channel devices. The second voice channel device is operating in ECR mode. Two telephones are connected to the MSI/SC stations for providing input and listening to the echo-cancelled output of the second voice device, and to the non-echo-cancelled output of the first voice device. See Figure 18, “An ECR Play Over the TDM bus”, on page 92. Perform the following to set up an ECR play over the TDM bus: 1. Get TDM bus transmit time slots of both MSI/SC devices and the ECR transmit time slots of the two voice channel devices. ms_getxmitslot (MS1, &MS1_TX); dx_getxmitslot (CH1, &CH1_TX); dx_getxmitslotecr (CH2, &CH2_ECR_TX); 2. Have the MSI/SC station 1 listen to the transmit (TX) of channel 1. ms_listen (MS1, & CH1_TX); 3. Have MSI/SC station 2 listen to the ECR transmit of channel 2. ms_listen (MS2, & CH2_ECR_TX); 4. Have voice channel 2 listen to MSI/SC station 1’s transmit. dx_listen (CH2, & MS1_TX); 5. Have voice channel 2 connect its echo canceller’s receive time slot to transmit of channel 1. This signal is used as the echo reference signal. dx_listenecr (CH2, & CH1_TX); Figure 18. An ECR Play Over the TDM bus CH2 Voice File TX (Unused) CH1 ECR TX EC TX RX ECR RX CH2_ECR_TX S C b u s S C b MS1_TX u MS2_TX (unused) s CH1_TX MS1 92 MS2 Voice API for Windows Operating Systems Programming Guide — November 2002 Recording and Playback Example #include #include #include #include #include mmain() { int chdev1, chdev2; int msdev1, msdev2; SC_TSINFO sc_tsinfo; long scts; long ms1txts, ch1txts, ch2ecrtxts; /* /* /* /* /* /* Voice channel device handles */ MSI/SC station device handles */ TDM bus time slot information structure */ Pointer to TDM bus time slot */ Transmit time slots of stations 1 & 2 */ Transmit time slots of echo-cancellers on voice channels 1 & 2 */ /* Open voice board 1 channel 1 device */ if ((chdev1 = dx_open("dxxxB1C1", 0)) == -1) { printf("Cannot open channel dxxxB1C1. errno = %d", errno); exit(1); } /* Open voice board 1 channel 2 device */ if ((chdev2 = dx_open("dxxxB1C2", 0)) == -1) { printf("Cannot open channel dxxxB1C2. errno = %d", errno); exit(1); } /* Open MSI/SC board 1 station 1 device */ if ((msdev1 = ms_open("msiB1C1", 0)) == -1) { printf("Cannot open station msiB1C1. errno = %d", errno); exit(1); } /* Open MSI/SC board 1 station 2 device */ if ((msdev2 = ms_open("msiB1C2", 0)) == -1) { printf("Cannot open station msiB1C2. errno = %d", errno); exit(1); } /* Initialize an TDM bus time slot information */ sc_tsinfo.sc_numts = 1; sc_tsinfo.sc_tsarrayp = &scts; /* Get TDM bus time slot connected to transmit of voice channel 1 on board 1 */ if (ms_getxmitslot(msdev1, &sc_tsinfo) == -1) { printf("Error message = %s, on %s", ATDV_ERRMSGP(msdev1), ATDV_NAMEP(msdev1)); exit(1); } ms1txts = scts; /* Get TDM bus time slot connected to transmit of voice channel 1 on board 1*/ if (dx_getxmitslot(chdev1, &sc_tsinfo) == -1) { printf("Error message = %s, on %s", ATDV_ERRMSGP(chdev1), ATDV_NAMEP(chdev1)); exit(1); } ch1txts = scts; /* Get TDM bus time slot connected to transmit of voice channel 1 on board 1 */ if (dx_getxmitslotecr(chdev2, &sc_tsinfo) == -1) { printf("Error message = %s, on %s", ATDV_ERRMSGP(chdev2), ATDV_NAMEP(chdev2)); exit(1); } ch2ecrtxts = scts; Voice API for Windows Operating Systems Programming Guide — November 2002 93 Recording and Playback /* Have station 1 listen to file played by voice channel 1 */ scts = ch1txts; if (ms_listen(msdev1, &sc_tsinfo) == -1) { printf("Error message = %s, on %s", ATDV_ERRMSGP(msdev1), ATDV_NAMEP(msdev1)); exit(1); } /* Have station 2 listen to echo-cancelled output of voice channel 2 */ scts = ch2ecrtxts; if (ms_listen(msdev2, &sc_tsinfo) == -1) { printf("Error message = %s, on %s", ATDV_ERRMSGP(msdev2), ATDV_NAMEP(msdev2)); exit(1); } /* Have voice channel 2 listen to echo-carrying signal from station 1 */ scts = ms1txts; if (dx_listen(chdev2, &sc_tsinfo) == -1) { printf("Error message = %s, on %s", ATDV_ERRMSGP(chdev1), ATDV_NAMEP(chdev1)); exit(1); } /* And activate the ECR feature on voice channel 2, with the echo-reference signal coming from voice channel 1 */ scts = ch1txts; if (dx_listenecr(chdev2, &sc_tsinfo) == -1) { printf("Error message = %s, on %s", ATDV_ERRMSGP(chdev2), ATDV_NAMEP(chdev2)); exit(1); } /* Setup completed, any signal transmitted from channel device 1, * will a) be received by station 1, * b) contribute echo to the transmit of station 1, * c) will be heard AFTER echo-cancellation (on channel 2) by * station 2.*/ /* . . Continue . */ /* Then perform xx_unlisten() and dx_unlistenecr(), plus all necessary xx_close()s */ if (ms_unlisten(msdev2) == -1) { printf("Error message = %s, on exit(1); } if (ms_unlisten(msdev1) == -1) { printf("Error message = %s, on exit(1); } if (dx_unlistenecr(chdev2) == -1) printf("Error message = %s, on exit(1); } if (dx_unlisten(chdev2) == -1) { printf("Error message = %s, on exit(1); } if (dx_close(chdev1) == -1) { printf("Error message = %s, on exit(1); } if (dx_close(chdev2) == -1) { printf("Error message = %s, on exit(1); } 94 %s", ATDV_ERRMSGP(msdev2), ATDV_NAMEP(msdev2)); %s", ATDV_ERRMSGP(msdev1), ATDV_NAMEP(msdev1)); { %s", ATDV_ERRMSGP(chdev2), TDV_NAMEP(chdev2)); %s", ATDV_ERRMSGP(chdev2), ATDV_NAMEP(chdev2)); %s", ATDV_ERRMSGP(chdev1), ATDV_NAMEP(chdev1)); %s", ATDV_ERRMSGP(chdev2), ATDV_NAMEP(chdev2)); Voice API for Windows Operating Systems Programming Guide — November 2002 Recording and Playback if (ms_close(msdev1) == -1) { printf("Error message = %s, on %s", ATDV_ERRMSGP(msdev1), ATDV_NAMEP(msdev1)); exit(1); } if (ms_close(msdev2) == -1) { printf("Error message = %s, on %s", ATDV_ERRMSGP(msdev2), ATDV_NAMEP(msdev2)); exit(1); } return(0); } Voice API for Windows Operating Systems Programming Guide — November 2002 95 Recording and Playback 96 Voice API for Windows Operating Systems Programming Guide — November 2002 Speed and Volume Control 9. 9 This chapter describes how to control the speed and volume of play on a channel. The following topics are discussed: • Speed and Volume Control Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 • Speed and Volume Convenience Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 • Speed and Volume Adjustment Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 • Speed and Volume Modification Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 • Play Adjustment Digits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 • Setting Play Adjustment Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 • Explicitly Adjusting Speed and Volume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 9.1 Speed and Volume Control Overview The voice software contains functions and data structures to control the speed and volume of play on a channel. This allows an end user to control the speed or volume of a message by entering a DTMF tone, for example. On DM3 boards, speed can be controlled on playbacks using ADPCM encoding, or using PCM Alaw or mu-law encoding at 8 kHz sampling rate. On Springware boards, speed can be controlled on playbacks using 24 Kbps or 32 Kbps ADPCM only. Volume can be controlled on all playbacks regardless of the encoding algorithm. For a list of supported encoding methods, see Section 8.5, “Voice Encoding Methods”, on page 79. 9.2 Speed and Volume Convenience Functions The convenience functions set a digit that will adjust speed or volume, but do not use any data structures. These convenience functions will only function properly if you use the default settings of the speed or volume modification tables. These functions assume that the modification tables have not been modified. The speed or volume convenience functions are: dx_addspddig( ) adds a digit that will modify speed by a specified amount dx_addvoldig( ) adds a digit that will modify volume by a specified amount Voice API for Windows Operating Systems Programming Guide — November 2002 97 Speed and Volume Control See the Voice API Library Reference for detailed information about these functions. 9.3 Speed and Volume Adjustment Functions Speed or volume can be adjusted explicitly or can be set to adjust in response to a preset condition, such as a specific digit. For example, speed could be set to increase a certain amount when “1” is pressed on the telephone keypad. The functions used for speed and volume adjustment are: dx_setsvcond( ) Sets conditions that adjust speed or volume. Use this function to adjust speed or volume in response to a DTMF digit or start of play. dx_adjsv( ) Adjusts speed or volume explicitly. Use this function if your adjustment condition is not a digit or start of play. For example, the application could call this function after detecting a spoken word (voice recognition) or a certain key on the keyboard. See the Voice API Library Reference for detailed information about these functions. 9.4 Speed and Volume Modification Tables Each channel has a speed or volume modification table for play speed or play volume adjustments. Except for the value of the settings, the table is the same for speed and volume. Each speed or volume modification table (SVMT) table has 21 entries, 20 that allow for a maximum of 10 increases and decreases in speed or volume. The entry in the middle of the table is referred to as the “origin” entry that represents normal speed or volume. The normal speed or volume is how playback occurs when the speed and volume control feature is not used. See Table 10, “Default Speed Modification Table”, on page 100 and Table 11, “Default Volume Modification Table”, on page 101. The origin, or normal speed or volume, is the basis for all settings in the table. Typically, the origin is set to 0. Speed and volume increases or decreases by moving up or down the tables. Other entries in the table specify a speed or volume setting in terms of a deviation from normal. For example, if a speed modification table (SMT) entry is -10, this value represents a 10% decrease from the normal speed. Although the origin is typically set to normal speed/volume, changing the setting of the origin does not affect the other settings, because all values in the SVMT are based on a deviation from normal speed/volume. Speed and volume control adjustments are specified by moving the current speed/volume pointer in the table to another SVMT table entry; this translates to increasing or decreasing the current speed/volume to the value specified in the table entry. A speed/volume adjustment stays in effect until the next adjustment on that channel or until a system reset. 98 Voice API for Windows Operating Systems Programming Guide — November 2002 Speed and Volume Control The SVMT is like a 21-speed bicycle. You can select the gear ratio for each of the 21 speeds before you go for a ride (by changing the values in the SVMT). And you can select any gear once you are on the bike, like adjusting the current speed/volume to any setting in the SVMT. To change the default values of the speed or volume modification table, use the dx_setsvmt( ) function, which in turn uses the DX_SVMT data structure. To return the current values of a table to the DX_SVMT structure, use dx_getsvmt( ). The DX_SVCB data structure uses this table when setting adjustment conditions. See the Voice API Library Reference for detailed information about these functions and data structures. Adjustments to speed or volume are made by dx_adjsv( ) and dx_setsvcond( ) according to the speed or volume modification table settings. These functions adjust speed or volume to one of the following: • a specified level (that is, to a specified absolute position in the speed table or volume table) • a change in level (that is, by a specified number of steps up or down in the speed table or volume table) For example, by default, each entry in the volume modification table is equivalent to 2 dB from the origin. Volume could be decreased by 2 dB by specifying position 1 in the table, or by moving one step down from the origin. Voice API for Windows Operating Systems Programming Guide — November 2002 99 Speed and Volume Control The default speed modification table is shown in Table 10. Table 10. Default Speed Modification Table Table Entry Default Value (%) Absolute Position decrease[0] -128 (80h) -10 decrease[1] -128 (80h) -9 decrease[2] -128 (80h) -8 decrease[3] -128 (80h) -7 decrease[4] -128 (80h) -6 decrease[5] -50 -5 decrease[6] -40 -4 decrease[7] -30 -3 decrease[8] -20 -2 decrease[9] -10 -1 0 0 increase[0] +10 1 increase[1] +20 2 increase[2] +30 3 increase[3] +40 4 increase[4] +50 5 increase[5] -128 (80h) 6 increase[6] -128 (80h) 7 increase[7] -128 (80h) 8 increase[8] -128 (80h) 9 increase[9] -128 (80h) 10 origin Consider the following usage information on the speed modification table: • Each entry in the table is a percentage deviation from the default play speed (“origin”). For example, the decrease[6] position reduces speed by 40%. This is four steps from the origin. • In this table, the lowest position used is the decrease[5] position. The remaining decrease fields are set to -128 (80h). If these “nonadjustment” positions are selected, the default action is to play at the decrease[5] speed. • These fields can be reset, as long as no values lower than -50 are used. For example, you could spread the 50% speed decrease over 10 steps rather than 5. Similarly, you could spread the 50% speed increase over 10 steps rather than 5. • The default entries for index values -10 to -6 and +6 to +10 are -128 which represent a null- entry. To customize the table entries, you must use the dx_setsvmt( ) function. • On DM3 boards, when adjustment is associated with a DTMF digit, speed can be increased or decreased in increments of 1 (10%) only. To achieve an increase in speed of 30% for example, the user would press the DTMF digit three times. 100 Voice API for Windows Operating Systems Programming Guide — November 2002 Speed and Volume Control The default volume modification table is shown in Table 11. Table 11. Default Volume Modification Table Table Entry Default Value (dB) Absolute Position decrease[0] -20 -10 decrease[1] -18 -9 decrease[2] -16 -8 decrease[3] -14 -7 decrease[4] -12 -6 decrease[5] -10 -5 decrease[6] -08 -4 decrease[7] -06 -3 decrease[8] -04 -2 decrease[9] -02 -1 0 0 increase[0] +02 1 increase[1] +04 2 increase[2] +06 3 increase[3] +08 4 increase[4] +10 5 increase[5] -128 (80h) 6 increase[6] -128 (80h) 7 increase[7] -128 (80h) 8 increase[8] -128 (80h) 9 increase[9] -128 (80h) 10 origin Consider the following usage information on the volume modification table: • Each entry in the table is a deviation in decibels from the starting point or volume (“origin”). Each entry in the table is equivalent to 2 dB from the origin. Volume can be decreased 2 dB by specifying position 1 in the table, or by moving one step down. For example, the increase[1] position (two steps from the origin) increases volume by 4 dB. • In this table, the highest position utilized is the increase[4] position. The remaining increase fields are set to -128 (80h). If these “non-adjustment” positions are selected, the default action is to play at the increase[4] volume. These fields can be reset, as long as no values higher than +10 are used; for example, you could spread the 10 dB volume increase over 10 steps rather than 5. • In the volume modification table, the default entries for index values +6 to +10 are -128 which represent a null-entry. To customize the table entries, you must use the dx_setsvmt( ) function. • On DM3 boards, when adjustment is associated with a DTMF digit, volume can be increased or decreased in increments of 1 (2 dB) only. To achieve an increase in volume of 6 dB for example, the user would press the DTMF digit three times. Voice API for Windows Operating Systems Programming Guide — November 2002 101 Speed and Volume Control 9.5 Play Adjustment Digits The voice software processes play adjustment digits differently from normal digits: • If a play adjustment digit is entered during playback, it causes a play adjustment only and has no other effect. This means that the digit is not added to the digit queue, it cannot be retrieved with the dx_getdig( ) function. • On DM3 boards, digits that are used for play adjustment may also be used as a terminating condition. If a digit is defined as both, then both actions are applied upon detection of that digit. • On Springware boards, digits that are used for play adjustment will not be used as a terminating condition. If a digit is defined as both, then the play adjustment will take priority. • If the digit queue contains adjustment digits when a play begins and play adjustment is set to be level sensitive, the digits will affect the speed or volume and then be removed from the queue. 9.6 Setting Play Adjustment Conditions Adjustment conditions are set in the same way for speed or volume. The following steps describe how to set conditions upon which volume should be adjusted: 1. Set up the volume modification table (if you do not want to use the defaults): • Set up the DX_SVMT structure to specify the size and number of the steps in the table. • Call the dx_setsvmt( ) function, which points to the DX_SVMT structure, to modify the volume modification table (dx_setsvmt( ) can also be used to reset the table to its default values). 2. Set up the DX_SVCB structure to specify the condition, the size, and the type of adjustment. 3. Call dx_setsvcond( ), which points to an array of DX_SVCB structures. All subsequent plays will adjust volume as required whenever one of the conditions specified in the array occurs. See the Voice API Library Reference for more information about these functions and data structures. 9.7 Explicitly Adjusting Speed and Volume Speed and volume adjustments are made in the same way. The following steps describe how to adjust speed, but you can use exactly the same procedure for volume: 1. Set up the speed modification table (if you do not want to use the defaults): • Set up the DX_SVMT structure to specify the size and number of the steps in the table. • Call the dx_setsvmt( ) function, which points to the DX_SVMT structure, to modify the speed modification table (dx_setsvmt( ) can also be used to reset the table to its default values). 2. When required, call dx_adjsv( ) to adjust the speed modification table by specifying the size and type of the adjustment. 102 Voice API for Windows Operating Systems Programming Guide — November 2002 Speed and Volume Control See the Voice API Library Reference for more information about these functions and data structures. Voice API for Windows Operating Systems Programming Guide — November 2002 103 Speed and Volume Control 104 Voice API for Windows Operating Systems Programming Guide — November 2002 Send and Receive FSK Data 10. 10 This chapter contains an overview of the Analog Display Services Interface (ADSI) protocol, an overview of two-way frequency shift keying (FSK), and a description of how to implement ADSI support using voice library functions. The following topics are covered: • Overview of ADSI and Two-Way FSK Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 • ADSI Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 • ADSI Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 • One-Way ADSI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 • Two-Way ADSI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 • ADSI and Two-Way FSK Voice Library Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 • Developing ADSI Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 • Modifying Older One-Way ADSI Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 10.1 Overview of ADSI and Two-Way FSK Support The Analog Display Services Interface (ADSI) is a Bellcore standard that defines a protocol used to transmit data to a display-based, ADSI-compliant telephone. ADSI enables data to be sent across an analog telephone line, providing asynchronous data communications with 8 data bits, 1 start and 1 stop bit, and no parity. For many years, one-way ADSI support was provided through the dx_play( ) and dx_playf( ) functions. This ADSI support enabled developers to use Intel Dialogic boards to make ADSI servers that work with ADSI phones and to support ADSI features such as visual voice mail. This is referred to as the “older” implementation of one-way ADSI. We have expanded the capabilities of basic ADSI with the introduction of two-way frequency shift keying (FSK) capabilities. Two-way FSK is a convenient and robust mechanism to exchange small amounts of data between the telephone and the server using FSK as the transport layer. The twoway FSK functionality allows products to transmit and receive half-duplex FSK Bell 202 1200 bps data over the Public Switched Telephone Network (PSTN). One of the applications of two-way FSK is Small Messages Service or SMS. This allows the server and display-based telephone to exchange small text messages via the PSTN. As with basic ADSI, the transmission and reception of two-way FSK data is initiated after a call between the server and the display-based telephone (or CPE) has been established, by one of the devices sending a special alerting signal (typically a CAS tone). The other device will then acknowledge and the data transmission (and/or reception) will then be initiated. Once the data transmission/reception is complete, the devices switch back to voice mode. Voice API for Windows Operating Systems Programming Guide — November 2002 105 Send and Receive FSK Data This newer implementation of ADSI is supported through the dx_RxIottData( ), dx_TxIottData( ), and dx_TxRxIottData( ) functions. This implementation is referred to simplay as "ADSI Support" or "Two-Way ADSI." This newer ADSI support provides for both one-way and two-way ADSI transmission and is the recommended method for implementing either one-way or two-way ADSI in an application program. The older one-way ADSI support can be used but is not recommended. Future enhancements to ADSI feature and functionality will not be made to the dx_play( ) and dx_playf( ) functions. See Section 10.8, “Modifying Older One-Way ADSI Applications”, on page 115 for information on converting from the older to the newer method for using ADSI. 10.2 ADSI Protocol ADSI is a superset of the caller ID and call waiting functions. ADSI is built on the same protocol as caller ID and shares the same ADSI Data Message Format (ADMF). The ADSI protocol requires a Bell 202/V.23 1200 bps FSK-based modem for data transmission. The ADSI protocol supports a variable display size on a display-based telephone. An ADSI telephone can work in either voice mode or data mode. Voice mode is for normal telephone audio communication, and data mode is for transmitting ADSI commands and controlling the telephone display (voice is muted in data mode). An ADSI alert tone is used to verify that the hardware is connected to an ADSI telephone and to alert the telephone that ADSI data will be transferred. The ADSI protocol consists of three defined layers, as follows: message assembly layer assembles the body of the ADMF message data link layer generates the checksum, which is used for error detection, and sends it to the driver physical layer transports the composite message via the modem to the CPE on a transparent (bit-for-bit) basis Intel provides only the physical layer and a portion of the data link layer of the ADSI protocol. The user is responsible for creating the ADSI messages and the corresponding checksums. The ADSI data must conform to interface requirements described in Bellcore Technical Reference GR-30-CORE, Voiceband Data Transmission Interface Generic Requirements. For information about message requirements (how the data should be displayed on the CPE), see Bellcore Technical Reference TR-NWT-001273, Generic Requirements for and SPCS to Customer Premises Equipment Data Interface for Analog Display Services. To obtain a copy of these technical references, call 1-800-521-2673 (from the U.S. and Canada) or +1-732-699-5800 (worldwide), or visit http://www.telcordia.com. Note that Bellcore is now known as Telcordia Technologies. 106 Voice API for Windows Operating Systems Programming Guide — November 2002 Send and Receive FSK Data 10.3 ADSI Operation ADSI data is encoded using a standard 1200 baud modem specification and transmitted to the telephone on the voice channel. The voice is muted for the data transfer to occur. Responses from the ADSI telephone are mapped into DTMF sequences. ADSI data is sent to the ADSI telephone in a message burst corresponding to a single transmission. Each message burst or transmission can contain up to 5 messages, with each message consisting of one or more ADSI commands. The ADSI alert tone causes the ADSI telephone to switch to data mode for 1 message burst or transmission. When the transmission is complete, the ADSI phone will revert to voice mode unless the transmission contained a message with the “Switch to Data” command. After the data is transmitted, the ADSI telephone sends an acknowledgment consisting of a DTMF “d” plus a digit from 1 to 5 indicating the number of messages in the transmission that the ADSI telephone received and understood. By obtaining this message count and comparing it with the number of messages transmitted, you can check for errors and retransmit any messages not received. (If you send 4 messages and the telephone receives 2, you must resend messages 3 and 4.) You can send more than one transmission during a call. After the initial transmission of a call, you do not have to re-establish the handshaking (sending the alert tone or receiving the acknowledgment digit) as long as you have left the ADSI telephone in data mode using the ADSI “Switch to Data” command. This is useful for performing additional data transmissions during the same call without needing to send the alert tone or receive the acknowledgment digit for each transmission. 10.4 One-Way ADSI One-way ADSI support enables Intel Dialogic boards to be used as ADSI servers and to support ADSI features such as visual voice mail. One-way ADSI allows for the one-way transmission of data from a server to a customer premises equipment (CPE) device, such as a display-based telephone. The phone (CPE) sends dual tone multi-frequency (DTMF) messages to the server, indicating whether the data was received successfully. For a more detailed description of the one-way ADSI data transfer process, see Section 10.7, “Developing ADSI Applications”, on page 110. ADSI data can be transferred only to display-based telephones that are ADSI compliant. Check with your telephone manufacturer to find out if your telephone is a true ADSI-compliant device. An ADSI alert tone, referred to as a CAS (CPE Alerting Signal), is sent by the Intel Dialogic server to query a CPE device, such as an ADSI display phone. The device responds appropriately and, if the device is ADSI-compliant, the ADSI data transfer is initiated. Note: ADSI-compliant phones are also referred to as "Type 3 CPE Devices" by Bellcore and by the Electronic Industry Association/Telecommunications Industry Association (EIA/TIA). Voice API for Windows Operating Systems Programming Guide — November 2002 107 Send and Receive FSK Data 10.5 Two-Way ADSI Two-way ADSI includes several enhancements to one-way ADSI, including the two-way frequency shift keying (FSK). The following topics discuss the two-way ADSI enhancements: • Transmit to On-Hook CPE • Two-Way FSK 10.5.1 Transmit to On-Hook CPE The transmit to on-hook customer premises equipment (CPE) feature allows messages to be sent to an ADSI phone when the phone is either on-hook or off-hook. This feature supports the transmission of FSK data burst messages to CPE devices that are kept in the on-hook state by either the CO or the PBX/KTS. This allows an ADSI/Caller ID phone to receive and potentially display messages while it is in the on-hook state. For example, ADSI phones can be configured, accessed, and downloaded with features, outside of regular business hours while the phone is on-hook, without ringing and without subscriber intervention. Note: 10.5.2 The transmit to on-hook CPE feature works only if the CO supports this feature, or if an ADSI device is connected directly to an Intel Dialogic MSI/SC board. Two-Way FSK The two-way frequency shift keying (FSK) feature allows users to send and receive character or binary data at 1200 bits/second between the server and compatible devices, such as certain ADSI phones with keyboards. The two-way FSK feature supports applications such as off-line e-mail editing and sending FSK Caller ID data to a customer premise equipment (CPE) device through an MSI/SC board. FSK (frequency shift keying) is the modulation technique used to transfer data over voice lines. The basic ADSI capability supports only FSK Transmit (one-way FSK), in which an FSK message is sent from the Intel Dialogic server to an ADSI display phone, with the phone in the off-hook state. The phone (CPE) sends dual tone multi-frequency (DTMF) messages to the server. As DTMF messages are sent to the server, the effective data rate is very slow, approximately 6 characters per second maximum. This speed is satisfactory for ACK/NAK signaling but it is not usable for any bulk data transport in the inbound direction from the CPE. FSK data reception uses a DSP-based Bell 202/V.23 low speed (1200 baud) modem receiver. A 1200 baud modem does not need to train for data transmission, and therefore is faster than a highspeed modem for short data bursts. Two-way FSK for ADSI supports the transmission and the reception of FSK data between the server and the CPE. The server initiates the reception of data from the CPE by sending a CAS to tell the CPE to switch to data mode, followed by a message that tells the CPE to switch to peripheral mode. Once it is in peripheral mode, the CPE can send FSK messages to the server using the ADSI Data Message Format (ADMF), instead of the slower DTMF-based scheme. 108 Voice API for Windows Operating Systems Programming Guide — November 2002 Send and Receive FSK Data See Section 10.7, “Developing ADSI Applications”, on page 110 for a more detailed description of how use library functions to develop two-way ADSI data transfer applications. For more information about two-way FSK transmission, see the Bellcore (now known as Telcordia Technologies) Special Report SR-3462, A Two-Way Frequency Shift Keying Communication for the ADSI. In addition to features provided by basic ADSI, two-way FSK for ADSI can be used in the following applications: • sending and receiving e-mail between display-based ADSI phones and the server • sending FSK Caller ID data through the MSI to a CPE device Note: 10.6 To send caller ID information through an MSI/SC board, the ADSI phones connected to the board must be able to detect and accept the transmission of caller ID information prior to the first ring. ADSI and Two-Way FSK Voice Library Support The voice library functions and data structure that support ADSI and two-way FSK are discussed in the following topics: • Support on DM3 Boards • Support on Springware Boards 10.6.1 Support on DM3 Boards DM3 boards support ADSI one-way and two-way FSK. The following voice library functions, data structure, and defines support ADSI on DM3 boards: dx_RxIottdata( ) function This function receives ADSI data on a specified channel. dx_TxIottdata( ) function This function transmits ADSI data on a specified channel. dx_TxRxIottdata( ) function This function starts a transmit-initiated reception of data (two-way ADSI) data on a specified channel. ADSI_XFERSTRUC data structure This structure stores information for the transmission and reception of ADSI data. It is used by the dx_RxIottdata( ), dx_TxIottdata( ), and dx_TxRxIottdata( ) functions. DX_MAXDATA termination condition Specify this condition in the tp_termno field of the DV_TPT data structure. Specify a valid value in tp_length field. Valid values are 1 through 65535. A Transmit/Receive FSK session is terminated when the specified value of FSK DX_MAXDATA (in bytes) is transmitted/received. TM_MAXDATA return value This value is returned by ATDX_TERMMSK( ) when the last I/O function terminates on DX_MAXDATA. Voice API for Windows Operating Systems Programming Guide — November 2002 109 Send and Receive FSK Data DXCH_FSKINTERBLKTIMEOUT channel parameter This parameter is set and obtained by the dx_setparm( ) and dx_getparm( ) functions, respectively; measured in milliseconds. The firmware gets FSK data in bursts. This parameter specifies how long the firmware should wait for the next burst of FSK data before it can conclude that no more data will be coming and can terminate the receive session. In short, this parameter denotes the maximum time between any two FSK data bursts in one receive session. This property can only be supplied for reception of FSK data with dx_RxIottdata( ). Note: To maintain compatibility with the way other termination conditions are specified, you can also specify TF_MAXDATA in the tp_flags field of the DV_TPT, but the library does not take note of that flag. For details on these functions, data structure, and defines, see the Voice API Library Reference. For an example of ADSI code on DM3 boards, see the Example section in the function descriptions for dx_RxIottdata( ), dx_TxIottdata( ), and dx_TxRxIottdata( ) in the Voice API Library Reference. 10.6.2 Support on Springware Boards Springware boards support ADSI one-way and two-way FSK. See Section 10.6.1, “Support on DM3 Boards”, on page 109 for more information on library support. The same functions are used for Springware boards. 10.7 Developing ADSI Applications This section provides the following information on developing applications for one-way and twoway ADSI FSK: • Technical Overview of One-Way ADSI Data Transfer • Implementing One-Way ADSI Using dx_TxIottData( ) • Technical Overview of Two-Way ADSI Data Transfer • Implementing Two-Way ADSI Using dx_TxIottData( ) • Implementing Two-Way ADSI Using dx_TxRxIottData( ) 10.7.1 Technical Overview of One-Way ADSI Data Transfer In one-way ADSI data transfer, the ADSI server sends ADSI messages to a CPE device, such as an ADSI-compliant telephone. The transactions that occur between the server and the CPE during one-way ADSI data transfer are as follows: 1. The server initiates the data transfer by sending a CPE Alerting Signal (CAS) to the CPE. 2. When the CPE receives the CAS, the device generates an ACK (DTMF ‘A’ signal) to the server. At this point the CPE device has switched from voice mode to data mode. (If the CPE device remains in data mode, subsequent transmissions do not require the CAS.) Note: Only ADSI-compliant CPE devices will respond to the CAS sent by the server. Check with your manufacturer to verify that your CPE device is a true ADSI-compliant device. ADSI-compliant devices are also referred to as "Type 3 CPE Devices" by Bellcore and the EIA/TIA. 110 Voice API for Windows Operating Systems Programming Guide — November 2002 Send and Receive FSK Data 3. Upon receipt of the ACK signal, the server initiates the FSK transmission sequence. Each FSK transmission sequence can contain anywhere from 1 to 5 messages. 4. The CPE receives the FSK data and uses the checksum included within the sequence to determine the number of messages successfully received. 5. The CPE device then responds to the server with an acknowledgment digit (DTMF ‘D’) followed by a DTMF of ‘0’ through ‘5,’ which indicates the number of messages successfully received. 6. The server interprets the DTMF as follows: • ACK = ‘D’ followed by a DTMF in the range of 1 – 5 • NAK = ‘D’ followed by a DTMF ‘0’ 10.7.2 Implementing One-Way ADSI Using dx_TxIottData( ) The dx_TxIottData( ) function is used to send the CAS to the CPE and implement one-way ADSI data transfer. To transfer ADSI FSK data, the function parameters and structures must be configured as follows: • set the wType parameter DT_ADSI • configure the DX_IOTT structure with the appropriate ADSI FSK data file(s). The application is responsible for constructing the messages and checksums for each transmission • set the termination conditions with the DV_TPT structure • set dwTxDataMode within the ADSI_XFERSTRUC referenced by lpParams to ADSI_ALERT to generate the CAS The following scenario illustrates the function calls that are required to generate an initial CAS to the CPE and begin one-way ADSI data transfer. 1. Prior to executing dx_TxIottData( ), the digit buffer for the desired voice channel is cleared using the dx_clrdigbuf( ) function. 2. The dx_TxIottData( ) function is issued. To generate an initial CAS to the CPE device, dwTxDataMode within ADSI_XFERSTRUC must be set to ADSI_ALERT. 3. The CAS is received by the CPE and the CPE sends an acknowledgment digit (DTMF ‘A’) to the voice device. Note: If the DTMF acknowledgment digit is not received from the CPE device within 500 ms following the end of the CAS, the function will return a 0 but the termination mask returned by ATDX_TERMMSK( ) will be TM_MAXTIME to indicate an ADSI protocol error. (The function will return a -1 if a failure is due to a general transmission error.) 4. Upon receipt of the DTMF ‘A’ ACK, the voice device automatically transmits the data file referenced in the DX_IOTT structure. 5. After receiving the data file(s), the CPE responds with a DTMF ACK or NAK, indicating the number of messages successfully received. (The application is responsible for determining whether the message count acknowledgment matches the number of messages that were transmitted and for re-transmitting any messages.) Note: Upon successful completion, the function terminates with a TM_EOD (end of data) termination mask returned by ATDX_TERMMSK( ). Voice API for Windows Operating Systems Programming Guide — November 2002 111 Send and Receive FSK Data 6. After completion of dx_TxIottData( ), the dx_getdig( ) function retrieves the DTMF ACK sequence from the CPE device. Set the DV_TPT tp_termno field to DX_DIGTYPE to receive the DTMF string "adx," where "x" is the message count acknowledgment digit (1-5). After the CAS is sent to the CPE, as described in the preceding scenario, the CPE is in data mode. Provided that the ADSI messages sent to the CPE instruct the CPE to remain in data mode, subsequent ADSI transmissions to the CPE do not require the CAS. To send ADSI data without the CAS, set the dwTxDataMode within the ADSI_XFERSTRUC referenced by lpParams to ADSI_NOALERT. All other settings are the same as above. The following scenario illustrates the function calls that are required to transfer ADSI data when the CPE is already in data mode (without sending a CAS). 1. Prior to executing dx_TxIottData( ), the dx_clrdigbuf( ) function is issued to ensure the voice channel digit buffer is empty. 2. The dx_TxIottData( ) function is issued with dwTxDataMode within the ADSI_XFERSTRUC set to ADSI_NOALERT. This initiates the immediate transfer of the data file(s) referenced in the DX_IOTT structure to the CPE device. 3. After receiving the data file(s), the CPE responds with a DTMF ACK or NAK, indicating the number of messages successfully received. (The application is responsible for determining whether the message count acknowledgment matches the number of messages that were transmitted and for re-transmitting any messages.) 4. After completion of dx_TxIottData( ), the dx_getdig( ) function retrieves the DTMF ACK sequence from the CPE device. Set the DV_TPT tp_termno field to DX_DIGTYPE to receive the DTMF string "adx," where "x" is the message count acknowledgment digit (1-5). 10.7.3 Technical Overview of Two-Way ADSI Data Transfer In two-way ADSI data transfer, both the ADSI server and CPE device can transmit and receive ADSI data messages. The CAS is used to initiate the transfer of ADSI FSK data and to return the CPE to voice mode after the data exchange is completed. The transactions that occur between the server and the CPE in two-way ADSI data transfer are as follows: 1. The server initiates the data transfer by sending a CPE Alerting Signal (CAS) to the CPE equipment. 2. Upon receipt of the CAS, the CPE device generates an ACK (DTMF ‘A’ signal) to the server. At this point the CPE device has switched from voice mode to data mode. (Once the CPE device is in data mode, subsequent FSK data transmissions do not require the CAS.) Note: Only ADSI-compliant CPE devices will respond to the CAS sent by the server. Check with your manufacturer to verify that your CPE device is a true ADSI-compliant device. ADSI-compliant devices are also referred to as "Type 3 CPE Devices" by Bellcore. 3. When the ACK signal is received, the server initiates the FSK transmission sequence. Each FSK transmission sequence can contain anywhere from 1 to 5 messages. A "Switch to Peripheral Mode" message (using 0x0A as a ‘requested peripheral’ code) must be included within the FSK transmission sequence. 112 Voice API for Windows Operating Systems Programming Guide — November 2002 Send and Receive FSK Data 4. The CPE receives the FSK data and uses the checksum included within the sequence to determine the number of messages successfully received. 5. The CPE device then responds to the server with a DTMF ‘D’ followed by a DTMF ‘0’ through ‘5’ to indicate the number of messages successfully received. In addition, the CPE device acknowledges the "Switch to Peripheral Mode" message by responding with either • DTMF ‘B,’ indicating that the requested peripheral is available and on line • DTMF ‘A,’ indicating that the requested peripheral is not available 6. The server interprets the DTMF signals as follows: • ‘D’ followed by a DTMF in the range of 1 – 5 = ACK • ‘D’ followed by a DTMF ‘0’ = NAK • DTMF ‘B’ = requested peripheral available (ready to receive and transmit ADSI data) • DTMF ‘A’ = requested peripheral unavailable (unable to transmit or receive ADSI data) Once the CPE device has acknowledged the "Switch to Peripheral Mode" message, the CPE may transmit data to the server at any time. The server must be prepared to receive data at any time until the CPE peripheral is switched back to voice mode. To return the CPE peripheral to voice mode, the server sends a CAS to the CPE. Upon receipt of the CAS, the CPE responds with a DTMF ‘A’ signal. Receipt of DTMF ‘A’ at the server completes the return to voice mode transition. 10.7.4 Implementing Two-Way ADSI Using dx_TxIottData( ) The dx_TxIottData( ) function is used to implement two-way ADSI data transfer. The dx_TxIottData( ) function transmits the CAS and the subsequent "Switch to Peripheral Mode Message" to the CPE. To transfer ADSI FSK data, set the parameters and configure the structures as described below: • Set the wType parameter DT_ADSI. • Configure the DX_IOTT structure with the appropriate ADSI FSK data file(s), including the "Switch to Peripheral Mode" message. The application is responsible for constructing the messages and checksums for each transmission. • Set the termination conditions with the DV_TPT structure. • Set dwTxDataMode within the ADSI_XFERSTRUC referenced by lpParams to ADSI_ALERT to generate the CAS. The following scenario illustrates the function calls that are required to generate an initial CAS to the CPE and begin two-way ADSI data transfer. 1. Prior to executing dx_TxIottData( ), the digit buffer for the desired voice channel is cleared using the dx_clrdigbuf( ) function. 2. The dx_TxIottData( ) function is issued. To generate an initial CAS to the CPE device, dwTxDataMode within ADSI_XFERSTRUC must be set to ADSI_ALERT. 3. The CAS is received by the CPE and the CPE sends an acknowledgment digit (DTMF ‘A’) to the voice device. Voice API for Windows Operating Systems Programming Guide — November 2002 113 Send and Receive FSK Data Note: If the DTMF acknowledgment digit is not received from the CPE device within 500 ms following the end of the CAS, the function will return a 0 but the termination mask returned by ATDX_TERMMSK( ) will be TM_MAXTIME to indicate an ADSI protocol error. (The function will return a -1 if a failure is due to a general transmission error.) 4. Upon receipt of the DTMF ‘A’ ACK, the voice device automatically transmits the data file referenced in the DX_IOTT structure, which must include the "Switch to Peripheral Mode" message. 5. After receiving the data file(s), the CPE responds with a DTMF ACK or NAK, indicating the number of messages successfully received. (The application is responsible for determining whether the message count acknowledgment matches the number of messages that were transmitted and for re-transmitting any messages.) Note: Upon successful completion, the function terminates with a TM_EOD (end of data) termination mask returned by ATDX_TERMMSK( ). 6. The CPE responds to the "Switch to Peripheral Mode" message with either DTMF ‘B’ if the peripheral is available or DTMF ‘A’ if the peripheral is unavailable. 7. After completion of dx_TxIottData( ), the dx_getdig( ) function retrieves the DTMF ACK sequence from the CPE device. Set the DV_TPT tp_termno parameter to DX_DIGTYPE to receive the DTMF string "adxb," where "x" is the message count acknowledgment digit (1-5). When the DTMF string is received, additional messages can be sent and received between the server and the CPE peripheral. 10.7.5 Implementing Two-Way ADSI Using dx_TxRxIottData( ) After the two-way ADSI transmission is implemented using the dx_TxIottData( ) function, additional ADSI FSK messages are typically sent to the CPE peripheral to configure the display and soft keys. Since at this point the CPE peripheral has been configured to send data to the server, the dx_TxRxIottData( ) function should be used to send the data to the CPE and then quickly turnaround and be ready to receive data from the CPE. To transfer ADSI FSK data using dx_TxRxIottData( ), set the function parameters and configure the structures as described below: • Set wType to DT_ADSI. • Configure DX_IOTT structures referenced by lpTxIott and lpRxIott with the appropriate ADSI FSK data files. The application is responsible for constructing the messages and checksums for each transmission. • Set the termination conditions for the transmit and receive portions of the function with the DV_TPT structures referenced by lpTxTerminations and lpRxTerminations, respectively. • Set dwTxDataMode and dwRxDataMode within the ADSI_XFERSTRUC referenced by lpParams to ADSI_NOALERT to transmit and receive FSK ADSI data without generation of a CAS. The following scenario illustrates the function calls that are required to send and receive FSK ADSI data between the server and the CPE. 1. Prior to executing dx_TxIottData( ), the digit buffer for the desired voice channel is cleared using the dx_clrdigbuf( ) function. 114 Voice API for Windows Operating Systems Programming Guide — November 2002 Send and Receive FSK Data 2. The dx_TxRxIottData( ) function is issued with dwTxDataMode and dwRxDataMode within ADSI_XFERSTRUC set to ADSI_NOALERT. This initiates the transmission of the data file referenced in the DX_IOTT structure to the CPE. The server voice channel is placed automatically in FSK ADSI data receive mode to receive data from the CPE. 3. After receiving the data file(s), the CPE responds with a DTMF ACK or NAK, indicating the number of messages successfully received. (The application is responsible for determining whether the message count acknowledgment matches the number of messages that were transmitted and for re-transmitting any messages.) 4. The server voice channel is ready and waiting for data from the CPE. 5. The CPE sends FSK ADSI data to the server. When an ADSI FSK message is successfully received or when the termination conditions set in lpRxTerminations are met, the dx_TxRxIottData( ) function completes. 6. After completion of dx_TxRxIottData( ), the dx_getdig( ) function retrieves the DTMF ACK sequence for the transmit portion of the function. When the DTMF string is received, additional messages can be sent and received between the server and the CPE peripheral. 7. In another thread of execution at the server, the received message(s) are processed by the application to determine the number of messages received and the integrity of the information. 8. The dx_RxIottData( ) function is issued to receive messages from the CPE. This function should be issued as soon as possible because the CPE peripheral can send data to the server after a minimum of 100 msec following the completion of its transmission. If data needs to be transmitted to the CPE when the server is waiting to receive data, issue dx_stopch( ) to terminate the current dx_RxIottData( ) function. Upon confirmation of termination of dx_RxIottData( ), issue dx_clrdigbuf( ) to clear the voice device channel buffer, and then issue dx_TxIottData( ) to send the data to the CPE. 10.8 Modifying Older One-Way ADSI Applications Prior to the release of the two-way ADSI, including two-way FSK, applications used the dx_play( ) function to implement one-way ADSI applications. With two-way ADSI, transmit and receive data functions are introduced for data transfer. To take advantage of on-hook ADSI transfer in a one-way ADSI application, and/or to introduce two-way FSK concepts into applications, older applications need to be modified. Applications developed prior to the release of the two-way ADSI use the following sequence of commands to generate a CAS tone followed by transmission of an ADSI file: /* Setup DX_IOTT to play from disk */ /* Setup DV_TPT for termination conditions */ /* Initiate ADSI play when DTMF ‘A’ is received from CPE */ parmval = DM_A; if (dx_setparm(Voice_Device, DXCH_DTINITSET, (void *)&parmval) == -1) { /* Process error */ } /* Clear digit buffer for impending ADSI protocol DTMFs */ if (dx_clrdigbuf(Voice_Device) == -1) { /* Process error */ } Voice API for Windows Operating Systems Programming Guide — November 2002 115 Send and Receive FSK Data /* Send CAS followed by ADSI data when DTMF ‘A’ is received */ if (dx_play(Voice_Device, &Iott_struct, &Tpt_struct, EV_SYNC | PM_ADSIALERT) == -1) { /* Process error */ } In older applications, the use of dx_play( ) for ADSI transmission can be replaced with the specialized dx_TxIottData( ) data transfer function. The same DV_TPT and DX_IOTT are used by dx_TxIottData( ) as for dx_play( ), however, the following additional parameters need to be configured: wType specifies the data type transferred. To transfer ADSI FSK data, wType is set to DT_ADSI lpParams specifies the data type specific information. To transmit CAS followed by the ADSI FSK message, dwTxDataMode within the ADSI_XFERSTRUC data structure pointed to by lpParams is set to ADSI_ALERT. Using these parameters, the CAS will be transmitted and, upon receipt of DTMF ‘A,’ the ADSI FSK data will be sent to the CPE device. The following sample code illustrates the use of the dx_TxIottData( ) function to generate a CAS tone and transmit an ADSI file: /* Setup DX_IOTT to play from disk */ /* Setup DV_TPT for termination conditions */ /* Setup ADSI_XFERSTRUC to send CAS followed by ADSI FSK upon receipt of DTMF ‘A’ */ adsimode.cbSize = sizeof(adsimode); adsimode.dwTxDataMode = ADSI_ALERT; /* Clear digit buffer for impending ADSI protocol DTMFs */ if (dx_clrdigbuf(Voice_Device) == -1) { /* Process error */ } /* Send CAS followed by ADSI data when DTMF ‘A’ is received */ if (dx_TxIottData(Voice_Device, &IOTT, &TPT, DT_ADSI, &adsimode, EV_SYNC) == -1) { /* Process error */ } 116 Voice API for Windows Operating Systems Programming Guide — November 2002 Caller ID 11. 11 This chapter provides information on caller ID: • Overview of Caller ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 • Caller ID Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 • Accessing Caller ID Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 • Enabling Channels to Use the Caller ID Feature. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 • Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 • Caller ID Technical Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 11.1 Overview of Caller ID Caller Identification (caller ID) is a service provided by local telephone companies to enable the subscriber to receive the caller’s phone number (directory number or DN) and other information about the call. The caller ID information is transmitted using FSK (frequency shift keying) to the subscriber from the service provider (telephone company Central Office) at 1200 baud. Caution: The information in this chapter applies to caller ID on Springware boards. Caller ID on DM3 boards is available via the Global Call API. For more information, see the Global Call Technology User’s Guide for your technology. An application can enable the caller ID feature on specific channels to process caller ID information as it is received with an incoming call. Caller ID information can include the calling party’s directory number (DN), the date and time of the call, and the calling party’s subscriber name. The functions and data structures associated with caller ID are described in the Voice API Library Reference. Note: 11.2 If caller ID is enabled, on-hook detection (DTMF, MF, and global tone detection) will not function. Caller ID Formats The following caller ID formats are supported: CLASS (Custom Local Area Signaling Services) a set of standards published by Bellcore (now known as Telcordia Technologies) and supported on boards with loop-start capabilities in the following formats: • Single Data Message (SDM) format • Multiple Data Message (MDM) format Voice API for Windows Operating Systems Programming Guide — November 2002 117 Caller ID ACLIP (Analog Calling Line Identity Presentation) a standard used in Singapore published by the Telecommunications Authority of Singapore and supported in the following formats: • Single Data Message (SDM) format • Multiple Data Message (MDM) format CLIP (Calling Line Identity Presentation) a standard used in the United Kingdom published by British Telecommunications (BT) JCLIP (Japanese Calling Line Identity Presentation) a standard for "Number Display" used in Japan published by Nippon Telegraph and Telephone Corporation (NTT). Note: JCLIP operation requires that the Japanese country-specific parameter file be installed and configured (select Japan in the Dialogic country configuration). Caller ID information is received from the Central Office (CO) between the first and second ring for CLASS and ACLIP, and before the first ring for CLIP. This information is supported as sent by the service provider in the format types described in Table 12. Table 12. Supported CLASS Caller ID Information Caller ID Information CLASS and ACLIP CLIP JCLIP SDM * MDM ** MDM ** Frame header (indicating SDM or MDM format type) X X X Calling line’s Directory Number (DN) X X X Date X X X Time X X X Calling line’s subscriber name X X Calling line’s DN (digits only) X X Dialed directory number (digits only) X X X Reason why caller DN is not available X X X Reason why calling subscriber name is not available X X X Indicate if the call is forwarded X Indicate if the call is “long distance” X Type of call (such as voice, ringback when free, message waiting call) X Network Message System status (number of messages waiting) X X * Single Data Message ** Multiple Data Message Note: 118 One or more of the caller ID features listed above may not be available from your service provider. Contact your service provider to determine the caller ID options available from your CO. Voice API for Windows Operating Systems Programming Guide — November 2002 Caller ID 11.3 Accessing Caller ID Information You can process caller ID information in your application in the following ways: • For CLASS or ACLIP, the caller ID information is received from the service provider between the first and second ring. Set the ring event in the application to occur on or after the second ring. The ring event indicates reception of the CLASS or ACLIP caller ID information from the CO. • For CLIP or JCLIP, the caller ID information is received from the service provider before the first ring. Set the ring event in the application to occur on or after the first ring. The ring event indicates reception of the CLIP caller ID information from the CO. The caller ID information is available for the call from the moment the ring event is generated (if the ring event is set in your application as stated above) until one of the following occurs: • If the call is answered (application channel goes off-hook), the caller ID information is available until the call is disconnected (application channel goes on-hook). • If the call is unanswered (application channel remains on-hook), caller ID information is available until rings are no longer received from the CO (signaled by ring event, if enabled). Notes: 1. If the call is answered before the caller ID information has been received from the CO, caller ID information will not be available to the application. 2. If the application remains on-hook and the ring event is received before the caller ID information has been received from the CO, caller ID information will not be available until the beginning of the second ring. The following voice API functions are used to access caller ID information received from the CO. These functions are not supported on DM3 boards: dx_gtcallid( ) Returns the calling line Directory Number (DN). Issue this function for applications that require only the calling line DN. dx_gtextcallid( ) Returns the requested caller ID message. Issue this function for each type of caller ID message required. dx_wtcallid( ) Waits for a specified number of rings and returns the calling station’s DN. This convenience function combines the functionality of the dx_setevtmsk( ), dx_getevt( ), and dx_gtcallid( ) functions. Contact your service provider to determine the caller ID options available from your CO. Based on the options provided, you can determine which caller ID function best meets the application’s needs. To determine if caller ID information has been received from the CO, before issuing a dx_gtcallid( ) or dx_gtextcallid( ), check the event data in the DX_EBLK event block structure. When the ring event is received (set by the application as stated above), the event data field in the event block is bit mapped and indicates that caller ID information is available when bit 0 (LSB) is set to 1 (see the function code examples in the Voice API Library Reference). Voice API for Windows Operating Systems Programming Guide — November 2002 119 Caller ID 11.4 Enabling Channels to Use the Caller ID Feature During Intel Dialogic System Service startup, before the initial use of caller ID functions, the application must enable the caller ID feature on the channels requiring caller ID. On Springware boards, caller ID is enabled by setting the DXCH_CALLID channel-based parameter to DX_CALLIDENABLE using dx_setparm( ). The default setting is caller ID disabled, DX_CALLIDDISABLE. Caller ID on DM3 boards is available via the Global Call API. For more information, see the Global Call Technology User’s Guide for your technology. 11.5 Error Handling When the caller ID function completes, check the return code: • If the caller ID function completes successfully, the buffer will contain the caller ID information. • If the caller ID function fails, an error code will be returned that indicates the reason for the error. The call is still active when the error is returned. When using the dx_gtextcallid( ) function, error codes depend upon the Message Type ID argument (infotype) passed to the function. All Message Types can produce an EDX_CLIDINFO error. Message Type CLIDINFO_CALLID can also produce EDX_CLIDOOA and EDX_CLIDBLK errors. When using the dx_gtcallid( ) caller ID function, if an error is returned indicating that the caller’s phone number (DN) is blocked or out of area, other information (for example, date or time) may be available by issuing the dx_gtextcallid( ) caller ID function. The information that is available, other than the caller’s phone number, is determined by the CO. 11.6 Caller ID Technical Specifications For information about caller ID technical specifications, contact the appropriate authority and request the technical references you require: CLASS CLASS documents are published by Telcordia Technologies (previously Bellcore). To obtain a copy of these technical references, call 1-800-521-2673 (from the U.S. and Canada) or +1732-699-5800 (worldwide), or visit http://www.telcordia.com. Note that Bellcore is now known as Telcordia Technologies. • TR-NWT-000031 (issue 4) CLASS Feature Calling Number Delivery • TR-NWT-001188 CLASS Feature Calling Name Delivery Generic Requirements • TR-NWT-000030 (issue 2) Voice Data Transmission Interface Generic Requirement ACLIP Contact the Telecommunications Authority of Singapore and Telcordia Technologies. • TAS TS PSTN1 A-CLIP: 1994 120 Voice API for Windows Operating Systems Programming Guide — November 2002 Caller ID • Bellcore specification TR-NWT-000030 (see Telcordia Technologies contact info provided in CLASS) CLIP Contact British Telecommunications. • SIN (Supplier Information Note) 242 (issue 01) • SIN (Supplier Information Note) 227 (issue 01) JCLIP Contact Nippon Telegraph and Telephone Corporation. • Telephone Service Interfaces, Edition 5, Technical Reference Voice API for Windows Operating Systems Programming Guide — November 2002 121 Caller ID 122 Voice API for Windows Operating Systems Programming Guide — November 2002 Cached Prompt Management 12. 12 This chapter discusses the cached prompt management feature of the voice library. The following topics are covered: • Overview of Cached Prompt Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 • Using Cached Prompt Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 • Cached Prompt Management Example Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 12.1 Overview of Cached Prompt Management Cached prompt management is a feature that allows you to store a prompt file in the on-board memory and subsequently retrieve it from this location rather than storing and retrieving from the host computer. An advantage of this feature is that it reduces latency. Cached prompt management is active on a board basis. A cached prompt cannot be restored to a board that has been hot swapped. A cached prompt that is created on one board is not accessible and cannot be used by other boards in the system. In addition, WAVE files cannot be played from on-board cache memory. 12.2 Using Cached Prompt Management The following topics provide information on how to use cached prompt management: • Discovering Cached Prompt Capability • Downloading Cached Prompts to a Board • Playing Cached Prompts • Recovering from Errors • Cached Prompt Management Hints and Tips 12.2.1 Discovering Cached Prompt Capability To determine whether a device has cached prompt capability, follow these steps: 1. Call SRLGetAllPhysicalBoards( ) to return the AUID of all the boards in the system. AUID refers to Addressable Unique Identifier and is an opaque identifier for an important object in the system. For information on this function, see the Standard Runtime Library API Library Reference. 2. Call SRLGetPhysicalBoardName( ) to return the board name, which is in the form brdBn, such as brdB1. This function is passed the AUID of the board from step 1. For information on this function, see the Standard Runtime Library API Library Reference. Voice API for Windows Operating Systems Programming Guide — November 2002 123 Cached Prompt Management 3. Call dx_open( ) with brdBn as the device name and get a handle to the physical board device. 4. Use the physical board handle from step 3 in a call to dx_play( ) with IO_CACHED specified in the DX_IOTT structure, or in a call to dx_getcachesize( ). If cached prompt capability is not supported, the device will return EDX_BADPROD error. For a description of these functions, see the Voice API Library Reference. 12.2.2 Downloading Cached Prompts to a Board Perform the procedure for downloading a cached prompt to a board at the start of the application or reinitialization of the board, or periodically during runtime. The steps are as follows: 1. Use dx_getcachesize( ) to determine the total size of memory available on the board or alternatively the remaining size of cache available for cached prompts. 2. Use dx_fileopen( ) to open the file to be cached. 3. After determining that enough memory is available, use dx_cacheprompt( ) to commit the file to memory. For a description of these functions, see the Voice API Library Reference. 12.2.3 Playing Cached Prompts Call dx_play( ) or dx_playiottdata( ) using the brdBn physical board handle to play the prompt. If running in asynchronous mode, the TDX_CACHEPROMPT event indicates termination of the play function. If playing multiple prompts from different sources, see the example code in Section 12.3, “Cached Prompt Management Example Code”, on page 125 for more information. 12.2.4 Recovering from Errors The following are some errors that may occur while loading a cached prompt: • If you specify an invalid board handle, this produces EDX_BADPARM. To avoid this situation, be sure to specify a valid board handle in the form brdBn. • If there is an error in specifying the data source (DX_IOTT), this produces EDX_BADIOTT. To troubleshoot this error, check the DX_IOTT structure. • If the combined length of data specified in the series of DX_IOTT data structures exceeds the available on-board memory, this results in the EDX_NOTENOUGHBRDMEM error. If this error occurs, none of the series of DX_IOTT is downloaded to the board. To avoid this situation, be sure to determine that there is sufficient on-board memory available for the cached prompt using dx_getcachesize( ) before issuing a play function. • For any other reason (including firmware) if the prompt cannot be downloaded, then EDX_SYSTEM is generated. If ATDV_LASTERR( ) returns EDX_SYSTEM error, call dx_fileerrno( ) to obtain the error value. 124 Voice API for Windows Operating Systems Programming Guide — November 2002 Cached Prompt Management The following are some errors that may occur while playing a cached prompt: • If you specify an invalid cached prompt handle, this results in EDX_BADIOTT. • If you specify an invalid board handle, this results in EDX_BADPARM. • If there is an error in the underlying components (such as firmware) while playing a cached prompt, then EDX_SYSTEM is generated. 12.2.5 Cached Prompt Management Hints and Tips This section provides hints and tips on using cached prompt management. There is no API function for deleting a cached prompt from on-board memory. Instead, you can stop the board and re-start it to flush the prompts from the cache. Unlike disk or host memory resident prompts, cached prompts on an individual board are lost when a board is hot swapped. Since the application is aware of board insertion and removal through the Operations, Administration, and Maintenance (OA&M) API, it is responsible for re-initiating the cached prompt download sequence when the BRD_APP_RDY event is received through the event service. The following rules govern the application’s treatment of cached prompts during hot swap operations. • Upon a hot swap removal, the application must consider all cached prompt IDs and also the physical board handle for the board to be invalid. Play operations to the board will fail. • Upon a hot swap insertion, the application must re-download the cached prompts for the new board. For more information on the OA&M API, see the OA&M API Library Reference and OA&M API Programming Guide. 12.3 Cached Prompt Management Example Code This example code illustrates one way to implement cached prompt management in your application. It uses the following key steps, as indicated in the comments: 1. Get the AUIDs of all physical boards in the system. 2. Get the names of all physical boards for the corresponding AUIDs. 3. Open all physical board devices. 4. Download cached prompts to a board, after verifying that total available cache memory is greater than total file size. 5. Play back any combination of files from multiple sources. 6. Shut down, free allocated memory, and close all opened devices. The example code is provided next. //Pseudo Application for Cached Prompts Voice API for Windows Operating Systems Programming Guide — November 2002 125 Cached Prompt Management #include "srllib.h" #include "dxxxlib.h" #include "malloc.h" //Sytem Initialization //Step 1 Get the AUID’s of all the Physical Boards in the system AUID *pAU; int iNumPhyBds; long retVal; iNumPhyBds = 0; pAU = 0; do { free(pAU); pAU = iNumPhyBds ? (AUID *)malloc(iNumPhyBds * sizeof(*pAU)) : 0; retVal = SRLGetAllPhysicalBoards(&iNumPhyBds, pAU); } while (ESR_INSUFBUF == retVal); if (ESR_NOERR != retVal) { // do some error handling ... } //Step 2 get all the names of the physical boards for the corresponding AUID’s and Step 3 - open all the physical boards int brdstrlen = 7;//say "brdB1" char * szBoardName; szBoardName = (char *) malloc (iNumPhyBds * brdstrlen * sizeof(char)); int offset=0; int *devh; devh = (int *)malloc(iNumPhyBds * sizeof(int)); for (int i= 0; i < iNumPhyBds; i++) { offset = i * brdstrlen; //Get the name of the board pointed to by the nth AUID retval = SRLGetPhysicalBoardName(pAU[i], &brdstrlen, &szBoardName[offset]); devh[i] = dx_open(&szBoardName[offset],0); } //Step 4 Download the prompts to a board after determining available cache size int nCacheSize; int result; int promptHandle; /* Handle of the prompt to be downloaded */ int fd1; /* First file descriptor for file to be downloaded */ int fd2; /* Second file descriptor for file to be downloaded */ DX_IOTT iott[2]; /* I/O transfer table to download cache prompt */ int totalfilesize; result = dx_getcachesize(&devh[0], &nCacheSize, DX_CACHEREMAINING); fd1 = dx_fileopen("HELLO.VOX", O_RDONLY|O_BINARY, 0); fd2 = dx_fileopen("GREETINGS.VOX", O_RDONLY|O_BINARY, 0); totalfilesize = _lseek(fd1, 0L, SEEK_END); totalfilesize += _lseek(fd2, 0L, SEEK_END); if (nCacheSize > totalfilesize) { /* Set up DX_IOTT */ /*This block specifies the first data file */ iott[0].io_fhandle = fd1; iott[0].io_offset = 0; 126 Voice API for Windows Operating Systems Programming Guide — November 2002 Cached Prompt Management iott[0].io_length = -1; iott[0].io_type = IO_DEV | IO_CONT; /*This block specifies the second data file */ iott[1].io_fhandle = fd2; iott[1].io_offset = 0; iott[1].io_length = -1; iott[1].io_type = IO_DEV | IO_EOT /* Download the prompts to the on-board memory */ int promptHandle; int result = dx_cacheprompt(brdhdl, iott, &promptHandle, EV_SYNC); } //Step 4 can be carried out with different prompts as long as the total filesize is less the available nCacheSize. Also this can be extended to other boards in the system. //Step 5 Download any combination of files from multiple sources int fd; /* file descriptor for file to be played */ DX_IOTT iottplay[2]; /* I/O transfer table for the play operation*/ DV_TPT tpt; /* termination parameter table */ DX_XPB xpb; /* I/O transfer parameter block */ . . . /* Open channel */ if ((chdev = dx_open("dxxxB1C1",0)) == -1) { printf("Cannot open channel\n"); /* Perform system error processing */ exit(1); } /* Set to terminate play on 1 digit */ tpt.tp_type = IO_EOT; tpt.tp_termno = DX_MAXDTMF; tpt.tp_length = 1; tpt.tp_flags = TF_MAXDTMF; /* Open VOX file to play */ if ((fd = dx_fileopen("HELLO.VOX",O_RDONLY|O_BINARY)) == -1) { printf("File open error\n"); exit(2); } /* Set up DX_IOTT */ /*This block specifies a regular data file */ iottplay[0].io_fhandle = fd; iottplay[0].io_bufp = 0; iottplay[0].io_offset = 0; iottplay[0].io_length = -1; iottplay[0].io_type = IO_DEV | IO_CONT; /*This block specifies the downloaded cached prompt iottplay[1].io_type = IO_CACHED | IO_EOT iottplay[1].io_fhandle = promptHandle; iottplay[1].io_offset = 0; iottplay[1].io_length = -1; */ /* * Specify VOX file format for ADPCM at 8KHz */ xpb.wFileFormat = FILE_FORMAT_VOX; xpb.wDataFormat = DATA_FORMAT_DIALOGIC_ADPCM; xpb.nSamplesPerSec = DRT_8KHZ; xpb.wBitsPerSample = 4; Voice API for Windows Operating Systems Programming Guide — November 2002 127 Cached Prompt Management /* Start playback */ if (dx_playiottdata(chdev,iottplay,&tpt,&xpb,EV_SYNC)==-1) { printf("Error playing file - %s\n", ATDV_ERRMSGP(chdev)); exit(4); } . . . //Shutdown //free allocated memory //close opened devices dx_close(chdev); //loop and close all physical device handles dx_close(devh[n]); 128 Voice API for Windows Operating Systems Programming Guide — November 2002 Global Tone Detection and Generation, and Cadenced Tone Generation 13. 13 This chapter discusses global tone detection (GTD), global tone generation (GTG), and cadenced tone generation: • Global Tone Detection (GTD) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 • Global Tone Generation (GTG). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 • Cadenced Tone Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 13.1 Global Tone Detection (GTD) Global tone detection (GTD) is described in the following sections: • Overview of Global Tone Detection • Defining Global Tone Detection Tones • Building Tone Templates • Working with Tone Templates • Retrieving Tone Events • Setting GTD Tones as Termination Conditions • Maximum Amount of Memory Available for User-Defined Tone Templates • Estimating Memory • Guidelines for Creating User-Defined Tones • Global Tone Detection Applications 13.1.1 Overview of Global Tone Detection Global tone detection (GTD) allows you to define the characteristics of a tone in order to detect a tone with these same characteristics. The characteristics of a tone are defined using GTD tone templates. The tone templates contain parameters that allow you to assign frequency bounds and cadence components. GTD can detect single- and dual-frequency tones by comparing all incoming sounds to the GTD tone templates. Global tone detection and GTD tones are also known as user-defined tone detection and userdefined tones. Voice API for Windows Operating Systems Programming Guide — November 2002 129 Global Tone Detection and Generation, and Cadenced Tone Generation GTD operates on a channel-by-channel basis and is active when the channel is off-hook, unless the system uses a DTI/xxx board, in which case GTD is always active. GTD works simultaneously with DTMF and MF tone detection. The driver responds to a detected tone by producing either a tone event (DE_TONEON or DE_TONEOFF) on the event queue or a digit on the digit queue. The particular response depends upon the GTD tone configuration. Use the global tone detection functions to access tone templates and enable detection of single- and dual-frequency tones that fall outside of those automatically provided with the voice driver. This includes tones outside the standard DTMF set of 0-9, a-d, *, and #, and the standard MF tones 0-9, *, and a-c. 13.1.2 Defining Global Tone Detection Tones GTD tones can have an associated ASCII digit (and digit type) specified using the digit and digtype parameters in the dx_addtone( ) function. When the tone is detected, the digit is placed in the DV_DIGIT buffer and can be retrieved using the dx_getdig( ) function. When the tone is detected, either the tone event or the digit associated with the tone can be used as a termination condition to terminate I/O functions. Termination conditions are set using the DV_TPT data structure. To terminate on multiple tones (or digits), you must specify the terminating conditions for each tone in a separate DV_TPT data structure. The functions and data structures associated with global tone detection are described in the Voice API Library Reference. 13.1.3 Building Tone Templates When creating the tone template, you can define the following: • single-frequency or dual-frequency (300 - 3500 Hz) • optional ASCII digit associated with the tone template • cadence components Adding a tone template to a channel enables detection of a tone on that channel. Although only one tone template can be created at a time, multiple tone templates can be added to a channel. Each channel can have a different set of tone templates. Once created, tone templates can be selectively enabled or disabled. Note: 130 A particular tone template cannot be changed or deleted. A tone template can be disabled on a channel, but to delete a tone template, all tone templates on that channel must be deleted. Voice API for Windows Operating Systems Programming Guide — November 2002 Global Tone Detection and Generation, and Cadenced Tone Generation The following functions are used to build and define tone templates: dx_bldst( ) Defines a single-frequency tone. Subsequent calls to dx_addtone( ) will use this tone until another tone is defined. Thus, you can build a tone template and add it to several different channels. dx_blddt( ) Defines a simple dual-frequency tone. Subsequent calls to dx_addtone( ) will use this tone until another tone is defined. Thus, you can build a tone template and add it to several different channels. Note that DM3 boards cannnot detect dual tones with frequency components closer than approximately 125 Hz. Note that Springware boards cannot detect dual tones with frequency components closer than approximately 63 Hz. Use a single tone description to detect dual tones that are closer together than the ranges specified above. dx_bldstcad( ) Defines a simple single-frequency cadence tone. Subsequent calls to dx_addtone( ) will use this tone until another tone is defined. Thus, you can build a tone template and add it to several different channels. A single-frequency cadence tone has single-frequency signals with specific on/off characteristics. dx_blddtcad( ) Defines a simple dual-frequency cadence tone. Subsequent calls to dx_addtone( ) will use this tone until another tone is defined. Thus, you can build a tone template and add it to several different channels. A dual-frequency cadence tone has dual-frequency signals with specific on/off characteristics. The minimum on- and off-time for cadence detection is 40 msec on and 40 msec off. dx_setgtdamp( ) Sets the amplitudes used by GTD. The amplitudes set using dx_setgtdamp( ) will be the default amplitudes that will apply to all tones built using the dx_bld...( ) functions. The amplitudes will remain valid for all tones built until dx_setgtdamp( ) is called again and the amplitudes are changed. Notes: 1. GTD build functions define new tone templates, and dx_addtone( ) adds the tone templates to a channel. 2. Use dx_addtone( ) to enable detection of the tone template on a channel. 3. After building a tone template using a dx_bld...( ) function, dx_addtone( ) must be called to add this tone template to a channel. If the template is not added, the next call to a dx_bld...( ) function will overwrite the tone definition contained in the previous template. Table 13 lists some standard Bell System Network call progress tones. The frequencies are useful when creating the tone templates. Voice API for Windows Operating Systems Programming Guide — November 2002 131 Global Tone Detection and Generation, and Cadenced Tone Generation Table 13. Standard Bell System Network Call Progress Tones Tone 13.1.4 Frequency (Hz) On Time (msec) Off Time (msec) Dial 350 + 440 Continuous Busy 480 + 620 500 500 Congestion (Toll) 480 + 620 200 300 Reorder (Local) 480 + 620 300 200 Ringback 440 + 480 2000 4000 Working with Tone Templates Use the following functions to add/delete tone templates or to enable/disable tone detection: dx_addtone( ) Adds a tone template that was defined by the most recent GTD build-tone function call to the specified channel. Adding a tone template to a channel downloads it to the board and enables detection of tone-on and tone-off events for that tone template. dx_deltones( ) Removes all tone templates previously added to a channel with dx_addtone( ). If no tone templates were previously enabled for this channel, the function has no effect. dx_deltones( ) does not affect tones defined by build-tone template functions and tone templates not yet defined. If you have added tones for call progress analysis, these tones are also deleted. dx_distone( ) Disables the detection of DE_TONEON and/or DE_TONEOFF events on a channel. Detection capability for user-defined tones is enabled on a channel by default when dx_addtone( ) is called. dx_enbtone( ) Enables the detection of DE_TONEON and/or DE_TONEOFF events on a channel. Detection capability for tones is enabled on a channel by default when dx_addtone( ) is called. The function can re-enable tones disabled by dx_distone( ). DE_TONEON and DE_TONEOFF events are call status transition (CST) events. Caution: Each tone template must have a unique identification. Caution: Errors will occur if you use dx_addtone( ) to change a tone template that has previously been added. 13.1.5 Retrieving Tone Events Tone-on and tone-off events are call status transition (CST) events. Retrieval of these events is handled differently for asynchronous and synchronous applications. Table 14 outlines the different processes for retrieving tone events. 132 Voice API for Windows Operating Systems Programming Guide — November 2002 Global Tone Detection and Generation, and Cadenced Tone Generation Table 14. Asynchronous/Synchronous Tone Event Handling Synchronous Asynchronous Call dx_addtone( ) or dx_enbtone( ) to enable tone-on/off detection. Call dx_addtone( ) or dx_enbtone( ) to enable tone-on/off detection. Call dx_getevt( ) to wait for CST event(s). Events are returned in the DX_EBLK data structure. Use Standard Runtime Library (SRL) to asynchronously wait for TDX_CST event(s). N/A Use sr_getevtdatap( ) to retrieve DX_CST data structure. Note: These procedures are the same as the retrieval of any other CST event, except that dx_addtone( ) or dx_enbtone( ) are used to enable event detection instead of dx_setevtmsk( ). You can optionally specify an associated ASCII digit (and digit type) with the tone template. In this case, the tone template is treated like DTMF tones. When the digit is detected, it is placed in the digit buffer and can be used for termination. When an associated ASCII digit is specified, tone events will not be generated for that tone. 13.1.6 Setting GTD Tones as Termination Conditions To detect a GTD (user-defined) tone, you can specify it as a termination condition for I/O functions. Set the tp_termno field in the DV_TPT structure to DX_TONE, and specify DX_TONEON or DX_TONEOFF in the tp_data field. 13.1.7 Maximum Amount of Memory Available for User-Defined Tone Templates Guidelines for the maximum amount of memory available for user-defined tone templates on voice and voice/fax boards are given in this section. Table 15 gives the maximum amount of memory available for user-defined tone templates on boards. The numbers in this table represent the number of memory blocks available to the user after all predefined tones and their indices have been allocated. Predefined tones include DTMFs. A single memory block may hold either a single tone template or a set of indices. Table 16 shows the maximum memory available for tone templates for each tone-creating voice feature. Voice API for Windows Operating Systems Programming Guide — November 2002 133 Global Tone Detection and Generation, and Cadenced Tone Generation Table 15. Maximum Memory Available for User-Defined Tone Templates Memory Blocks Available Hardware Per Board Per Channel D/21D D/21H 142 71 D/41D D/41H D/41ESC D/41EPCI D41JCT/ D/42-NS DIALOG/4 142 35 D/80SC 284 35 D/160SC D/160SC-LS D/240PCI-T1 D/240SC D/240SC-T1 D/240SC-2T1 D240JCT D/300PCI-E1 D/300PSC-E1 D/300SC-E1 D/300SC-2E1 D/300JCT D/320SC D/480SC-2T1 D/480JCT D/600SC-2E1 D/600JCT D/640SC 510 for each group of 16 channels 31 VFX/40ESC VFX/40ESCplus VFX/41JCT 142 35 Table 16. Maximum Memory Available for Tone Templates for Tone-Creating Voice Features Feature 134 Memory Blocks Available per Channel SIT: 1 Tone 2 SIT: 3 Tones 5 CPA (PerfectCall) 17 R2/MF 17 Socotel 19 User Defined See Section 13.1.8, “Estimating Memory”, on page 135. Voice API for Windows Operating Systems Programming Guide — November 2002 Global Tone Detection and Generation, and Cadenced Tone Generation 13.1.8 Estimating Memory Refer to the following guidelines to estimate the memory used for each tone on each channel. Calculate the total frequency range covered by the tone. For single tones, this is twice the deviation (unless the range is truncated by the GTD detection range); for dual tones, this is twice the deviation of each of the two tones minus any overlap (and minus any truncation by the GTD detection range). For example: • Single Tone: 400 Hz (125 Hz deviation) = bandwidth of 275 to 525 Hz, total of 250Hz. • Dual Tone: 450 Hz (50 Hz deviation) and 1000 Hz (75 Hz deviation) = bandwidth of 400 to 500 Hz and 925 to 1075 Hz, total of 250Hz. • Dual Tone: 450 Hz (100 Hz deviation) and 600 Hz (100 Hz deviation) = bandwidth of 350 to 550 Hz and 500 to 700 Hz; eliminating overlap, total range = 350 to 700 Hz, total of 350 Hz. Each tone costs, on average, 1 + round up [1/16 * round up (total frequency range /62.5)]. This allows for: • 1 memory block for the actual template • 1/16 portion of a memory block for an index entry • range/62.5 multiple indexing for speed In practice, the 1/16 should be added across tones that have frequency overlap, rather than rounded up for each tone. Note: 13.1.9 The firmware will often use memory more efficiently than described by the guidelines given above. These guidelines estimate the maximum memory usage for user-defined tones; the actual usage may be lower. Guidelines for Creating User-Defined Tones When creating user-defined tones, keep the following guidelines in mind: Note: The terms “user-defined tones” and “tone templates” are used interchangeably. Each tone template specifies the characteristics of one user-defined tone. • The maximum number of tone templates is based on tone templates that define a dual tone with a frequency range (bandwidth) of 62 Hz. (The detection range is the difference between the minimum and maximum defined frequencies for the tone.) • The tone detection range should be limited to a maximum of 200 Hz per tone to reduce the chance of exceeding the available memory. • On DM3 boards, the number of tone templates which can be added to a voice device and enabled for detection is limited. The default maximum number of events for each instance is 20. This number can be increased using the SD_ParmMaxSigsPerInst parameter. By Voice API for Windows Operating Systems Programming Guide — November 2002 135 Global Tone Detection and Generation, and Cadenced Tone Generation increasing this number, the memory usage will increase. For more information on this parameter, see the Configuration Guide for your product family. Also, for single tone definition and dual tone definition, the frequency deviation that is defined in the tone template for each frequency must be no less than +/- 30 Hz. • If you use call progress analysis to detect the different call progress signals (dial tone, busy tone, ringback tone, fax or modem tone), call progress analysis creates GTD tones. This reduces the number of user-defined tones you can create. Call progress analysis creates 8 GTD tones; this uses 17 memory blocks on each channel on which it is activated. • If you use call progress analysis to identify tri-tone special information tone (SIT) sequences, call progress analysis will create GTD tones internally, and this reduces the number of userdefined tones you can create. Call progress analysis creates one GTD tone (or tone template) for each single-frequency tone that you define in the DX_CAP structure. For example, if detecting the SIT tri-tone sequences per channel (3 frequencies), the GTD memory will be reduced by five blocks. • If you initiate call progress analysis and there is not enough memory to create the GTD tones, you will get an EDX_MAXTMPLT error. This indicates that you are trying to exceed the maximum number of GTD tones. • If you use dx_blddt( ) (or one of the dx_bld...( ) build-tone functions) or r2_creatfsig( ) to define a user-defined tone that alone or with existing user-defined tones exceeds the available memory, you will get an EDX_MAXTMPLT error. • The dx_deltones( ) function deletes all user-defined tones from a specified channel and releases the memory that was used for those user-defined tones. When an associated ASCII digit is specified, tone events will not be generated for that tone. • If you initiate call progress analysis and there is not enough memory to create the SIT tones internally, you will get a CR_MEMERR. • If you create R2/MF user-defined tones using r2_creatfsig( ), the voice boards will usually be able to create all 15 R2/MF user-defined tones due to the overlap in frequencies for the R2/MF signals. If these boards do not have sufficient memory, they may be able to support R2/MF signaling through a reduced number of R2/MF user-defined tones. The r2_creatfsig( ) function is not supported on DM3 boards. See Table 15, “Maximum Memory Available for User-Defined Tone Templates”, on page 134, Table 16, “Maximum Memory Available for Tone Templates for Tone-Creating Voice Features”, on page 134, and Table 17, “Maximum Memory and Tone Templates (for Dual Tones)”, on page 137 for more guidelines on tone templates. 136 Voice API for Windows Operating Systems Programming Guide — November 2002 Global Tone Detection and Generation, and Cadenced Tone Generation Table 17. Maximum Memory and Tone Templates (for Dual Tones) Tone Templates Per Board Tone Templates Per Channel D/21D 33 16 D/4xD 33 8 D/21E 33 16 D/41E 33 8 D/41ESC 33 8 D/41JCT 33 8 D/81A 100 12 D/121A 166 13 D/121B 166 13 D/160SC-LS 240 15 D/240SC 300 15 D/240SC-T1 300 15 D/240JCT 300 15 D/300SC-E1 450 15 D/300JCT 450 15 D/320SC 450 15 DTI/240SC 300 15 DTI/241SC 300 15 DTI/300SC 450 15 DTI/301SC 450 15 LSI/81SC 240 15 LSI/161SC 240 15 Hardware Voice API for Windows Operating Systems Programming Guide — November 2002 137 Global Tone Detection and Generation, and Cadenced Tone Generation 13.1.10 Global Tone Detection Applications Sample applications for global tone detection (GTD) are described in the following sections: • Detecting Disconnect Tone • Detecting Leading Edge Debounce Time 13.1.10.1 Detecting Disconnect Tone The information in this section does not apply to DM3 boards.Global tone detection can be used for disconnect tone supervision. When a telephone call terminates, the central office may send a momentary drop in loop current to signal the disconnect. In configurations where the voice board is connected to a Private Branch Exchange (PBX), it is likely that there will be no drop in loop current for the voice board to detect. Instead, the PBX may initiate a fast-busy signal to indicate the disconnect. Global tone detection can be used to detect this fast-busy signal. Perform the following to detect the signal: 1. Determine the frequencies of the signal. 2. Characterize the on/off durations and tolerances of the signal cadence. 3. Use a build-tone function to define the characteristics of a single or dual tone with cadence in a tone template. 4. Use the dx_addtone( ) function to add the GTD tone template for global tone detection on each channel. 13.1.10.2 Detecting Leading Edge Debounce Time Rather than detecting a signal immediately, an application may want to wait for a period of time (debounce time) before the DE_TONEON event is generated indicating the detection of the signal. The dx_bldstcad( ) and dx_blddtcad( ) functions can detect leading edge debounce on-time. A tone must be present at a given frequency and for a period of time (debounce time) before a DE_TONEON event is generated. The debounce time is specified using the ontime and ondev parameters in the dx_bldstcad( ) or dx_blddtcad( ) functions. To use this application, specify the following values for the dx_bldstcad( ) or dx_blddtcad( ) function parameters listed below: • For ontime, specify 1/2 of the desired debounce time • For ondev, specify -1/2 of the desired debounce time • For offtime, specify 0 • For offdev, specify 0 • For repcnt, specify 0 Note: 138 This application cannot work with the functions dx_blddt( ) and dx_bldst( ) since these functions do not have timing field parameters. Voice API for Windows Operating Systems Programming Guide — November 2002 Global Tone Detection and Generation, and Cadenced Tone Generation 13.2 Global Tone Generation (GTG) The following topics provide information on using global tone generation: • Using GTG • GTG Functions • Building and Implementing a Tone Generation Template 13.2.1 Using GTG Global tone generation enables the creation of user-defined tones. The tone generation template, TN_GEN, is used to define the tones with the following information: • Single or dual tone • Frequency fields • Amplitude for each frequency • Duration of tone The functions and data structures associated with global tone generation are described in the Voice API Library Reference. 13.2.2 GTG Functions The following functions are used to generate tones: dx_bldtngen( ) Builds a tone generation template. This convenience function sets up the tone generation template data structure (TN_GEN) by allowing the assignment of specified values to the appropriate fields. The tone generation template is placed in the user’s return buffer and can then be used by the dx_playtone( ) function to generate the tone. dx_playtone( ) Plays a tone specified by the tone generation template (pointed to by tngenp). Termination conditions are set using the DV_TPT structure. The reason for termination is returned by the ATDX_TERMMSK( ) function. dx_playtone( ) returns a 0 to indicate that it has completed successfully. 13.2.3 Building and Implementing a Tone Generation Template The tone generation template defines the frequency, amplitude, and duration of a single- or dualfrequency tone to be played. You can use the convenience function dx_bldtngen( ) to set up the structure. Use dx_playtone( ) to play the tone. Voice API for Windows Operating Systems Programming Guide — November 2002 139 Global Tone Detection and Generation, and Cadenced Tone Generation The TN_GEN data structure is defined as: typedef struct { unsigned short unsigned short unsigned short short int short int short int } TN_GEN; tg_dflag; tg_freq1; tg_freq2; tg_ampl1; tg_ampl2; tg_dur; /* /* /* /* /* /* dual tone = 1, single tone = 0 */ frequency of tone 1 (in Hz) */ frequency of tone 2 (in Hz) */ amplitude of tone 1 (in dB) */ amplitude of tone 2 (in dB) */ duration (in 10 msec units) */ After you build the TN_GEN data structure, there are two ways to define each tone template. You may either: • Include the values in the structure • Pass the values to TN_GEN using the dx_bldtngen( ) function If you include the values in the structure, you must create a structure for each tone template. If you pass the values using the dx_playtone( ) function, then you can reuse the structure. If you are only changing one value in a template with many variables, it may be more convenient to use several structures in the code instead of reusing just one. After defining the template by either of these methods, pass TN_GEN to dx_playtone( ) to play the tone. 13.3 Cadenced Tone Generation The following topics provide information on enabling and using cadenced tone generation: • Using Cadenced Tone Generation • How To Generate a Custom Cadenced Tone • How To Generate a Non-Cadenced Tone • TN_GENCAD Data Structure - Cadenced Tone Generation • How To Generate a Standard PBX Call Progress Signal • Predefined Set of Standard PBX Call Progress Signals • Important Considerations for Using Predefined Call Progress Signals 140 Voice API for Windows Operating Systems Programming Guide — November 2002 Global Tone Detection and Generation, and Cadenced Tone Generation 13.3.1 Using Cadenced Tone Generation Cadenced tone generation is an enhancement to global tone generation that enables you to generate a signal with up to four single- or dual-tone elements, each with its own on/off duration creating the signal pattern or cadence. Cadenced tone generation is accomplished with the dx_playtoneEx( ) function and the TN_GENCAD data structure. You can define your own custom cadenced tone or take advantage of the built-in set of standard PBX call progress signals. The functions and data structures associated with cadenced tone generation are described in the Voice API Library Reference. 13.3.2 How To Generate a Custom Cadenced Tone A custom cadenced tone is defined by specifying in a TN_GENCAD data structure the repeating elements of the signal (the cycle) and the number of desired repetitions. The cycle can consist of up to 4 segments, each with its own tone definition and cadence. A segment consists of a TN_GEN single- or dual-tone definition (frequency, amplitude, & duration) followed by a corresponding off-time (silence duration) that is optional. The dx_bldtngen( ) function can be used to set up the TN_GEN components of the TN_GENCAD structure. The tone duration, or on-time, from TN_GEN (tg_dur) and the offtime from TN_GENCAD are combined to produce the cadence for the segment. The segments are seamlessly concatenated in ascending order to generate the signal cycle. Use the following procedure to generate a custom cadenced tone: 1. Identify the repeating elements of the signal (the cycle). 2. Use a TN_GENCAD structure to define the segments in the cycle: a. Start with the first tone element in the cycle and identify the single- or dual-tone frequencies, amplitudes, and duration (on-time). b. Use the dx_bldtngen( ) function to specify this tone definition in tone[0] (the first TN_GEN tone array element) of the TN_GENCAD structure. c. Identify the off-time for the first tone element and specify it in offtime[0]. If the first tone element is followed immediately by a second tone element, set offtime[0] = 0. d. Define the next segment of the cycle in tone[1] and offtime[1] the same way as above, and so on, up to the maximum of 4 segments or until you reach the end of the cycle. 3. Use the TN_GENCAD to define the parameters of the cycle: a. Specify the number of segments in the cycle (numsegs). b. Specify the number of cycle repetitions (cycles). 4. Set the termination conditions in a DV_TPT structure. 5. Call the dx_playtoneEx( ) function and use the tngencadp parameter to specify the custom cadenced tone that you defined in the TN_GENCAD. Voice API for Windows Operating Systems Programming Guide — November 2002 141 Global Tone Detection and Generation, and Cadenced Tone Generation For an illustration of this procedure, see Figure 19. Figure 19. Example of Custom Cadenced Tone Generation Define the Signal as a Dialogic Custom Cadence Tome Set the TN_GENCAD Parameters tngencad.cycles = 255; tngencad.numsegs = 2; tngencad.offtime (0) = 0; tngencad.offtime (1) = 300; dx_bidtngen(&tgencad.tone(0),440, 480, -16, -16, 100) Call thhe dx_playtoneEx( ) dx_playtoneEx (dxxxdev, &tngencad, tpt, EV_SYNC) The TN_GENCAD Definition and Resulting Signal 142 TN_GENCAD cycles numsegs offtime(0) offtime(1) offtime(2) offtime(3) = = = = = = tngencad 255 2 0 300 0 0 TN_GEN tone dflag(0) tgfreq1(0) tgfreq2(0) tg_amp11(0) tg_amp12(0) tg_dur(0) (0) = = = = = = 0 440 480 -16 -16 100 TN_GEN tone dflag(1) tgfreq1(1) tgfreq2(1) tg_amp11(1) tg_amp12(1) tg_dur(1) (1) = = = = = = 0 440 0 -16 0 20 TN_GEN tone dflag(2) tgfreq1(2) tgfreq2(2) tg_amp11(2) tg_amp12(2) tg_dur(2) (2) = = = = = = 0 0 0 0 0 0 TN_GEN tone dflag(3) tgfreq1(3) tgfreq2(3) tg_amp11(3) tg_amp12(3) tg_dur(3) (3) = = = = = = 0 0 0 0 0 0 100 -16 dB 440+480 Hz Description of the Cadence Tome Used in this Example Signal Description: Repetition of combined tones (440 = 480 Hz) ON for 0.8 to 1.2 seconds, followed by 440 Hz tone ON for 0.2 seconds, and tone OFF for 2.7 to 3.3 seconds applied within a power range of -14.5 to 17.5 dBm. Note: Dialogic provides a predefined set of standard call progress signals that can be generated by dx_playtoneEx(). This example shows how you would define the Special Audible Ring Tone 1 as a custom cadence tone if it were not already in the standard set as CP_RINGBACK1_CALLWAIT. 20 440 Hz Segment 1 440 = 480 Hz dual tone at -16 dB with on-time of 100 (10ms units) and no off time. 300 Segment 2 SIngle tone of 440 Hz at -16 dB with on-time of 20 (10ms units) and offtime of 300 (or 3 Cycle: 2 segments repeating indefinitely, or until a tpt termination occurs. Voice API for Windows Operating Systems Programming Guide — November 2002 Global Tone Detection and Generation, and Cadenced Tone Generation 13.3.3 How To Generate a Non-Cadenced Tone Either the dx_playtoneEx( ) or the dx_playtone( ) function can generate a non-cadenced tone. Non-cadenced call progress signals can be generated by the dx_playtone( ) function if you define them in a TN_GEN: Dial Tone, Executive Override Tone, and Busy Verification Tone Part A. The dx_playtoneEx( ) function can also generate a non-cadenced tone by using a TN_GENCAD data structure that defines a single segment. If you want to generate a continuous, non-cadenced signal, use a single segment and zero off-time, and specify 1) an infinite number of cycles, 2) an infinite on-time, or 3) both. (You must also specify the appropriate termination conditions in a DV_TPT structure or else the tone will never end). For example: cycles = 255; numsegs = 1; offtime[0] = 0; tone[0].tg_dur = -1 13.3.4 TN_GENCAD Data Structure - Cadenced Tone Generation TN_GENCAD is a voice library data structure (dxxxlib.h) that defines a cadenced tone that can be generated by using the dx_playtoneEx( ) function. The TN_GENCAD data structure contains a tone array with four elements that are TN_GEN data structures (Tone Generation Templates). For details on TN_GEN and TN_GENCAD, see the Voice API Library Reference. For examples of TN_GENCAD, see the definitions of standard call progress signals in Table 19, “TN_GENCAD Definitions for Standard PBX Call Progress Signals”, on page 148. 13.3.5 How To Generate a Standard PBX Call Progress Signal Use the following procedure to generate a standard PBX call progress signal from the predefined set of standard PBX call progress signals: 1. Select a call progress signal from Table 18, “Standard PBX Call Progress Signals”, on page 145 and note the signal ID (see also Figure 20, “Standard PBX Call Progress Signals (Part 1)”, on page 146). 2. Set the termination conditions in a DV_TPT structure. 3. Call the dx_playtoneEx( ) function and specify the signal ID for the tngencadp parameter. For example: dx_playtoneEx(dxxxdev, CP_BUSY, tpt, EV_SYNC) Voice API for Windows Operating Systems Programming Guide — November 2002 143 Global Tone Detection and Generation, and Cadenced Tone Generation 13.3.6 Predefined Set of Standard PBX Call Progress Signals The following information describes the predefined set of standard PBX call progress signals that are provided by Intel: • Table 18, “Standard PBX Call Progress Signals”, on page 145 lists the predefined, standard, call progress signals and their signal IDs. The signal IDs can be used with the dx_playtoneEx( ) function to generate the signal. (The #defines for the signal IDs are located in the dxxxlib.h file.) • Figure 20, “Standard PBX Call Progress Signals (Part 1)”, on page 146 illustrates the signals along with their tone specifications and cadences. The signals were divided into two parts so they could be illustrated to scale while providing sufficient detail. Part 1 uses a smaller scale than Part 2. (For this reason, the order of the signals is different than in the tables.) • Table 19, “TN_GENCAD Definitions for Standard PBX Call Progress Signals”, on page 148 lists the TN_GENCAD definitions of the signal cycle and segment definitions for each predefined call progress signal. These definitions are located in the dxgtd.c file. • Section 13.3.7, “Important Considerations for Using Predefined Call Progress Signals”, on page 149 describes what standard was used, how the standard was implemented, information regarding the signal power levels, usage and other considerations. 144 Voice API for Windows Operating Systems Programming Guide — November 2002 Global Tone Detection and Generation, and Cadenced Tone Generation Table 18. Standard PBX Call Progress Signals Name Meaning Signal ID (tngencadp) Dial Tone Ready for dialing CP_DIAL Reorder Tone (Paths-Busy, AllTrunks-Busy, Fast Busy) Call blocked: resources unavailable CP_REORDER Busy Tone (Slow Busy) Called line is busy CP_BUSY Audible Ring Tone 1 (Ringback Tone) Called party is being alerted CP_RINGBACK1 Audible Ring Tone 2 (Slow Ringback Tone) Called party is being alerted CP_RINGBACK2 Special Audible Ring Tone 1 1 Called party has Call Waiting feature and is being alerted CP_RINGBACK1_CALLWAIT Special Audible Ring Tone 2 1 Called party has Call Waiting feature and is being alerted CP_RINGBACK2_CALLWAIT Recall Dial Tone Ready for additional dialing on established connection CP_RECALL_DIAL 1 Intercept Tone Call blocked: invalid CP_INTERCEPT Call Waiting Tone 1 2 Call is waiting: single burst C_CALLWAIT1 Call Waiting Tone 2 2 Call is waiting: double burst CP_CALLWAIT2 Busy Verification Tone (Part A) Alerts parties that attendant is about to enter connection CP_BUSY_VERIFY_A Busy Verification Tone (Part B) Attendant remains connected CP_BUSY_VERIFY_B Executive Override Tone Overriding party about to be bridged onto connection CP_EXEC_OVERRIDE Confirmation Tone Feature has been activated or deactivated CP_FEATURE_CONFIRM Stutter Dial Tone (Message Waiting Dial Tone) Message waiting; ready for dialing CP_STUTTER_DIAL or CP_MSG_WAIT_DIAL 1 Either of the two Audible Ring Tones can be used but are not intended to be intermixed in a system. When using the Special Audible Ring Tone (1 or 2), it should correspond to the Audible Ring Tone (1 or 2) that is used. The two Call Waiting Tones (1 & 2) can be used to differentiate between internally and externally originated calls. Call Waiting Tone 2 is defined as a double burst in this implementation, although “multiple” bursts are permissible. 2 Voice API for Windows Operating Systems Programming Guide — November 2002 145 Global Tone Detection and Generation, and Cadenced Tone Generation Figure 20. Standard PBX Call Progress Signals (Part 1) Continuous CP_DIAL 350 + 440 Hz -16 dB CP_REORDER 480 + 620 Hz -21 dB CP_BUSY 480 + 620 Hz -21 dB CP_RINGBACK1 440 + 480 Hz -16 dB 25 25 25 146 25 25 50 50 50 100 ≈ 300 ≈ 100 ≈ 400 ≈ 100 CP_RINGBACK2_CALLWAIT a) 440 + 480 Hz b) 440 Hz -16 dB 25 25 50 CP_RINGBACK2 440 + 480 Hz -16 dB CP_RINGBACK1_CALLWAIT a) 440 + 480 Hz b) 440 Hz -16 dB 25 ≈ 20 440+480 440 Hz Hz 300 ≈ 200 20 440+480 Hz 440 Hz ≈ 400 Voice API for Windows Operating Systems Programming Guide — November 2002 Global Tone Detection and Generation, and Cadenced Tone Generation Figure 21. Standard PBX Call Progress Signals (Part 2) 10 10 CP_RECALL_DIAL 350 + 440 Hz -17 db CP_INTERCEPT a) 440 Hz + b) 620 Hz -14 db 10 10 10 continuous 10 25 25 25 25 25 25 25 25 440 Hz 620 Hz 440 Hz 620 Hz 440 Hz 620 Hz 440 Hz 620 Hz 20 20 CP_CALLWAIT1 440 Hz -23 db 1000 = 20 20 CP_CALLWAIT2 440 Hz -23 db 20 20 1000 = 20 20 175 CP_BUSY_VERIFY_A 440 Hz -14 db 60 CP_BUSY_VERIFY_B 440 Hz -14 db 900 = 300 = CP_EXEC_OVERRIDE 440 Hz -14 db 10 CP_FEATURE_CONFIRM 350 + 440 Hz -17 db CP_MSG_WAIT_DIAL or CP_STUTTER_DIAL 350 + 440 Hz -17 db 10 10 10 10 125 = 125 = 25 25 Voice API for Windows Operating Systems Programming Guide — November 2002 147 Global Tone Detection and Generation, and Cadenced Tone Generation Table 19. TN_GENCAD Definitions for Standard PBX Call Progress Signals SIGNAL_ID Cycle Definition Segment Definitions Number of Cycles1 Number of Segments in Cycle Frequency #1 (Hz) Frequency #2 (Hz) Amplitude #1 (dB) Amplitude #2 (dB) OnTime2 (10 msec) OffTime (10 msec) cycles numsegs tg_freq1 tg_freq2 tg_ampl1 tg_ampl2 tg_dur offtime 1 350 440 -17 -17 -1 0 1 480 620 -21 -21 25 25 1 480 620 -21 -21 50 50 1 440 480 -16 -16 100 300 1 440 480 -16 -16 200 400 440 440 480 0 -16 -16 -16 0 100 20 0 300 440 440 480 0 -16 -16 -16 0 200 20 0 400 4 350 350 350 350 440 440 440 440 -17 -17 -17 -17 -17 -17 -17 -17 10 10 10 -1 10 10 10 0 2 440 620 0 0 -14 -14 0 0 25 25 0 0 2 440 440 0 0 -23 -23 0 0 20 20 1000 0 4 440 440 440 440 0 0 0 0 -23 -23 -23 -23 0 0 0 0 20 20 20 20 20 1000 20 0 CP_DIAL 1 CP_REORDER 255 CP_BUSY 255 CP_RINGBACK1 255 CP_RINGBACK2 255 CP_RINGBACK1_CALLWAIT 255 2 CP_RINGBACK2_CALLWAIT 255 2 CP_RECALL_DIAL 1 CP_INTERCEPT 255 CP_CALLWAIT1 1 CP_CALLWAIT2 1 1 255 2- specifies an infinite number of cycles (cycles) 1 specifies an infinite tone duration (tg_dur) 148 Voice API for Windows Operating Systems Programming Guide — November 2002 Global Tone Detection and Generation, and Cadenced Tone Generation Table 19. TN_GENCAD Definitions for Standard PBX Call Progress Signals (Continued) SIGNAL_ID Cycle Definition Segment Definitions Number of Cycles1 Number of Segments in Cycle Frequency #1 (Hz) Frequency #2 (Hz) Amplitude #1 (dB) Amplitude #2 (dB) OnTime2 (10 msec) OffTime (10 msec) cycles numsegs tg_freq1 tg_freq2 tg_ampl1 tg_ampl2 tg_dur offtime 440 0 -14 0 175 0 440 0 -14 0 60 900 440 0 -14 0 300 0 350 350 350 440 440 440 -17 -17 -17 -17 -17 -17 10 10 10 10 10 0 350 440 -17 -17 125 25 CP_BUSY_VERIFY_A 1 1 CP_BUSY_VERIFY_B 255 1 CP_EXEC_OVERRIDE 1 1 CP_FEATURE_CONFIRM 1 3 CP_STUTTER_DIAL or CP_MSG_WAIT_DIAL 255 1 1 255 specifies an infinite number of cycles (cycles) 2 -1 specifies an infinite tone duration (tg_dur) 13.3.7 Important Considerations for Using Predefined Call Progress Signals Take into account the following considerations when using the predefined call progress signals: • Signal definitions are based on the TIA/EIA Standard: Requirements for Private Branch Exchange (PBX) Switching Equipment, TIA/EIA-464-B, April 1996 (Telecommunications Industry Association in association with the Electronic Industries Association, Standards and Technology Department, 2500 Wilson Blvd., Arlington, VA 22201). To order copies, contact Global Engineering Documents in the USA at 1-800-854-7179 or 1-303-397-7956. • A separate Line Lockout Warning Tone, which indicates that the station line has been locked out because dialing took too long or the station failed to disconnect at the end of a call, is not necessary and is not recommended. You can use the Reorder tone over trunks; or the Intercept, Reorder, or Busy tone over stations. • For signals that specify an infinite repetition of the signal cycle (cycles = 255 on Springware or 40 on DM3) or an infinite duration of a tone (tg_dur = -1), you must specify the appropriate termination conditions in the DV_TPT structure used by dx_playtoneEx( ). • There may be more than one way to use TN_GENCAD to generate a given signal. For example, the three bursts of the Confirmation Tone can be created through one cycle Voice API for Windows Operating Systems Programming Guide — November 2002 149 Global Tone Detection and Generation, and Cadenced Tone Generation containing three segments (as in the Intel Dialogic implementation) or through a single segment that is repeated in three cycles. • To generate a continuous, non-cadenced signal, you can use dx_playtoneEx( ) and TN_GENCAD to specify a single segment with zero off-time and with an infinite number of cycles and/or an infinite on-time. Alternatively, you could use dx_playtone( ) and TN_GEN to generate a non-cadenced signal. The following non-cadenced call progress signals could be generated by the dx_playtone( ) function if you defined them in a TN_GEN: 1) Dial Tone, 2) Executive Override Tone, and 3) Busy Verification Tone Part A. • Note that the Intercept Tone consists of alternating single tones. • Although the TIA/EIA Standard describes the Busy Verification Tone as one signal, the two segments are separate tones/events: Part A is a single burst almost three times longer than Part B and it alerts the parties before the attendant intrudes; Part B is a short burst every 9 seconds continuing as long as the interruption lasts. The TIA/EIA Standard does not define an off-time between Part A and B. Therefore, the application developer is responsible for implementing the timing between the two parts of this signal. • The TIA/EIA Standard specifies the range of permissible power levels per frequency for 1) the Central Office trunk interface and 2) all other interfaces (including off-premise stations and tie trunks). The Intel Dialogic implementation adopted the approximate middle value in the acceptable range of power levels for applying the signals to the CO trunk interface. These power levels were more restrictive than those for the other interfaces. According to the following statement in the TIA/EIA Standard, additional requirements and considerations may apply: “Studies have shown that the lower level tones that are transmitted over trunks should be 6 dB hotter at the trunk interface (than at the line interface) to compensate for increased loss on the end-to-end connection. In the case of tones used at higher levels, the 6 dB difference is not used since power at trunk interfaces must be limited to -13 dBm0 total when averaged over any 3-second interval to prevent carrier overload. Maximum permissible powers listed are consistent with this requirement taking into account the allowable interruption rates for the various tones. Uninterrupted tones, such as Dial Tone and Intercept Tone, shall be continuously limited to -13 dBm.” For related power level information, see also a) Note 1 for Tables 29 and 30, b) Section 5.9, and c) Section 6.3.5. 150 Voice API for Windows Operating Systems Programming Guide — November 2002 Global Dial Pulse Detection 14. 14 Global dial pulse detection (global DPD) is a signaling component of the voice library. The following topics provide more information on global DPD: • Key Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 • Global DPD Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 • Enabling Global DPD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 • Global DPD Programming Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 • Dial Pulse Detection Digit Type Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 • Defines for Digit Type Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 • Global DPD Programming Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 • Global DPD Example Code (Synchronous Model). . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 14.1 Key Features Global dial pulse detection is not supported on DM3 boards. Dial Pulse Detection (DPD) allows applications to detect dial pulses from rotary or pulse phones by detecting the audible clicks produced when a number is dialed, and to use these clicks as if they were DTMF digits. Intel Dialogic global dial pulse detection, called global DPD, is a softwarebased dial pulse detection method that can use country-customized parameters for extremely accurate performance. Global DPD provides the following features and benefits: • The global DPD algorithm is adaptive and can train on any DPD digit it encounters, with the greatest accuracy produced from training on a digit that has 5 or more pulses. Global DPD does not require a leading “0” to train the global DPD algorithm. • Global DPD can be performed simultaneously with DTMF detection. The application can determine whether the digit detected is a DTMF or DPD digit. • Global DPD can be performed simultaneously with Global Tone Detection (GTD). For example, the application can use GTD to monitor for disconnect tones (dial tone or busy) simultaneously with DPD. • Global DPD supports pulse-digit cut-through during a voice playback, with the correct digit returned in the digit buffer. Global DPD uses echo cancellation, which provides more accurate reporting of digits during voice playback. Voice API for Windows Operating Systems Programming Guide — November 2002 151 Global Dial Pulse Detection • The application can enable global DPD and volume control. (Previously, there was a restriction that DPD digits had to be sent to the event queue instead of the digit queue if volume control was enabled.) Note: Speed control is not supported while the GDPD feature is enabled on the D/160SC-LS-IDPD, D/240SC-T1-IDPD, D/300SC-E1-75-IDPD, D/300SC-E1-120-IDPD and D/320SC-IDPD boards. You may adjust the speed before or after placing or receiving a call that uses GDPD. If any speed control adjustments are attempted while GDPD is enabled, the function will return with a -1 indicating failure. The following applications are supported by the global DPD feature: • Analog applications using the loop-start telephone interface on a supported voice board • Digital applications using a supported voice board See the Release Guide for information on boards that support the global DPD feature. 14.2 Global DPD Parameters This implementation of dial pulse detection is referred to as global DPD because its detection algorithm supports a wide range of dial pulses, from 8 pulse-per-second (PPS) to 22 PPS telephones. Intel is continually qualifying its Dial Pulse Detection algorithm against dial pulse data collected from different parts of the world to improve DPD accuracy for telephone systems and telephones in different regions. As appropriate, Intel will issue download parameters from time to time to improve the accuracy of DPD in a given region of the world, whether it is part of a country, an entire country, or a group of countries. Customized global DPD download parameters are provided for several countries such as Argentina, Brazil, Colombia, India, Japan, Mexico and Venezuela, one of which can be selected during installation (refer to the Country Specific Parameter File). As additional regions are qualified for customized global DPD, relevant region-specific support will be released. Support for a generic 10 pulse-per-second (PPS) global DPD parameter file is provided for countries that use 10 PPS phones. You must install the Country-Specific Parameters and select a country to obtain support for global DPD. 14.3 Enabling Global DPD Global DPD works only on DPD-enabled boards. You must order a separate GDPD enablement package from Intel to enable GDPD on these boards (except for boards with the "IDPD" suffix, which are already enabled). See the Release Guide for information on boards that support the global DPD feature. 152 Voice API for Windows Operating Systems Programming Guide — November 2002 Global Dial Pulse Detection To indicate that a board is DPD-enabled, apply the sticker provided with the GDPD enablement package to your board. Additionally, it is recommended that you write down the serial number of the DPD-enabled board for your records. Global DPD must be implemented on a call-by-call basis. Global DPD uses the dx_setdigtyp( ) function to enable DPD. See the Voice API Library Reference for information on all functions and data structures described in this chapter. For any digit detected, you can determine the digit type such as DTMF or DPD by using the DV_DIGIT data structure in the application. When a dx_getdig( ) or dx_getdigEx( ) function call is performed, the digits are collected from the firmware and transferred to the user’s digit buffer. The digits are stored as an array inside the DV_DIGIT structure. You then use a pointer to the structure that contains a digit buffer. For an example, see Section 14.8, “Global DPD Example Code (Synchronous Model)”, on page 154. This method allows you to determine very quickly whether a pulse or DTMF telephone is being used. If your application has been designed to work with a DPD/120 board, you may need to modify the application to work with the DPD-enabled voice boards and the improved capabilities of global DPD. 14.4 Global DPD Programming Considerations The global DPD algorithm will accurately detect digits in the supported regions without requesting a special training digit from the caller or requiring any other restrictions on the application. However, observe the following considerations when designing the application: • Talk-off rejection (the ability of the algorithm to distinguish between dial pulses and the human voice) will improve after the first digit is detected. • Digit detection will be slightly more accurate (about 2%) after detecting a digit of 5 or greater. It is not necessary to dial a special training digit to do this. The application may simply restrict the first menu to digits 5, 6, 7, 8, 9, and 0, and the training will be complete. Subsequent menus may be unrestricted. • In general, detection accuracy is greater for higher digits than for lower. While detection accuracy is very high, it may be further improved by restricting menu selections, whenever convenient, to digits greater than 3. 14.5 Dial Pulse Detection Digit Type Reporting Two defines are provided for identifying the Dial Pulse Detection digit type, depending upon how the digit type is retrieved: DG_DPD Dial Pulse Detection digit from the DX_EBLK event queue data (cst_data) through a DE_DIGITS Call Status Transition event DG_DPD_ASCII Dial Pulse Detection digit from the DV_DIGIT dg_type digit buffer using dx_getdig( ) Voice API for Windows Operating Systems Programming Guide — November 2002 153 Global Dial Pulse Detection Obtaining the digit type for DPD digits is valid only in the case when the voice and DPD capabilities are both present on the same board. In the case where a voice board does not support DPD, you cannot detect DPD digits or obtain the DPD digit type even though you can enable DPD and digit type reporting without an error. 14.6 Defines for Digit Type Reporting Use the defines as shown here to determine the digit type from the value returned in the dg_type (digit type) field from the DV_DIGIT digit buffer. If you get the digit from the DV_DIGIT dg_type digit buffer using dx_getdig( ), you should use the digit type define that has the "_ASCII" suffix. Otherwise, if you get the digit from the DX_EBLK event queue data (cst_data) through a DE_DIGITS Call Status Transition event, you should use the digit type define without the "_ASCII" suffix. Defines for dg_type from Digit Type DTMF 14.7 Digit Buffer DG_DTMF_ASCII Event Queue DG_DTMF DPD DG_DPD_ASCII DG_DPD MF DG_MF_ASCII DG_MF GTD DG_USER1_ASCII DG_USER1 (user-defined) DG_USER2_ASCII DG_USER2 DG_USER3_ASCII DG_USER3 DG_USER4_ASCII DG_USER4 DG_USER5_ASCII DG_USER5 Global DPD Programming Procedure Use the following procedure to implement global DPD: 1. Define a data structure of type DV_DIGIT (this structure is specified in the DXDIGIT.H file). 2. Enable DPD on the desired channels using the dx_setdigtyp( ) function. For new calls you must use the D_DPDZ mask that initializes the DPD detector for new calls. 3. Execute the dx_getdig( ) function to collect and transfer the digits to the user’s digit buffer. The digits are stored in the dg_value field of the DV_DIGIT structure with the corresponding digit types stored in the dg_type field of the DV_DIGIT structure. 14.8 Global DPD Example Code (Synchronous Model) The following example code illustrates how to set up and use global DPD. /*$ dx_setdigtyp( )and dx_getdig( ) example for global dial pulse detection $*/ #include #include #include 154 "srllib.h" "dxxxlib.h" Voice API for Windows Operating Systems Programming Guide — November 2002 Global Dial Pulse Detection void main(int argc, char **argv) { int dev; DV_DIGIT DV_TPT tpt; /* Dialogic device handle */ dig; /* * Open device, make or accept call */ /* setup TPT to dx_clrtpt(&tpt, tpt.tp_type = tpt.tp_termno = tpt.tp_length = tpt.tp_flags = wait for 3 digits and terminate */ 1); IO_EOT; DX_MAXDTMF; 3; TF_MAXDTMF; /* enable DPD and DTMF digits */ dx_setdigtyp(dev, D_DPDZ|D_DTMF); /* clear the digit buffer */ dx_clrdigbuf(dev); /* collect 3 digits from the user */ if (dx_getdig(dev, &tpt, &dig, EV_SYNC) == -1) { /* error, display error message */ printf("dx_getdig error %d, %s\n", ATDV_LASTERR(dev), ATDV_ERRMSGP(dev)); } else { /* display digits received and digit type */ printf("Received \"%s\"\n", dig.dg_value); printf("Digit type is "); /* * digit types have 0x30 ORed with them strip it off * so that we can use the DG_xxx equates from the header files */ switch ((dig.dg_type[0] & 0x000f)) { case DG_DTMF: printf("DTMF\n"); break; case DG_DPD: printf("DPD\n"); break; default: printf("Unknown, %d\n", (dig.dg_type[0] &0x000f)); } } /* * continue processing call */ Voice API for Windows Operating Systems Programming Guide — November 2002 155 Global Dial Pulse Detection 156 Voice API for Windows Operating Systems Programming Guide — November 2002 15 R2/MF Signaling 15. This chapter provides a description of R2/MF signaling protocol. The following topics are presented: • R2/MF Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 • Direct Dialing-In Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158 • R2/MF Multifrequency Combinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158 • R2/MF Signal Meanings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 • R2/MF Compelled Signaling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 • R2/MF Voice Library Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 • R2/MF Tone Detection Template Memory Requirements . . . . . . . . . . . . . . . . . . . . . . 168 15.1 R2/MF Overview R2/MF signaling is an international signaling system that is used in Europe and Asia to permit the transmission of numerical and other information relating to the called and calling subscribers’ lines. Note: R2/MF signaling is typically accomplished through the Global Call API. For more information, see the Global Call documentation set. The information in this chapter is provided for reference purposes only. It is not recommended that the voice library functions described in this chapter be used for R2/MF signaling. R2/MF signals that control the call setup are referred to as interregister signals. In the case of the signals sent between the central office (CO) and the customer premises equipment (CPE), the CO is referred to as the outgoing register and the CPE as the incoming register. Signals sent from the CO are forward signals; signals sent from the CPE are backward signals. The outgoing register (CO) sends forward interregister signals and receives backward interregister signals. The incoming register (CPE) receives forward interregister signals and sends backward interregister signals. See Figure 22. Figure 22. Forward and Backward Interregister Signals Outgoing Register (CO) Forward Signal Backward Signal Incoming Register (CPE) The focus of this section is on the forward and backward interregister signals, and more specifically, the address signals, which can provide the telephone number of the called subscriber’s line. For national traffic, the address signals can also provide the telephone number of a calling subscriber’s line for automatic number identification (ANI) applications. Voice API for Windows Operating Systems Programming Guide — November 2002 157 R2/MF Signaling R2/MF signals that are used for supervisory signaling on the network are called line signals. Line signals are beyond the scope of this document. 15.2 Direct Dialing-In Service Since R2/MF address signals can provide the telephone number of the called subscriber’s line, the signals may be used by applications providing direct dialing-in (DDI) service, also known as direct inward dialing (DID), and dialed number identification service (DNIS). DDI service allows an outside caller to dial an extension within a company without requiring an operator to transfer the call. The central office (CO) passes the last 2, 3, or 4 digits of the dialed number to the customer premises equipment (CPE) and the CPE completes the call. 15.3 R2/MF Multifrequency Combinations R2/MF signaling uses a multifrequency code system based on six fundamental frequencies in the forward direction (1380, 1500, 1620, 1740, 1860, and 1980 Hz) and six frequencies in the backward direction (1140, 1020, 900, 780, 660, and 540 Hz). Each signal is composed of two out of the six fundamental frequencies, which results in 15 different tone combinations in each direction. Although R2/MF is designed for operation on international networks with 15 multifrequency combinations in each direction, in national networks it can be used with a reduced number of signaling frequencies (for example, 10 multifrequency combinations). See Table 20 and Table 21 for lists of the signal tone pairs. Table 20. Forward Signals, CCITT Signaling System R2/MF tones R2/MF TONES 158 INTEL DIALOGIC INFORMATION Tone Number Tone Pair Frequencies (Hz) Group I Define Group II Define Tone Detect. ID 1 1380 1500 SIGI_1 SIGII_1 101 2 1380 1620 SIGI_2 SIGII_2 102 3 1500 1620 SIGI_3 SIGII_3 103 4 1380 1740 SIGI_4 SIGII_4 104 5 1500 1740 SIGI_5 SIGII_5 105 6 1620 1740 SIGI_6 SIGII_6 106 7 1380 1860 SIGI_7 SIGII_7 107 8 1500 1860 SIGI_8 SIGII_8 108 9 1620 1860 SIGI_9 SIGII_9 109 10 1740 1860 SIGI_0 SIGII_0 110 11 1380 1980 SIGI_11 SIGII_11 111 12 1500 1980 SIGI_12 SIGII_12 112 Voice API for Windows Operating Systems Programming Guide — November 2002 R2/MF Signaling Table 20. Forward Signals, CCITT Signaling System R2/MF tones (Continued) R2/MF TONES INTEL DIALOGIC INFORMATION Tone Number Tone Pair Frequencies (Hz) Group I Define Group II Define Tone Detect. ID 13 1620 1980 SIGI_13 SIGII_13 113 14 1740 1980 SIGI_14 SIGII_14 114 15 1860 1980 SIGI_15 SIGII_15 115 Table 21. Backward Signals, CCITT Signaling System R2/MF tones R2/MF TONES Tone Number 15.4 INTEL DIALOGIC INFORMATION Tone Pair Frequencies (Hz) Group A Define Group B Define 1 1140 1020 SIGA_1 SIGB_1 2 1140 900 SIGA_2 SIGB_2 3 1020 900 SIGA_3 SIGB_3 4 1140 780 SIGA_4 SIGB_4 5 1020 780 SIGA_5 SIGB_5 6 900 780 SIGA_6 SIGB_6 7 1140 660 SIGA_7 SIGB_7 8 1020 660 SIGA_8 SIGB_8 9 900 660 SIGA_9 SIGB_9 10 780 660 SIGA_0 SIGB_0 11 1140 540 SIGA_11 SIGB_11 12 1020 540 SIGA_12 SIGB_12 13 900 540 SIGA_13 SIGB_13 14 780 540 SIGA_14 SIGB_14 15 660 540 SIGA_15 SIGB_15 R2/MF Signal Meanings There are two groups of meanings associated with each set of signals. Group I meanings and Group II meanings are associated with the 15 forward signals. Group A meanings and Group B meanings are associated with the 15 backward signals. See Figure 23. Voice API for Windows Operating Systems Programming Guide — November 2002 159 R2/MF Signaling Figure 23. Multiple Meanings for R2/MF Signals Group I Meanings Group A Meanings Backward Signals Forward Signals Group II Meanings Group B Meanings In general, Group I forward signals and Group A backward signals are used to control the call setup and to transfer address information between the outgoing register (CO) and the incoming register (CPE). The incoming register can then signal to the outgoing register to change over to the Group II and Group B meanings. Group II forward signals provide the calling party’s category, and Group B backward signals provide the condition of the called subscriber’s line. For further information, see Table 22, “Purpose of Signal Groups and Changeover in Meaning”, on page 160 describing the purpose of the signal groups and the changeover in meanings. Signaling must always begin with a Group I forward signal followed by a Group A backward signal that serves to acknowledge the signal just received and also has its own meaning. Each signal then requires a response from the other party. Each response becomes an acknowledgment of the event and an event for the other party to respond to. Backward signals serve to indicate certain conditions encountered during call setup or to announce switch-over to changed meanings of subsequent backward signals. Changeover to Group II and Group B meanings allows information about the state of the called subscriber’s line to be transferred. Table 22. Purpose of Signal Groups and Changeover in Meaning Signal 160 Purpose Group I Group I signals control the call set-up and provide address information. Group A Group A signals acknowledge Group I signals (see exception under signal A-5 below) for call set-up, and can also request address and other information. Group A signals also control the changeover to Group II and Group B meanings through the following signals: A-3 Address Complete - Changeover to Reception of Group B Signals: Indicates the address is complete and signals a changeover to Group II/B meanings; after signal A-3 is sent, signaling cannot change back to Group I/A meanings. A-5 Send Calling Party’s Category: Requests transmission of a single Group II signal providing the calling party’s category. Signal A-5 requests a Group II signal but does not indicate changeover to Group B signals. When the Group II signal requested by A-5 is received, it is acknowledged by a Group A signal; this is an exception to the rule that Group A signals acknowledge Group I signals. Group II Group II signals acknowledge signal A-3 or A-5 and provide the calling party category (national or international call, operator or subscriber, data transmission, maintenance or test call). Group B Group B signals acknowledge Group II signals and provide the condition of the called subscriber’s line. Before Group B signals can be transmitted, the preceding backward signal must have been A-3. Signals cannot change back to Group I/A. Voice API for Windows Operating Systems Programming Guide — November 2002 R2/MF Signaling The incoming register backward signals can request: • Transmission of address – Send next digit – Send digit previous to last digit sent – Send second digit previous to last digit sent – Send third digit previous to last digit sent • Category of the call (the nature and origin) – National or international call – Operator or subscriber – Data transmission – Maintenance or test call • Whether or not the circuit includes a satellite link • Country code and language for international calls • Information on use of an echo suppressor The incoming register backward signals can indicate: • Address complete - send category of call • Address complete - put call through • International, national, or local congestion • Condition of subscriber’s line – Send SIT to indicate long-term unavailability – Line busy – Unallocated number – Line free - charge on answer – Line free - no charge on answer (only for special destinations) – Line out of order Note: The meaning of certain forward multifrequency combinations may also vary depending upon their position in the signaling sequence. For example, with terminal calls the first forward signal transmitted in international working is a language or discriminating digit (signals I-1 through I-10). When the same signal is sent as other than the first signal, it usually means a numerical digit. See the following tables for the signal meanings: • Table 23, “Meanings for R2/MF Group I Forward Signals”, on page 162 • Table 24, “Meanings for R2/MF Group II Forward Signals”, on page 163 • Table 25, “Meanings for R2/MF Group A Backward Signals”, on page 164 • Table 26, “Meanings for R2/MF Group B Backward Signals”, on page 165 Voice API for Windows Operating Systems Programming Guide — November 2002 161 R2/MF Signaling Table 23. Meanings for R2/MF Group I Forward Signals Tone Number 162 Intel Dialogic Define (A) Primary Meaning (B) Secondary Meaning 1 SIGI_1 (A) Digit 1 (B) Language digit-French 2 SIGI_2 (A) Digit 2 (B) Language digit-English 3 SIGI_3 (A) Digit 3 (B) Language digit-German 4 SIGI_4 (A) Digit 4 (B) Language digit-Russian 5 SIGI_5 (A) Digit 5 (B) Language digit-Spanish 6 SIGI_6 (A) Digit 6 (B) Spare (language digit) 7 SIGI_7 (A) Digit 7 (B) Spare (language digit) 8 SIGI_8 (A) Digit 8 (B) Spare (language digit) 9 SIGI_9 (A) Digit 9 (B) Spare (discriminating digit) 10 SIGI_0 (A) Digit 0 (B) Discriminating digit 11 SIGI_11 (A) Access to incoming operator (Code 11) (B) Country code indicator: outgoing half-echo suppressor required 12 SIGI_12 (A) Access to delay operator (code 12); request not accepted (B) Country code indicator: no echo suppressor required 13 SIGI_13 (A) Access to test equipment (code 13); satellite link not included (B) Test call indicator 14 SIGI_14 (A) Incoming half-echo suppressor required; satellite link included (B) Country code indicator: outgoing half-echo suppressor inserted 15 SIGI_15 (A) End of pulsing (code 15); end of identification (B) Signal not used Voice API for Windows Operating Systems Programming Guide — November 2002 R2/MF Signaling Table 24. Meanings for R2/MF Group II Forward Signals Tone Number Intel Dialogic Define Meaning 1 SIGII_1 National: Subscriber without priority 2 SIGII_2 National: Subscriber with priority 3 SIGII_3 National: Maintenance equipment 4 SIGII_4 National: Spare 5 SIGII_5 National: Operator 6 SIGII_6 National: Data transmission 7 SIGII_7 International: Subscriber, operator, or maintenance equipment (without forward transfer) 8 SIGII_8 International: Data transmission 9 SIGII_9 International: Subscriber with priority 10 SIGII_0 International: Operator with forward transfer facility 11 SIGII_11 Spare for national use 12 SIGII_12 Spare for national use 13 SIGII_13 Spare for national use 14 SIGII_14 Spare for national use 15 SIGII_15 Spare for national use Voice API for Windows Operating Systems Programming Guide — November 2002 163 R2/MF Signaling Table 25. Meanings for R2/MF Group A Backward Signals Tone Number 164 Intel Dialogic Define Meaning 1 SIGA_1 Send next digit (n+1) 2 SIGA_2 Send last but one digit (n-1) 3 SIGA_3 Address complete; change to Group B signals; no change back 4 SIGA_4 Congestion in the national network 5 SIGA_5 Send calling party’s category; change to Group II; can change back 6 SIGA_6 Address complete; charge; set up speech conditions 7 SIGA_7 Send last but two digit (n-2) 8 SIGA_8 Send last but three digit (n-3) 9 SIGA_9 Spare for national use 10 SIGA_0 Spare for national use 11 SIGA_11 Send country code indicator 12 SIGA_12 Send language or discriminating digit 13 SIGA_13 Send nature of circuit (satellite link only) 14 SIGA_14 Request for information on use of an echo suppressor 15 SIGA_15 Congestion in an international exchange or at its output Voice API for Windows Operating Systems Programming Guide — November 2002 R2/MF Signaling Table 26. Meanings for R2/MF Group B Backward Signals Tone Number 15.5 Intel Dialogic Define Meaning 1 SIGB_1 Spare for national use 2 SIGB_2 Send special information tone to indicate long-term unavailability 3 SIGB_3 Subscriber line busy 4 SIGB_4 Congestion encountered after change to Group B 5 SIGB_5 Unallocated number 6 SIGB_6 Subscriber line free; charge on answer 7 SIGB_7 Subscriber line free; no charge (only for calls to special destinations) 8 SIGB_8 Subscriber line out of order 9 SIGB_9 Spare for national use 10 SIGB_0 Spare for national use 11 SIGB_11 Spare for national use 12 SIGB_12 Spare for national use 13 SIGB_13 Spare for national use 14 SIGB_14 Spare for national use 15 SIGB_15 Spare for national use R2/MF Compelled Signaling R2/MF interregister signaling uses forward and backward compelled signaling. Simply put, with compelled signaling each signal is sent until it is responded to by a return signal, which in turn is sent until responded to by the other party. Each signal stays on until the other party responds, thus compelling a response from the other party. Reliability and speed requirements for signaling systems are often in conflict: the faster the signaling, the more unreliable it is likely to be. Compelled signaling provides a balance between speed and reliability because it adapts its signaling speed to the working conditions with a minimum loss of reliability. The R2/MF signal is composed of two significant events: tone-on and tone-off. Each tone event requires a response from the other party. Each response becomes an acknowledgment of the event and an event for the other party to respond to. Compelled signaling must always begin with a Group I forward signal. • The CO starts to send the first forward signal. • As soon as the CPE recognizes the signal, it starts to send a backward signal that serves as an acknowledgment and at the same time has its own meaning. Voice API for Windows Operating Systems Programming Guide — November 2002 165 R2/MF Signaling • As soon as the CO recognizes the CPE acknowledging signal, it stops sending the forward signal. • As soon as the CPE recognizes the end of the forward signal, it stops sending the backward signal. • As soon as the CO recognizes the CPE end of the backward signal, it may start to send the next forward signal. The CPE responds to a tone-on with a tone-on and to a tone-off with a tone-off. The CO responds to a tone-on with a tone-off and to a tone-off with a tone-on. See Figure 24 and Figure 25 for more information. Figure 24. R2/MF Compelled Signaling Cycle CO Forward Signal A ON A) CO: Turns Forward Signal ON CO Backward Signal ON B) CPE: Detects Forward Signal ON Turns Backward SIgnal ON C) CO: Detects Backward Signal ON Turns Forward Signal OFF B D) CPE: Detects Forward Signal OFF Turns Backward SIgnal OFF C OFF E) CO: Detects Backward Signal OFF Begins Next Signal Cycle OFF D Detected Event E ON Response Time ON OFF OFF 166 Voice API for Windows Operating Systems Programming Guide — November 2002 R2/MF Signaling Figure 25. Example of R2/MF Signals for 4-digit DDI Application CPE Backward Signal CO Forward Signal Digit 3 1-3 Detected Event A-1 Send Next Digit Digit 9 1-9 Response A-1 Send Next Digit Digit 6 1-6 A-1 Send Next Digit Digit 0 1-0 Category of Calling Party: Subscriber w/o Priority-National A-3 Address Complete Changeover to Group B B-6 Subscriber Line Free Charge on Answer II-1 15.6 R2/MF Voice Library Functions The R2/MF voice library functions are not supported on DM3 boards. For R2/MF signaling on DM3 boards, see the Global Call documentation set. The voice software support for R2/MF signaling is based on global tone detection and global tone generation. The following R2/MF functions allow you to define R2/MF tones for detecting the forward signals and to play the backward signals in the correct timing sequence required by the compelled signaling procedure: r2_creatfsig( ) create R2/MF Forward Signal Tone r2_playbsig( ) play R2/MF Backward Signal See the Voice API Library Reference for a detailed description of these functions. Voice API for Windows Operating Systems Programming Guide — November 2002 167 R2/MF Signaling Four sets of defines are provided to specify the 15 Group I and 15 Group II forward signals, and the 15 Group A and 15 Group B backward signals. For a list of these defines, see Table 23, “Meanings for R2/MF Group I Forward Signals”, on page 162, Table 24, “Meanings for R2/MF Group II Forward Signals”, on page 163, Table 25, “Meanings for R2/MF Group A Backward Signals”, on page 164, and Table 26, “Meanings for R2/MF Group B Backward Signals”, on page 165. 15.7 R2/MF Tone Detection Template Memory Requirements To implement R2/MF signaling, the board must have sufficient memory blocks to create the number of user-defined tones required by your application. Your application may not need to detect all 15 forward signals, especially if you do not need to support R2/MF signaling for international calls. If that is the case, your application can work with a reduced number of R2/MF tones. High-density boards such as D/160SC-LS, D/240JCT-T1, and D/300JCT-E1 normally contain sufficient memory to create the necessary R2/MF tones. However, you should be aware of the maximum number of user-defined tones (including non-R2/MF tones) allowed on the board. Low-density boards such as D/41JCT-LS, D/41H, Dialog/4, and ProLine/2V boards may also be able to create all 15 R2/MF tones due to the overlap in frequencies for the R2/MF signals. If creating these tones exceeds the maximum number of tones allowed, you may be able to support R2/MF signaling through a reduced number of R2/MF user-defined tones. See Section 13.1.7, “Maximum Amount of Memory Available for User-Defined Tone Templates”, on page 133 for more information. 168 Voice API for Windows Operating Systems Programming Guide — November 2002 Syntellect License Automated Attendant 16. 16 This chapter discusses Intel® Dialogic® hardware and software that include a license for the Syntellect Technology Corporation (STC) patent portfolio: • Overview of Automated Attendant Function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 • Syntellect License Automated Attendant Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 • How to Use the Automated Attendant Function Call . . . . . . . . . . . . . . . . . . . . . . . . . . 170 16.1 Overview of Automated Attendant Function The information in this chapter does not apply to DM3 boards. As a result of a patent license agreement between Dialogic and Syntellect Technology Corporation (STC), you can purchase products that are licensed for specific telephony patents held by Syntellect Technology Corporation directly from Intel. These patents cover a range of common functions used in computer telephony such as automated attendant, automated access and call processing to facilitate call completions. One way to protect yourself from possible patent infringement is by purchasing specific Intel Dialogic hardware and software that include a license for the Syntellect Technology Corporation (STC) patent portfolio. Boards that support the Syntellect License Automated Attendant have “STC” included in the part number. By doing so, you participate in a program that covers past, present and future applications. (Any Intel Dialogic product that does not contain the “STC” designation in its part number is not licensed under the STC patent portfolio.) The Syntellect software is designed to be incorporated into any type of application. If your application requires patented Syntellect technology, you can use the API function calls in the Syntellect software to assure that licensed STC-enabled hardware is in the system, and if so, you can implement the patented functions. The Syntellect hardware and software package offers a superset of features not available on nonSTC boards. They include: • a new library of API function calls • a sample automated attendant application that can be integrated in your voice processing application. The automated attendant: – checks for an incoming call – answers the call and plays a voice file – receives digit input and transfers the call to the proper extension Voice API for Windows Operating Systems Programming Guide 169 Syntellect License Automated Attendant • the source code and demonstration code for the automated attendant application 16.2 Syntellect License Automated Attendant Functions Intel Dialogic boards that are enabled with the Syntellect Technology Corporation (STC) patent license offer a new library interface that contains several API functions. The following functions are described in the Voice API Library Reference: li_attendant( ) Performs the actions of an automated attendant. li_islicensed_syntellect( ) Returns TRUE/FALSE value on whether the STC license is enabled on the board. 16.3 How to Use the Automated Attendant Function Call The li_attendant( ) API performs the actions of an automated attendant. This API operates in loop forever, synchronous mode and is designed to work in your application as a “created” thread. To use this function in your application: • You must provide the address of the li_attendant( ) as the entry point to the system call _beginthread( ). Do not use createthread( ). • Before the li_attendant( ) thread can be created, your application must initialize a data structure providing information for the proper operation of the li_attendant( ) thread. This data structure, called DX_ATTENDANT, is described in the Voice API Library Reference. To provide a way to terminate the li_attendant( ) thread, you must define a “named event” in the data structure. During the initialization process, the API verifies that the data structure contains valid entries. It checks for the presence of the named event. If the named event exists, li_attendant( ) continues and runs the automated attendant. If the named event does not exist, an error is returned. If the channel is on a non-STC board, li_attendant( ) terminates. For more information on the synchronous programming model, refer to the Standard Runtime Library API Programming Guide. 170 Voice API for Windows Operating Systems Programming Guide Building Applications 17. 17 This chapter provides information on building applications using the voice library. The following topics are discussed: • Voice and SRL Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 • Compiling and Linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 17.1 Voice and SRL Libraries The C-language application programming interface (API) included with the voice software provides a library of functions used to create voice processing applications. The voice library and Standard Runtime Library (SRL) files are part of the voice software. These libraries provide the interface to the voice driver. For detailed information on the SRL, see the Standard Runtime Library API Programming Guide and Standard Runtime Library API Library Reference. Figure 26 illustrates how the voice and SRL libraries interface with the driver. Figure 26. Voice and SRL Libraries APPLICATION STANDARD RUNTIME LIBRARY VOICE LIBRARY DRIVER Voice API for Windows Operating Systems Programming Guide — November 2002 171 Building Applications 17.2 Compiling and Linking The following topics discuss compiling and linking requirements: • Include Files • Required Libraries • Variables for Compiling and Linking 17.2.1 Include Files Function prototypes and equates are defined in include files, also known as header files. Applications that use voice library functions must contain statements for include files in this form, where filename represents the include file name: #include The following header files must be included in application code in the order shown prior to calling voice library functions: srllib.h Contains function prototypes and equates for the Standard Runtime Library (SRL). Used for all application development. dxxxlib.h Contains function prototypes and equates for the voice library. Used for voice processing applications. Note: srllib.h must be included in code before all other Intel Dialogic header files. By default, the header files are located in the following directory: . :\ \dialogic\inc. 17.2.2 Required Libraries Simple C language interfaces in source-code format are provided to each individual technology DLL (such as standard runtime, voice, fax, and network interfaces). These C language interfaces allow an application to perform run-time linking instead of compile-time linking. Note: Compile-time linking requires that all functions called in an application be contained in the DLL that resides on the system. You must link the following library files in the order shown when compiling your voice processing application: libdxxmt.lib Main voice library file. libsrlmt.lib Standard Runtime Library file. 172 Voice API for Windows Operating Systems Programming Guide — November 2002 Building Applications By default, the library files are located in the directory given by the INTEL_DIALOGIC_LIB environment variable. 17.2.3 Run-time Linking Run-time linking resolves the entry points to the Intel Dialogic DLLs when the application is loaded and executed. This allows the application to contain function calls that are not contained in the DLL that resides on the target system. Several files are provided for run-time linking and are installed in the CLIB subdirectory under the Intel Dialogic home directory. Some examples are: • SRLLIB.C and SRLLIB.CPP • DXXXLIB.C and DXXXLIB.CPP To use run-time linking, the application must first call the technology xx_libinit( ) functions, where xx specifies the technology (sr, dx, fx, and so on). All other Intel Dialogic function calls are the same as when using compile-time linking. Some examples of technology xx_libinit( ) functions are: dx_libinit( ) Initializes the voice Library DLL sr_libinit( ) Initializes the Standard Run-time Library DLL The xx_libinit( ) function calls the LoadLibrary( ) function to load a specific technology DLL. If the DLL does not exist, all its functions are set up as default Not Implemented Functions. If the DLL does exist, the xx_libinit( ) function performs a series of GetProcAddress( ) function calls that sets up the address pointers for the functions. 17.2.4 Variables for Compiling and Linking In System Release 6.0, the following variables have been introduced to provide a standardized way of referencing the directories that contain header files and shared objects: INTEL_DIALOGIC_INC Variable that points to the directory where header files are stored. INTEL_DIALOGIC_LIB Variable that points to the directory where shared library files are stored. These variables are automatically set at login and should be used in compiling and linking commands. The following is an example of a compiling and linking command that uses these variables: cc -I${INTEL_DIALOGIC_INC} -o myapp myapp.c -L${INTEL_DIALOGIC_LIB} -lgc Note: It is strongly recommended that developers begin using these variables when compiling and linking applications since they will be required in future releases. The name of the variables will remain constant, but the values may change in future releases. Voice API for Windows Operating Systems Programming Guide — November 2002 173 Building Applications 174 Voice API for Windows Operating Systems Programming Guide — November 2002 Glossary A-law: Pulse Code Modulation (PCM) algorithm used in digitizing telephone audio signals in E-1 areas. See also mu-law. ADPCM (Adaptive Differential Pulse Code Modulation): A sophisticated compression algorithm for digitizing audio that stores the differences between successive samples rather than the absolute value of each sample. This method of digitization reduces storage requirements from 64 kilobits/second to as low as 24 kilobits/second. ADSI (Analog Display Services Interface): A Bellcore standard defining a protocol for the flow of information between a switch, a server, a voice mail system, a service bureau, or a similar device and a subscriber’s telephone, PC, data terminal, or other communicating device with a screen. ADSI adds words to a system that usually only uses touch tones. It displays information on a screen attached to a phone. ADSI’s signaling is DTMF and standard Bell 202 modem signals from the service to a 202-modem-equipped phone. AGC (Automatic Gain Control): An electronic circuit used to maintain the audio signal volume at a constant level. AGC maintains nearly constant gain during voice signals, thereby avoiding distortion, and optimizes the perceptual quality of voice signals by using a new method to process silence intervals (background noise). analog: 1. A method of telephony transmission in which the signals from the source (for example, speech in a human conversation) are converted into an electrical signal that varies continuously over a range of amplitude values analogous to the original signals. 2. Not digital signaling. 3. Used to refer to applications that use loop start signaling. ANI (Automatic Number Identification): Identifies the phone number that is calling. Digits may arrive in analog or digital form. API (Application Programming Interface): A set of standard software interrupts, calls, and data formats that application programs use to initiate contact with network services, mainframe communications programs, or other program-to-program communications. ASCIIZ string: A null-terminated string of ASCII characters. asynchronous function: A function that allows program execution to continue without waiting for a task to complete. To implement an asynchronous function, an application-defined event handler must be enabled to trap and process the completed event. Contrast with synchronous function. bit mask: A pattern which selects or ignores specific bits in a bit-mapped control or status field. bitmap: An entity of data (byte or word) in which individual bits contain independent control or status information. board device: A board-level object that can be manipulated by a physical library. Board devices can be real physical boards, such as a D/41EPCI, or virtual boards. See virtual board. Voice API for Windows Operating Systems Library Reference — November 2002 175 board locator technology (BLT): Operates in conjunction with a rotary switch to determine and set nonconflicting slot and IRQ interrupt-level parameters, thus eliminating the need to set confusing jumpers or DIP switches. buffer: A block of memory or temporary storage device that holds data until it can be processed. It is used to compensate for the difference in the rate of the flow of information (or time occurrence of events) when transmitting data from one device to another. bus: An electronic path which allows communication between multiple points or devices in a system. busy device: A device that has one of the following characteristics: is stopped, being configured, has a multitasking or non-multitasking function active on it, or I/O function active on it. cadence: A pattern of tones and silence intervals generated by a given audio signal. The pattern can be classified as a single ring, a double ring, or a busy signal. cadence detection: A voice driver feature that analyzes the audio signal on the line to detect a repeating pattern of sound and silence. call progress analysis: A process used to automatically determine what happens after an outgoing call is dialed. On DM3 boards, a further distinction is made. Call progress refers to activity that occurs before a call is connected (pre-connect), such as busy or ringback. Call analysis refers to activity that occurs after a call is connected (post-connect), such as voice detection and answering machine detection. The term call progress analysis is used to encompass both call progress and call analysis. call status transition event functions: A class of functions that set and monitor events on devices. caller ID: calling party identification information. CCITT (Comite Consultatif Internationale de Telegraphique et Telephonique): One of the four permanent parts of the International Telecommunications Union, a United Nations agency based in Geneva. The CCITT is divided into three sections: 1. Study Groups set up standards for telecommunications equipment, systems, networks, and services. 2. Plan Committees develop general plans for the evolution of networks and services. 3. Specialized Autonomous Groups produce handbooks, strategies, and case studies to support developing countries. channel: 1. When used in reference to an Intel® Dialogic® analog expansion board, an audio path, or the activity happening on that audio path (for example, when you say the channel goes off-hook). 2. When used in reference to an Intel® Dialogic® digital expansion board, a data path, or the activity happening on that data path. 3. When used in reference to a bus, an electrical circuit carrying control information and data. channel device: A channel-level object that can be manipulated by a physical library, such as an individual telephone line connection. A channel is also a subdevice of a board. See also subdevice. CO (Central Office): A local phone network exchange, the telephone company facility where subscriber lines are linked, through switches, to other subscriber lines (including local and long distance lines). The term “Central Office” is used in North America. The rest of the world calls it “PTT”, for Post, Telephone, and Telegraph. computer telephony (CT): The extension of computer-based intelligence and processing over the telephone network to a telephone. Sometimes called computer-telephony integration (CTI), it lets you interact with computer databases or applications from a telephone, and enables computer-based applications to access the telephone 176 Voice API for Windows Operating Systems Library Reference — November 2002 network. Computer telephony technology supports applications such as: automatic call processing; automatic speech recognition; text-to-speech conversion for information-on-demand; call switching and conferencing; unified messaging, which lets you access or transmit voice, fax, and e-mail messages from a single point; voice mail and voice messaging; fax systems, including fax broadcasting, fax mailboxes, fax-on-demand, and fax gateways; transaction processing, such as Audiotex and Pay-Per-Call information systems; and call centers handling a large number of agents or telephone operators for processing requests for products, services, or information. configuration file: An unformatted ASCII file that stores device initialization information for an application. convenience function: A class of functions that simplify application writing, sometimes by calling other, lower-level API functions. CPE: customer premise equipment. CT Bus: Computer Telephony bus. A time division multiplexing communications bus that provides 4096 time slots for transmission of digital information between CT Bus products. See TDM bus. data structure: Programming term for a data element consisting of fields, where each field may have a different type definition and length. A group of data structure elements usually share a common purpose or functionality. DCM: Intel® Dialogic® Configuration Manager. A utility with a graphical user interface (GUI) that enables you to add new boards to your system, start and stop system service, and work with board configuration data. debouncing: Eliminating false signal detection by filtering out rapid signal changes. Any detected signal change must last for the minimum duration as specified by the debounce parameters before the signal is considered valid. Also known as deglitching. deglitching: See debouncing. device: A computer peripheral or component controlled through a software device driver. An Intel® Dialogic® voice and/or network interface expansion board is considered a physical board containing one or more logical board devices, and each channel or time slot on the board is a device. device channel: An Intel® Dialogic® voice data path that processes one incoming or outgoing call at a time (equivalent to the terminal equipment terminating a phone line). device driver: Software that acts as an interface between an application and hardware devices. device handle: Numerical reference to a device, obtained when a device is opened using xx_open( ), where xx is the prefix defining the device to be opened. The device handle is used for all operations on that device. device name: Literal reference to a device, used to gain access to the device via an xx_open( ) function, where xx is the prefix defining the device to be opened. DIALOG/HD (Dialogic High Density) boards: Refers to Intel® Dialogic® voice and telephone network interface resource boards having 8 or more ports. All DIALOG/HD boards use Board Locator Technology and can communicate via the TDM bus. Intel® Dialogic® Configuration Manager: See DCM. Voice API for Windows Operating Systems Library Reference — November 2002 177 digitize: The process of converting an analog waveform into a digital data set. DM3: Refers to Intel® Dialogic® mediastream processing architecture, which is open, layered, and flexible, encompassing hardware as well as software components. A whole set of products from Intel are built on DM3 architecture. Contrast with Springware which is earlier-generation architecture. download: The process where board level program instructions and routines are loaded during board initialization to a reserved section of shared RAM. downloadable Springware firmware: Software features loaded to Intel® Dialogic® voice hardware. Features include voice recording and playback, enhanced voice coding, tone detection, tone generation, dialing, call progress analysis, voice detection, answering machine detection, speed control, volume control, ADSI support, automatic gain control, and silence detection. driver: A software module which provides a defined interface between an application program and the firmware interface. DSP (Digital Signal Processor): A specialized microprocessor designed to perform speedy and complex operations on digital signals. DTMF (Dual-Tone Multi-Frequency): Push-button or touch-tone dialing based on transmitting a high- and a low-frequency tone to identify each digit on a telephone keypad. E-1: A CEPT digital telephony format devised by the CCITT, used in Europe and other countries around the world. A digital transmission channel that carries data at the rate of 2.048 Mbps (DS-1 level). CEPT stands for the Conference of European Postal and Telecommunication Administrations. Contrast with T-1. echo: The component of an analog device’s receive signal reflected into the analog device’s transmit signal. echo cancellation: Removal of echo from an echo-carrying signal. emulated device: A virtual device whose software interface mimics the interface of a particular physical device, such as a D/4x boards that is emulated by a D/12x or a D/xxxSC board. On a functional level, a D/12x board is perceived by an application as three D/4x boards. Contrast with physical device. event: An unsolicited or asynchronous message from a hardware device to an operating system, application, or driver. Events are generally attention-getting messages, allowing a process to know when a task is complete or when an external event occurs. event handler: A portion of an application program designed to trap and control processing of device-specific events. extended attribute functions: A class of functions that take one input parameter (a valid Intel® Dialogic® device handle) and return device-specific information. For instance, a voice device’s extended attribute function returns information specific to the voice devices. Extended attribute function names are case-sensitive and must be in capital letters. See also Standard Runtime Library. firmware: A set of program instructions that reside on an expansion board. firmware load file: The firmware file that is downloaded to a voice board. 178 Voice API for Windows Operating Systems Library Reference — November 2002 flash: A signal generated by a momentary on-hook condition. This signal is used by the voice hardware to alert a telephone switch that special instructions will follow. It usually initiates a call transfer. See also hook state. frequency shift keying (FSK): A frequency modulation technique used to send digital data over voice band telephone lines. G.726: An international standard for encoding 8 kHz sampled audio signals for transmission over 16, 24, 32 and 40 kbps channels. The G.726 standard specifies an adaptive differential pulse code modulation (ADPCM) system for coding and decoding samples. GSM: A speech compression algorithm developed for the Global System for Mobile telecommunication (GSM), Europe’s popular protocol suite for digital cellular communication. hook state: A general term for the current line status of the channel: either on-hook or off-hook. A telephone station is said to be on-hook when the conductor loop between the station and the switch is open and no current is flowing. When the loop is closed and current is flowing, the station is off-hook. These terms are derived from the position of the old fashioned telephone set receiver in relation to the mounting hook provided for it. hook switch: The circuitry that controls the on-hook and off-hook state of the voice device telephone interface. I/O: Input-Output idle device: A device that has no functions active on it. in-band: The use of robbed-bit signaling (T-1 systems only) on the network. The signaling for a particular channel or time slot is carried within the voice samples for that time slot, thus within the 64 kbps (kilobits per second) voice bandwidth. in-band signaling: (1) In an analog telephony circuit, in-band refers to signaling that occupies the same transmission path and frequency band used to transmit voice tones. (2) In digital telephony, in-band means signaling transmitted within an 8-bit voice sample or time slot, as in T-1 “robbed-bit” signaling. kernel: A set of programs in an operating system that implement the system’s functions. loop: The physical circuit between the telephone switch and the voice processing board. loop current: The current that flows through the circuit from the telephone switch when the voice device is offhook. loop current detection: A voice driver feature that returns a connect after detecting a loop current drop. loop start: In an analog environment, an electrical circuit consisting of two wires (or leads) called tip and ring, which are the two conductors of a telephone cable pair. The CO provides voltage (called “talk battery” or just “battery”) to power the line. When the circuit is complete, this voltage produces a current called loop current. The circuit provides a method of starting (seizing) a telephone line or trunk by sending a supervisory signal (going off-hook) to the CO. loop-start interfaces: Devices, such as an analog telephones, that receive an analog electric current. For example, taking the receiver off-hook closes the current loop and initiates the calling process. Voice API for Windows Operating Systems Library Reference — November 2002 179 mu-law: (1) Pulse Code Modulation (PCM) algorithm used in digitizing telephone audio signals in T-1 areas. (2) The PCM coding and companding standard used in Japan and North America. See also A-law. off-hook: The state of a telephone station when the conductor loop between the station and the switch is closed and current is flowing. When a telephone handset is lifted from its cradle (or an equivalent condition occurs), the telephone line state is said to be off-hook. See also hook state. on-hook: Condition or state of a telephone line when a handset on the line is returned to its cradle (or an equivalent condition occurs). See also hook state. PBX: Private Branch Exchange. A small version of the phone company’s larger central switching office. A local premises or campus switch. PCM (Pulse Code Modulation): A technique used in DSP voice boards for reducing voice data storage requirements. Intel supports either mu-law PCM, which is used in North America and Japan, or A-law PCM, which is used in the rest of the world. physical device: A device that is an actual piece of hardware, such as a D/4x board; not an emulated device. See emulated device. polling: The process of repeatedly checking the status of a resource to determine when state changes occur. PSTN (or STN): Public (or Private) Switched Telephony Network resource: Functionality (for example, voice-store-and-forward) that can be assigned to a call. Resources are shared when functionality is selectively assigned to a call and may be shared among multiple calls. Resources are dedicated when functionality is fixed to the one call. resource board: An Intel® Dialogic® expansion board that needs a network or switching interface to provide a technology for processing telecommunications data in different forms, such as voice store-and-forward, speech recognition, fax, and text-to-speech. RFU: reserved for future use ring detect: The act of sensing that an incoming call is present by determining that the telephone switch is providing a ringing signal to the voice board. robbed-bit signaling: The type of signaling protocol implemented in areas using the T-1 telephony standard. In robbed-bit signaling, signaling information is carried in-band, within the 8-bit voice samples. These bits are later stripped away, or “robbed,” to produce the signaling information for each of the 24 time slots. route: Assign a resource to a time slot. sampling rate: Frequency at which a digitizer quantizes the analog voice signal. SCbus (Signal Computing Bus): A hardwired connection between Switch Handlers on SCbus-based products. SCbus is a third generation TDM (Time Division Multiplexed) resource sharing bus that allows information to be transmitted and received among resources over 1024 time slots. SCR: See Silence Compressed Record. 180 Voice API for Windows Operating Systems Library Reference — November 2002 signaling insertion: The signaling information (on hook/off hook) associated with each channel is digitized, inserted into the bit stream of each time slot by the device driver, and transmitted across the bus to another resource device. The network interface device generates the outgoing signaling information. silence compressed record: A recording that eliminates or limits the amount of silence in the recording without dropping the beginning of words that activate recording. silence threshold: The level that sets whether incoming data to the voice board is recognized as silence or nonsilence. SIT: (1) Standard Information Tones: tones sent out by a central office to indicate that the dialed call has been answered by the distant phone. (2) Special Information Tones: detection of a SIT sequence indicates an operator intercept or other problem in completing the call. solicited event: An expected event. It is specified using one of the device library’s asynchronous functions. Springware: Software algorithms build into the downloadable firmware that provides the voice processing features available on all Intel® Dialogic® voice boards. The term Springware is also used to refer to a whole set of boards from Intel built using this architecture. Contrast with DM3 which is newer-generation architecture. SRL: See Standard Runtime Library. standard attribute functions: Class of functions that take one input parameter (a valid device handle) and return generic information about the device. For instance, standard attribute functions return IRQ and error information for all device types. Standard attribute function names are case-sensitive and must be in capital letters. Standard attribute functions for all Intel® Dialogic® devices are contained in the SRL. See Standard Runtime Library. standard runtime library (SRL): An Intel® Dialogic® software resource containing event management and standard attribute functions and data structures used by all Intel® Dialogic® devices, but which return data unique to the device. station device: Any analog telephone or telephony device (such as a telephone or headset) that uses a loop-start interface and connects to an MSI/SC board. string: An array of ASCII characters. subdevice: Any device that is a direct child of another device. Since “subdevice” describes a relationship between devices, a subdevice can be a device that is a direct child of another subdevice, as a channel is a child of a board. synchronous function: Blocks program execution until a value is returned by the device. Also called a blocking function. Contrast with asynchronous function. system release: The software and user documentation provided by Intel that is required to develop applications. T-1: The digital telephony format used in North America and Japan. In T-1, 24 voice conversations are timedivision multiplexed into a single digital data stream containing 24 time slots. Signaling data are carried “in-band”; as all available time slots are used for conversations, signaling bits are substituted for voice bits in certain frames. Voice API for Windows Operating Systems Library Reference — November 2002 181 Hardware at the receiving end must use the “robbed-bit” technique for extracting signaling information. T-1 carries data at the rate of 1.544 Mbps (DS-1 level). TDM (Time Division Multiplexing): A technique for transmitting multiple voice, data, or video signals simultaneously over the same transmission medium. TDM is a digital technique that interleaves groups of bits from each signal, one after another. Each group is assigned its own “time slot” and can be identified and extracted at the receiving end. See also time slot. TDM bus: Time division multiplexing bus. A resource sharing bus such as the SCbus or CT Bus that allows information to be transmitted and received among resources over multiple data lines. See also TDM. termination condition: An event or condition which, when present, causes a process to stop. termination event: An event that is generated when an asynchronous function terminates. See also asynchronous function. time division multiplexing (TDM): See TDM. time slot: The smallest, switchable data unit on a TDM bus. A time slot consists of 8 consecutive bits of data. One time slot is equivalent to a data path with a bandwidth of 64 Kbps. In a digital telephony environment, a normally continuous and individual communication (for example, someone speaking on a telephone) is (1) digitized, (2) broken up into pieces consisting of a fixed number of bits, (3) combined with pieces of other individual communications in a regularly repeating, timed sequence (multiplexed), and (4) transmitted serially over a single telephone line. The process happens at such a fast rate that, once the pieces are sorted out and put back together again at the receiving end, the speech is normal and continuous. Each individual, pieced-together communication is called a time slot. time slot assignment: The ability to route the digital information contained in a time slot to a specific analog or digital channel on an expansion board. See also device channel. transparent signaling: The mode in which a network interface device accepts signaling data from a resource device transparently, or without modification. In transparent signaling, outgoing T-1 signaling bits are generated by a TDM bus resource device. In effect the resource device performs signaling to the network. virtual board: The device driver views a single physical voice board with more than four channels as multiple emulated D/4x boards. These emulated boards are called virtual boards. For example, a D120JCTLS has 12 channels of voice processing and contains 3 virtual boards. voice processing: The science of converting human voice into data that can be reconstructed and played back at a later time. voice system: A combination of expansion boards and software that lets you develop and run voice processing applications. wink: In T-1 or E-1 systems, a signaling bit transition from on to off, or off to on, and back again to the original state. In T-1 systems, the wink signal can be transmitted on either the A or B signaling bit. In E-1 systems, the wink signal can be transmitted on either the A, B, C, or D signaling bit. Using either system, the choice of signaling bit and wink polarity (on-off-on or off-on-off hook) is configurable through DTI/xxx board download parameters. 182 Voice API for Windows Operating Systems Library Reference — November 2002 Index A C Adaptive Differential Pulse Code Modulation 80 address signals, R2/MF signaling 157 ADPCM, G.726 80 A-law PCM 79 Analog Display Services Interface (ADSI) 19, 105 answering machine detection 56 asynchronous programming model 21 ATDV_ERRMSGP( ) 29 ATDV_LASTERR( ) 29 ATDX_CONNTYPE( ) connection types returned 55 ATDX_CPTERM( ) 46 ATDX_CRTNID( ) 55 ATDX_FRQDUR( ) use in SIT detection 64 ATDX_FRQDUR2( ) use in SIT detection 65 ATDX_FRQDUR3( ) use in SIT detection 65 ATDX_FRQHZ( ) use in single-tone detection 66 use in SIT detection 64 ATDX_FRQHZ2( ) use in SIT detection 64 ATDX_FRQHZ3( ) use in SIT detection 65 ATDX_TERMMSK( ) 139 automated attendant 170 C language interfaces 172 cached prompt management 123 device discovery 123 downloading prompts 124 hints 125 physical board handle 124 playing prompts 124 sample application 125 cadence detection, call progress analysis 44, 68 cadenced tone generation 141 custom tone 141 dx_playtoneEx( ) 141 call outcome, determining 48 B backward signals (CCITT Signaling System tones) 159 backward signals (CCITT signaling system tones) 157 basic call progress analysis 43 beginthread( ) 170 busy state 31 busy tone 145 busy tone detection 55 busy verification tone 145 Voice API for Windows Operating Systems Programming Guide — November 2002 183 call progress analysis 43 activating 48 ATDX_CPERROR( ) 67 ATDX_CPTERM( ) 46 cadence detection 44 call outcomes 48 components 45 dial tone detection 53 disabling 48 DM3 scenarios 51 DX_CAP parameter structure 46 errors 67 extended attribute functions 49 fax machine detection 57 features 44 frequency detection 44, 61 errors 65 initiating 48 loop current detection 44 modem detection 57 obtaining additional information 49 outcomes 49 positive voice detection 44, 55 results 48 ringback detection 54 SIT tones 61 termination results 48 tone definitions 60 tone detection 52 tone template DM3 59 Springware 60 tone types 52 tri-tone frequency detection parameters 62 types 43 use of global tone detection 60 call progress signals PBX 143 call status transition event handling asynchronous 132 synchronous 132 call waiting tone 145 call waiting) 145 caller ID accessing information 119 enabling 120 error handling 120 support 117 supported formats 117 CCITT Signaling System R2/MF tones 158 channel definition 23 184 CLASS 117 cluster configuration 35 coders 79 compelled signaling, R2/MF 165 compile-time linking 172 compiling library files 172 variables 173 CON_CAD connection type 54 CON_LPC connection type 59 CON_PAMD connection type 56 CON_PVD connection type 55 configuration fixed/flexible routing 34 confirmation tone 145 continuous tone 143 convenience functions dx_wtcallid( ) 119 speed and volume 97 coupled resources 35 CP_BUSY 145 CP_BUSY_VERIFY_A 145 CP_BUSY_VERIFY_B 145 CP_CALLWAIT1 145 CP_CALLWAIT2 145 CP_DIAL 145 CP_EXEC_OVERRIDE 145 CP_FEATURE_CONFIRM 145 CP_INTERCEPT 145 CP_MSG_WAIT_DIAL 145 CP_RECALL_DIAL 145 CP_REORDER 145, 148 CP_RINGBACK1 145 CP_RINGBACK1_CALLWAIT 145 CP_RINGBACK2 145 CP_RINGBACK2_CALLWAIT 145 CP_STUTTER_DIAL 145 CR_BUSY 48 CR_CEPT 48 CR_CNCT 48 CR_FAXTONE 49 CR_LGTUERR 67 CR_MEMERR 67 CR_MXFRQERR 67 CR_NOANS 49 CR_NODIALTONE 49 CR_NORB 49 Voice API for Windows Operating Systems Programming Guide — November 2002 CR_OVRLPERR 67 CR_STOPD 49 CR_TMOUTOFF 67 CR_TMOUTON 67 CR_UNEXPTN 67 CR_UPFRQERR 67 custom cadenced tone 141 Custom Local Area Signaling Services 117 cycle 141 D data formats 79 data structures clearing 34 DDI (Direct Dialing-In) service 158 DE_WINK event 41 device definition 23 handle for 23 device name definition 23 devices initializing hint 38 states of 31 dial pulse detection 17 see Global DPD 151 dial tone 145 detection 53 dial tone (message waiting) 145 dial tone (recall) 145 dial tone (stutter) 145 Dialed Number Identification Service 158 DID (Direct Inward Dialing) service 158 digitizing methods 79 disabling call progress analysis 48 disconnect supervision 138 disconnect tone supervision 57 DM_WINK 41 DM3 call progress analysis scenarios 51 considerations 36 tone definitions 59 DM3 application considerations 36 DNIS (Dialed Number Identification Service) 158 DV_TPT data structure clearing 34 setting termination conditions 32 dx_addspddig( ) 97 dx_addtone( ) 138 use in global tone detection 130 use with tone templates 132 dx_addvoldig( ) 97 dx_adjsv( ) 98, 102 dx_blddt( ) 131 dx_blddtcad( ) 131 dx_bldst( ) 131 dx_bldstcad( ) 131 dx_bldtngen( ) 139 DX_CAP data structure 46, 56 clearing 34 SIT tone setup 62 dx_chgdur( ) 61 dx_chgfreq( ) 61 dx_chgrepcnt( ) 61 dx_clrcap( ) 34, 46 dx_clrtpt( ) 34 dx_deltones( ) 48 use with tone templates 132 dx_dial( ) 46, 48 DM3 support 51 Springware support 51 dx_distone( ) 132 dx_enbtone( ) 132 dx_getcachesize( ) 124 dx_getdig( ) 102 use in global tone detection 130 dx_getevt( ) 133 dx_getsvmt( ) 99 dx_getxmitslot( ) 86 dx_getxmitslotecr( ) 86 dx_gtcallid( ) 119 dx_gtextcallid( ) 119 dx_initcallp( ) 46, 47 dx_listen( ) 86 dx_mreciottdata( ) 81 dx_play( ) 78, 106 dx_playf( ) 78, 106 dx_playiottdata( ) 80 dx_playtone( ) 139 dx_playtoneEx( ) cadenced tone generation 141 dx_playvox( ) 78 dx_rec( ) 78, 82 dx_recf( ) 78 dx_reciottdata( ) 80 dx_recvox( ) 78 Voice API for Windows Operating Systems Programming Guide — November 2002 185 dx_RxIottData( ) 106 dx_setevtmsk( ) 41, 133 dx_setgtdamp( ) 131 dx_sethook( ) 41 dx_setparm( ) enabling caller ID 120 dx_setsvcond( ) 98, 102 dx_setsvmt( ) 99, 102 DX_SVCB data structure 102 DX_SVMT data structure 102 dx_TSFstatus( ) 59 dx_TxIottData( ) 106 dx_TxRxIottData( ) 106 dx_unlistenecr( ) 86 dx_wtcallid( ) 119 DXBD_OFFHDLY 41 DXCH_MAXRWINK 41 DXCH_MINRWINK 41 DXCH_WINKDLY 41 DXCH_WINKLEN 41 dxxxlib.h 172 fixed routing configuration 34 configuration, restrictions 36 flexible routing configuration 34 forward signals (CCITT signaling system tones) 157, 158 frequency detection 44 used in call progress analysis 61 frequency duration 50 frequency shift keying (FSK) 19, 105 functions error 29 G echo cancellation resource (ECR) 84 application models 88 modes of operation 86 echo component 85 echo reference signal 85 echo-carrying signal 84 ECR 84 ECR mode, echo canceller 87 encoding algorithms 79 G.726 80 encoding algorithms, support in SCR 83 enhanced call analysis 16 error handling in caller ID 120 errors 29 event management functions 25 events categories 25 executive override tone 145 extended attribute functions, use in call progress analysis 49 G.711 PCM A-law voice coder 80 G.711 PCM mu-law voice coder 80 G.721 voice coder 79 G.726 bit exact voice coder 79, 80 G.726 voice coder 80 global dial pulse detection 17, 151 global DPD 17, 151 enabling 153 example code 154 improving detection 153 global tone detection applications 138 building tone templates 130 call progress analysis memory usage 65 defining GTD tones 130 defining tones 130 definition 129 disconnect supervision 138 functions with which GTD cannot work 138 leading edge detection 138 maximum number of tones 135, 136 R2/MF 167 using with PBX 138 with caller ID 117 global tone generation cadenced 141 definition 139 R2/MF 167 TN_GEN data structure 139 tone generation template 139 GSM 6.10 full rate voice coder 79, 80 F H fast busy 145 fax machine detection 57 header files voice and SRL 172 E 186 Voice API for Windows Operating Systems Programming Guide — November 2002 hot swap cached prompts 125 I I/O functions terminations 31 idle state 31 include files voice and SRL 172 incoming register 161 incoming register, R2/MF signaling 157 incoming signals, indicating 161 independent resources 35 infinite tone 143 INTEL_DIALOGIC_INC 173 INTEL_DIALOGIC_LIB 173 intercept tone 145 interregister signals, R2/MF signaling 157 L leading edge detection using debounce time 138 libdxxmt.lib 172 library files 172 libsrlmt.lib 172 line signals, R2/MF signaling 158 linear PCM 79, 80 linking library files 172 variables 173 loop current detection parameters affecting a connect 58 use in call progress analysis 44, 58 M media loads 38 memory requirements, R2/MF 168 message waiting dial tone 145 modem detection 57 mu-law PCM 79 N named event 170 non-cadenced tone 143 O OKI ADPCM 79, 80 one-way ADSI implementing 111 technical overview 110 operator intercept SIT tones 61 outgoing register 157 outgoing register,R2/MF signaling 157 P PAMD 56 PAMD See Positive Answering Machine Detection 56 PAMD_ACCU 56 PAMD_FULL 56 PAMD_QUICK 56 parameter files, voice.prm 82 patent license Syntellect 169 PBX standard call progress signals 143 PBX call progress signals cadenced tone generation 141 PBX Expert utility 59 physical board definition 23 playback 77 positive answering machine detection 44, 56 positive voice detection 44 positive voice detection using call progress analysis 55 Private Branch Exchange (PBX) Switching Equipment requirements 149 programming models 21 prompts, cached 123 R R2/MF signaling backward signals 159, 161 compelled signaling 165 DDI (Direct Dialing-In) service 158 DNIS (Dialed Number Identification Service) 158 forward signals 158 Group I and II signals 160 incoming register 157 maximum number of tones 168 multifrequency combinations 158 signal meanings 159 Voice board support 167 Voice API for Windows Operating Systems Programming Guide — November 2002 187 r2_creatfsig( ) use in R2/MF signaling 167 r2_playbsig( ) use in R2/MF signaling 167 R4 on DM3 considerations 36 recall dial tone 145 recording 77 with silence compression 81 reorder tone 145 resources, coupled/independent 35 ringback detection 54 ringback tone 145 ringback tone (call waiting) 145 ringback tone (slow 145 ringback tone (slow) 145 routing configuration (fixed/flexible) overview 34 run-time linking 173 S segment 141 signals custom cadenced 141 predefined standard PBX call progress 143 silence compressed record (SCR) 18, 81 SIT tones call progress analysis parameter setup 62 detection using call progress analysis 61 effect on GTD tones 65 frequency information 66 memory usage for detection 65 tone sequences 62 using extended attribute functions 64 slow busy 145 special information tones 61 speed and volume control adjustment digits 102 speed control adjustment functions 98 convenience functions 97 explicitly adjusting 102 modification tables 98 on DM3 boards 100 setting adjustment conditions 102 Springware tone definitions 60 sr_getevtdatap( ) 133 SRLGetAllPhysicalBoards( ) 123 188 SRLGetPhysicalBoardName( ) 123 srllib.h 172 Standard Runtime Library definition 21 event management functions 25 Standard Runtime Library (SRL) 171 standard voice processing (svp) mode 86 standard voice processing (SVP) mode, echo canceller 87 states 31 STC boards 170 Syntellect Technology Corporation 169 structures clearing 34 stutter dial tone 145 SVMT table 98 SVP mode, echo canceller 87 synchronous programming 170 synchronous programming model 21 Syntellect patent license 169 T talk-off rejection 153 TDM bus application considerations 39 TDX_CACHEPROMPT event 124 TDX_CST events 133 termination conditions 31 byte transfer count 32 dx_stopch( ) occurred 32 end of file reached 32 loop current drop 32 maximum delay between digits 32 maximum digits received 33 maximum function time 33 maximum length of non-silence 33 maximum length of silence 33 pattern of silence and non-silence 33 specific digit received 33 user-defined digit received 34 user-defined tone on/tone off event detected 34 user-defined tones 133 thread 170 TIA/EIA Standard 149 TID_BUSY1 55 TID_BUSY2 55 TN_GEN data structure 139 TN_GENCAD data structure 141, 143 Voice API for Windows Operating Systems Programming Guide — November 2002 tone continuous 143 tone definition 141 tone definitions 60 DM3 59 Springware 60 tone detection call progress analysis 52 tone generation cadenced 141 tone set file 59 tone template DM3 59 Springware 60 tone templates 130 functions used 132 tone types call progress analysis 52 tones custom cadenced 141 maximum number for global tone detection 135 maximum number for global tonedetection 136 predefined standard PBX 143 transaction record 81 TrueSpeech voice coder 79 trunks busy 145 two-way ADSI 108 implementing 113, 114 technical overview 112 two-way FSK 108 volume control adjustment functions 98 convenience functions 97 explicitly adjusting 102 modification tables 98 on DM3 boards 101 setting adjustment conditions 102 VPIM 80 W wink inbound 41 setting delay 40 setting duration 41 U user-defined tones tp_data 133 tp_termno 133 V variables compiling and linking 173 virtual board definition 23 voice coders 79 voice encoding methods 79 voice library 171 voice profile for internet messaging (VPIM) 80 voice.prm 82 Voice API for Windows Operating Systems Programming Guide — November 2002 189 190 Voice API for Windows Operating Systems Programming Guide — November 2002
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.3 Linearized : No Producer : Acrobat Distiller 4.05 for Windows Create Date : 2002:11:18 09:46:03 Creator : FrameMaker 6.0 Subject : Author : Title : Voice API for Windows Operating Systems Programming Guide Modify Date : 2002:11:18 12:24:38-05:00 Page Count : 190 Page Mode : UseOutlinesEXIF Metadata provided by EXIF.tools