Intel 05-1832-002 User Manual
Voice API for Windows Operating
Systems
Library Reference
November 2003
05-1832-002
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 Library Reference 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 par t 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-2003, Intel Corporation
AnyPoint, BoardWatch, BunnyPeople, CablePort, Celeron, Chips, CT Media, Dialogic, DM3, EtherExpress, ETOX, FlashFile, i386, i486, i960, iCOMP,
InstantIP, Intel, Intel Centrino, Intel Centrino logo, Intel logo, Intel386, Intel486, Intel740, IntelDX2, IntelDX4, IntelSX2, Intel InBusiness, Intel Inside,
Intel Inside logo, Intel NetBurst, Intel NetMerge, Intel NetStructure, Intel SingleDriver, Intel SpeedStep, Intel StrataFlash, Intel TeamStation, Intel Xeon,
Intel XScale, IPLink, Itanium, MCS, MMX, MMX logo, Optimizer logo, OverDrive, Paragon, PDCharm, Pentium, Pentium II Xeon, Pentium III Xeon,
Performance at Your Command, RemoteExpress, SmartDie, Solutions960, Sound Mark, StorageExpress, The Computer Inside., The Journey Inside,
TokenExpress, 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 2003
Document Number: 05-1832-002
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 Telecom Products website at:
http://www.intel.com/design/network/products/telecom
For Sales Offices and other contact information, visit the Where to Buy Intel Telecom Products page at:
http://www.intel.com/buy/wtb/wtb1028.htm
Voice API for Windows Operating Systems Library Reference – November 2003
Contents
Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
About This Publication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
How to Use This Publication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Related Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
1 Function Summary by Category . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
1.1 Device Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
1.2 Configuration Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
1.3 I/O Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
1.4 I/O Convenience Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
1.5 Streaming to Board Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
1.6 Analog Display Services Interface (ADSI) Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
1.7 Audio Input Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
1.8 Transaction Record Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
1.9 Cached Prompt Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
1.10 Call Status Transition (CST) Event Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
1.11 TDM Routing Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
1.12 Global Tone Detection (GTD) Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
1.13 Global Tone Generation (GTG) Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
1.14 R2/MF Convenience Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
1.15 Speed and Volume Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
1.16 Call Progress Analysis Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
1.17 Caller ID Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
1.18 File Manipulation Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
1.19 Echo Cancellation Resource Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
1.20 Structure Clearance Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
1.21 Syntellect License Automated Attendant Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
1.22 Extended Attribute Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
1.23 Voice Function Support by Platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
2 Function Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
2.1 Function Syntax Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
ag_getctinfo( ) – get information about an analog device. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
ag_getxmitslot( ) – get TDM bus time slot number of analog transmit channel . . . . . . . . . . . . . . 38
ag_listen( ) – connect analog receive channel to TDM bus time slot . . . . . . . . . . . . . . . . . . . . . . 41
ag_unlisten( ) – disconnect analog receive channel from TDM bus . . . . . . . . . . . . . . . . . . . . . . . 44
ai_close( ) – close an audio input device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
ai_getxmitslot( ) – get TDM bus time slot number of audio input transmit channel . . . . . . . . . . . 48
ai_open( ) – open an audio input device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
ATDX_ANSRSIZ( ) – return the duration of the answer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
ATDX_BDNAMEP( ) – return a pointer to the board device name . . . . . . . . . . . . . . . . . . . . . . . . 54
ATDX_BDTYPE( ) – return the board type for the device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Voice API for Windows Operating Systems Library Reference – November 2003 3
Contents
ATDX_BUFDIGS( ) – return the number of uncollected digits . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
ATDX_CHNAMES( ) – retrieve all channel names for a board . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
ATDX_CHNUM( ) – return the channel number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
ATDX_CONNTYPE( ) – return the connection type for a completed call . . . . . . . . . . . . . . . . . . . 64
ATDX_CPERROR( ) – return the call progress analysis error . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
ATDX_CPTERM( ) – return the last result of call progress analysis termination . . . . . . . . . . . . . 70
ATDX_CRTNID( ) – return the last call progress analysis termination . . . . . . . . . . . . . . . . . . . . . 73
ATDX_DEVTYPE( ) – return the device type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
ATDX_DTNFAIL( ) – return character for dial tone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
ATDX_FRQDUR( ) – return the duration of the first SIT sequence. . . . . . . . . . . . . . . . . . . . . . . . 81
ATDX_FRQDUR2( ) – return the duration of the second SIT sequence . . . . . . . . . . . . . . . . . . . . 83
ATDX_FRQDUR3( ) – return the duration of the third SIT sequence . . . . . . . . . . . . . . . . . . . . . . 85
ATDX_FRQHZ( ) – return the frequency of the first SIT sequence . . . . . . . . . . . . . . . . . . . . . . . . 87
ATDX_FRQHZ2( ) – return the frequency of the second SIT sequence . . . . . . . . . . . . . . . . . . . . 89
ATDX_FRQHZ3( ) – return the frequency of the third SIT sequence . . . . . . . . . . . . . . . . . . . . . . 91
ATDX_FRQOUT( ) – return percentage of time SIT tone was out of bounds . . . . . . . . . . . . . . . . 93
ATDX_FWVER( ) – return the voice firmware version number . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
ATDX_HOOKST( ) – return the current hook-switch state . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
ATDX_LINEST( ) – return the current activity on the channel. . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
ATDX_LONGLOW( ) – return duration of longer silence detected . . . . . . . . . . . . . . . . . . . . . . . 101
ATDX_PHYADDR( ) – return the physical board address. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
ATDX_SHORTLOW( ) – return duration of shorter silence detected . . . . . . . . . . . . . . . . . . . . . 105
ATDX_SIZEHI( ) – return duration of initial non-silence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
ATDX_STATE( ) – return the current state of the channel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
ATDX_TERMMSK( ) – return the reason for the last I/O function termination . . . . . . . . . . . . . .111
ATDX_TONEID( ) – return user-defined tone ID that terminated I/O function. . . . . . . . . . . . . . . 115
ATDX_TRCOUNT( ) – return the byte count for the last I/O transfer . . . . . . . . . . . . . . . . . . . . . 118
dx_addspddig( ) – set a DTMF digit to adjust speed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
dx_addtone( ) – add a user-defined tone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
dx_addvoldig( ) – set a DTMF digit to adjust volume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
dx_adjsv( ) – adjust speed or volume immediately . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
dx_blddt( ) – define a user-defined dual-frequency tone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
dx_blddtcad( ) – define a user-defined dual frequency cadenced tone. . . . . . . . . . . . . . . . . . . . 139
dx_bldst( ) – define a user-defined single-frequency tone. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
dx_bldstcad( ) – define a user-defined single-frequency cadenced tone . . . . . . . . . . . . . . . . . . 145
dx_bldtngen( ) – define a tone for generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
dx_cacheprompt( ) – download a cached prompt from multiple sources . . . . . . . . . . . . . . . . . . 151
dx_chgdur( ) – change the duration definition for a tone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
dx_chgfreq( ) – change the frequency definition for a tone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
dx_chgrepcnt( ) – change the repetition definition for a tone . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
dx_close( ) – close a channel or board device handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
dx_CloseStreamBuffer( ) – delete a circular stream buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
dx_clrcap( ) – clear all fields in a DX_CAP structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
dx_clrdigbuf( ) – clear all digits in the firmware digit buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
dx_clrsvcond( ) – clear all speed or volume adjustment conditions . . . . . . . . . . . . . . . . . . . . . . 175
dx_clrtpt( ) – clear all fields in a DV_TPT structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
4 Voice API for Windows Operating Systems Library Reference – November 2003
Contents
dx_createtone( ) – create a new tone definition for a specific call progress tone . . . . . . . . . . . . 179
dx_deletetone( ) – delete a specific call progress tone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
dx_deltones( ) – delete all user-defined tones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
dx_dial( ) – dial an ASCIIZ string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
dx_distone( ) – disable detection of a user-defined tone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
dx_enbtone( ) – enable detection of a user-defined tone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
dx_fileclose( ) – close a file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
dx_fileerrno( ) – return the system error value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
dx_fileopen( ) – open a file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
dx_fileread( ) – read data from a file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
dx_fileseek( ) – move a file pointer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
dx_filewrite( ) – write data from a buffer into a file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
dx_getcachesize( ) – get size of on-board memory for cached prompts . . . . . . . . . . . . . . . . . . 219
dx_getctinfo( ) – get information about a voice device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
dx_getcursv( ) – return the specified current speed and volume settings . . . . . . . . . . . . . . . . . 223
dx_getdig( ) – collect digits from a channel digit buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
dx_GetDllVersion( ) – retrieve the voice DLL version number . . . . . . . . . . . . . . . . . . . . . . . . . . 232
dx_getevt( ) – monitor channel events synchronously . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
dx_getfeaturelist( ) – retrieve feature support information for the device . . . . . . . . . . . . . . . . . . 237
dx_getparm( ) – get the current parameter settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
dx_GetRscStatus( ) – return assignment status of a shared resource . . . . . . . . . . . . . . . . . . . . 245
dx_GetStreamInfo( ) – retrieve information about the circular stream buffer . . . . . . . . . . . . . . . 247
dx_getsvmt( ) – return the current speed or volume modification table . . . . . . . . . . . . . . . . . . . 249
dx_getxmitslot( ) – get TDM bus time slot number of voice transmit channel . . . . . . . . . . . . . . 252
dx_getxmitslotecr( ) – get echo cancellation resource transmit time slot number . . . . . . . . . . . 255
dx_gtcallid( ) – return the calling line Directory Number. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
dx_gtextcallid( ) – retrieve a caller ID message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
dx_gtsernum( ) – retrieve the board serial number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
dx_initcallp( ) – initialize and activate call progress analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
dx_libinit( ) – initialize the voice library DLL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
dx_listen( ) – connect a voice listen channel to TDM bus time slot . . . . . . . . . . . . . . . . . . . . . . 277
dx_listenecr( ) – enable echo cancellation resource mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
dx_listenecrex( ) – modify characteristics of the echo canceller . . . . . . . . . . . . . . . . . . . . . . . . 283
dx_mreciottdata( ) – record voice data from two TDM bus time slots . . . . . . . . . . . . . . . . . . . . 286
dx_open( ) – open a voice device and return a unique device handle . . . . . . . . . . . . . . . . . . . . 292
dx_OpenStreamBuffer( ) – create and initialize a circular stream buffer . . . . . . . . . . . . . . . . . . 295
dx_pause( ) – pause on-going play . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
dx_play( ) – play recorded voice data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
dx_playf( ) – synchronously play voice data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
dx_playiottdata( ) – play back recorded voice data from multiple sources . . . . . . . . . . . . . . . . . 310
dx_playtone( ) – play tone defined by TN_GEN structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
dx_playtoneEx( ) – play the cadenced tone defined by TN_GENCAD. . . . . . . . . . . . . . . . . . . . 319
dx_playvox( ) – play voice data stored in a single VOX file . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
dx_playwav( ) – play voice data stored in a single WAVE file . . . . . . . . . . . . . . . . . . . . . . . . . . 327
dx_PutStreamData( ) – place data into a circular stream buffer. . . . . . . . . . . . . . . . . . . . . . . . . 330
dx_querytone( ) – get tone information for a specific call progress tone . . . . . . . . . . . . . . . . . . 333
Voice API for Windows Operating Systems Library Reference – November 2003 5
Contents
dx_rec( ) – record voice data from a single channel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
dx_recf( ) – record voice data to a single file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
dx_reciottdata( ) – record voice data to multiple destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
dx_recvox( ) – record voice data to a single VOX file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
dx_recwav( ) – record voice data to a single WAVE file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
dx_ResetStreamBuffer( ) – reset internal data for a circular stream buffer . . . . . . . . . . . . . . . . . 357
dx_resume( ) – resume paused play . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
dx_RxIottData( ) – receive data on a specified channel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
dx_sendevt( ) – allow inter-process event communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
dx_setchxfercnt( ) – set the bulk queue buffer size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
dx_setdevuio( ) – install and retrieve user-defined I/O functions. . . . . . . . . . . . . . . . . . . . . . . . . 369
dx_setdigbuf( ) – set the digit buffering mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
dx_setdigtyp( ) – control the types of digits detected by the voice channel. . . . . . . . . . . . . . . . . 374
dx_setevtmsk( ) – enable detection of call status transition (CST) events . . . . . . . . . . . . . . . . . 377
dx_setgtdamp( ) – set up the tone detection amplitudes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
dx_sethook( ) – provide control of the hook switch status. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
dx_setparm( ) – set physical parameters of a channel or board device . . . . . . . . . . . . . . . . . . . 388
dx_SetRecordNotifyBeepTone( ) – specify the template of the cadenced tone . . . . . . . . . . . . . 399
dx_setsvcond( ) – set conditions that adjust speed or volume of play . . . . . . . . . . . . . . . . . . . . 401
dx_setsvmt( ) – change default values of the speed or volume modification table . . . . . . . . . . . 405
dx_settonelen( ) – change the duration of the built-in beep tone . . . . . . . . . . . . . . . . . . . . . . . . 409
dx_setuio( ) – install user-defined I/O functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412
dx_SetWaterMark( ) – set water mark for the circular stream buffer . . . . . . . . . . . . . . . . . . . . . . 415
dx_stopch( ) – force termination of currently active I/O functions . . . . . . . . . . . . . . . . . . . . . . . . 417
dx_TSFStatus( ) – return the status of tone set file loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
dx_TxIottData( ) – transmit data on a specified channel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423
dx_TxRxIottData( ) – start a transmit-initiated reception of data . . . . . . . . . . . . . . . . . . . . . . . . . 426
dx_unlisten( ) – disconnect voice receive channel from TDM bus . . . . . . . . . . . . . . . . . . . . . . . 431
dx_unlistenecr( ) – disable echo cancellation resource (ECR) mode . . . . . . . . . . . . . . . . . . . . . 433
dx_wink( ) – generate an outbound wink. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436
dx_wtcallid( ) – wait for rings and report caller ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
dx_wtring( ) – wait for a specified number of rings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
li_attendant( ) – perform the actions of an automated attendant. . . . . . . . . . . . . . . . . . . . . . . . . 446
li_islicensed_syntellect( ) – verify Syntellect patent license on board . . . . . . . . . . . . . . . . . . . . . 450
nr_scroute( ) – make a full or half-duplex connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451
nr_scunroute( ) – break a full or half-duplex connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457
r2_creatfsig( ) – create R2/MF forward signal tone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462
r2_playbsig( ) – play R2/MF backward signal tone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466
3 Events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471
3.1 Overview of Events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .471
3.2 Termination Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .471
3.3 Unsolicited Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .473
3.4 Call Status Transition (CST) Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473
4 Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477
ADSI_XFERSTRUC – ADSI 2-way FSK data transfer buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . 478
6 Voice API for Windows Operating Systems Library Reference – November 2003
Contents
CT_DEVINFO – channel/time slot device information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479
DV_DIGIT – user digit buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483
DV_TPT – termination parameter table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485
DX_ATTENDANT – Syntellect License Automated Attendant . . . . . . . . . . . . . . . . . . . . . . . . . . 493
DX_CAP – call progress analysis parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496
DX_CST – call status transition (CST) information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504
DX_EBLK – call status transition event block. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 506
DX_ECRCT – echo cancellation resource (ECR) characteristics . . . . . . . . . . . . . . . . . . . . . . . 508
DX_IOTT – input/output transfer table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509
DX_STREAMSTAT – status of stream buffer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512
DX_SVCB – speed and volume adjustment condition block . . . . . . . . . . . . . . . . . . . . . . . . . . . 514
DX_SVMT – speed and volume modification tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517
DX_UIO – user-defined input/output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519
DX_XPB – input/output transfer parameter block. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520
FEATURE_TABLE – feature information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 525
SC_TSINFO – TDM bus time slot information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529
TN_GEN – tone generation template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530
TN_GENCAD – cadenced tone generation template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531
TONE_DATA – tone information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533
5 Error Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535
6 Supplementary Reference Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539
6.1 DTMF and MF Tone Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539
6.2 DTMF and MF Detection Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 540
Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551
Voice API for Windows Operating Systems Library Reference – November 2003 7
Contents
Figures
1 Format of General Caller ID Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
8 Voice API for Windows Operating Systems Library Reference – November 2003
Contents
Tables
1 Voice Function Support by Platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
2 Valid Dial String Characters (DM3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
3 Valid Dial String Characters (Springware) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
4 System Error Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
5 Caller ID Common Message Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
6 Caller ID CLASS Message Types (Multiple Data Message) . . . . . . . . . . . . . . . . . . . . . . . . . . 265
7 Caller ID ACLIP Message Types (Multiple Data Message) . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
8 Caller ID CLIP Message Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
9 Caller ID JCLIP Message Types (Multiple Data Message) . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
10 Play Mode Selections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
11 Record Mode Selections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
12 Voice Board Parameters (DM3). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
13 Voice Board Parameters (Springware) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
14 Voice Channel Parameters (DM3). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
15 Voice Channel Parameters (Springware) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
16 DV_TPT Field Settings Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490
17 G.711 Voice Coder Support Fields (DM3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521
18 G.721 Voice Coder Support Fields (DM3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522
19 Linear PCM Voice Coder Support Fields (DM3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522
20 OKI ADPCM Voice Coder Support Fields (DM3). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522
21 G.726 Voice Coder Support Fields (DM3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522
22 GSM Voice Coder Support Fields (DM3). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523
23 TrueSpeech Voice Coder Support Fields (DM3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523
24 IMA ADPCM Voice Coder Support Fields (DM3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523
25 G.726 Voice Coder Support Fields (Springware) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523
26 GSM Voice Coder Support Fields (Springware) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524
27 DTMF Tone Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539
28 MF Tone Specifications (CCITT R1 Tone Plan) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 540
29 Detecting MF Digits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541
30 Detecting DTMF Digits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541
Voice API for Windows Operating Systems Library Reference – November 2003 9
Revision History
This revision history summarizes the changes made in each published version of this document.
Document No. Publication Date Description of Revisions
05-1832-002 November 2003 Function Summary by Category chapter : Added functions to I/O Functions category;
added a section for Streaming to Board category; added functions to the Call
Progress Analysis category; added a function to the Configuration category.
Voice Function Support by Platform table : Added new functions to table.
dx_cacheprompt( ) function reference: Removed statement from the Cautions
section about cached prompts not being flushed and added new information.
dx_close( ) function reference: Removed oflags parameter.
dx_CloseStreamBuffer( ) function reference: New function.
dx_createtone( ) function reference: New function.
dx_deletetone( ) function reference: New function.
dx_getfeaturelist( ) function reference: Added support for board device as an
argument in addition to channel device. Added new bullet item in the Cautions
section about returning front end information.
dx_GetStreamInfo( ) function reference: New function.
dx_OpenStreamBuffer( ) function reference: New function.
dx_pause( ) function reference: New function.
dx_PutStreamData( ) function reference: New function.
dx_querytone( ) function reference: New function.
dx_ResetStreamBuffer( ) function reference: New function.
dx_resume( ) function reference: New function.
dx_RxIottData( ) function reference: Added caution for Springware boards in
Cautions section.
dx_setevtmsk( ) function reference: Added DM_UNDERRUN bitmask for streaming
to board feature.
dx_setparm( ) function reference: Added parameters for ETSI Compliant Frequency
Shift Keying (FSK) and automatic gain control (AGC) in Voice Channel
Parameters (DM3) table.
dx_SetRecordNotifyBeepTone( ) function reference: New function.
dx_SetWaterMark( ) function reference: New function.
dx_setsvcond( ) function reference : Added support for pause/resume play feature.
CT_DEVINFO data structure: Revised structure with new fields.
DV_TPT data structure : In tp_termno field description, added restriction on use of
DX_IDDTIME on DM3 boards; added usage note on DX_MAXTIME and
DX_IDDTIME. In tp_flags field description, indicated that TF_SETINIT is now
supported on DM3 boards; added new TF_IMMEDIATE bit for DM3 boards only.
DX_IOTT data structure: New io_type field value for streaming to board feature.
DX_STREAMSTAT data structure: New data structure for streaming to board
feature.
DX_SVCB data structure: Added new values for pause/resume play feature.
DX_XPB data structure : Added 8 kHz linear PCM to Linear PCM Voice Coder
Support Fields (DM3) table.
Voice API for Windows Operating Systems Library Reference — November 2003 10
Revision History
Document No. Publication Date Description of Revisions
05-1832-002 November 2003 TONE_DATA data structure: New data structure for call progress analysis
05-1832-001 November 2002 Initial version of document. Much of the information contained in this document was
enhancements.
Events chapter: Added section for unsolicited events returned by streaming to board
functions.
previously published in the Voice Software Reference Programmer's Guide for
Windows, document number 05-1456-003.
Voice API for Windows Operating Systems Library Reference — November 2003 11
Revision History
12 Voice API for Windows Operating Systems Library Reference — November 2003
About This Publication
The following topics provide information about this publication:
• Purpose
• Intended Audience
• How to Use This Publication
• Related Information
Purpose
This publication provides a reference to all voice functions, parameters and data structures in the
voice API, also called the R4 voice API, supported on Windows* operating systems. It is a
companion document to the Voice API Programming Guide, the Standard Runtime Library API
Programming Guide, and the Standard Runtime Library API Library Reference.
Intended Audience
This information is intended for:
• Distributors
• System Integrators
• Toolkit Developers
• Independent Software Vendors (ISVs)
• Value Added Resellers (VARs)
• Original Equipment Manufacturers (OEMs)
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.
The information in this guide is organized as follows:
• Chapter 1, “Function Summary by Category” introduces the various categories of voice
functions and provides a brief description of each function.
• Chapter 2, “Function Information” provides an alphabetical reference to all voice functions.
Voice API for Windows Operating Systems Library Reference — November 2003 13
About This Publication
• Chapter 3, “Events” provides an alphabetical reference to events that may be returned by the
voice software.
• Chapter 4, “Data Structures” provides an alphabetical reference to all voice data structures.
• Chapter 5, “Error Codes” presents a listing of error codes that may be returned by the voice
software.
• Chapter 6, “Supplementary Reference Information” provides additional reference information
on topics such as DTMF Tone Specifications, and MF Tone Specifications.
A glossary and index are provided for your reference.
Related Information
See the following for more information:
• For information about voice library features and guidelines for building applications using
voice software, see the Voice API Programming Guide.
• For details on the Standard Runtime Library, supported programming models, and
programming guidelines for building all applications, see the Standard Runtime Library API
Programming Guide. The Standard Runtime Library 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 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 website
contains developer support information, downloads, release documentation, technical notes,
application notes, a user discussion forum, and more.
• For product and services information, see http://www.intel.com/network/csp/.
14 Voice API for Windows Operating Systems Library Reference — November 2003
1.Function Summary by Category
This chapter describes the categories into which the voice library functions can be logically
grouped. This chapter also includes a table listing function support on various platforms (DM3,
Springware) as well as synchronous/asynchronous support.
• Device Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
• Configuration Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
• I/O Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
• I/O Convenience Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
• Streaming to Board Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
• Analog Display Services Interface (ADSI) Functions. . . . . . . . . . . . . . . . . . . . . . . . . . 20
• Audio Input Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
• Transaction Record Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
• Cached Prompt Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
• Call Status Transition (CST) Event Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
• TDM Routing Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
1
• Global Tone Detection (GTD) Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
• Global Tone Generation (GTG) Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
• R2/MF Convenience Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
• Speed and Volume Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
• Call Progress Analysis Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
• Caller ID Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
• File Manipulation Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
• Echo Cancellation Resource Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
• Structure Clearance Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
• Syntellect License Automated Attendant Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
• Extended Attribute Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
• Voice Function Support by Platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
1.1 Device Management Functions
Device management functions open and close devices, which include boards and channels.
Voice API for Windows Operating Systems Library Reference — November 2003 15
Function Summary by Category
Before you can call any other library function on a device, that device must be opened using a
device management function. The dx_open( ) function returns a unique voice device handle. This
handle is the only way the device can be identified once it has been opened. The dx_close( )
function closes a device via its handle.
A set of device management functions exists for each Intel® Dialogic® library, such as fax (fx_
functions), modular station interface (ms_ functions), and conferencing (dcb_ functions). See the
appropriate API Library Reference for more information on these functions.
Device management functions do not cause a device to be busy. In addition, these functions will
work on a device whether the device is busy or idle.
For more information about opening and using voice devices, particularly on DM3 boards, see the
Voice API Programming Guide. Also see this guide for more information about naming
conventions for board and channel devices.
Use Standard Runtime Library device mapper functions to return information about the structure of
the system, such as a list of all physical boards, a list of all virtual boards on a physical board, and
a list of all subdevices on a virtual board. This device information is used as input to device
management functions. For more information on device mapper functions, see the Standard
Runtime Library API Library Reference.
The device management functions are:
dx_close( )
closes a board or channel device handle
dx_open( )
opens a board or channel device handle
1.2 Configuration Functions
Configuration functions allow you to alter, examine, and control the physical configuration of an
open device. In general, configuration functions operate on an idle device. Configuration functions
cause a device to be busy and return the device to an idle state when the configuration is complete.
See the Voice API Programming Guide for information about busy and idle states.
The configuration functions are:
dx_clrdigbuf( )
clears all digits in the firmware digit buffer
dx_GetDllVersion( )
returns the voice dynamic link library (DLL) version number
dx_getfeaturelist( )
returns information about the features supported on the device
dx_getparm( )
gets the current parameter settings for an open device
16 Voice API for Windows Operating Systems Library Reference — November 2003
Function Summary by Category
dx_GetRscStatus( )
returns the assignment status of a shared resource for the specified channel
dx_gtsernum( )
returns the board serial number
dx_libinit( )
initializes the voice dynamic link library (DLL)
dx_setchxfercnt( )
sets the bulk queue buffer size for the channel
dx_setdigbuf( )
sets the digit buffering mode
dx_setdigtyp( )
controls the types of digits detected by the device
dx_sethook( )
sets the hook switch state
dx_setparm( )
sets physical parameters for the device
dx_SetRecordNotifyBeepTone( )
specifies the template of the cadenced tone for record notification beep tone
dx_settonelen( )
changes the duration of the built-in beep tone (pre-record beep)
dx_TSFStatus( )
returns the status of tone set file loading
dx_wtring( )
waits for a specified number of rings
Note: The dx_sethook( ) and dx_setdigbuf( ) functions can also be classified as an I/O function and all
I/O characteristics apply.
1.3 I/O Functions
An I/O function transfers data to and from an open, idle channel. All I/O functions cause a channel
to be busy while data transfer is taking place and return the channel to an idle state when data
transfer is complete.
I/O functions can be run synchronously or asynchronously, with some exceptions (for example,
dx_setuio( ) can be run synchronously only). When running synchronously, they return after
completing successfully or after an error. When running asynchronously, they return immediately
to indicate successful initiation (or an error), and continue processing until a termination condition
is satisfied. See the Standard Runtime Library API Programming Guide for more information on
asynchronous and synchronous operation.
A set of termination conditions can be specified for I/O functions, except for dx_stopch( ) and
dx_wink( ). These conditions dictate what events will cause an I/O function to terminate. The
Voice API for Windows Operating Systems Library Reference — November 2003 17
Function Summary by Category
termination conditions are specified just before the I/O function call is made. Obtain termination
reasons for I/O functions by calling the extended attribute function ATDX_TERMMSK( ). See the
Voice API Programming Guide for information about I/O terminations.
Note: To send and receive FSK data from an Analog Display Services Interface (ADSI) device, see
Section 1.6, “Analog Display Services Interface (ADSI) Functions”, on page 20.
The I/O functions are:
dx_dial( )
dials an ASCIIZ string of digits
dx_getdig( )
collects digits from a channel digit buffer (for up to 31 digits plus the null terminator)
dx_pause( )
pauses on-going play
dx_play( )
plays voice data from any combination of data files, memory, or custom devices
dx_playiottdata( )
plays voice data from any combination of data files, memory, or custom devices, and lets the
user specify format information
dx_rec( )
records voice data to any combination of data files, memory, or custom devices
dx_reciottdata( )
records voice data to any combination of data files, memory, or custom devices, and lets the
user specify format information
dx_resume( )
resumes paused play
dx_setdevuio( )
installs and retrieves user-defined I/O functions in your application
dx_setuio( )
installs user-defined I/O functions in your application
dx_stopch( )
forces termination of currently active I/O functions
dx_wink( )
generates an outbound wink
Notes: 1. The dx_playtone( ) function, which is grouped with global tone generation functions, can also
be classified as an I/O function and all I/O characteristics apply.
2. The dx_playvox( ) and dx_recvox( ) functions, which are grouped with I/O convenience
functions, can also be classified as I/O functions and all I/O characteristics apply.
18 Voice API for Windows Operating Systems Library Reference — November 2003
1.4 I/O Convenience Functions
Convenience functions enable you to easily implement certain basic functionality of the library
functions. I/O convenience functions simplify synchronous play and record.
The dx_playf( ) function performs a playback from a single file by specifying the filename. The
same operation can be done by using dx_play( ) and supplying 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.
The dx_playvox( ) function also plays voice data stored in a single VOX file. This function
internally calls dx_playiottdata( ). Similarly, dx_recvox( ) records VOX files using
dx_reciottdata( ).
The I/O convenience functions are:
dx_playf( )
plays voice data from a single VOX file without the need to specify DX_IOTT
dx_playvox( )
plays voice data from a single VOX file using dx_playiottdata( )
Function Summary by Category
dx_playwav( )
plays voice data stored in a single WAVE file
dx_recf( )
records voice data from a channel to a single VOX file without the need to specify DX_IOTT
dx_recvox( )
records voice data from a channel to a single VOX file using dx_reciottdata( )
dx_recwav( )
records voice data to a single WAVE file
1.5 Streaming to Board Functions
The streaming to board feature enables real time data streaming to the board. Streaming to board
functions allow you to create, maintain, and delete a circular stream buffer within the library. These
functions also provide notification when high and low water marks are reached. See the Voice API
Programming Guide for more information about the streaming to board feature.
The streaming to board functions include:
dx_CloseStreamBuffer( )
deletes a circular stream buffer
dx_GetStreamInfo( )
retrieves information about the circular stream buffer
dx_OpenStreamBuffer( )
creates and initializes a circular stream buffer
Voice API for Windows Operating Systems Library Reference — November 2003 19
Function Summary by Category
dx_PutStreamData( )
places data into the circular stream buffer
dx_ResetStreamBuffer( )
resets internal data for a circular stream buffer
dx_SetWaterMark( )
sets high and low water marks for the circular stream buffer
1.6 Analog Display Services Interface (ADSI) Functions
The send and receive frequency shift keying (FSK) data interface is used for Analog Display
Services Interface (ADSI) and fixed line short message service (SMS). Frequency shift keying is a
frequency modulation technique to send digital data over voiced band telephone lines.
The functions listed here support both one-way and two-way frequency shift keying (FSK). See the
Voice API Programming Guide for more information about ADSI, two-way FSK, and SMS.
dx_RxIottData( )
receives data on a specified channel
dx_TxIottData( )
transmits data on a specified channel
dx_TxRxIottData( )
starts a transmit-initiated reception of data
1.7 Audio Input Functions
The Audio Input (AI) functions are used to provide music or other information on-hold.
ai_open( )
opens an audio input device
ai_close( )
closes an audio input device
ai_getxmitslot( )
gets the TDM bus time slot number of the audio input transmit channel
1.8 Transaction Record Functions
Transaction record enables the recording of a two-party conversation by allowing data from two
time division multiplexing (TDM) bus time slots from a single channel to be recorded.
dx_mreciottdata( )
records voice data from two TDM bus time slots to a data file, memory or custom device
20 Voice API for Windows Operating Systems Library Reference — November 2003
Function Summary by Category
1.9 Cached Prompt Management Functions
The cached prompt management feature enables you to store prompts in on-board memory and
play them from this location rather than from the host disk drive. See the Voice API Programming
Guide for more information about cached prompt management.
dx_cacheprompt( )
downloads voice data (prompts) from multiple sources to the on-board memory
dx_getcachesize( )
returns the size of the on-board memory used to store cached prompts
1.10 Call Status Transition (CST) Event Functions
Call status transition (CST) event functions set and monitor CST events that can occur on a device.
CST events indicate changes in the status of the call, such as rings or a tone detected, or the line
going on-hook or off-hook. See the call status transition structure (DX_CST) description for a full
list of CST events.
The dx_getevt( ) function retrieves CST events in a synchronous environment. To retrieve CST
events in an asynchronous environment, use the Standard Runtime Library event management
functions.
dx_setevtmsk( ) enables detection of CST event(s). User-defined tones are CST events, but
detection for these events is enabled using dx_addtone( ) or dx_enbtone( ), which are global tone
detection functions.
The call status transition event functions are:
dx_getevt( )
gets a CST event in a synchronous environment
dx_sendevt( )
allows inter-process event communication and sends a specified CST event to a specified
device
dx_setevtmsk( )
enables detection of CST events
1.11 TDM Routing Functions
TDM routing functions are used in time division multiplexing (TDM) bus configurations, which
include the CT Bus and SCbus. A TDM bus is resource sharing bus that allows information to be
transmitted and received among resources over multiple time slots.
TDM routing functions enable the application to make or break a connection between voice,
telephone network interface, and other resource channels connected via TDM bus time slots. Each
device connected to the bus has a transmit component that can transmit on a time slot and a receive
component that can listen to a time slot.
Voice API for Windows Operating Systems Library Reference — November 2003 21
Function Summary by Category
The transmit component of each channel of a device is assigned to a time slot at system
initialization and download. To listen to other devices on the bus, the receive component of the
device channel is connected to any one time slot. Any number of device channels can listen to a
time slot.
Note: When you see references to the SCbus or SCbus routing, this information also applies to the CT
Bus. That is, the physical interboard connection can be either SCbus or CT Bus. The SCbus
protocol is used and the SCbus routing API applies to all the boards regardless of whether they use
an SCbus or CT Bus physical interboard connection.
A set of TDM routing functions exist for each Intel® Dialogic library, such as fax (fx_ functions),
modular station interface (ms_ functions), and conferencing (dcb_ functions). See the appropriate
API Library Reference for more information on these functions.
TDM routing convenience functions, nr_scroute( ) and nr_scunroute( ), are provided to make or
break a half or full-duplex connection between any two channels transmitting on the bus. These
functions are not a part of any library but are provided in a separate C source file called sctools.c.
The functions are defined in sctools.h.
The TDM routing functions are:
ag_getctinfo( )
returns information about an analog device connected to the TDM bus
ag_getxmitslot( )
returns the number of the TDM bus time slot connected to the transmit component of an
analog channel
ag_listen( )
connects the listen (receive) component of an analog channel to the TDM bus time slot
ag_unlisten( )
disconnects the listen (receive) component of an analog channel from the TDM bus time slot
dx_getctinfo( )
returns information about voice device connected to TDM bus
dx_getxmitslot( )
returns the number of the TDM bus time slot connected to the transmit component of a voice
channel
dx_listen( )
connects the listen (receive) component of a voice channel to a TDM bus time slot
dx_unlisten( )
disconnects the listen (receive) component of a voice channel from TDM bus time slot
nr_scroute( )
makes a half or full-duplex connection between two channels transmitting on the TDM bus
nr_scunroute( )
breaks a half or full-duplex connection between two TDM bus devices
22 Voice API for Windows Operating Systems Library Reference — November 2003
Function Summary by Category
1.12 Global Tone Detection (GTD) Functions
The global tone detection (GTD) functions define and enable detection of single and dual
frequency tones that fall outside the range of those automatically provided with the voice driver.
They include tones outside the standard DTMF range of 0-9, a-d, *, and #.
The GTD dx_blddt( ), dx_blddtcad( ), dx_bldst( ), and dx_bldstcad( ) functions define tones
which can then be added to the channel using dx_addtone( ). This enables detection of the tone on
that channel. See the Voice API Programming Guide for a full description of global tone detection.
The global tone detection functions are:
dx_addtone( )
adds a user-defined tone
dx_blddt( )
builds a user-defined dual frequency tone description
dx_blddtcad( )
builds a user-defined dual frequency tone cadence description
dx_bldst( )
builds a user-defined single frequency tone description
dx_bldstcad( )
builds a user-defined single frequency tone cadence description
dx_deltones( )
deletes all user-defined tones
dx_distone( )
disables detection of user-defined tones
dx_enbtone( )
enables detection of user-defined tones
dx_setgtdamp( )
sets amplitudes used by global tone detection (GTD)
1.13 Global Tone Generation (GTG) Functions
Global tone generation (GTG) functions define and play single and dual tones that fall outside the
range of those automatically provided with the voice driver.
The dx_bldtngen( ) function defines a tone template structure, TN_GEN. The dx_playtone( )
function can then be used to generate the tone.
See the Voice API Programming Guide for a full description of global tone generation.
The global tone generation functions are:
dx_bldtngen( )
builds a user-defined tone template structure, TN_GEN
Voice API for Windows Operating Systems Library Reference — November 2003 23
Function Summary by Category
dx_playtone( )
plays a user-defined tone as defined in TN_GEN structure
dx_playtoneEx( )
plays the cadenced tone defined by TN_GENCAD structure
Note: The dx_playtone( ) and dx_playtoneEx( ) functions can also be classified as an I/O function and
all I/O characteristics apply.
1.14 R2/MF Convenience Functions
R2/MF convenience functions enable detection of R2/MF forward signals on a channel, and play
R2/MF backward signals in response. For more information about voice support for R2/MF, see the
Voice API Programming Guide.
Note: R2/MF signaling is typically accomplished through the Global Call API. For more information, see
the Global Call documentation set. The R2/MF functions listed here are provided for backward
compatibility only and should not be used for R2/MF signaling.
r2_creatfsig( )
creates R2/MF forward signal tone
r2_playbsig( )
plays R2/MF backward signal tone
1.15 Speed and Volume Functions
Speed and volume functions adjust the speed and volume of the play. A speed modification table
and volume modification table are associated with each channel, and can be used for increasing or
decreasing the speed or volume. These tables have default values which can be changed using the
dx_setsvmt( ) function.
The dx_addspddig( ) and dx_addvoldig( ) functions are convenience functions that specify a digit
and an adjustment to occur on that digit, without having to set any data structures. These functions
use the default settings of the speed and volume modification tables.
See the Voice API Programming Guide for more information about the speed and volume feature in
general, and speed and volume modification tables in particular.
The speed and volume functions are:
dx_adjsv( )
adjusts speed or volume immediately
dx_addspddig( )
sets a dual tone multi-frequency (DTMF) digit for speed adjustment
dx_addvoldig( )
adds a dual tone multi-frequency (DTMF) digit for volume adjustment
24 Voice API for Windows Operating Systems Library Reference — November 2003
Function Summary by Category
dx_clrsvcond( )
clears speed or volume conditions
dx_getcursv( )
returns current speed and volume settings
dx_getsvmt( )
returns current speed or volume modification table
dx_setsvcond( )
sets conditions (such as digit) for speed or volume adjustment; also sets conditions for play
(pause and resume)
dx_setsvmt( )
changes default values of speed or volume modification table
1.16 Call Progress Analysis Functions
Call progress analysis functions are used to enable the call progress analysis feature and change the
default definition of call progress analysis tones. See the Voice API Programming Guide for more
information about call progress analysis.
Notes: 1. Two forms of call progress analysis exist: basic and PerfectCall (formerly called “enhanced call
analysis”). 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.
2. Throughout this document, call progress analysis refers to PerfectCall call progress analysis
unless otherwise noted.
The call progress analysis functions are:
dx_chgdur( )
changes the default call progress analysis signal duration
dx_chgfreq( )
changes the default call progress analysis signal frequency
dx_chgrepcnt( )
changes the default call progress analysis signal repetition count
dx_initcallp( )
initializes call progress analysis on a channel
dx_createtone( )
creates a new tone definition for a specific call progress tone
dx_deletetone( )
deletes a specific call progress tone
dx_querytone( )
returns tone information for a specific call progress tone
Voice API for Windows Operating Systems Library Reference — November 2003 25
Function Summary by Category
1.17 Caller ID Functions
Caller ID functions are used to handle caller ID requests. Caller ID is enabled by setting a channelbased parameter in dx_setparm( ). See the Voice API Programming Guide for more information
about caller ID.
dx_gtcallid( )
returns the calling line directory number (DN)
dx_gtextcallid( )
returns the requested caller ID message by specifying the message type ID
dx_wtcallid( )
waits for rings and reports caller ID, if available
1.18 File Manipulation Functions
These file manipulation functions map to C run-time functions, and can only be used if the file is
opened with the dx_fileopen( ) function. The arguments for these Intel® Dialogic® functions are
identical to the equivalent Microsoft* Visual C++ run-time functions.
dx_fileclose( )
closes the file associated with the handle
dx_fileerrno( )
obtains the system error value
dx_fileopen( )
opens the file specified by filep
dx_fileread( )
reads data from the file associated with the handle
dx_fileseek( )
moves a file pointer associated with the handle
dx_filewrite( )
writes data from a buffer into a file associated with the handle
1.19 Echo Cancellation Resource Functions
The echo cancellation resource (ECR) feature is a voice channel mode that reduces the echo
component in an external TDM bus time slot signal. The echo cancellation resource functions
enable use of the ECR feature.
Note: The ECR functions have been replaced by the continuous speech processing (CSP) API functions.
CSP provides enhanced echo cancellation. For more information, see the Continuous Speech
Processing API Programming Guide and Continuous Speech Processing API Programming Guide.
dx_getxmitslotecr( )
provides the TDM bus transmit time-slot number of the specified voice channel device when in
ECR mode
26 Voice API for Windows Operating Systems Library Reference — November 2003
dx_listenecr( )
enables echo cancellation on a specified voice channel and connects the voice channel to the
echo-referenced signal on the specified TDM bus time slot (ECR mode)
dx_listenecrex( )
performs identically to dx_listenecr( ) and also provides the ability to modify the
characteristics of the echo canceller
dx_unlistenecr( )
disables echo cancellation on a specified voice channel and disconnects the voice channel from
the echo-referenced signal (SVP mode)
1.20 Structure Clearance Functions
These functions do not affect a device. The dx_clrcap( ) and dx_clrtpt( ) functions provide a
convenient method for clearing the DX_CAP and DV_TPT data structures. These structures are
discussed in Chapter 4, “Data Structures”.
dx_clrcap( )
clears all fields in a DX_CAP structure
Function Summary by Category
dx_clrtpt( )
clears all fields in a DV_TPT structure
1.21 Syntellect License Automated Attendant Functions
These functions are used with Intel® Dialogic® products that are licensed for specific telephony
patents held by Syntellect Technology Corporation. For more information, see the Voice API
Programming Guide.
li_attendant( )
performs the actions of an automated attendant
li_islicensed_syntellect( )
verifies Syntellect patent license on board
1.22 Extended Attribute Functions
Voice library extended attribute functions return information specific to the voice device specified
in the function call.
ATDX_ANSRSIZ( )
returns the duration of the answer detected during call progress analysis
ATDX_BDNAMEP( )
returns a pointer to the board device name string
ATDX_BDTYPE( )
returns the board type for the device
Voice API for Windows Operating Systems Library Reference — November 2003 27
Function Summary by Category
ATDX_BUFDIGS( )
returns the number of digits in the firmware since the last dx_getdig( ) for a given channel
ATDX_CHNAMES( )
returns a pointer to an array of channel name strings
ATDX_CHNUM( )
returns the channel number on board associated with the channel device handle
ATDX_CONNTYPE( )
returns the connection type for a completed call
ATDX_CPERROR( )
returns call progress analysis error
ATDX _C PT ER M( )
returns last call progress analysis termination
ATDX_CRTNID( )
returns the identifier of the tone that caused the most recent call progress analysis termination
ATDX_DEVTYPE( )
returns device type (board or channel)
ATDX _D TN FAI L( )
returns the dial tone character that indicates which dial tone call progress analysis failed to
detect
ATDX_FRQDUR( )
returns the duration of the first special information tone (SIT) frequency
ATDX_FRQDUR2( )
returns the duration of the second special information tone (SIT) frequency
ATDX_FRQDUR3( )
returns the duration of the third special information tone (SIT) frequency
ATDX_FRQHZ( )
returns the frequency of the first detected SIT
ATDX_FRQHZ2( )
returns the frequency of the second detected SIT
ATDX_FRQHZ3( )
returns the frequency of the third detected SIT
ATDX_FRQOUT( )
returns the percentage of frequency out of bounds detected during call progress analysis
ATDX _F WV ER ( )
returns the firmware version
ATDX_HOOKST( )
returns the current hook state of the channel
ATDX_LINEST( )
returns the current line status of the channel
ATDX _L ON GL OW( )
returns the duration of longer silence detected during call progress analysis
28 Voice API for Windows Operating Systems Library Reference — November 2003
Function Summary by Category
ATDX_PHYADDR( )
returns the physical address of board
ATDX_SHORTLOW( )
returns the duration of shorter silence detected during call progress analysis
ATDX_SIZEHI( )
returns the duration of non-silence detected during call progress analysis
ATDX_STATE( )
returns the current state of the device
ATDX_TERMMSK( )
returns the reason for last I/O function termination in a bitmap
ATDX_TONEID( )
returns the tone ID (used in global tone detection)
ATDX_TRCOUNT( )
returns the last record or play transfer count
1.23 Voice Function Support by Platform
Table 1 provides an alphabetical listing of voice API functions. The table indicates which platforms
(DM3 or Springware) are supported for each of the functions.
DM3 boards refers to products based on the Intel® DM3 mediastream architecture. Typically DM3
board names have the prefix “DM,” such as Intel® NetStructure™ DM/V2400A-PCI. Springware
boards refer to boards based on earlier-generation architecture. Typically Springware board names
have the prefix “D,” such as Intel® Dialogic® D/240JCT-T1.
Although a function may be supported on both DM3 and Springware boards, there may be some
restrictions on its use. For example, some parameters or parameter values may not be supported.
For details, see the function reference descriptions in Chapter 2, “Function Information”.
Table 1. Voice Function Support by Platform
Function DM3 Springware
ag_getctinfo( ) NS S
ag_getxmitslot( ) NS S
ag_listen( ) NS S
ag_unlisten( ) NS S
ai_close( ) SNS
ai_getxmitslot( ) SNS
NS = Not supported
S = Supported
* = Variances between platforms; refer to the function reference for more information.
† = Asynchronous and synchronous mode supported (all other functions support synchronous mode only)
‡ = On DM3, call progress analysis is available directly through dx_dial( ).
Voice API for Windows Operating Systems Library Reference — November 2003 29
Function Summary by Category
Table 1. Voice Function Support by Platform (Continued)
Function DM3 Springware
ATDX_ANSRSIZ( ) NS S
ATDX_BDNAMEP( ) SS
ATDX_BDTYPE( ) SS
ATDX_BUFDIGS( ) SS
ATDX_CHNAMES( ) SS
ATDX_CHNUM( ) SS
ATDX_CONNTYPE( ) SS
ATDX_CPERROR( ) SS
ATDX_CPTERM( ) SS
ATDX_CRTNID( ) NS S
ATDX_DEVTYPE( ) SS
ATDX _DTN FAI L( ) NS S
ATDX_FRQDUR( ) NS S
ATDX_FRQDUR2( ) NS S
ATDX_FRQDUR3( ) NS S
ATDX_FRQHZ( ) NS S
ATDX_FRQHZ2( ) NS S
ATDX_FRQHZ3( ) NS S
ATDX_FRQOUT( ) NS S
ATDX _FW VER( ) NS S
ATDX_HOOKST( ) NS S
ATDX _LIN EST ( ) NS S
ATDX_LONGLOW( ) NS S
ATDX_PHYADDR( ) NS S
ATDX_SHORTLOW( ) NS S
ATDX _SI ZEHI( ) NS S
ATDX _STATE( ) SS
ATDX _TE RMM SK( ) SS
ATDX_TONEID( ) SS
ATDX_TRCOUNT( ) SS
dx_addspddig( ) S * S
dx_addtone( ) S * S
NS = Not supported
S = Supported
* = Variances between platforms; refer to the function reference for more information.
† = Asynchronous and synchronous mode supported (all other functions support synchronous mode only)
‡ = On DM3, call progress analysis is available directly through dx_dial( ).
30 Voice API for Windows Operating Systems Library Reference — November 2003
Loading...