Intel 52377002 Revision History

Voice API Programming Guide — June 2005 11

Revision History

This revision history summarizes the changes made in each published version of this document.

Document No. Publication Date Description of Revisions

05-2377-002 June 2005 Application Development Guidelines chapter: Added bullet about digits not always

being cleared by dx_clrdigbuf() in Tone Detection Considerations section [PTR

33806].

Call Progress Analysis chapter: Added eight new SIT sequences that can be

returned by ATDX_CRTNID() for DM3 boards in Types of Tones section.

Revised values of TID_SIT_NC (Freq of first segment changed from 950/1001 to

950/1020) and TID_SIT_VC (Freq of first segment changed from 950/1001 to

950/1020) in table of Special Information Tone Sequences (DM3); also added

four new SIT sequences to this table. Added note about SRL device mapper

functions in Steps to Modify a Tone Definition on DM3 Boards section.

Recording and Playback chapter: Added Recording with the Voice Activity Detector

section that describes new modes for dx_reciottdata().

Send and Receive FSK Data chapter: Updated Fixed-Line Short Message Service

(SMS) section to indicate that fixed-line short message service (SMS) is

supported on Springware boards. Updated Library Support on Springware

Boards section to indicate that Springware boards in Linux support ADSI two-

way FSK and SMS.

Cached Prompt Management chapter: Added sentence to second paragraph about

flushing cached prompts in Overview of Cached Prompt Management section.

Added second paragraph about flushing cached prompts in Cached Prompt

Management Hints and Tips section.

05-2377-001 November 2004 Initial version of document. Much of the information contained in this document was

previously published in the Voice API for Linux Operating System Programming

Guide (document number 05-1829-001) and the Voice API for Windows Operating

Systems Programming Guide (document number 05-1831-002).

This document now supports both Linux and Windows operating systems. When

information is specific to an operating system, it is noted.

Contents

Main Voice API Programming Guide June 2005 Contents Page Page Page Page Page Figures Tab le s Revision History This revision history summarizes the changes made in each published version of this document. Page About This Publication Purpose Applicability Intended Audience How to Use This Publication Related Information Page 1.1 Overview 1.2 R4 API 1.3 Call Progress Analysis 1.4 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 1.5 Dial Pulse Detection 1.6 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 Streaming to Board 1.7 Send and Receive FSK Data 1.8 Caller ID 1.9 R2/MF Signaling 1.10 TDM Bus Routing 2.1 Standard Runtime Library 2.2 Asynchronous Programming Models 2.3 Synchronous Programming Model Page 3.1 Device Concepts 3.2 Voice Device Names Page 4.1 Overview of Event Handling 4.2 Event Management Functions Table2. Voice Device Returns from Event Management Functions Page Page Guidelines 6.1 General Considerations 6.1.1 Busy and Idle States 6.1.2 Setting Termination Conditions for I/O Functions Page 6.1.3 Setting Termination Conditions for Digits 6.1.4 Clearing Structures Before Use 6.1.5 Working with User-Defined I/O Functions 6.2 Fixed and Flexible Routing Configurations Fixed Routing (Coupled Resources) Flexible Routing (Independent Resources) 6.3 Fixed Routing Configuration Restrictions 6.4 Additional DM3 Considerations 6.4.1 Call Control Through Global Call API Library 6.4.2 Multithreading and Multiprocessing 6.4.3 DM3 Media Loads 6.4.4 Device Discovery for DM3 and Springware 6.4.5 Device Initialization Hint 6.4.6 TDM Bus Time Slot Considerations 6.4.7 Tone Detection Considerations 6.5 Using Wink Signaling 6.5.1 Setting Delay Prior to Wink 6.5.2 Setting Wink Duration 6.5.3 Receiving an Inbound Wink 7.1 Call Progress Analysis Overview 7.2 Call Progress and Call Analysis Terminology 7.3 Call Progress Analysis Components Page 7.4 Using Call Progress Analysis on DM3 Boards 7.4.1 Call Progress Analysis Rules on DM3 Boards 7.4.2 Overview of Steps to Initiate Call Progress Analysis 7.4.3 Setting Up Call Progress Analysis Parameters in DX_CAP 7.4.4 Executing a Dial Function 7.4.5 Determining the Outcome of a Call 7.4.6 Obtaining Additional Call Outcome Information 7.5 Call Progress Analysis Tone Detection on DM3 Boards 7.5.1 Tone Detection Overview 7.5.2 Types of Tones 7.5.3 Ringback Detection 7.5.4 Busy Tone Detection 7.5.5 Fax or Modem Tone Detection 7.5.6 SIT Frequency Detection Page 7.6 Media Tone Detection on DM3 Boards 7.6.1 Positive Voice Detection (PVD) 7.6.2 Positive Answering Machine Detection (PAMD) 7.7 Default Call Progress Analysis Tone Definitions on DM3 Boards 7.8 Modifying Default Call Progress Analysis Tone Definitions on DM3 Boards 7.8.1 API Functions for Manipulating Tone Definitions 7.8.2 TONE_DATA Data Structure 7.8.3 Rules for Modifying a Tone Definition on DM3 Boards 7.8.4 Rules for Using a Single Tone Proxy for a Dual Tone 7.8.5 Steps to Modify a Tone Definition on DM3 Boards 7.9 Call Progress Analysis Errors 7.10 Using Call Progress Analysis on Springware Boards 7.10.1 Overview of Steps to Initiate Call Progress Analysis 7.10.2 Setting Up Call Progress Analysis Features in DX_CAP 7.10.3 Enabling Call Progress Analysis 7.10.4 Executing a Dial Function 7.10.5 Determining the Outcome of a Call 7.10.6 Obtaining Additional Call Outcome Information 7.11 Call Progress Analysis Tone Detection on Springware Boards 7.11.1 Tone Detection Overview 7.11.2 Types of Tones 7.11.3 Dial Tone Detection 7.11.4 Ringback Detection 7.11.5 Busy Tone Detection 7.11.6 Fax or Modem Tone Detection 7.11.7 Loop Current Detection 7.11.7.1 Loop Current Detection Parameters Affecting a Connect 7.12 Media Tone Detection on Springware Boards 7.12.1 Positive Voice Detection (PVD) 7.12.2 Positive Answering Machine Detection (PAMD) 7.13 Default Call Progress Analysis Tone Definitions on Springware Boards 7.14 Modifying Default Call Progress Analysis Tone Definitions on Springware Boards 7.15 SIT Frequency Detection (Springware Only) 7.15.1 Tri-Tone SIT Sequences 7.15.2 Setting Tri-Tone SIT Frequency Detection Parameters General First Tone Second Tone Third Tone 7.15.3 Obtaining Tri-Tone SIT Frequency Information 7.15.4 Global Tone Detection Tone Memory Usage 7.15.5 Frequency Detection Errors 7.15.6 Setting Single Tone Frequency Detection Parameters 7.15.7 Obtaining Single Tone Frequency Information 7.16 Cadence Detection in Basic Call Progress Analysis (Springware Only) 7.16.1 Overview 7.16.2 Typical Cadence Patterns 7.16.3 Elements of a Cadence Page 7.16.4 Outcomes of Cadence Detection 7.16.5 Setting Selected Cadence Detection Parameters 7.16.5.1 General Cadence Detection Parameters 7.16.5.2 Cadence Detection Parameters Affecting a No Ringback 7.16.5.3 Cadence Detection Parameters Affecting a No Answer or Busy 7.16.5.4 Cadence Detection Parameters Affecting a Connect Page 7.16.6 Obtaining Cadence Information 8.1 Overview of Recording and Playback 8.2 Digital Recording and Playback 8.3 Play and Record Functions 8.4 Play and Record Convenience Functions 8.5 Voice Encoding Methods Page 8.6 G.726 Voice Coder 8.7 Transaction Record 8.8 Silence Compressed Record 8.8.1 Overview 8.8.2 Enabling 8.8.3 Encoding Methods Supported 8.9 Recording with the Voice Activity Detector 8.9.1 Overview 8.9.2 Enabling 8.9.3 Encoding Methods Supported 8.10 Streaming to Board 8.10.1 Streaming to Board Overview 8.10.2 Streaming to Board Functions 8.10.3 Implementing Streaming to Board 8.10.4 Streaming to Board Hints and Tips 8.11 Pause and Resume Play 8.11.1 Pause and Resume Play Overview 8.11.2 Pause and Resume Play Functions 8.11.3 Implementing Pause and Resume Play 8.11.4 Pause and Resume Play Hints and Tips 8.12 Echo Cancellation Resource 8.12.1 Overview of Echo Cancellation Resource 8.12.2 Echo Cancellation Resource Operation Page 8.12.3 Modes of Operation 8.12.3.1 Overview of Modes 8.12.3.2 Standard Voice Processing (SVP) Mode 8.12.3.3 Echo Cancellation Resource (ECR) Mode 8.12.4 Echo Cancellation Resource Application Models 8.12.4.1 How to Set Up the ECR Bridge 106 Voice API Programming Guide June 2005 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); Example Page Page 8.12.4.2 How to Set Up an ECR Play Over the TDM bus Figure 18. An ECR Play Over the TDM bus Example Page Page 9.1 Speed and Volume Control Overview 9.2 Speed and Volume Convenience Functions 9.3 Speed and Volume Adjustment Functions 9.4 Speed and Volume Modification Tables Page Page Page 9.5 Play Adjustment Digits 9.6 Setting Play Adjustment Conditions 9.7 Explicitly Adjusting Speed and Volume Page Page 10.1 Overview of ADSI and Two-Way FSK Support 10.2 ADSI Protocol 10.3 ADSI Operation 10.4 One-Way ADSI 10.5 Two-Way ADSI 10.5.1 Transmit to On-Hook CPE 10.5.2 Two-Way FSK 10.6 Fixed-Line Short Message Service (SMS) 10.7 ADSI and Two-Way FSK Voice Library Support 10.7.1 Library Support on DM3 Boards 10.7.2 Library Support on Springware Boards 10.8 Developing ADSI Applications 10.8.1 Technical Overview of One-Way ADSI Data Transfer 10.8.2 Implementing One-Way ADSI Using dx_TxIottData( ) Page 10.8.3 Technical Overview of Two-Way ADSI Data Transfer 10.8.4 Implementing Two-Way ADSI Using dx_TxIottData( ) 10.8.5 Implementing Two-Way ADSI Using dx_TxRxIottData( ) 10.9 Modifying Older One-Way ADSI Applications Page 11.1 Overview of Caller ID 11.2 Caller ID Formats Page 11.3 Accessing Caller ID Information 11.4 Enabling Channels to Use the Caller ID Feature 11.5 Error Handling 11.6 Caller ID Technical Specifications Page Page 12.1 Overview of Cached Prompt Management 12.2 Using Cached Prompt Management 12.2.1 Discovering Cached Prompt Capability 12.2.2 Downloading Cached Prompts to a Board 12.2.3 Playing Cached Prompts 12.2.4 Recovering from Errors 12.2.5 Cached Prompt Management Hints and Tips 12.3 Cached Prompt Management Example Code Page Cached Prompt Management Generation, and Cadenced Tone Generation 13.1 Global Tone Detection (GTD) 13.1.1 Overview of Global Tone Detection 13.1.2 Global Tone Detection on DM3 Boards versus Springware Boards 13.1.3 Defining Global Tone Detection Tones 13.1.4 Building Tone Templates API Library Functions Instructions for Building Tone Templates Tips and Hints for Building Tone Templates 13.1.5 Working with Tone Templates 13.1.6 Retrieving Tone Events 13.1.7 Setting GTD Tones as Termination Conditions 13.1.8 Maximum Amount of Memory for Tone Templates 13.1.9 Estimating Memory 13.1.10 Guidelines for Creating User-Defined Tones Page 13.1.11 Global Tone Detection Application 13.2 Global Tone Generation (GTG) 13.2.1 Using GTG 13.2.2 GTG Functions 13.2.3 Building and Implementing a Tone Generation Template 13.3 Cadenced Tone Generation 13.3.1 Using Cadenced Tone Generation 13.3.2 How To Generate a Custom Cadenced Tone Page Figure 19. Example of Custom Cadenced Tone Generation and no off time. 13.3.3 How To Generate a Non-Cadenced Tone 13.3.4 TN_GENCAD Data Structure - Cadenced Tone Generation 13.3.5 How To Generate a Standard PBX Call Progress Signal 13.3.6 Predefined Set of Standard PBX Call Progress Signals Table19. Standard PBX Call Progress Signals Figure 20. Standard PBX Call Progress Signals (Part 1) Figure 21. Standard PBX Call Progress Signals (Part 2) Table20. TN_GENCAD Definitions for Standard PBX Call Progress Signals 13.3.7 Important Considerations for Using Predefined Call Progress Signals Page Page 14.1 Key Features 14.2 Global DPD Parameters 14.3 Enabling Global DPD 14.4 Global DPD Programming Considerations 14.5 Retrieving Digits from the Digit Buffer 14.6 Retrieving Digits as Events 14.7 Dial Pulse Detection Digit Type Reporting 14.8 Defines for Digit Type Reporting 14.9 Global DPD Programming Procedure 14.10 Global DPD Example Code Global Dial Pulse Detection 15.1 R2/MF Overview 15.2 Direct Dialing-In Service 15.3 R2/MF Multifrequency Combinations 15.4 R2/MF Signal Meanings Table22. Backward Signals, CCITT Signaling System R2/MF tones Table21. Forward Signals, CCITT Signaling System R2/MF tones (Continued) Page Page Table24. Meanings for R2/MF Group I Forward Signals Table25. Meanings for R2/MF Group II Forward Signals Table26. Meanings for R2/MF Group A Backward Signals 15.5 R2/MF Compelled Signaling Page 15.6 R2/MF Voice Library Functions 15.7 R2/MF Tone Detection Template Memory Requirements Attendant 16.1 Overview of Automated Attendant Function 16.2 Syntellect License Automated Attendant Functions 16.3 How to Use the Automated Attendant Function Call 17.1 Voice and SRL Libraries 17.2 Compiling and Linking 17.2.1 Include Files 17.2.2 Required Libraries Linux Windows 17.2.3 Run-time Linking 17.2.4 Variables for Compiling and Linking Page Glossary Page Page Page Page Page Page Page Index A B C D E F G H I L M N O P R S T U V W