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
Table 1. Voice Function Support by Platform (Continued)
Function DM3 Springware
dx_addvoldig( ) S * S
dx_adjsv( ) SS
dx_blddt( ) SS
dx_blddtcad( ) SS
dx_bldst( ) SS
dx_bldstcad( ) SS
dx_bldtngen( ) SS
dx_cacheprompt( )
dx_chgdur( ) NS S
dx_chgfreq( ) NS S
dx_chgrepcnt( ) NS S
dx_close( ) SS
dx_CloseStreamBuffer( ) SNS
dx_clrcap( ) SS
dx_clrdigbuf( ) SS
dx_clrsvcond( ) SS
dx_clrtpt( ) SS
dx_createtone( )
dx_deletetone( )
dx_deltones( ) SS
dx_dial( )
† SS
dx_distone( ) SS
dx_enbtone( ) SS
dx_fileclose( ) SS
dx_fileopen( ) SS
dx_fileerrno( ) SS
dx_fileread( ) SS
dx_fileseek( ) SS
dx_filewrite( ) SS
dx_getcachesize( ) SNS
dx_getctinfo( ) SS
dx_getcursv( ) SS
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( ).
† SNS
† SNS
† SNS
Function Summary by Category
Voice API for Windows Operating Systems Library Reference — November 2003 31
Function Summary by Category
Table 1. Voice Function Support by Platform (Continued)
Function DM3 Springware
dx_getdig( ) † SS
dx_GetDllVersion( ) SS
dx_getevt( ) SS
dx_getfeaturelist( ) SS
dx_getparm( ) SS
dx_GetRscStatus( ) NS S
dx_GetStreamInfo( ) SNS
dx_getsvmt( ) SS
dx_getxmitslot( ) S * S
dx_getxmitslotecr( ) NS S
dx_gtcallid( ) NS S
dx_gtextcallid( ) NS S
dx_gtsernum( ) SS
dx_initcallp( ) ‡NSS
dx_libinit( ) SS
dx_listen( ) S * S
dx_listenecr( ) NS S
dx_listenecrex( ) NS S
dx_open( ) SS
dx_OpenStreamBuffer( ) SNS
dx_mreciottdata( ) SS
dx_pause( ) SNS
dx_play( )
dx_playf( ) SS
dx_playiottdata( )
dx_playtone( )
dx_playtoneEx( )
dx_playwav( ) SS
dx_PutStreamData( ) SNS
dx_querytone( )
dx_rec( )
dx_recf( ) SS
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( ).
† SS
† SS
† SS
† SS
† SNS
† S * S
32 Voice API for Windows Operating Systems Library Reference — November 2003
Table 1. Voice Function Support by Platform (Continued)
Function DM3 Springware
dx_reciottdata( ) † S * S
dx_recvox( ) SS
dx_recwav( ) SS
dx_ResetStreamBuffer( ) SNS
dx_resume( ) SNS
dx_RxIottData( )
dx_sendevt( ) NS S
dx_setchxfercnt( ) SS
dx_setdevuio( ) SS
dx_setdigbuf( ) NS S
dx_setdigtyp( ) S * S
dx_setevtmsk( ) S * S
dx_setgtdamp( ) SS
dx_sethook( )
dx_setparm( ) S * S
dx_SetRecordNotifyBeepTone( ) SNS
dx_setsvcond( ) S * S
dx_setsvmt( ) SS
dx_settonelen( ) NS S
dx_setuio( ) SS
dx_SetWaterMark( ) SNS
dx_stopch( )
dx_TSFStatus( ) NS S
dx_TxIottData( )
dx_TxRxIottData( )
dx_unlisten( ) S * S
dx_unlistenecr( ) NS S
dx_wink( )
dx_wtcallid( ) NS S
dx_wtring( ) NS S
li_attendant( ) NS S
li_islicensed_syntellect( ) NS 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( ).
† SS
† NS S
† SS
† SS
† SS
† NS S
Function Summary by Category
Voice API for Windows Operating Systems Library Reference — November 2003 33
Function Summary by Category
Table 1. Voice Function Support by Platform (Continued)
Function DM3 Springware
nr_scroute( ) S * S
nr_scunroute( ) S * S
r2_creatfsig( ) NS S
r2_playbsig( )
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( ).
† NS S
34 Voice API for Windows Operating Systems Library Reference — November 2003
2.Function Information
This chapter provides an alphabetical reference to the functions in the voice library.
2.1 Function Syntax Conventions
The voice functions use the following syntax:
data_type voice_function(device_handle, parameter1, ... parameterN)
where:
data type
refers to the data type, such as integer, long or void
voice_function
represents the function name. Typically, voice functions begin with “dx” although there are
exceptions. Extended attribute functions begin with “ATDX.”
device_handle
represents the device handle, which is a numerical reference to a device, obtained when a
device is opened. The device handle is used for all operations on that device.
2
parameter1
represents the first parameter
parameterN
represents the last parameter
Voice API for Windows Operating Systems Library Reference — November 2003 35
ag_getctinfo( ) — get information about an analog device
ag_getctinfo( )
get information about an analog device
Name: int ag_getctinfo(chdev, ct_devinfop)
Inputs: int chdev
• valid analog channel device handle
CT_DEVINFO *ct_devinfop
Returns: 0 on success
-1 on error
Includes: srllib.h
dxxxlib.h
Category: Routing
Mode: synchronous
Platform: Springware
!!!! Description
The ag_getctinfo( ) function returns information about an analog channel on an analog device.
This information is contained in a CT_DEVINFO structure.
Parameter Description
chdev specifies the valid analog channel handle obtained when the channel was
ct_devinfop specifies a pointer to the data structure CT_DEVINFO
!!!! Cautions
• pointer to device information structure
opened using dx_open( )
This function will fail if an invalid channel handle is specified.
!!!! Errors
If the function returns -1, use the Standard Runtime Library (SRL) Standard Attribute function
ATDV_LASTERR( ) to obtain the error code or use ATDV_ERRMSGP( ) to obtain a descriptive
error message. One of the following error codes may be returned:
EDX_BADPARM
Parameter error
EDX_SH_BADEXTTS
TDM bus time slot is not supported at current clock rate
EDX_SH_BADINDX
Invalid Switch Handler library index number
EDX_SH_BADTYPE
Invalid channel type (voice, analog, etc.)
36 Voice API for Windows Operating Systems Library Reference — November 2003
get information about an analog device — ag_getctinfo( )
EDX_SH_CMDBLOCK
Blocking command is in progress
EDX_SH_LIBBSY
Switch Handler library is busy
EDX_SH_LIBNOTINIT
Switch Handler library is uninitialized
EDX_SH_MISSING
Switch Handler is not present
EDX_SH_NOCLK
Switch Handler clock fallback failed
EDX_SYSTEM
Error from operating system; use dx_fileerrno( ) to obtain error value
!!!! Example
#include <srllib.h>
#include <dxxxlib.h>
main()
{
int chdev; /* Channel device handle */
CT_DEVINFO ct_devinfo; /* Device information structure */
/* Open board 1 channel 1 devices */
if ((chdev = dx_open("dxxxB1C1", 0)) == -1) {
/* process error */
}
/* Get Device Information */
if (ag_getctinfo(chdev, &ct_devinfo) == -1) {
printf("Error message = %s", ATDV_ERRMSGP(chdev));
exit(1);
}
printf("%s Product Id = 0x%x, Family = %d, Mode = %d, Network = %d, Bus mode = %d,
Encoding = %d", ATDV_NAMEP(chdev), ct_devinfo.ct_prodid,
ct_devinfo.ct_devfamily, ct_devinfo.ct_devmode, ct_devinfo.ct_nettype,
ct_devinfo.ct_busmode, ct_devinfo.ct_busencoding);
}
!!!! See Also
• dt_getctinfo( ) in the Digital Network Interface Software Reference
• dx_getctinfo( )
Voice API for Windows Operating Systems Library Reference — November 2003 37
ag_getxmitslot( ) — get TDM bus time slot number of analog transmit channel
ag_getxmitslot( )
get TDM bus time slot number of analog transmit channel
Name: int ag_getxmitslot(chdev, sc_tsinfop)
Inputs: int chdev
• valid analog channel device handle
SC_TSINFO *sc_tsinfop
Returns: 0 on success
-1 on error
Includes: srllib.h
dxxxlib.h
Category: Routing
Mode: synchronous
Platform: Springware
!!!! Description
The ag_getxmitslot( ) function provides the TDM bus time slot number of the analog transmit
channel. This information is contained in an SC_TSINFO structure that also includes the number
of the time slot connected to the analog transmit channel. For more information on this structure,
see SC_TSINFO, on page 529.
Note: Routing convenience function nr_scroute( ) includes ag_getxmitslot( ) functionality.
Parameter Description
chdev specifies the valid analog channel handle obtained when the channel was
opened using dx_open( )
sc_tsinfop specifies a pointer to the data structure SC_TSINFO
• pointer to TDM bus time slot information structure
An analog channel can transmit on only one TDM bus time slot.
!!!! Cautions
This function fails if an invalid channel device handle is specified.
!!!! Errors
If the function returns -1, use the Standard Runtime Library (SRL) Standard Attribute function
ATDV_LASTERR( ) to obtain the error code or use ATDV_ERRMSGP( ) to obtain a descriptive
error message. One of the following error codes may be returned:
EDX_BADPARM
Parameter error
EDX_SH_BADCMD
Command is not supported in current bus configuration
38 Voice API for Windows Operating Systems Library Reference — November 2003
get TDM bus time slot number of analog transmit channel — ag_getxmitslot( )
EDX_SH_BADINDX
Invalid Switch Handler library index number
EDX_SH_BADLCTS
Invalid channel number
EDX_SH_BADMODE
Function is not supported in current bus configuration
EDX_SH_BADTYPE
Invalid channel type (voice, analog, etc.) number
EDX_SH_CMDBLOCK
Blocking command is in progress
EDX_SH_LCLDSCNCT
Channel is already disconnected from TDM bus time slot
EDX_SH_LIBBSY
Switch Handler library is busy
EDX_SH_LIBNOTINIT
Switch Handler library is uninitialized
EDX_SH_MISSING
Switch Handler is not present
EDX_SH_NOCLK
Switch Handler clock fallback failed
EDX_SYSTEM
Error from operating system; use dx_fileerrno( ) to obtain error value
!!!! Example
#include <windows.h>
#include <srllib.h>
#include <dxxxlib.h>
main()
{
int chdev; /* Channel device handle */
SC_TSINFO sc_tsinfo; /* Time slot information structure */
long scts; /* TDM bus time slot */
/* Open board 1 channel 1 devices */
if ((chdev = dx_open("dxxxB1C1", 0)) == -1) {
/* process error */
}
/* Fill in the TDM bus time slot information */
sc_tsinfo.sc_numts = 1;
sc_tsinfo.sc_tsarrayp = &scts;
/* Get TDM bus time slot connected to transmit of analog channel 1 on board ...1 */
if (ag_getxmitslot(chdev, &sc_tsinfo) == -1) {
printf("Error message = %s", ATDV_ERRMSGP(chdev));
exit(1);
}
printf("%s is transmitting on TDM bus time slot %d", ATDV_NAMEP(chdev), ...scts);
}
Voice API for Windows Operating Systems Library Reference — November 2003 39
ag_getxmitslot( ) — get TDM bus time slot number of analog transmit channel
!!!! See Also
• ag_listen( )
• dt_listen( ) in the Digital Network Interface Software Reference
• dx_listen( )
• fx_listen( ) in the Fax Software Reference
• ms_listen( ) in the Modular Station Interface API Library Reference
40 Voice API for Windows Operating Systems Library Reference — November 2003
ag_listen( )
connect analog receive channel to TDM bus time slot
Name: int ag_listen (chdev, sc_tsinfop)
Inputs: int chdev
connect analog receive channel to TDM bus time slot — ag_listen( )
• valid analog channel device handle
SC_TSINFO *sc_tsinfop
Returns: 0 on success
-1 on error
Includes: srllib.h
dxxxlib.h
Category: Routing
Mode: synchronous
Platform: Springware
!!!! Description
The ag_listen( ) function connects an analog receive channel to a TDM bus time slot. This function
uses the information stored in the SC_TSINFO data structure to connect the analog receive (listen)
channel to a TDM bus time slot. This function sets up a half-duplex connection. For a full-duplex
connection, the receive (listen) channel of the other device must be connected to the analog
transmit channel.
Due to analog signal processing on voice boards with on-board analog devices, a voice device and
its corresponding analog device (analog device 1 to voice device 1, etc.) comprise a single channel.
At system initialization, default TDM bus routing is to connect these devices in full-duplex
communications.
• pointer to TDM bus time slot information structure
Note: Routing convenience function nr_scroute( ) includes ag_listen( ) functionality.
Parameter Description
chdev specifies the valid analog channel device handle obtained when the
channel was opened using dx_open( )
sc_tsinfop specifies a pointer to the SC_TSINFO structure. For more information on
this structure, see SC_TSINFO, on page 529.
Although multiple analog channels may listen (be connected) to the same TDM bus time slot, the
analog receive (listen) channel can connect to only one TDM bus time slot.
!!!! Cautions
This function will fail when an invalid channel handle or invalid TDM bus time slot number is
specified.
Voice API for Windows Operating Systems Library Reference — November 2003 41
ag_listen( ) — connect analog receive channel to TDM bus time slot
!!!! Errors
If the function returns -1, use the Standard Runtime Library (SRL) Standard Attribute function
ATDV_LASTERR( ) to obtain the error code or use ATDV_ERRMSGP( ) to obtain a descriptive
error message. One of the following error codes may be returned:
EDX_BADPARM
Parameter error
EDX_SH_BADCMD
Command is not supported in current bus configuration
EDX_SH_BADEXTTS
TDM bus time slot is not supported at current clock rate
EDX_SH_BADINDX
Invalid Switch Handler index number
EDX_SH_BADLCLTS
Invalid channel number
EDX_SH_BADMODE
Function is not supported in current bus configuration
EDX_SH_BADTYPE
Invalid channel local time slot type (voice, analog, etc.)
EDX_SH_CMDBLOCK
Blocking command is in progress
EDX_SH_LCLTSCNCT
Channel is already connected to TDM bus time slot
EDX_SH_LIBBSY
Switch Handler library is busy
EDX_SH_LIBNOTINIT
Switch Handler library is uninitialized
EDX_SH_NOCLK
Switch Handler clock fallback failed
EDX_SYSTEM
System error
!!!! Example
#include <windows.h>
#include <srllib.h>
#include <dxxxlib.h
main()
{
int chdev; /* Channel device handle */
SC_TSINFO sc_tsinfo; /* Time slot information structure */
long scts; /* TDM bus time slot */
42 Voice API for Windows Operating Systems Library Reference — November 2003
connect analog receive channel to TDM bus time slot — ag_listen( )
/* Open board 1 channel 1 devices */
if ((chdev = dx_open("dxxxB1C1", 0)) == -1) {
/* process error */
}
/* Fill in the 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 (dx_getxmitslot(chdev, &sc_tsinfo) == -1) {
printf("Error message = %s", ATDV_ERRMSGP(chdev));
exit(1);
}
/* Connect the receive of analog channel 1 on board 1 to TDM bus
time slot of voice channel 1 */
if (ag_listen(chdev, &sc_tsinfo) == -1) {
printf("Error message = %s", ATDV_ERRMSGP(chdev));
exit(1);
}
}
!!!! See Also
• dx_getxmitslot( )
• dt_getxmitslot( ) in the Digital Network Interface Software Reference
• fx_getxmitslot( ) in the Fax Software Reference
• ag_unlisten( )
Voice API for Windows Operating Systems Library Reference — November 2003 43
ag_unlisten( ) — disconnect analog receive channel from TDM bus
ag_unlisten( )
disconnect analog receive channel from TDM bus
Name: int ag_unlisten(chdev)
Inputs: int chdev
Returns: 0 on success
-1 on error
Includes: srllib.h
dxxxlib.h
Category: Routing
Mode: synchronous
Platform: Springware
!!!! Description
The ag_unlisten( ) function disconnects an analog receive channel from the TDM bus. This
function disconnects the analog receive (listen) channel from the TDM bus time slot it was
listening to.
• analog channel device handle
Calling ag_listen( ) to connect to a different TDM bus time slot will automatically break an
existing connection. Thus, when changing connections, you need not call the ag_unlisten( )
function first.
Note: Routing convenience function nr_scunroute( ) includes ag_unlisten( ) functionality.
Parameter Description
chdev specifies the valid channel device handle obtained when the channel was opened
using dx_open( )
!!!! Cautions
This function will fail when an invalid channel handle is specified.
!!!! Errors
If the function returns -1, use the Standard Runtime Library (SRL) Standard Attribute function
ATDV_LASTERR( ) to obtain the error code or use ATDV_ERRMSGP( ) to obtain a descriptive
error message. One of the following error codes may be returned:
EDX_BADPARM
Parameter error
EDX_SH_BADCMD
Command is not supported in current bus configuration
EDX_SH_BADINDX
Invalid Switch Handler index number
44 Voice API for Windows Operating Systems Library Reference — November 2003
disconnect analog receive channel from TDM bus — ag_unlisten( )
EDX_SH_BADLCLTS
Invalid channel number
EDX_SH_BADMODE
Function is not supported in current bus configuration
EDX_SH_BADTYPE
Invalid channel local time slot type (voice, analog, etc.)
EDX_SH_CMDBLOCK
Blocking command is in progress
EDX_SH_LCLDSCNCT
Channel is already disconnected from TDM bus time slot
EDX_SH_LIBBSY
Switch Handler library is busy
EDX_SH_LIBNOTINIT
Switch Handler library is uninitialized
EDX_SH_MISSING
Switch Handler is not present
EDX_SH_NOCLK
Switch Handler clock fallback failed
EDX_SYSTEM
System error
!!!! Example
#include <windows.h>
#include <srllib.h>
#include <dxxxlib.h>
main()
{
int chdev; /* Voice Channel handle */
/* Open board 1 channel 1 device */
if ((chdev = dx_open("dxxxB1C1", 0)) == -1) {
/* process error */
}
/* Disconnect receive of board 1, channel 1 from TDM bus time slot */
if (ag_unlisten(chdev) == -1) {
printf("Error message = %s", ATDV_ERRMSGP(chdev));
exit(1);
}
}
!!!! See Also
• ag_listen( )
Voice API for Windows Operating Systems Library Reference — November 2003 45
ai_close( ) — close an audio input device
ai_close( )
close an audio input device
Name: int ai_close(devh)
Inputs: int devh
Returns: 0 if successful
-1 if failure
Includes: srllib.h
dxxxlib.h
Category: Audio Input
Mode: synchronous
Platform: DM3
!!!! Description
The ai_close( ) function closes an audio input device that was previously opened using ai_open( ).
This function releases the handle and breaks any link between the calling process and the device.
• valid audio input device handle
Parameter Description
devh specifies the valid device handle obtained when an audio input device is
opened using ai_open( )
!!!! Cautions
This function fails when an invalid channel device handle is specified.
!!!! Errors
If this function returns -1 to indicate failure, a system error has occurred; use dx_fileerrno( ) to
obtain the system error value. Refer to the dx_fileerrno( ) function for a list of the possible system
error values.
!!!! Example
#include <windows.h>
#include <stdio.h>
#include <srllib.h>
#include <dxxxlib.h>
int main()
{
int aidev; /* Audio input device handle */
SC_TSINFO sc_tsinfo; /* Time slot information structure */
long scts; /* TDM bus time slot */
46 Voice API for Windows Operating Systems Library Reference — November 2003
close an audio input device — ai_close( )
/* Open audio input device aiB1 */
if ((aidev = ai_open("aiB1")) < 0) {
/* process error */
}
/* Fill in the TDM bus time slot information */
sc_tsinfo.sc_numts = 1;
sc_tsinfo.sc_tsarrayp = &scts;
/* Get TDM bus time slot connected to transmit of audio input device */
if (ai_getxmitslot(aidev, &sc_tsinfo) < 0) {
/* process error */
}
else {
printf("%s is transmitting on TDM time slot %d", ATDV_NAMEP(aidev), scts);
}
/* Close audio input device */
if (ai_close(aidev) < 0) {
/* process error */
}
return 0;
}
!!!! See Also
• ai_getxmitslot( )
• ai_open( )
Voice API for Windows Operating Systems Library Reference — November 2003 47
ai_getxmitslot( ) — get TDM bus time slot number of audio input transmit channel
ai_getxmitslot( )
get TDM bus time slot number of audio input transmit channel
Name: int ai_getxmitslot(devh, sc_tsinfop)
Inputs: int devh
• valid audio input device handle
SC_TSINFO *sc_tsinfop
Returns: 0 on success
-1 on error
Includes: srllib.h
dxxxlib.h
Category: Audio Input
Mode: synchronous
Platform: DM3
!!!! Description
The ai_getxmitslot( ) function returns the TDM bus time slot number of the audio input transmit
channel. The TDM bus time slot information is contained in an SC_TSINFO structure.
Parameter Description
devh specifies the valid device handle obtained when the audio input device is
sc_tsinfop specifies a pointer to the TDM bus time slot information structure,
• pointer to TDM bus time slot information structure
opened using ai_open( )
SC_TSINFO.
The sc_numts field of the SC_TSINFO structure must be initialized with the
number of TDM bus time slots requested (1). The sc_tsarrayp field of the
SC_TSINFO structure must be initialized with a valid pointer to a long
variable. Upon successful return from the function, the long variable will
contain the number of the time slot on which the audio input device transmits.
For more information on this structure, see SC_TSINFO, on page 529.
!!!! Cautions
This function fails when an invalid channel device handle is specified.
!!!! Errors
If the function returns -1, use the SRL Standard Attribute function ATDV_LASTERR( ) to obtain
the error code or use ATDV_ERRMSGP( ) to obtain a descriptive error message.
48 Voice API for Windows Operating Systems Library Reference — November 2003
get TDM bus time slot number of audio input transmit channel — ai_getxmitslot( )
!!!! Example
#include <windows.h>
#include <stdio.h>
#include <srllib.h>
#include <dxxxlib.h>
int main()
{
int aidev; /* Audio input device handle */
SC_TSINFO sc_tsinfo; /* Time slot information structure */
long scts; /* TDM bus time slot */
/* Open audio input device aiB1 */
if ((aidev = ai_open("aiB1")) < 0) {
/* process error */
}
/* Fill in the TDM bus time slot information */
sc_tsinfo.sc_numts = 1;
sc_tsinfo.sc_tsarrayp = &scts;
/* Get TDM bus time slot connected to transmit of audio input device */
if (ai_getxmitslot(aidev, &sc_tsinfo) < 0) {
/* process error */
}
else {
printf("%s is transmitting on TDM time slot %d", ATDV_NAMEP(aidev), scts);
}
/* Close audio input device */
if (ai_close(aidev) < 0) {
/* process error */
}
return 0;
}
!!!! See Also
• ai_open( )
• ai_close( )
Voice API for Windows Operating Systems Library Reference — November 2003 49
ai_open( ) — open an audio input device
ai_open( )
open an audio input device
Name: int ai_open(namep)
Inputs: const char *namep
Returns: audio input device handle if successful
-1 if failure
Includes: srllib.h
dxxxlib.h
Category: Audio Input
Mode: synchronous
Platform: DM3
!!!! Description
• pointer to an ASCIIZ string that contains the name of a valid audio input
device
The ai_open( ) function opens an audio input device and returns a unique device handle to identify
the device. Until the device is closed, all subsequent references to the opened device must be made
using the handle.
Parameter Description
namep points to an ASCIIZ string that contains the name of the valid audio input
device, in the form aiBn, where n is the audio input device number
!!!! Cautions
This function will fail and return -1 if:
• The device name is invalid.
• A hardware error on the board or channel is discovered.
!!!! Errors
If this function returns -1 to indicate failure, a system error has occurred; use dx_fileerrno( ) to
obtain the system error value. Refer to the dx_fileerrno( ) function for a list of the possible system
error values.
!!!! Example
#include <windows.h>
#include <stdio.h>
#include <srllib.h>
#include <dxxxlib.h>
50 Voice API for Windows Operating Systems Library Reference — November 2003
open an audio input device — ai_open( )
int main()
{
int aidev; /* Audio input device handle */
SC_TSINFO sc_tsinfo; /* Time slot information structure */
long scts; /* TDM bus time slot */
/* Open audio input device aiB1 */
if ((aidev = ai_open("aiB1")) < 0) {
/* process error */
}
/* Fill in the TDM bus time slot information */
sc_tsinfo.sc_numts = 1;
sc_tsinfo.sc_tsarrayp = &scts;
/* Get TDM bus time slot connected to transmit of audio input device */
if (ai_getxmitslot(aidev, &sc_tsinfo) < 0) {
/* process error */
}
else {
printf("%s is transmitting on TDM time slot %d", ATDV_NAMEP(aidev), scts);
}
/* Close audio input device */
if (ai_close(aidev) < 0) {
/* process error */
}
return 0;
}
!!!! See Also
• ai_close( )
• ai_getxmitslot( )
• sr_getboardcnt( )
Voice API for Windows Operating Systems Library Reference — November 2003 51
ATDX_ANSRSIZ( ) — return the duration of the answer
ATDX_ANSRSIZ( )
return the duration of the answer
Name: long ATDX_ANSRSIZ(chdev)
Inputs: int chdev
Returns: answer duration in 10 msec units if successful
AT_FAILURE if error
Includes: srllib.h
dxxxlib.h
Category: Extended Attribute
Mode: synchronous
Platform: Springware
!!!! Description
The ATDX_ANSRSIZ( ) function returns the duration of the answer that occurs when dx_dial( )
with Basic call progress analysis enabled is called on a channel. An answer is considered the period
of non-silence that begins after cadence is broken and a connection is made. This measurement is
taken before a connect event is returned. The duration of the answer can be used to determine if the
call was answered by a person or an answering machine. This feature is based on the assumption
that an answering machine typically answers a call with a longer greeting than a live person does.
• valid channel device handle
See the Voice API Programming Guide for information about call progress analysis. Also see this
guide for information about how cadence detection parameters affect a connect and are used to
distinguish between a live voice and a voice recorded on an answering machine.
Parameter Description
chdev specifies the valid channel device handle obtained when the channel was opened
using dx_open( )
!!!! Cautions
None.
!!!! Errors
This function will fail and return AT_FAILURE if an invalid channel device handle is specified in
chdev.
!!!! Example
/* Call Progress Analysis with user-specified parameters */
#include <stdio.h>
#include <srllib.h>
#include <dxxxlib.h>
52 Voice API for Windows Operating Systems Library Reference — November 2003
return the duration of the answer — ATDX_ANSRSIZ( )
main()
{
int cares, chdev;
DX_CAP capp;
.
.
/* open the channel using dx_open( ). Obtain channel device descriptor in
* chdev
*/
if ((chdev = dx_open("dxxxB1C1",NULL)) == -1) {
/* process error */
}
/* take the phone off-hook */
if (dx_sethook(chdev,DX_OFFHOOK,EV_SYNC) == -1) {
/* process error */
}
/* Set the DX_CAP structure as needed for call progress analysis. Perform the
* outbound dial with call progress analysis enabled
*/
if ((cares = dx_dial(chdev,"5551212",&capp,DX_CALLP|EV_SYNC)) == -1) {
/* perform error routine */
}
switch (cares) {
case CR_CNCT: /* Call Connected, get some additional info */
printf("\nDuration of short low - %ld ms",ATDX_SHORTLOW(chdev)*10);
printf("\nDuration of long low - %ld ms",ATDX_LONGLOW(chdev)*10);
printf("\nDuration of answer - %ld ms",ATDX_ANSRSIZ(chdev)*10);
break;
case CR_CEPT: /* Operator Intercept detected */
printf("\nFrequency detected - %ld Hz",ATDX_FRQHZ(chdev));
printf("\n%% of Frequency out of bounds - %ld Hz",ATDX_FRQOUT(chdev));
break;
case CR_BUSY:
.
.
}
}
!!!! See Also
• dx_dial( )
• DX_CAP data structure
Voice API for Windows Operating Systems Library Reference — November 2003 53
ATDX_BDNAMEP( ) — return a pointer to the board device name
ATDX_BDNAMEP( )
return a pointer to the board device name
Name: char * ATDX_BDNAMEP(chdev)
Inputs: int chdev
Returns: pointer to board device name string if successful
pointer to ASCIIZ string “Unknown device” if error
Includes: srllib.h
dxxxlib.h
Category: Extended Attribute
Mode: synchronous
Platform: DM3, Springware
!!!! Description
The ATDX_BDNAMEP( ) function returns a pointer to the board device name on which the
channel accessed by chdev resides.
• valid channel device handle
As illustrated in the example, this may be used to open the board device that corresponds to a
particular channel device prior to setting board parameters.
Parameter Description
chdev specifies the valid channel device handle obtained when the channel was opened
using dx_open( )
!!!! Cautions
None.
!!!! Errors
This function will fail and return a pointer to “Unknown device” if an invalid channel device handle
is specified in chdev.
!!!! Example
#include <stdio.h>
#include <srllib.h>
#include <dxxxlib.h>
main()
{
int chdev, bddev;
char *bdnamep;
.
54 Voice API for Windows Operating Systems Library Reference — November 2003
return a pointer to the board device name — ATDX_BDNAMEP( )
.
/* Open the channel device */
if ((chdev = dx_open("dxxxB1C1", NULL)) == -1) {
/* Process error */
}
/* Display board name */
bdnamep = ATDX_BDNAMEP(chdev);
printf("The board device is: %s\n", bdnamep);
/* Open the board device */
if ((bddev = dx_open(bdnamep, NULL)) == -1) {
/* Process error */
}
.
.
}
!!!! See Also
None.
Voice API for Windows Operating Systems Library Reference — November 2003 55
ATDX_BDTYPE( ) — return the board type for the device
ATDX_BDTYPE( )
return the board type for the device
Name: long ATDX_BDTYPE(dev)
Inputs: int dev
Returns: board or channel device type if successful
AT_FAILURE if error
Includes: srllib.h
dxxxlib.h
Category: Extended Attribute
Mode: synchronous
Platform: DM3, Springware
!!!! Description
The ATDX_BDTYPE( ) function returns the board type for the device specified in dev.
• valid board or channel device handle
A typical use would be to determine whether or not the device can support particular features, such
as call progress analysis.
Parameter Description
dev specifies the valid device handle obtained when a board or channel was opened
using dx_open( )
Possible return values are the following:
DI_D41BD
D/41 Board Device. This value represents the “dxxxBn type” devices (virtual boards).
DI_D41CH
D/41 Channel Device. This value represents the “dxxxBnCm” type devices (channel device).
The values DI_41BD and DI_41CH will be returned for any D/41 board, and any board which
emulates the voice resources of multiple D/41 boards.
!!!! Cautions
None.
!!!! Errors
This function will fail and return AT_FAILURE if an invalid board or channel device handle is
specified in dev.
56 Voice API for Windows Operating Systems Library Reference — November 2003
return the board type for the device — ATDX_BDTYPE( )
!!!! Example
#include <stdio.h>
#include <srllib.h>
#include <dxxxlib.h>
#define ON 1
main()
{
int bddev;
long bdtype;
int call_analysis=0;
/* Open the board device */
if ((bddev = dx_open("dxxxB1",NULL)) == -1) {
/* Process error */
}
if((bdtype = ATDX_BDTYPE(bddev)) == AT_FAILURE) {
/* Process error */
}
if(bdtype == DI_D41BD) {
printf("Device is a D/41 Board\n");
call_analysis = ON;
}
.
.
}
!!!! See Also
None.
Voice API for Windows Operating Systems Library Reference — November 2003 57
ATDX_BUFDIGS( ) — return the number of uncollected digits
ATDX_BUFDIGS( )
return the number of uncollected digits
Name: long ATDX_BUFDIGS(chdev)
Inputs: int chdev
Returns: number of uncollected digits in the firmware buffer if successful
AT_FAILURE if error
Includes: srllib.h
dxxxlib.h
Category: Extended Attribute
Mode: synchronous
Platform: DM3, Springware
!!!! Description
The ATDX_BUFDIGS( ) function returns the number of uncollected digits in the firmware buffer
for channel chdev. This is the number of digits that have arrived since the last call to dx_getdig( )
or the last time the buffer was cleared using dx_clrdigbuf( ). The digit buffer contains a maximum
of 31 digits and a null terminator.
• valid channel device handle
This function is supported on DM3 boards but must be manually enabled. You must enable the
function before the application is loaded in memory. To enable this function, set parameter
SupportForSignalCounting to 1 in Key
HKEY_LOCAL_MACHINE\SOFTWARE\Dialogic\Cheetah\CC.
To subsequently disable this function, set this parameter to 0.
Parameter Description
chdev specifies the valid channel device handle obtained when the channel was opened
using dx_open( )
!!!! Cautions
Digits that adjust speed and volume (see dx_setsvcond( )) will not be passed to the digit buffer.
!!!! Errors
This function will fail and return AT_FAILURE if an invalid channel device handle is specified in
chdev.
!!!! Example
#include <fcntl.h>
#include <srllib.h>
#include <dxxxlib.h>
58 Voice API for Windows Operating Systems Library Reference — November 2003
return the number of uncollected digits — ATDX_BUFDIGS( )
main()
{
int chdev;
long bufdigs;
DX_IOTT iott;
DV_TPT tpt[2];
/* Open the device using dx_open( ). Get channel device descriptor in
* chdev. */
if ((chdev = dx_open("dxxxB1C1",NULL)) == -1) {
/* process error */
}
/* set up DX_IOTT */
iott.io_type = IO_DEV|IO_EOT;
iott.io_bufp = 0;
iott.io_offset = 0;
iott.io_length = -1; /* play till end of file */
if((iott.io_fhandle = dx_fileopen("prompt.vox", O_RDONLY)) == -1) {
/* process error */
}
/* set up DV_TPT */
dx_clrtpt(tpt,2);
tpt[0].tp_type = IO_CONT;
tpt[0].tp_termno = DX_MAXDTMF; /* Maximum digits */
tpt[0].tp_length = 4; /* terminate on 4 digits */
tpt[0].tp_flags = TF_MAXDTMF; /* Use the default flags */
tpt[1].tp_type = IO_EOT;
tpt[1].tp_termno = DX_DIGMASK; /* Digit termination */
tpt[1].tp_length = DM_5; /* terminate on the digit "5" */
tpt[1].tp_flags = TF_DIGMASK; /* Use the default flags */
/* Play a voice file. Terminate on receiving 4 digits, the digit "5" or
* at end of file.*/
if (dx_play(chdev,&iott,tpt,EV_SYNC) == -1) {
/* process error */
}
/* Check # of digits collected and continue processing. */
if((bufdigs=ATDX_BUFDIGS(chdev))==AT_FAILURE) {
/* process error */
}
.
.
.
}
!!!! See Also
• dx_getdig( )
• dx_clrdigbuf( )
Voice API for Windows Operating Systems Library Reference — November 2003 59
ATDX_CHNAMES( ) — retrieve all channel names for a board
ATDX_CHNAMES( )
retrieve all channel names for a board
Name: char ** ATDX_CHNAMES(bddev)
Inputs: int bddev
Returns: pointer to array of channel names if successful
pointer to array of pointers that point to “Unknown device” if error
Includes: srllib.h
dxxxlib.h
Category: Extended Attribute
Mode: synchronous
Platform: DM3, Springware
!!!! Description
The ATDX_CHNAMES( ) function returns a pointer to an array of channel names associated with
the specified board device handle, bddev.
• valid board device handle
A possible use for this attribute is to display the names of the channel devices associated with a
particular board device.
Parameter Description
bddev specifies the valid board device handle obtained when the board was opened
using dx_open( )
!!!! Cautions
None.
!!!! Errors
This function will fail and return the address of a pointer to “Unknown device” if an invalid board
device handle is specified in bddev.
!!!! Example
#include <stdio.h>
#include <srllib.h>
#include <dxxxlib.h>
main()
{
int bddev, cnt;
char **chnames;
long subdevs;
.
.
/* Open the board device */
if ((bddev = dx_open("dxxxB1",NULL)) == -1) {
60 Voice API for Windows Operating Systems Library Reference — November 2003
retrieve all channel names for a board — ATDX_CHNAMES( )
/* Process error */
}
.
.
/* Display channels on board */
chnames = ATDX_CHNAMES(bddev);
subdevs = ATDV_SUBDEVS(bddev); /* number of sub-devices on board */
printf("Channels on this board are:\n");
for(cnt=0; cnt<subdevs; cnt++) {
printf("%s\n",*(chnames + cnt));
}
/* Call dx_open( ) to open each of the
* channels and store the device descriptors
*/
.
.
}
!!!! See Also
None.
Voice API for Windows Operating Systems Library Reference — November 2003 61
ATDX_CHNUM( ) — return the channel number
ATDX_CHNUM( )
return the channel number
Name: long ATDX_CHNUM(chdev)
Inputs: int chdev
Returns: channel number if successful
AT_FAILURE if error
Includes: srllib.h
dxxxlib.h
Category: Extended Attribute
Mode: synchronous
Platform: DM3, Springware
!!!! Description
The ATDX_CHNUM( ) function returns the channel number associated with the channel device
chdev. Channel numbering starts at 1.
• valid channel device handle
For example, use the channel as an index into an array of channel-specific information.
Parameter Description
chdev specifies the valid channel device handle obtained when the channel was opened
using dx_open( )
!!!! Cautions
None.
!!!! Errors
This function will fail and return AT_FAILURE if an invalid channel device handle is specified in
chdev.
!!!! Example
#include <srllib.h>
#include <dxxxlib.h>
main()
{
int chdev;
long chno;
.
.
/* Open the channel device */
if ((chdev = dx_open("dxxxB1C1", NULL)) == -1) {
/* Process error */
}
/* Get Channel number */
62 Voice API for Windows Operating Systems Library Reference — November 2003
if((chno = ATDX_CHNUM(chdev)) == AT_FAILURE) {
/* Process error */
}
/* Use chno for application-specific purposes */
.
.
}
!!!! See Also
None.
return the channel number — ATDX_CHNUM( )
Voice API for Windows Operating Systems Library Reference — November 2003 63
ATDX_CONNTYPE( ) — return the connection type for a completed call
ATDX_CONNTYPE( )
return the connection type for a completed call
Name: long ATDX_CONNTYPE(chdev)
Inputs: int chdev
Returns: connection type if success
AT_FAILURE if error
Includes: srllib.h
dxxxlib.h
Category: Extended Attribute
Mode: synchronous
Platform: DM3, Springware
!!!! Description
The ATDX_CONNTYPE( ) function returns the connection type for a completed call on the
channel device chdev. Use this function when a CR_CNCT (called line connected) is returned by
ATDX _C PT ER M( ) after termination of dx_dial( ) with call progress analysis enabled.
• valid channel device handle
See the Voice API Programming Guide for more information about call progress analysis.
Parameter Description
chdev specifies the valid channel device handle obtained when the channel was opened
using dx_open( )
On DM3 boards, possible return values are the following:
CON_CAD
Connection due to cadence break
CON_PVD
Connection due to positive voice detection
CON_PAMD
Connection due to positive answering machine detection
On Springware boards, possible return values are the following:
CON_CAD
Connection due to cadence break
CON_LPC
Connection due to loop current
CON_PVD
Connection due to positive voice detection
CON_PAMD
Connection due to positive answering machine detection
64 Voice API for Windows Operating Systems Library Reference — November 2003
return the connection type for a completed call — ATDX_CONNTYPE( )
!!!! Cautions
None.
!!!! Errors
This function will fail and return AT_FAILURE if an invalid channel device handle is specified in
chdev.
!!!! Example
#include <stdio.h>
#include <srllib.h>
#include <dxxxlib.h>
main()
{
int dxxxdev;
int cares;
/*
* Open the Voice Channel Device and Enable a Handler
*/
if ( ( dxxxdev = dx_open( "dxxxB1C1", NULL) ) == -1 ) {
perror( "dxxxB1C1" );
exit( 1 );
}
/*
* Delete any previous tones
*/
if ( dx_deltones(dxxxdev) < 0 ) {
/* handle error */
}
/*
* Now enable call progress analysis with above changed settings.
*/
if (dx_initcallp( dxxxdev )) {
/* handle error */
}
/*
* Take the phone off-hook
*/
if ( dx_sethook( dxxxdev, DX_OFFHOOK, EV_SYNC ) == -1 ) {
printf( "Unable to set the phone off-hook\n" );
printf( "Lasterror = %d Err Msg = %s\n",
ATDV_LASTERR( dxxxdev ), ATDV_ERRMSGP( dxxxdev ) );
dx_close( dxxxdev );
exit( 1 );
}
/*
* Perform an outbound dial with call progress analysis, using
* the default call progress analysis parameters.
*/
if ((cares=dx_dial( dxxxdev, ",84",(DX_CAP *)NULL, DX_CALLP ) ) == -1 ) {
printf( "Outbound dial failed - reason = %d\n",
ATDX_CPERROR( dxxxdev ) );
dx_close( dxxxdev );
exit( 1 );
}
Voice API for Windows Operating Systems Library Reference — November 2003 65
ATDX_CONNTYPE( ) — return the connection type for a completed call
printf( "call progress analysis returned %d\n", cares );
if ( cares == CR_CNCT ) {
switch ( ATDX_CONNTYPE( dxxxdev ) ) {
case CON_CAD:
printf( "Cadence Break\n" );
break;
case CON_LPC:
printf( "Loop Current Drop\n" );
break;
case CON_PVD:
printf( "Positive Voice Detection\n" );
break;
case CON_PAMD:
printf( "Positive Answering Machine Detection\n" );
break;
default:
printf( "Unknown connection type\n" );
break;
}
}
/*
* Continue Processing
* .
* .
* .
*/
/*
* Close the opened Voice Channel Device
*/
if ( dx_close( dxxxdev ) != 0 ) {
perror( "close" );
}
/* Terminate the Program */
exit( 0 );
}
!!!! See Also
• dx_dial( )
• ATDX _C PT ER M( )
• DX_CAP data structure
66 Voice API for Windows Operating Systems Library Reference — November 2003
ATDX_CPERROR( )
return the call progress analysis error
Name: long ATDX_CPERROR(chdev)
Inputs: int chdev
Returns: call progress analysis error if success
AT_FAILURE if function fails
Includes: srllib.h
dxxxlib.h
Category: Extended Attribute
Mode: synchronous
Platform: DM3, Springware
!!!! Description
The ATDX_CPERROR( ) function returns the call progress analysis error that caused dx_dial( )
to terminate when checking for operator intercept Special Information Tone (SIT) sequences. See
the Voice API Programming Guide for more information about call progress analysis.
• valid channel device handle
return the call progress analysis error — ATDX_CPERROR( )
Parameter Description
chdev specifies the valid channel device handle obtained when the channel was opened
using dx_open( )
!!!! Cautions
None.
!!!! Errors
When dx_dial( ) terminates due to a call progress analysis error, CR_ERROR is returned by
ATDX_CPTERM( ).
If CR_ERROR is returned, use ATDX_CPERROR( ) to determine the call progress analysis error.
One of the following values will be returned:
CR_LGTUERR
lower frequency greater than upper frequency
CR_MEMERR
out of memory trying to create temporary Special Information Tone (SIT) tone templates
(exceeds maximum number of templates)
CR_MXFRQERR
invalid ca_maxtimefrq 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.
Voice API for Windows Operating Systems Library Reference — November 2003 67
ATDX_CPERROR( ) — return the call progress analysis error
CR_OVRLPERR
overlap in selected SIT tones
CR_TMOUTOFF
timeout waiting for SIT tone to terminate (exceeds a ca_mxtimefrq parameter)
CR_TMOUTON
timeout waiting for SIT tone to commence
CR_UNEXPTN
unexpected SIT tone (the sequence of detected tones did not correspond to the SIT sequence)
CR_UPFRQERR
invalid upper frequency selection. This value must be nonzero for detection of any SIT.
!!!! Example
#include <stdio.h>
#include <srllib.h>
#include <dxxxlib.h>
main()
{
int dxxxdev;
int cares;
/*
* Open the Voice Channel Device and Enable a Handler
*/
if ( ( dxxxdev = dx_open( "dxxxB1C1", NULL) ) == -1 ) {
perror( "dxxxB1C1" );
exit( 1 );
}
/*
* Take the phone off-hook
*/
if ( dx_sethook( dxxxdev, DX_OFFHOOK, EV_SYNC ) == -1 ) {
printf( "Unable to set the phone off-hook\n" );
printf( "Lasterror = %d Err Msg = %s\n",
ATDV_LASTERR( dxxxdev ), ATDV_ERRMSGP( dxxxdev ) );
dx_close( dxxxdev );
exit( 1 );
}
/*
* Perform an outbound dial with call progress analysis, using
* the default call progress analysis parameters.
*/
if((cares = dx_dial( dxxxdev,",84",(DX_CAP *) NULL, DX_CALLP )) == -1 ) {
printf( "Outbound dial failed - reason = %d\n",
ATDX_CPERROR( dxxxdev ) );
dx_close( dxxxdev );
exit( 1 );
}
/*
* Continue Processing
* .
* .
* .
*/
68 Voice API for Windows Operating Systems Library Reference — November 2003
return the call progress analysis error — ATDX_CPERROR( )
/*
* Close the opened Voice Channel Device
*/
if ( dx_close( dxxxdev ) != 0 ) {
perror( "close" );
}
/* Terminate the Program */
exit( 0 );
}
!!!! See Also
• dx_dial( )
• ATDX_CPTERM( )
• DX_CAP data structure
Voice API for Windows Operating Systems Library Reference — November 2003 69
ATDX_CPTERM( ) — return the last result of call progress analysis termination
ATDX_CPTERM( )
return the last result of call progress analysis termination
Name: long ATDX_CPTERM(chdev)
Inputs: int chdev
Returns: last call progress analysis termination if successful
AT_FAILURE if error
Includes: srllib.h
dxxxlib.h
Category: Extended Attribute
Mode: synchronous
Platform: DM3, Springware
!!!! Description
The ATDX_CPTERM( ) function returns the last result of call progress analysis termination on
the channel chdev. Call this function to determine the call status after dialing out with call progress
analysis enabled.
• valid channel device handle
See the Voice API Programming Guide for more information about call progress analysis.
Parameter Description
chdev specifies the valid channel device handle obtained when the channel was opened
using dx_open( )
Possible return values are the following:
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.
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. This return value is not supported on DM3
boards.
CR_NORB
No ringback on called line.
70 Voice API for Windows Operating Systems Library Reference — November 2003
return the last result of call progress analysis termination — ATDX_CPTERM( )
CR_STOPD
Call progress analysis stopped due to dx_stopch( ).
CR_ERROR
Call progress analysis error occurred. Use ATDX_CPERROR( ) to return the type of error.
!!!! Cautions
None.
!!!! Errors
This function will fail and return AT_FAILURE if an invalid channel device handle is specified in
chdev.
!!!! Example
/* Call progress analysis with user-specified parameters */
#include <srllib.h>
#include <dxxxlib.h>
main()
{
int chdev;
DX_CAP capp;
.
.
/* open the channel using dx_open( ). Obtain channel device descriptor
* in chdev
*/
if ((chdev = dx_open("dxxxB1C1",NULL)) == -1) {
/* process error */
}
/* take the phone off-hook */
if (dx_sethook(chdev,DX_OFFHOOK,EV_SYNC) == -1) {
/* process error */
} else {
/* Clear DX_CAP structure */
dx_clrcap(&capp);
/* Set the DX_CAP structure as needed for call progress analysis.
* Allow 3 rings before no answer.
*/
capp.ca_nbrdna = 3;
/* Perform the outbound dial with call progress analysis enabled. */
if (dx_dial(chdev,"5551212",&capp,DX_CALLP|EV_SYNC) == -1) {
/* perform error routine */
}
}
.
.
/* Examine last call progress termination on the device */
switch (ATDX_CPTERM(chdev)) {
case CR_CNCT: /* Call Connected, get some additional info */
.
.
break;
case CR_CEPT: /* Operator Intercept detected */
Voice API for Windows Operating Systems Library Reference — November 2003 71
ATDX_CPTERM( ) — return the last result of call progress analysis termination
.
.
break;
.
.
case AT_FAILURE: /* Error */
}
}
!!!! See Also
• dx_dial( )
• DX_CAP data structure
72 Voice API for Windows Operating Systems Library Reference — November 2003
return the last call progress analysis termination — ATDX_CRTNID( )
ATDX_CRTNID( )
return the last call progress analysis termination
Name: long ATDX_CRTNID(chdev)
Inputs: int chdev
Returns: identifier of the tone that caused the most recent call progress analysis termination, if successful
AT_FAILURE if error
Includes: srllib.h
dxxxlib.h
Category: Extended Attribute
Mode: synchronous
Platform: Springware
!!!! Description
The ATDX_CRTNID( ) function returns the last call progress analysis termination of the tone that
caused the most recent call progress analysis termination of the channel device. See the Voice API
Programming Guide for a description of call progress analysis.
• valid channel device handle
Parameter Description
chdev specifies the valid channel device handle obtained when the channel was opened
using dx_open( )
Possible return values are the following:
TID_BUSY1
First signal busy
TID_BUSY2
Second signal busy
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
First fax or modem tone
TID_FAX2
Second fax or modem tone
Voice API for Windows Operating Systems Library Reference — November 2003 73
ATDX_CRTNID( ) — return the last call progress analysis termination
TID_RNGBK1
Ringback (detected as single tone)
TID_RNGBK2
Ringback (detected as dual tone)
!!!! Cautions
None.
!!!! Errors
This function fails and returns AT_FAILURE if an invalid device handle is specified.
!!!! Example
#include <stdio.h>
#include <srllib.h>
#include <dxxxlib.h>
main()
{
DX_CAP cap_s;
int ddd, car;
char *chnam, *dialstrg;
chnam = "dxxxB1C1";
dialstrg = "L1234";
/*
* Open channel
*/
if ((ddd = dx_open( chnam, NULL )) == -1 ) {
/* handle error */
}
/*
* Delete any previous tones
*/
if ( dx_deltones(ddd) < 0 ) {
/* handle error */
}
/*
* Now enable call progress analysis with above changed settings.
*/
if (dx_initcallp( ddd )) {
/* handle error */
}
/*
* Set off Hook
*/
if ((dx_sethook( ddd, DX_OFFHOOK, EV_SYNC )) == -1) {
/* handle error */
}
74 Voice API for Windows Operating Systems Library Reference — November 2003
return the last call progress analysis termination — ATDX_CRTNID( )
/*
* Dial
*/
printf("Dialing %s\n", dialstrg );
car = dx_dial(ddd,dialstrg,(DX_CAP *)&cap_s,DX_CALLP|EV_SYNC);
if (car == -1) {
/* handle error */
}
switch( car ) {
case CR_NODIALTONE:
switch( ATDX_DTNFAIL(ddd) ) {
case 'L':
printf(" Unable to get Local dial tone\n");
break;
case 'I':
printf(" Unable to get International dial tone\n");
break;
case 'X':
printf(" Unable to get special eXtra dial tone\n");
break;
}
break;
case CR_BUSY:
printf(" %s engaged - %s detected\n", dialstrg,
(ATDX_CRTNID(ddd) == TID_BUSY1 ? "Busy 1" : "Busy 2") );
break;
case CR_CNCT:
printf(" Successful connection to %s\n", dialstrg );
break;
default:
break;
}
/*
* Set on Hook
*/
if ((dx_sethook( ddd, DX_ONHOOK, EV_SYNC )) == -1) {
/* handle error */
}
dx_close( ddd );
}
!!!! See Also
None.
Voice API for Windows Operating Systems Library Reference — November 2003 75
ATDX_DEVTYPE( ) — return the device type
ATDX_DEVTYPE( )
return the device type
Name: long ATDX_DEVTYPE(dev)
Inputs: int dev
Returns: device type if successful
AT_FAILURE if error
Includes: srllib.h
dxxxlib.h
Category: Extended Attribute
Mode: synchronous
Platform: DM3, Springware
!!!! Description
The ATDX_DEVTYPE( ) function returns the device type of the board or channel dev.
• valid board or channel device handle
Parameter Description
dev specifies the valid device handle obtained when a board or channel was opened
using dx_open( )
Possible return values are the following:
DT_DXBD
Board device (indicates virtual board)
DT_DXCH
Channel device
DT_PHYBD
Physical board device
!!!! Cautions
None.
!!!! Errors
This function will fail and return AT_FAILURE if an invalid board or channel device handle is
specified in dev.
76 Voice API for Windows Operating Systems Library Reference — November 2003
!!!! Example
#include <stdio.h>
#include <srllib.h>
#include <dxxxlib.h>
main()
{
int bddev;
long devtype;
/* Open the board device */
if ((bddev = dx_open("dxxxB1",NULL)) == -1) {
/* Process error */
}
if((devtype = ATDX_DEVTYPE(bddev)) == AT_FAILURE) {
/* Process error */
}
if(devtype == DT_DXBD) {
printf("Device is a Board\n");
}
/* Continue processing */
.
.
}
return the device type — ATDX_DEVTYPE( )
!!!! See Also
None.
Voice API for Windows Operating Systems Library Reference — November 2003 77
ATDX_DTNFAIL( ) — return character for dial tone
ATDX_DTNFAI L( )
return character for dial tone
Name: long ATDX_DTNFAIL(chdev)
Inputs: int chdev
Returns: code for the dial tone that failed to appear
AT_FAILURE if error
Includes: srllib.h
dxxxlib.h
Category: Extended Attribute
Mode: synchronous
Platform: Springware
!!!! Description
The ATDX_DTNFAIL( ) function returns the dial tone character that indicates which dial tone
call progress analysis failed to detect.
• valid channel device handle
Parameter Description
chdev specifies the valid channel device handle obtained when the channel was opened
using dx_open( )
Possible return values are the following:
L
Local dial tone
I
International dial tone
X
Special (“extra”) dial tone
!!!! Cautions
None.
!!!! Errors
This function fails and returns AT_FAILURE if an invalid device handle is specified.
!!!! Example
#include <stdio.h>
#include <srllib.h>
#include <dxxxlib.h>
78 Voice API for Windows Operating Systems Library Reference — November 2003
return character for dial tone — ATDX_DTNFAIL( )
main()
{
DX_CAP cap_s;
int ddd, car;
char *chnam, *dialstrg;
chnam = "dxxxB1C1";
dialstrg = "L1234";
/*
* Open channel
*/
if ((ddd = dx_open( chnam, NULL )) == -1 ) {
/* handle error */
}
/*
* Delete any previous tones
*/
if ( dx_deltones(ddd) < 0 ) {
/* handle error */
}
/*
* Now enable call progress analysis with above changed settings.
*/
if (dx_initcallp( ddd )) {
/* handle error */
}
/*
* Set off Hook
*/
if ((dx_sethook( ddd, DX_OFFHOOK, EV_SYNC )) == -1) {
/* handle error */
}
/*
* Dial
*/
printf("Dialing %s\n", dialstrg );
car = dx_dial(ddd,dialstrg,(DX_CAP *)&cap_s,DX_CALLP|EV_SYNC);
if (car == -1) {
/* handle error */
}
switch( car ) {
case CR_NODIALTONE:
switch( ATDX_DTNFAIL(ddd) ) {
case 'L':
printf(" Unable to get Local dial tone\n");
break;
case 'I':
printf(" Unable to get International dial tone\n");
break;
case 'X':
printf(" Unable to get special eXtra dial tone\n");
break;
}
break;
case CR_BUSY:
printf(" %s engaged - %s detected\n", dialstrg,
break;
ATDX_CRTNID(ddd) == TID_BUSY1 ? "Busy 1" : "Busy 2") );
Voice API for Windows Operating Systems Library Reference — November 2003 79
ATDX_DTNFAIL( ) — return character for dial tone
case CR_CNCT:
printf(" Successful connection to %s\n", dialstrg );
break;
default:
break;
}
/*
* Set on Hook
*/
if ((dx_sethook( ddd, DX_ONHOOK, EV_SYNC )) == -1) {
/* handle error */
}
dx_close( ddd );
}
!!!! See Also
None.
80 Voice API for Windows Operating Systems Library Reference — November 2003
return the duration of the first SIT sequence — ATDX_FRQDUR( )
ATDX_FRQDUR( )
return the duration of the first SIT sequence
Name: long ATDX_FRQDUR(chdev)
Inputs: int chdev
Returns: first frequency duration in 10 msec units if success
AT_FAILURE if error
Includes: srllib.h
dxxxlib.h
Category: Extended Attribute
Mode: synchronous
Platform: Springware
!!!! Description
The ATDX_FRQDUR( ) function returns the duration of the first Special Information Tone (SIT)
sequence in 10 msec units after dx_dial( ) terminated due to an Operator Intercept.
• valid channel device handle
Termination due to Operator Intercept is indicated by ATDX_CPTERM( ) returning CR_CEPT.
For information on SIT frequency detection, see the Voice API Programming Guide.
Parameter Description
chdev specifies the valid channel device handle obtained when the channel was opened
using dx_open( )
!!!! Cautions
None.
!!!! Errors
This function fails and returns AT_FAILURE if an invalid channel device handle is specified.
!!!! Example
This example illustrates ATDX_FRQDUR( ), ATDX_FRQDUR2( ), and ATDX_FRQDUR3( ).
/* Call progress analysis with user-specified parameters */
#include <stdio.h>
#include <srllib.h>
#include <dxxxlib.h>
main()
{
int cares, chdev;
DX_CAP capp;
.
.
Voice API for Windows Operating Systems Library Reference — November 2003 81
ATDX_FRQDUR( ) — return the duration of the first SIT sequence
/* open the channel using dx_open( ). Obtain channel device descriptor in
* chdev
*/
if ((chdev = dx_open("dxxxB1C1",NULL)) == -1) {
/* process error */
}
/* take the phone off-hook */
if (dx_sethook(chdev,DX_OFFHOOK,EV_SYNC) == -1) {
/* process error */
}
/* Set the DX_CAP structure as needed for call progress analysis. Perform the
* outbound dial with call progress analysis enabled
*/
if ((cares = dx_dial(chdev,"5551212",&capp,DX_CALLP|EV_SYNC)) == -1) {
/* perform error routine */
}
switch (cares) {
case CR_CNCT: /* Call Connected, get some additional info */
printf("\nDuration of short low - %ld ms",ATDX_SHORTLOW(chdev)*10);
printf("\nDuration of long low - %ld ms",ATDX_LONGLOW(chdev)*10);
printf("\nDuration of answer - %ld ms",ATDX_ANSRSIZ(chdev)*10);
break;
case CR_CEPT: /* Operator Intercept detected */
printf("\nFirst frequency detected - %ld Hz",ATDX_FRQHZ(chdev));
printf("\nSecond frequency detected - %ld Hz", ATDX_FRQHZ2(chdev));
printf("\nThird frequency detected - %ld Hz", ATDX_FRQHZ3(chdev));
printf("\nDuration of first frequency - %ld ms",
printf("\nDuration of second frequency - %ld ms",
printf("\nDuration of third frequency - %ld ms",
break;
case CR_BUSY:
break;
.
.
}
}
ATDX_FRQDUR(chdev)
ATDX_FRQDUR2(chdev)
ATDX_FRQDUR3(chdev)
);
);
);
!!!! See Also
• dx_dial( )
• ATDX _C PT ER M( )
• DX_CAP data structure
• call progress analysis topic in the Voice API Programming Guide
• ATDX_FRQDUR2( )
• ATDX_FRQDUR3( )
• ATDX_FRQHZ( )
• ATDX_FRQHZ2( )
• ATDX_FRQHZ3( )
82 Voice API for Windows Operating Systems Library Reference — November 2003
return the duration of the second SIT sequence — ATDX_FRQDUR2( )
ATDX_FRQDUR2( )
return the duration of the second SIT sequence
Name: long ATDX_FRQDUR2(chdev)
Inputs: int chdev
Returns: second frequency duration in 10 msec units if success
AT_FAILURE if error
Includes: srllib.h
dxxxlib.h
Category: Extended Attribute
Mode: synchronous
Platform: Springware
!!!! Description
The ATDX_FRQDUR2( ) function returns the duration of the second Special Information Tone
(SIT) sequence in 10 msec units after dx_dial( ) terminated due to an Operator Intercept.
• valid channel device handle
Termination due to Operator Intercept is indicated by ATDX_CPTERM( ) returning CR_CEPT.
For information on SIT frequency detection, see the Voice API Programming Guide.
Parameter Description
chdev specifies the valid channel device handle obtained when the channel was opened
using dx_open( )
!!!! Cautions
None.
!!!! Errors
This function fails and returns AT_FAILURE if an invalid channel device handle is specified.
!!!! Example
See the example for ATDX_FRQDUR( ).
!!!! See Also
• dx_dial( )
• ATDX_CPTERM( )
• DX_CAP data structure
• call progress analysis topic in the Voice API Programming Guide
• ATDX_FRQDUR( )
Voice API for Windows Operating Systems Library Reference — November 2003 83
ATDX_FRQDUR2( ) — return the duration of the second SIT sequence
• ATDX_FRQDUR3( )
• ATDX_FRQHZ( )
• ATDX_FRQHZ2( )
• ATDX_FRQHZ3( )
84 Voice API for Windows Operating Systems Library Reference — November 2003
return the duration of the third SIT sequence — ATDX_FRQDUR3( )
ATDX_FRQDUR3( )
return the duration of the third SIT sequence
Name: long ATDX_FRQDUR3(chdev)
Inputs: int chdev
Returns: third frequency duration in 10 msec units if success
AT_FAILURE if error
Includes: srllib.h
dxxxlib.h
Category: Extended Attribute
Mode: synchronous
Platform: Springware
!!!! Description
The ATDX_FRQDUR3( ) function returns the duration of the third Special Information Tone
(SIT) sequence in 10 msec units after dx_dial( ) terminated due to an Operator Intercept.
• valid channel device handle
Termination due to Operator Intercept is indicated by ATDX_CPTERM( ) returning CR_CEPT.
For information on SIT frequency detection, see the Voice API Programming Guide.
Parameter Description
chdev specifies the valid channel device handle obtained when the channel was opened
using dx_open( )
!!!! Cautions
None.
!!!! Errors
This function fails and returns AT_FAILURE if an invalid channel device handle is specified.
!!!! Example
See the example for ATDX_FRQDUR( ).
!!!! See Also
• dx_dial( )
• ATDX_CPTERM( )
• DX_CAP data structure
• call progress analysis topic in Voice API Programming Guide
• ATDX_FRQDUR( )
Voice API for Windows Operating Systems Library Reference — November 2003 85
ATDX_FRQDUR3( ) — return the duration of the third SIT sequence
• ATDX_FRQDUR2( )
• ATDX_FRQHZ( )
• ATDX_FRQHZ2( )
• ATDX_FRQHZ3( )
86 Voice API for Windows Operating Systems Library Reference — November 2003
return the frequency of the first SIT sequence — ATDX_FRQHZ( )
ATDX_FRQHZ( )
return the frequency of the first SIT sequence
Name: long ATDX_FRQHZ(chdev)
Inputs: int chdev
Returns: first tone frequency in Hz if success
AT_FAILURE if error
Includes: srllib.h
dxxxlib.h
Category: Extended Attribute
Mode: synchronous
Platform: Springware
!!!! Description
The ATDX_FRQHZ( ) function returns the frequency in Hz of the first Special Information Tone
(SIT) sequence after dx_dial( )has terminated due to an Operator Intercept.
• valid channel device handle
Termination due to Operator Intercept is indicated by ATDX_CPTERM( ) returning CR_CEPT.
For information on SIT frequency detection, see the Voice API Programming Guide.
Parameter Description
chdev specifies the valid channel device handle obtained when the channel was opened
using dx_open( )
!!!! Cautions
None.
!!!! Errors
This function fails and returns AT_FAILURE if an invalid channel device handle is specified.
!!!! Example
This example illustrates the use of ATDX_FRQHZ( ), ATDX_FRQHZ2( ), and
ATDX_FRQHZ3( ).
/* Call progress analysis with user-specified parameters */
#include <stdio.h>
#include <srllib.h>
#include <dxxxlib.h>
main()
{
int cares, chdev;
DX_CAP capp;
.
Voice API for Windows Operating Systems Library Reference — November 2003 87
ATDX_FRQHZ( ) — return the frequency of the first SIT sequence
.
/* open the channel using dx_open( ). Obtain channel device descriptor in
* chdev
*/
if ((chdev = dx_open("dxxxB1C1",NULL)) == -1) {
/* process error */
}
/* take the phone off-hook */
if (dx_sethook(chdev,DX_OFFHOOK,EV_SYNC) == -1) {
/* process error */
}
/* Set the DX_CAP structure as needed for call progress analysis. Perform the
* outbound dial with call progress analysis enabled
*/
if ((cares = dx_dial(chdev,"5551212",&capp,DX_CALLP|EV_SYNC)) == -1) {
/* perform error routine */
}
switch (cares) {
case CR_CNCT: /* Call Connected, get some additional info */
printf("\nDuration of short low - %ld ms",ATDX_SHORTLOW(chdev)*10);
printf("\nDuration of long low - %ld ms",ATDX_LONGLOW(chdev)*10);
printf("\nDuration of answer - %ld ms",ATDX_ANSRSIZ(chdev)*10);
break;
case CR_CEPT: /* Operator Intercept detected */
printf("\nFirst frequency detected - %ld Hz",
printf("\nSecond frequency detected - %ld Hz",
printf("\nThird frequency detected - %ld Hz",
printf("\nDuration of first frequency - %ld ms", ATDX_FRQDUR(chdev));
printf("\nDuration of second frequency - %ld ms", ATDX_FRQDUR2(chdev));
printf("\nDuration of third frequency - %ld ms", ATDX_FRQDUR3(chdev));
break;
case CR_BUSY:
break;
.
.
}
}
ATDX_FRQHZ(chdev)
ATDX_FRQHZ2(chdev)
ATDX_FRQHZ3(chdev)
);
);
);
!!!! See Also
• dx_dial( )
• ATDX _C PT ER M( )
• DX_CAP data structure
• call progress analysis topic in the Voice API Programming Guide
• ATDX_FRQHZ2( )
• ATDX_FRQHZ3( )
• ATDX_FRQDUR( )
• ATDX_FRQDUR2( )
• ATDX_FRQDUR3( )
88 Voice API for Windows Operating Systems Library Reference — November 2003
return the frequency of the second SIT sequence — ATDX_FRQHZ2( )
ATDX_FRQHZ2( )
return the frequency of the second SIT sequence
Name: long ATDX_FRQHZ2(chdev)
Inputs: int chdev
Returns: second tone frequency in Hz if success
AT_FAILURE if error
Includes: srllib.h
dxxxlib.h
Category: Extended Attribute
Mode: synchronous
Platform: Springware
!!!! Description
The ATDX_FRQHZ2( ) function returns the frequency in Hz of the second Special Information
Tone (SIT) sequence after dx_dial( ) has terminated due to an Operator Intercept.
• valid channel device handle
Termination due to Operator Intercept is indicated by ATDX_CPTERM( ) returning CR_CEPT.
For information on SIT frequency detection, see the Voice API Programming Guide.
Parameter Description
chdev specifies the valid channel device handle obtained when the channel was opened
using dx_open( )
!!!! Cautions
None.
!!!! Errors
This function fails and returns AT_FAILURE if an invalid channel device handle is specified.
!!!! Example
See the example for ATDX_FRQHZ( ).
!!!! See Also
• dx_dial( )
• ATDX_CPTERM( )
• DX_CAP data structure
• call progress analysis topic in the Voice API Programming Guide
• ATDX_FRQHZ( )
Voice API for Windows Operating Systems Library Reference — November 2003 89
ATDX_FRQHZ2( ) — return the frequency of the second SIT sequence
• ATDX_FRQHZ3( )
• ATDX_FRQDUR( )
• ATDX_FRQDUR2( )
• ATDX_FRQDUR3( )
90 Voice API for Windows Operating Systems Library Reference — November 2003
return the frequency of the third SIT sequence — ATDX_FRQHZ3( )
ATDX_FRQHZ3( )
return the frequency of the third SIT sequence
Name: long ATDX_FRQHZ3(chdev)
Inputs: int chdev
Returns: third tone frequency in Hz if success
AT_FAILURE if error
Includes: srllib.h
dxxxlib.h
Category: Extended Attribute
Mode: synchronous
Platform: Springware
!!!! Description
The ATDX_FRQHZ3( ) function returns the frequency in Hz of the third Special Information
Tone (SIT) sequence after dx_dial( ) has terminated due to an Operator Intercept.
• valid channel device handle
Termination due to Operator Intercept is indicated by ATD X _C PT ER M ( ) returning CR_CEPT.
For information on SIT frequency detection, see the Voice API Programming Guide.
Parameter Description
chdev specifies the valid channel device handle obtained when the channel was opened
using dx_open( )
!!!! Cautions
None.
!!!! Errors
This function fails and returns AT_FAILURE if an invalid channel device handle is specified.
!!!! Example
See the example for ATDX_FRQHZ( ).
!!!! See Also
• dx_dial( )
• ATDX_CPTERM( )
• DX_CAP structure
• call progress analysis topic in the Voice API Programming Guide
• ATDX_FRQHZ( )
Voice API for Windows Operating Systems Library Reference — November 2003 91
ATDX_FRQHZ3( ) — return the frequency of the third SIT sequence
• ATDX_FRQHZ2( )
• ATDX_FRQDUR( )
• ATDX_FRQDUR2( )
• ATDX_FRQDUR3( )
92 Voice API for Windows Operating Systems Library Reference — November 2003
return percentage of time SIT tone was out of bounds — ATDX_FRQOUT( )
ATDX_FRQOUT( )
return percentage of time SIT tone was out of bounds
Name: long ATDX_FRQOUT(chdev)
Inputs: int chdev
Returns: percentage frequency out-of bounds
AT_FAILURE if error
Includes: srllib.h
dxxxlib.h
Category: Extended Attribute
Mode: synchronous
Platform: Springware
!!!! Description
The ATDX_FRQOUT( ) function returns percentage of time SIT tone was out of bounds as
specified by the range in the DX_CAP structure.
• valid channel device handle
Upon detection of a frequency within the range specified in the DX_CAP structure ca_upperfrq
and lower ca_lowerfrq, use this function to optimize the ca_rejctfrq parameter (which sets the
percentage of time that the frequency can be out of bounds).
For information on SIT frequency detection, see the Voice API Programming Guide.
Parameter Description
chdev specifies the valid channel device handle obtained when the channel was opened
using dx_open( )
!!!! Cautions
This function is only for use with non-DSP boards. If you call it on a DSP board, it will return zero.
!!!! Errors
This function will fail and return AT_FAILURE if an invalid channel device handle is specified in
chdev.
!!!! Example
/* Call progress analysis with user-specified parameters */
#include <stdio.h>
#include <srllib.h>
#include <dxxxlib.h>
Voice API for Windows Operating Systems Library Reference — November 2003 93
ATDX_FRQOUT( ) — return percentage of time SIT tone was out of bounds
main()
{
int cares, chdev;
DX_CAP capp;
.
.
/* open the channel using dx_open( ). Obtain channel device descriptor in
* chdev
*/
if ((chdev = dx_open("dxxxB1C1",NULL)) == -1) {
/* process error */
}
/* take the phone off-hook */
if (dx_sethook(chdev,DX_OFFHOOK,EV_SYNC) == -1) {
/* process error */
}
/* Set the DX_CAP structure as needed for call progress analysis. Perform the
* outbound dial with call progress analysis enabled.
*/
if ((cares = dx_dial(chdev,"5551212",&capp,DX_CALLP|EV_SYNC)) == -1) {
/* perform error routine */
}
switch (cares) {
case CR_CNCT: /* Call Connected, get some additional info */
printf("\nDuration of short low - %ld ms",ATDX_SHORTLOW(chdev)*10);
printf("\nDuration of long low - %ld ms",ATDX_LONGLOW(chdev)*10);
printf("\nDuration of answer - %ld ms",ATDX_ANSRSIZ(chdev)*10);
break;
case CR_CEPT: /* Operator Intercept detected */
printf("\nFrequency detected - %ld Hz",ATDX_FRQHZ(chdev));
printf("\n%% of Frequency out of bounds - %ld Hz",
break;
case CR_BUSY:
break;
.
.
}
}
ATDX_FRQOUT(chdev)
);
!!!! See Also
• dx_dial( )
• ATDX _C PT ER M( )
• DX_CAP data structure
• call progress analysis topic in the Voice API Programming Guide
94 Voice API for Windows Operating Systems Library Reference — November 2003
ATD X_FWVE R( )
return the voice firmware version number
Name: long ATDX_FWVER(bddev)
Inputs: int bddev
Returns: D/4x Firmware version if successful
AT_FAILURE if error
Includes: srllib.h
dxxxlib.h
Category: Extended Attribute
Mode: synchronous
Platform: Springware
!!!! Description
The ATDX_FWVER( ) function returns the voice firmware version number or emulated D/4x
firmware version number.
• valid board device handle
return the voice firmware version number — ATDX_FWVER( )
Parameter Description
bddev specifies the valid board device handle obtained when the board was opened
using dx_open( )
This function returns a 32-bit value in the following format.
TTTT|MMMM|mmmmmmmm|AAAAAAAA|aaaaaaaa
where each letter represents one bit of data with the following meanings:
Letter Description
T Type of Release. Decimal values have the following meanings (example: 0010
for Alpha release):
• 0 – Production
• 1 – Beta
• 2 – Alpha
• 3 – Experimental
• 4 – Special
M Major version number for a production release in BCD format. Example: 0011
for version “3”
m Minor version number for a production release in BCD format. Example:
00000001 for “.10”
A Major version number for a non-production release in BCD format. Example:
00000100 for version “4”
a Minor version number for a non-production release in BCD format. Example:
00000010 for version “.02”
Voice API for Windows Operating Systems Library Reference — November 2003 95
ATDX_FWVER( ) — return the voice firmware version number
Example: 0000 0010 0001 0101 0000 0000 0000 0000 (Production v2.15)
!!!! Cautions
None.
!!!! Errors
This function will fail and return AT_FAILURE if an invalid device handle is specified in bddev.
!!!! Example
#include <stdio.h>
#include <srllib.h>
#include <dxxxlib.h>
#include <windows.h>
void GetFwlVersion(char *, long);
main()
{
int bddev;
char *bdname, FWVersion[50];
long fwver;
bdname = "dxxxB1";
/*
* Open board device
*/
if ((bddev = dx_open(bdname, NULL)) == -1)
{
/* Handle error */
}
if ((fwver =
{
/* Handle error */
}
/*
* Parse fw version
*/
GetFwlVersion(FWVersion, fwver);
printf("%s\n", FWVersion");
} /* end main */
ATDX_FWVER(bddev)
) == AT_FAILURE)
!!!! See Also
None.
96 Voice API for Windows Operating Systems Library Reference — November 2003
ATDX_HOOKST( )
return the current hook-switch state
Name: long ATDX_HOOKST(chdev)
Inputs: int chdev
Returns: current hook state of channel if successful
AT_FAILURE if error
Includes: srllib.h
dxxxlib.h
Category: Extended Attribute
Mode: synchronous
Platform: Springware
!!!! Description
The ATDX_HOOKST( ) function returns the current hook-switch state of the channel chdev.
• valid channel device handle
return the current hook-switch state — ATDX_HOOKST( )
Note: This function is not supported on digital interfaces.
Parameter Description
chdev specifies the valid channel device handle obtained when the channel was opened
using dx_open( )
Possible return values are the following:
DX_OFFHOOK
Channel is off-hook
DX_ONHOOK
Channel is on-hook
!!!! Cautions
None.
!!!! Errors
This function will fail and return AT_FAILURE if an invalid channel device handle is specified in
chdev.
!!!! Example
#include <srllib.h>
#include <dxxxlib.h>
Voice API for Windows Operating Systems Library Reference — November 2003 97
ATDX_HOOKST( ) — return the current hook-switch state
main()
{
int chdev;
long hookst;
/* Open the channel device */
if ((chdev = dx_open("dxxxB1C1",NULL)) == -1) {
/* Process error */
}
.
.
/* Examine Hook state of the channel. Perform application specific action */
if((hookst =
/* Process error */
}
if(hookst == DX_OFFHOOK) {
/* Channel is Off-hook */
}
.
.
}
ATDX_HOOKST(chdev)
) == AT_FAILURE) {
!!!! See Also
• dx_sethook( )
• DX_CST structure
• dx_setevtmsk( ) for enabling hook state (call status transition events)
• sr_getevt( ) for synchronous call status transition event detection
• DX_EBLK for asynchronous call status transition event detection
• sr_getevtdatap( ) in the Standard Runtime Library API Library Reference
98 Voice API for Windows Operating Systems Library Reference — November 2003
return the current activity on the channel — ATDX_LINEST( )
ATDX_LINEST( )
return the current activity on the channel
Name: long ATDX_LINEST(chdev)
Inputs: int chdev
Returns: current line status of channel if successful
AT_FAILURE if error
Includes: srllib.h
dxxxlib.h
Category: Extended Attribute
Mode: synchronous
Platform: Springware
!!!! Description
The ATDX_LINEST( ) function returns the current activity on the channel specified in chdev. The
information is returned in a bitmap.
• valid channel device handle
Parameter Description
chdev specifies the valid channel device handle obtained when the channel was opened
using dx_open( )
Possible return values are the following:
RLS_DTMF
DTMF signal present
RLS_HOOK
Channel is on-hook
RLS_LCSENSE
Loop current not present
RLS_RING
Ring not present
RLS_RINGBK
Audible ringback detected
RLS_SILENCE
Silence on the line
!!!! Cautions
None.
Voice API for Windows Operating Systems Library Reference — November 2003 99
ATDX_LINEST( ) — return the current activity on the channel
!!!! Errors
This function will fail and return AT_FAILURE if an invalid channel device handle is specified in
chdev.
!!!! Example
#include <srllib.h>
#include <dxxxlib.h>
main()
{
int chdev;
long linest;
/* Open the channel device */
if ((chdev = dx_open("dxxxB1C1",NULL)) == -1) {
/* Process error */
}
/* Examine line status bitmap of the channel. Perform application-specific
* action
*/
if((linest =
/* Process error */
}
ATDX_LINEST(chdev)
) == AT_FAILURE) {
if(linest & RLS_LCSENSE) {
/* No loop current */
}
.
.
}
!!!! See Also
None.
100 Voice API for Windows Operating Systems Library Reference — November 2003
Loading...