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.
Contents Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 About This Publication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Intended Audience. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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 . . . . . . . . . . . . . . . . . . .
Contents dx_createtone( ) – create a new tone definition for a specific call progress tone . . . . . . . . . . . . dx_deletetone( ) – delete a specific call progress tone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . dx_deltones( ) – delete all user-defined tones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . dx_dial( ) – dial an ASCIIZ string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents CT_DEVINFO – channel/time slot device information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DV_DIGIT – user digit buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DV_TPT – termination parameter table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DX_ATTENDANT – Syntellect License Automated Attendant . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Figures 1 8 Format of General Caller ID Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Tables 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 Voice Function Support by Platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 Valid Dial String Characters (DM3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 Valid Dial String Characters (Springware) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190 System Error Values . . . . .
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.
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 enhancements. Events chapter : Added section for unsolicited events returned by streaming to board functions. 05-1832-001 November 2002 Initial version of document. Much of the information contained in this document was previously published in the Voice Software Reference Programmer's Guide for Windows, document number 05-1456-003.
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.
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.
Function Summary by Category 1. 1 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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.
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
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.
Function Summary by Category 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.
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).
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.
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.
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( ).
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: 1.14 The dx_playtone( ) and dx_playtoneEx( ) functions can also be classified as an I/O function and all I/O characteristics apply. 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.
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.
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.
Function Summary by Category 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.
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_CPTERM( ) returns last call progress analysis termination ATDX_CRTNID( ) returns the id
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
Function Summary by Category Table 1.
Function Summary by Category Table 1.
Function Summary by Category Table 1.
Function Summary by Category Table 1.
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 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( ).
Function Information 2. 2 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.
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 • pointer to device information structure 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.
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 #include
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 • pointer to TDM bus time slot information structure Returns: 0 on success -1 on error Includes: srllib.h dxxxlib.
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.
ag_getxmitslot( ) — get TDM bus time slot number of analog transmit channel ! See Also 40 • 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 Voice API for Windows Operating Systems Library Reference — November 2003
connect analog receive channel to TDM bus time slot — ag_listen( ) ag_listen( ) connect analog receive channel to TDM bus time slot Name: int ag_listen (chdev, sc_tsinfop) Inputs: int chdev • valid analog channel device handle SC_TSINFO *sc_tsinfop • pointer to TDM bus time slot information structure Returns: 0 on success -1 on error Includes: srllib.h dxxxlib.
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.
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.
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 • analog channel device handle 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.
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.
ai_close( ) — close an audio input device ai_close( ) close an audio input device Name: int ai_close(devh) Inputs: int devh • valid audio input device handle 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.
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.
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 • pointer to TDM bus time slot information structure Returns: 0 on success -1 on error Includes: srllib.h dxxxlib.
get TDM bus time slot number of audio input transmit channel — ai_getxmitslot( ) ! Example #include #include #include #include int main() { int SC_TSINFO long aidev; sc_tsinfo; scts; /* Audio input device handle */ /* Time slot information structure */ /* 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.
ai_open( ) — open an audio input device ai_open( ) open an audio input device Name: int ai_open(namep) Inputs: const char *namep • pointer to an ASCIIZ string that contains the name of a valid audio input device Returns: audio input device handle if successful -1 if failure Includes: srllib.h dxxxlib.h Category: Audio Input Mode: synchronous Platform: DM3 ! Description The ai_open( ) function opens an audio input device and returns a unique device handle to identify the device.
open an audio input device — ai_open( ) int main() { int SC_TSINFO long aidev; sc_tsinfo; scts; /* Audio input device handle */ /* Time slot information structure */ /* 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.
ATDX_ANSRSIZ( ) — return the duration of the answer ATDX_ANSRSIZ( ) return the duration of the answer Name: long ATDX_ANSRSIZ(chdev) Inputs: int chdev • valid channel device handle Returns: answer duration in 10 msec units if successful AT_FAILURE if error Includes: srllib.h dxxxlib.
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.
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 • valid channel device handle Returns: pointer to board device name string if successful pointer to ASCIIZ string “Unknown device” if error Includes: srllib.h dxxxlib.
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.
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 • valid board or channel device handle 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.
return the board type for the device — ATDX_BDTYPE( ) ! Example #include #include #include #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.
ATDX_BUFDIGS( ) — return the number of uncollected digits ATDX_BUFDIGS( ) return the number of uncollected digits Name: long ATDX_BUFDIGS(chdev) Inputs: int chdev • valid channel device handle Returns: number of uncollected digits in the firmware buffer if successful AT_FAILURE if error Includes: srllib.h dxxxlib.
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.
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 • valid board device handle 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.
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
ATDX_CHNUM( ) — return the channel number ATDX_CHNUM( ) return the channel number Name: long ATDX_CHNUM(chdev) Inputs: int chdev • valid channel device handle 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.
return the channel number — ATDX_CHNUM( ) if((chno = ATDX_CHNUM(chdev)) == AT_FAILURE) { /* Process error */ } /* Use chno for application-specific purposes */ . . } ! See Also None.
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 • valid channel device handle 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.
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 #include #include
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
return the call progress analysis error — ATDX_CPERROR( ) ATDX_CPERROR( ) return the call progress analysis error Name: long ATDX_CPERROR(chdev) Inputs: int chdev • valid channel device handle Returns: call progress analysis error if success AT_FAILURE if function fails Includes: srllib.h dxxxlib.
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 #include #include
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 • valid channel device handle Returns: last call progress analysis termination if successful AT_FAILURE if error Includes: srllib.h dxxxlib.
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 #include
ATDX_CPTERM( ) — return the last result of call progress analysis termination . . break; . .
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 • valid channel device handle Returns: identifier of the tone that caused the most recent call progress analysis termination, if successful AT_FAILURE if error Includes: srllib.h dxxxlib.
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 #include #include
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 break; case 'I': printf(" Unable to get break; case 'X': printf(" Unable to get break; } break; ) { Local dial tone\n"); International dial tone\n"); special eXtra dial tone\n"); case CR_BUSY: pr
ATDX_DEVTYPE( ) — return the device type ATDX_DEVTYPE( ) return the device type Name: long ATDX_DEVTYPE(dev) Inputs: int dev • valid board or channel device handle 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.
return the device type — ATDX_DEVTYPE( ) ! Example #include #include #include 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 */ . . } ! See Also None.
ATDX_DTNFAIL( ) — return character for dial tone ATDX_DTNFAIL( ) return character for dial tone Name: long ATDX_DTNFAIL(chdev) Inputs: int chdev • valid channel device handle 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.
return character for dial tone — ATDX_DTNFAIL( ) main() { DX_CAP int char cap_s; ddd, car; *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.
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.
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 • valid channel device handle Returns: first frequency duration in 10 msec units if success AT_FAILURE if error Includes: srllib.h dxxxlib.
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.
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 • valid channel device handle Returns: second frequency duration in 10 msec units if success AT_FAILURE if error Includes: srllib.h dxxxlib.
ATDX_FRQDUR2( ) — return the duration of the second SIT sequence 84 • ATDX_FRQDUR3( ) • ATDX_FRQHZ( ) • ATDX_FRQHZ2( ) • ATDX_FRQHZ3( ) 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 • valid channel device handle Returns: third frequency duration in 10 msec units if success AT_FAILURE if error Includes: srllib.h dxxxlib.
ATDX_FRQDUR3( ) — return the duration of the third SIT sequence 86 • ATDX_FRQDUR2( ) • ATDX_FRQHZ( ) • ATDX_FRQHZ2( ) • ATDX_FRQHZ3( ) 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 • valid channel device handle Returns: first tone frequency in Hz if success AT_FAILURE if error Includes: srllib.h dxxxlib.
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.
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 • valid channel device handle Returns: second tone frequency in Hz if success AT_FAILURE if error Includes: srllib.h dxxxlib.
ATDX_FRQHZ2( ) — return the frequency of the second SIT sequence 90 • ATDX_FRQHZ3( ) • ATDX_FRQDUR( ) • ATDX_FRQDUR2( ) • ATDX_FRQDUR3( ) 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 • valid channel device handle Returns: third tone frequency in Hz if success AT_FAILURE if error Includes: srllib.h dxxxlib.
ATDX_FRQHZ3( ) — return the frequency of the third SIT sequence 92 • ATDX_FRQHZ2( ) • ATDX_FRQDUR( ) • ATDX_FRQDUR2( ) • ATDX_FRQDUR3( ) 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 • valid channel device handle Returns: percentage frequency out-of bounds AT_FAILURE if error Includes: srllib.h dxxxlib.
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.
return the voice firmware version number — ATDX_FWVER( ) ATDX_FWVER( ) return the voice firmware version number Name: long ATDX_FWVER(bddev) Inputs: int bddev • valid board device handle 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.
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 #include #include #include
return the current hook-switch state — ATDX_HOOKST( ) ATDX_HOOKST( ) return the current hook-switch state Name: long ATDX_HOOKST(chdev) Inputs: int chdev • valid channel device handle 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.
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 = ATDX_HOOKST(chdev)) == AT_FAILURE) { /* Process error */ } if(hookst == DX_OFFHOOK) { /* Channel is Off-hook */ } . .
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 • valid channel device handle 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.
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 #include 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.
return duration of longer silence detected — ATDX_LONGLOW( ) ATDX_LONGLOW( ) return duration of longer silence detected Name: long ATDX_LONGLOW(chdev) Inputs: int chdev • valid channel device handle Returns: duration of longer silence if successful AT_FAILURE if error Includes: srllib.h dxxxlib.
ATDX_LONGLOW( ) — return duration of longer silence detected . /* 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.
return the physical board address — ATDX_PHYADDR( ) ATDX_PHYADDR( ) return the physical board address Name: long ATDX_PHYADDR(bddev) Inputs: int bddev • valid board device handle Returns: physical address of board if successful AT_FAILURE if error Includes: srllib.h dxxxlib.h Category: Extended Attribute Mode: synchronous Platform: Springware ! Description The ATDX_PHYADDR( ) function returns the physical board address for the board device bddev.
ATDX_PHYADDR( ) — return the physical board address printf("Board is at address %X\n",phyaddr); . . } ! See Also None.
return duration of shorter silence detected — ATDX_SHORTLOW( ) ATDX_SHORTLOW( ) return duration of shorter silence detected Name: long ATDX_SHORTLOW(chdev) Inputs: int chdev • valid channel device handle Returns: duration of shorter silence if successful AT_FAILURE if error Includes: srllib.h dxxxlib.
ATDX_SHORTLOW( ) — return duration of shorter silence detected ! Example /* Call progress analysis with user-specified parameters */ #include #include #include main() { int cares, chdev; DX_CAP capp; . . /* open the channel using dx_open( ).
return duration of initial non-silence — ATDX_SIZEHI( ) ATDX_SIZEHI( ) return duration of initial non-silence Name: long ATDX_SIZEHI(chdev) Inputs: int chdev • valid channel device handle Returns: non-silence duration in 10 msec units if successful AT_FAILURE if error Includes: srllib.h dxxxlib.
ATDX_SIZEHI( ) — return duration of initial non-silence . /* 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.
return the current state of the channel — ATDX_STATE( ) ATDX_STATE( ) return the current state of the channel Name: long ATDX_STATE(chdev) Inputs: int chdev • valid channel device handle Returns: current state of channel if successful AT_FAILURE if error Includes: srllib.h dxxxlib.h Category: Extended Attribute Mode: synchronous Platform: DM3, Springware ! Description The ATDX_STATE( ) function returns the current state of the channel chdev.
ATDX_STATE( ) — return the current state of the channel CS_WINK Wink state When a VFX combined resource board is being used to send and receive faxes the following states may be returned: CS_SENDFAX Channel is in a fax transmission state. CS_RECVFAX Channel is in a fax reception state. Note: A device is idle if there is no I/O function active on it. ! Cautions This function extracts the current state from the driver and requires the same processing resources as many other functions.
return the reason for the last I/O function termination — ATDX_TERMMSK( ) ATDX_TERMMSK( ) return the reason for the last I/O function termination Name: long ATDX_TERMMSK(chdev) Inputs: int chdev • valid channel device handle Returns: channel’s last termination bitmap if successful AT_FAILURE if error Includes: srllib.h dxxxlib.
ATDX_TERMMSK( ) — return the reason for the last I/O function termination TM_NORMTERM Normal termination (for dx_dial( ), dx_sethook( )) TM_TONE Tone-on/off event TM_USRSTOP Function stopped by user On Springware boards, possible return values are the following: TM_DIGIT Specific digit received TM_EOD End of data reached (on playback, receive) TM_ERROR I/O device error TM_IDDTIME Inter-digit delay TM_LCOFF Loop current off.
return the reason for the last I/O function termination — ATDX_TERMMSK( ) • On DM3 boards, when both DX_MAXDTMF and DX_DIGMASK termination conditions are specified in the DV_TPT structure, and both conditions are satisfied, the ATDX_TERMMSK( ) function will return the TM_MAXDTMF termination event only.
ATDX_TERMMSK( ) — return the reason for the last I/O function termination tpt[2].tp_termno tpt[2].tp_length tpt[2].tp_flags tpt[3].tp_type tpt[3].tp_termno tpt[3].tp_length tpt[3].
return user-defined tone ID that terminated I/O function — ATDX_TONEID( ) ATDX_TONEID( ) return user-defined tone ID that terminated I/O function Name: long ATDX_TONEID(chdev) Inputs: int chdev • valid channel device handle Returns: user-defined tone ID if successful AT_FAILURE if error Includes: srllib.h dxxxlib.h Category: Extended Attribute Mode: synchronous Platform: DM3, Springware ! Description The ATDX_TONEID( ) function returns the user-defined tone ID that terminated an I/O function.
ATDX_TONEID( ) — return user-defined tone ID that terminated I/O function /* * Open the D/xxx Channel Device and Enable a Handler */ if ( ( chdev = dx_open( "dxxxB1C1", NULL ) ) == -1 ) { perror( "dxxxB1C1" ); exit( 1 ); } /* * Describe a Simple Dual Tone Frequency Tone of 950* 1050 Hz and 475-525 Hz using leading edge detection.
return user-defined tone ID that terminated I/O function — ATDX_TONEID( ) /* * Continue Processing * . * . * . */ /* * Close the opened D/xxx Channel Device */ if ( dx_close( chdev ) != 0 ) { perror( "close" ); } /* Terminate the Program */ exit( 0 ); } ! See Also None.
ATDX_TRCOUNT( ) — return the byte count for the last I/O transfer ATDX_TRCOUNT( ) return the byte count for the last I/O transfer Name: long ATDX_TRCOUNT(chdev) Inputs: int chdev • valid channel device handle Returns: last play/record transfer count if successful AT_FAILURE if error Includes: srllib.h dxxxlib.
return the byte count for the last I/O transfer — ATDX_TRCOUNT( ) /* Record a voice file. Terminate on receiving a digit, max time, * or reaching a byte count of 50000 bytes. */ . . /* set up DX_IOTT */ iott.io_type = IO_DEV|IO_EOT; iott.io_bufp = 0; iott.io_offset = 0L; iott.io_length = 50000L; if((iott.io_fhandle = dx_fileopen("file.vox", O_RDWR)) == -1) { /* process error */ } /* set up DV_TPTs for the required dx_clrtpt(tpt,2); tpt[0].tp_type = IO_CONT; tpt[0].tp_termno = DX_MAXDTMF; tpt[0].
dx_addspddig( ) — set a DTMF digit to adjust speed dx_addspddig( ) set a DTMF digit to adjust speed Name: int dx_addspddig(chdev, digit, adjval) Inputs: int chdev • valid channel device handle char digit • DTMF digit short adjval • speed adjustment value Returns: 0 if success -1 if failure Includes: srllib.h dxxxlib.
set a DTMF digit to adjust speed — dx_addspddig( ) Parameter Description digit specifies a DTMF digit (0-9, *,#) that will modify speed by the amount specified in adjval adjval specifies a speed adjustment value to take effect whenever the digit specified in digit occurs: On DM3 boards, the following are valid values: • SV_ADD10PCT – increase play speed by 10% • SV_NORMAL – set play speed to origin (regular speed) when the play begins. digit must be set to NULL.
dx_addspddig( ) — set a DTMF digit to adjust speed ! 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.
set a DTMF digit to adjust speed — dx_addspddig( ) /* * Close the opened Voice Channel Device */ if ( dx_close( dxxxdev ) != 0 ) { perror( "close" ); } /* Terminate the Program */ exit( 0 ); } ! See Also • dx_addvoldig( ) • dx_adjsv( ) • dx_clrsvcond( ) • dx_getcursv( ) • dx_getsvmt( ) • dx_setsvcond( ) • dx_setsvmt( ) • speed and volume modification tables in the Voice API Programming Guide • DX_SVMT data structure • DX_SVCB data structure Voice API for Windows Operating Systems Libra
dx_addtone( ) — add a user-defined tone dx_addtone( ) add a user-defined tone Name: int dx_addtone(chdev, digit, digtype) Inputs: int chdev • valid channel device handle unsigned char digit • optional digit associated with the bound tone unsigned char digtype • digit type Returns: 0 if success -1 if failure Includes: srllib.h dxxxlib.
add a user-defined tone — dx_addtone( ) Parameter Description digtype specifies the type of digit the channel will detect On DM3 boards, the valid value is: • DG_USER1 On Springware boards, valid values are: • DG_USER1 • DG_USER2 • DG_USER3 • DG_USER4 • DG_USER5 Up to twenty digits can be associated with each of these digit types. Note: These types can be specified in addition to the digit types already defined for the voice library (DTMF, MF) which are specified using dx_setdigtyp( ).
dx_addtone( ) — add a user-defined tone EDX_FREQDET Invalid tone frequency EDX_INVSUBCMD Invalid sub-command EDX_MAXTMPLT Maximum number of user-defined tones for the board EDX_SYSTEM Error from operating system; use dx_fileerrno( ) to obtain error value EDX_TONEID Invalid tone template ID ! Example #include #include #include #include
add a user-defined tone — dx_addtone( ) /* * Describe a Dual Tone Frequency Tone of 950-1050 Hz * and 475-525 Hz. On between 190-210 msecs and off * 990-1010 msecs and a cadence of 3.
dx_addtone( ) — add a user-defined tone /* * Close the opened Voice Channel Device */ if ( dx_close( dxxxdev ) != 0 ) { perror( "close" ); } /* Terminate the Program */ exit( 0 ); } ! See Also 128 • dx_blddt( ), dx_bldst( ), dx_blddtcad( ), dx_bldstcad( ) • dx_distone( ) • dx_enbtone( ) • global tone detection in the Voice API Programming Guide • dx_getevt( ) • DX_CST data structure • sr_getevtdatap( ) in the Standard Runtime Library API Library Reference • dx_getdig( ) • dx_setdigtyp(
set a DTMF digit to adjust volume — dx_addvoldig( ) dx_addvoldig( ) set a DTMF digit to adjust volume Name: int dx_addvoldig(chdev, digit, adjval) Inputs: int chdev • valid channel device handle char digit • DTMF digit short adjval • volume adjustment value Returns: 0 if success -1 if failure Includes: srllib.h dxxxlib.
dx_addvoldig( ) — set a DTMF digit to adjust volume Parameter Description adjval specifies a speed adjustment value to take effect whenever the digit specified in digit occurs On DM3 boards, the following are valid values: • SV_ADD2DB – increase play volume by 2 dB • SV_SUB2DB – decrease play volume by 2 dB • SV_NORMAL – set play volume to origin when the play begins (digit must be set to NULL) On Springware boards, the following are valid values: • SV_ADD2DB – increase play volume by 2 dB • SV_ADD4DB –
set a DTMF digit to adjust volume — dx_addvoldig( ) EDX_SVADJBLKS Invalid number of play adjustment blocks EDX_SYSTEM Error from operating system; use dx_fileerrno( ) to obtain error value ! Example #include #include #include #include
dx_addvoldig( ) — set a DTMF digit to adjust volume 132 • dx_getcursv( ) • dx_getsvmt( ) • dx_setsvcond( ) • dx_setsvmt( ) Voice API for Windows Operating Systems Library Reference — November 2003
adjust speed or volume immediately — dx_adjsv( ) dx_adjsv( ) adjust speed or volume immediately Name: int dx_adjsv(chdev, tabletype, action, adjsize) Inputs: int chdev • valid channel device handle unsigned short tabletype • type of table to set (speed or volume) unsigned short action • how to adjust (absolute position, relative change, or toggle) unsigned short adjsize • adjustment size Returns: 0 if successful -1 if failure Includes: srllib.h dxxxlib.
dx_adjsv( ) — adjust speed or volume immediately Parameter action Description specifies the type of adjustment to make. Set to one of the following: • SV_ABSPOS – set speed or volume to a specified position in the appropriate table. (The position is set using the adjsize parameter.) • SV_RELCURPOS – adjust speed or volume by the number of steps specified using the adjsize parameter • SV_TOGGLE – toggle between values specified using the adjsize parameter adjsize specifies the size of the adjustment.
adjust speed or volume immediately — dx_adjsv( ) ! Example #include #include #include #include main() { int dxxxdev; /* * Open the Voice Channel Device and Enable a Handler */ if ( ( dxxxdev = dx_open( "dxxxB1C1", 0 ) ) == -1 ) { perror( "dxxxB1C1" ); exit( 1 ); } /* * Modify the Volume of the playback so that it is 4dB * higher than normal.
dx_blddt( ) — define a user-defined dual-frequency tone dx_blddt( ) define a user-defined dual-frequency tone Name: int dx_blddt(tid, freq1, fq1dev, freq2, fq2dev, mode) Inputs: unsigned int tid • tone ID to assign unsigned int freq1 • frequency 1 in Hz unsigned int fq1dev • frequency 1 deviation in Hz unsigned int freq2 • frequency 2 in Hz unsigned int fq2dev • frequency 2 deviation in Hz unsigned int mode • leading or trailing edge Returns: 0 if success -1 if failure Includes: srllib.
define a user-defined dual-frequency tone — dx_blddt( ) ! Cautions • Only one tone per process can be defined at any time. Ensure that dx_blddt( ) is called for each dx_addtone( ). The tone is not created until dx_addtone( ) is called, and a second consecutive call to dx_blddt( ) will replace the previous tone definition for the channel. If you call dx_addtone( ) without calling dx_blddt( ) an error will occur. • Do not use tone IDs 261, 262 and 263; they are reserved for library use.
dx_blddt( ) — define a user-defined dual-frequency tone /* Terminate the Program */ exit( 0 ); } ! See Also 138 • global tone detection topic in Voice API Programming Guide • dx_bldst( ) • dx_blddtcad( ) • dx_bldstcad( ) • dx_addtone( ) • dx_distone( ) • dx_enbtone( ) • r2_creatfsig( ) • r2_playbsig( ) Voice API for Windows Operating Systems Library Reference — November 2003
define a user-defined dual frequency cadenced tone — dx_blddtcad( ) dx_blddtcad( ) define a user-defined dual frequency cadenced tone Name: int dx_blddtcad(tid, freq1, fq1dev, freq2, fq2dev, ontime, ontdev, offtime, offtdev, repcnt) Inputs: unsigned int tid • tone ID to assign unsigned int freq1 • frequency 1 in Hz unsigned int fq1dev • frequency 1 deviation in Hz unsigned int freq2 • frequency 2 in Hz unsigned int fq2dev • frequency 2 deviation in Hz unsigned int ontime • tone-on time in 10 mse
dx_blddtcad( ) — define a user-defined dual frequency cadenced tone Parameter Description ontime specifies the length of time for which the cadence is on (in 10 msec units) ontdev specifies the allowable deviation for on time (in 10 msec units) offtime specifies the length of time for which the cadence is off (in 10 msec units) offtdev specifies the allowable deviation for off time (in 10 msec units) repcnt specifies the number of repetitions for the cadence (that is, the number of times that an
define a user-defined dual frequency cadenced tone — dx_blddtcad( ) /* * Continue Processing * . * .
dx_bldst( ) — define a user-defined single-frequency tone dx_bldst( ) define a user-defined single-frequency tone Name: int dx_bldst(tid, freq, fqdev, mode) Inputs: unsigned int tid • tone ID to assign unsigned int freq • frequency in Hz unsigned int fqdev • frequency deviation in Hz unsigned int mode • leading or trailing edge Returns: 0 if success -1 if failure Includes: srllib.h dxxxlib.
define a user-defined single-frequency tone — dx_bldst( ) • If you are using R2/MF tone detection, reserve the use of tone IDs 101 to 115 for the R2/MF tones. See r2_creatfsig( ) for further information. • When using this function in a multi-threaded application, use critical sections or a semaphore around the function call to ensure a thread-safe application. Failure to do so will result in “Bad Tone Template ID” errors. ! Errors None. ! Example #include #include #include #include
dx_bldst( ) — define a user-defined single-frequency tone 144 • dx_blddt( ) • dx_bldstcad( ) • dx_addtone( ) • dx_distone( ) • dx_enbtone( ) • r2_creatfsig( ) • r2_playbsig( ) Voice API for Windows Operating Systems Library Reference — November 2003
define a user-defined single-frequency cadenced tone — dx_bldstcad( ) dx_bldstcad( ) define a user-defined single-frequency cadenced tone Name: int dx_bldstcad(tid, freq, fqdev, ontime, ontdev, offtime, offtdev, repcnt) Inputs: unsigned int tid • tone ID to assign unsigned int freq • frequency in Hz unsigned int fqdev • frequency deviation in Hz unsigned int ontime • tone on time in 10 msec unsigned int ontdev • on time deviation in 10 msec unsigned int offtime • tone off time in 10 msec unsign
dx_bldstcad( ) — define a user-defined single-frequency cadenced tone Parameter Description offtdev specifies the allowable deviation for off time (in 10 msec units) repcnt specifies the number of repetitions for the cadence (i.e., the number of times that an on/off signal is repeated) ! Cautions • Only one tone per application may be defined at any time. dx_bldstcad( ) will replace the previous user-defined tone definition.
define a user-defined single-frequency cadenced tone — dx_bldstcad( ) /* * Close the opened Voice Channel Device */ if ( dx_close( dxxxdev ) != 0 ) { perror( "close" ); } /* Terminate the Program */ exit( 0 ); } ! See Also • global tone detection topic in Voice API Programming Guide • dx_blddtcad( ) • dx_blddt( ) • dx_bldst( ) • dx_addtone( ) • dx_distone( ) • dx_enbtone( ) • r2_creatfsig( ) • r2_playbsig( ) Voice API for Windows Operating Systems Library Reference — November 2003 147
dx_bldtngen( ) — define a tone for generation dx_bldtngen( ) define a tone for generation Name: void dx_bldtngen(tngenp, freq1, freq2, ampl1, ampl2, duration) Inputs: TN_GEN *tngenp • pointer to tone generation structure unsigned short freq1 • frequency of tone 1 in Hz unsigned short freq2 • frequency of tone 2 in Hz short ampl1 • amplitude of tone 1 in dB short ampl2 • amplitude of tone 2 in dB short duration • duration of tone in 10 msec units Returns: none Includes: srllib.h dxxxlib.
define a tone for generation — dx_bldtngen( ) Generating a tone with a high frequency component (approximately 700 Hz or higher) will cause the amplitude of the tone to increase. The increase will be approximately 1 dB at 1000 Hz. Also, the amplitude of the tone will increase by 2 dB if an analog (loop start) device is used. ! Cautions None. ! Errors None. ! Example #include #include #include #include
dx_bldtngen( ) — define a tone for generation 150 • dx_playtone( ) • global tone generation topic in Voice API Programming Guide • r2_creatfsig( ) • r2_playbsig( ) Voice API for Windows Operating Systems Library Reference — November 2003
download a cached prompt from multiple sources — dx_cacheprompt( ) dx_cacheprompt( ) download a cached prompt from multiple sources Name: int dx_cacheprompt(brdhdl, iottp, prompthdl, mode) Inputs: int brdhdl • valid physical board device handle DX_IOTT *iottp • pointer to I/O Transfer Table int prompthdl • pointer to return the cached prompt handle unsigned short mode • cached prompt mode Returns: > 0 if successful -1 if failure Includes: srllib.h dxxxlib.
dx_cacheprompt( ) — download a cached prompt from multiple sources • If the function is called in asynchronous mode (mode = EV_ASYNC), then the cached prompt handle returned should be used only after the TDX_CACHEPROMPT event is received. • When iottp parameter points to an array of DX_IOTT data structures (voice data being specified from multiple sources), the cached prompt handle that is returned refers to the beginning of the combined set of voice data that is downloaded.
download a cached prompt from multiple sources — dx_cacheprompt( ) /* Set up DX_IOTT */ /*This block specifies the first data file */ iott[0].io_fhandle = fd1; iott[0].io_offset = 0; iott[0].io_length = -1; iott[0].io_type = IO_DEV | IO_CONT; /*This block specifies the second data file */ iott[1].io_fhandle = fd2; iott[1].io_offset = 0; iott[1].io_length = -1; iott[1].
dx_chgdur( ) — change the duration definition for a tone dx_chgdur( ) change the duration definition for a tone Name: int dx_chgdur(tonetype, ontime, ondev, offtime, offdev) Inputs: int tonetype • tone to modify int ontime • on duration int ondev • ontime deviation int offtime • off duration int offdev • offtime deviation Returns: 0 on success -1 if tone does not have cadence values -2 if unknown tone type Includes: srllib.h dxxxlib.
change the duration definition for a tone — dx_chgdur( ) Parameter Description tonetype specifies the identifier of the tone whose definition is to be modified.
dx_chgdur( ) — change the duration definition for a tone /* * Delete any previous tones */ if ( dx_deltones(ddd) < 0 ) { /* handle error */ } /* * Change Enhanced call progress default local dial tone */ if (dx_chgfreq( TID_DIAL_LCL, 425, 150, 0, 0 ) < 0) { /* handle error */ } /* * Change Enhanced call progress default busy cadence */ if (dx_chgdur( TID_BUSY1, 550, 400, 550, 400 ) < 0) { /* handle error */ } if (dx_chgrepcnt( TID_BUSY1, 4 ) < 0) { /* handle error */ } /* * Now enable Enhanced call progres
change the duration definition for a tone — dx_chgdur( ) /* * Set on Hook */ if ((dx_sethook( ddd, DX_ONHOOK, EV_SYNC )) == -1) { /* handle error */ } dx_close( ddd ); } ! See Also • dx_chgfreq( ) • dx_chgrepcnt( ) • dx_deltones( ) • dx_initcallp( ) Voice API for Windows Operating Systems Library Reference — November 2003 157
dx_chgfreq( ) — change the frequency definition for a tone dx_chgfreq( ) change the frequency definition for a tone Name: int dx_chgfreq(tonetype, freq1, freq1dev, freq2, freq2dev) Inputs: int tonetype • tone to modify int freq1 • frequency of first tone int freq1dev • frequency deviation for first tone int freq2 • frequency of second tone int freq2dev • frequency deviation of second tone Returns: 0 on success -1 on failure due to bad parameter(s) for tone type -2 on failure due to unknown tone t
change the frequency definition for a tone — dx_chgfreq( ) Parameter Description tonetype specifies the identifier of the tone whose definition is to be modified.
dx_chgfreq( ) — change the frequency definition for a tone /* * Delete any previous tones */ if ( dx_deltones(ddd) < 0 ) { /* handle error */ } /* * Change Enhanced call progress default local dial tone */ if (dx_chgfreq( TID_DIAL_LCL, 425, 150, 0, 0 ) < 0) { /* handle error */ } /* * Change Enhanced call progress default busy cadence */ if (dx_chgdur( TID_BUSY1, 550, 400, 550, 400 ) < 0) { /* handle error */ } if (dx_chgrepcnt( TID_BUSY1, 4 ) < 0) { /* handle error */ } /* * Now enable Enhanced call progr
change the frequency definition for a tone — dx_chgfreq( ) /* * Set on Hook */ if ((dx_sethook( ddd, DX_ONHOOK, EV_SYNC )) == -1) { /* handle error */ } dx_close( ddd ); } ! See Also • dx_chgdur( ) • dx_chgrepcnt( ) • dx_deltones( ) • dx_initcallp( ) Voice API for Windows Operating Systems Library Reference — November 2003 161
dx_chgrepcnt( ) — change the repetition definition for a tone dx_chgrepcnt( ) change the repetition definition for a tone Name: int dx_chgrepcnt(tonetype, repcnt) Inputs: int tonetype • tone to modify int repcnt • repetition count Returns: 0 if success -1 if tone does not have a repetition value 2 if unknown tone type Includes: srllib.h dxxxlib.
change the repetition definition for a tone — dx_chgrepcnt( ) Parameter Description tonetype specifies the identifier of the tone whose definition is to be modified.
dx_chgrepcnt( ) — change the repetition definition for a tone /* * Change Enhanced call progress default local dial tone */ if (dx_chgfreq( TID_DIAL_LCL, 425, 150, 0, 0 ) < 0) { /* handle error */ } /* * Change Enhanced call progress default busy cadence */ if (dx_chgdur( TID_BUSY1, 550, 400, 550, 400 ) < 0) { /* handle error */ } if (dx_chgrepcnt( TID_BUSY1, 4 ) < 0) { /* handle error */ } /* * Now enable Enhanced call progress with above changed settings.
change the repetition definition for a tone — dx_chgrepcnt( ) • dx_chgfreq( ) • dx_deltones( ) • dx_initcallp( ) Voice API for Windows Operating Systems Library Reference — November 2003 165
dx_close( ) — close a channel or board device handle dx_close( ) close a channel or board device handle Name: int dx_close(dev) Inputs: int dev • valid channel or board device handle Returns: 0 if successful -1 if error Includes: srllib.h dxxxlib.h Category: Device Management Mode: synchronous Platform: DM3, Springware ! Description The dx_close( ) function closes a channel device handle or board device handle that was previously opened using dx_open( ).
close a channel or board device handle — dx_close( ) ! 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 1 This example illustrates how to close a channel device handle. #include #include #include main() { int chdev; . . .
dx_close( ) — close a channel or board device handle ! See Also • 168 dx_open( ) Voice API for Windows Operating Systems Library Reference — November 2003
delete a circular stream buffer — dx_CloseStreamBuffer( ) dx_CloseStreamBuffer( ) delete a circular stream buffer Name: int dx_CloseStreamBuffer(hBuffer) Inputs: int hBuffer • stream buffer handle Returns: 0 if successful -1 if failure Includes: srllib.h dxxxlib.h Category: streaming to board Mode: synchronous Platform: DM3 ! Description The dx_CloseStreamBuffer( ) function deletes the circular stream buffer identified by the stream buffer handle.
dx_CloseStreamBuffer( ) — delete a circular stream buffer ! Example #include #include
clear all fields in a DX_CAP structure — dx_clrcap( ) dx_clrcap( ) clear all fields in a DX_CAP structure Name: void dx_clrcap(capp) Inputs: DX_CAP *capp • pointer to call progress analysis parameter data structure Returns: none Includes: srllib.h dxxxlib.h Category: Structure Clearance Mode: synchronous Platform: DM3, Springware ! Description The dx_clrcap( ) function clears all fields in a DX_CAP structure by setting them to zero. dx_clrcap( ) is a VOID function that returns no value.
dx_clrcap( ) — clear all fields in a DX_CAP structure cap.ca_nbrdna = 5; /* 5 rings before no answer */ . . /* continue with call progress analysis */ . .
clear all digits in the firmware digit buffer — dx_clrdigbuf( ) dx_clrdigbuf( ) clear all digits in the firmware digit buffer Name: int dx_clrdigbuf(chdev) Inputs: int chdev • valid channel device handle Returns: 0 if success -1 if failure Includes: srllib.h dxxxlib.h Category: Configuration Mode: synchronous Platform: DM3, Springware ! Description The dx_clrdigbuf( ) function clears all digits in the firmware digit buffer of the channel specified by chdev.
dx_clrdigbuf( ) — clear all digits in the firmware digit buffer main() { int chdev; /* channel descriptor */ . . . /* Open Channel */ if ((chdev = dx_open("dxxxB1C1",NULL)) == -1) { /* process error */ } /* Clear digit buffer */ if (dx_clrdigbuf(chdev) == -1) { /* process error*/ } . . } ! See Also None.
clear all speed or volume adjustment conditions — dx_clrsvcond( ) dx_clrsvcond( ) clear all speed or volume adjustment conditions Name: int dx_clrsvcond(chdev) Inputs: int chdev • valid channel device handle Returns: 0 if success -1 if failure Includes: srllib.h dxxxlib.
dx_clrsvcond( ) — clear all speed or volume adjustment conditions ! Example #include #include #include #include main() { int
clear all fields in a DV_TPT structure — dx_clrtpt( ) dx_clrtpt( ) clear all fields in a DV_TPT structure Name: int dx_clrtpt(tptp, size) Inputs: DV_TPT *tptp • pointer to Termination Parameter Table structure int size • number of entries to clear Returns: 0 if success -1 if failure Includes: srllib.h dxxxlib.
dx_clrtpt( ) — clear all fields in a DV_TPT structure ! Errors The function will fail and return -1 if IO_EOT is encountered in the tp_type field before the number of DV_TPT structures specified in size have been cleared. ! Example #include #include #include main() { DV_TPT tpt1[2]; DV_TPT tpt2[2]; /* Set up the links in the DV_TPTs */ tpt1[0].tp_type = IO_CONT; tpt1[1].tp_type = IO_LINK; tpt1[1].tp_nextp = &tpt2[0]; tpt2[0].tp_type = IO_CONT; tpt2[1].
create a new tone definition for a specific call progress tone — dx_createtone( ) dx_createtone( ) create a new tone definition for a specific call progress tone Name: int dx_createtone(brdhdl, toneid, *tonedata, mode) Inputs: int brdhdl • a valid physical board device handle int toneid • tone ID of the call progress tone TONE_DATA *tonedata • pointer to the TONE_DATA structure unsigned short mode • mode Returns: 0 if successful -1 if failure Includes: srllib.h dxxxlib.
dx_createtone( ) — create a new tone definition for a specific call progress tone Parameter Description brdhdl specifies a valid physical board device handle (of the format brdBn) obtained by a call to dx_open( ) toneid specifies the tone ID of the call progress tone whose definition needs to be created.
create a new tone definition for a specific call progress tone — dx_createtone( ) ! 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.
dx_createtone( ) — create a new tone definition for a specific call progress tone toneinfo.toneseg[0].tnoff_min = 400; toneinfo.toneseg[0].tnoff_max = 550; /* Debounce Min. OFF Time */ /* Debounce Max. OFF Time */ tonedata.toneseg[0].
delete a specific call progress tone — dx_deletetone( ) dx_deletetone( ) delete a specific call progress tone Name: int dx_deletetone(brdhdl, toneid, mode) Inputs: int brdhdl • a valid physical board device handle int toneid • tone ID of the call progress tone unsigned short mode • mode Returns: 0 if successful -1 if failure Includes: srllib.h dxxxlib.
dx_deletetone( ) — delete a specific call progress tone Parameter Description toneid specifies the tone ID of the call progress tone.
delete a specific call progress tone — dx_deletetone( ) ! Example #include "srllib.h" #include "dxxxlib.h" main() { int brdhdl; /* board handle */ . . .
dx_deltones( ) — delete all user-defined tones dx_deltones( ) delete all user-defined tones Name: int dx_deltones(chdev) Inputs: int chdev • valid channel device handle Returns: 0 if successful -1 if error Includes: srllib.h dxxxlib.h Category: Global Tone Detection Mode: synchronous Platform: DM3, Springware ! Description The dx_deltones( ) function deletes all user-defined tones previously added to a channel with dx_addtone( ).
delete all user-defined tones — dx_deltones( ) ! Example #include #include #include #include main() { int
dx_dial( ) — dial an ASCIIZ string dx_dial( ) dial an ASCIIZ string Name: int dx_dial(chdev, dialstrp, capp, mode) Inputs: int chdev • valid channel device handle char *dialstrp • pointer to the ASCIIZ dial string DX_CAP *capp • pointer to call progress analysis parameter structure unsigned short mode • asynchronous/synchronous setting and call progress analysis flag Returns: 0 to indicate successful initiation (asynchronous) ≥0 to indicate call progress analysis result if successful (synchronous)
dial an ASCIIZ string — dx_dial( ) Parameter Description capp points to the call progress analysis parameter structure, DX_CAP. To use the default call progress analysis parameters, specify NULL in capp and DX_CALLP in mode. mode specifies whether the ASCIIZ string will be dialed with or without call progress analysis enabled, and whether the function will run asynchronously or synchronously.
dx_dial( ) — dial an ASCIIZ string • Dial string characters are case-sensitive. • The default dialing mode is “T” (DTMF tone dialing). • When you change the dialing mode by specifying the M or T control characters, it becomes the new default and that dialing mode remains in effect for all dialing until a new dialing mode is specified or the system is restarted. For this reason, we recommend that you always put “T”in the dialing string for DTMF tone dialing after using the M (MF) dial mode.
dial an ASCIIZ string — dx_dial( ) • When you change the dialing mode by specifying the P, M, or T control characters, it becomes the new default and that dialing mode remains in effect for all dialing until a new dialing mode is specified or the system is restarted. For this reason, we recommend that you always put “T”in the dialing string for DTMF tone dialing after using the P (pulse) or M (MF) dial modes. The dx_close( ) and dx_open( ) do not reset the default dialing mode to DTMF tone dialing.
dx_dial( ) — dial an ASCIIZ string call progress analysis parameters, or by using the call progress analysis parameter structure (DX_CAP). Call progress analysis results can be retrieved using ATDX_CPTERM( ). If dx_dial( ) is running synchronously, the call progress analysis results will also be returned by the dx_dial( ) function.
dial an ASCIIZ string — dx_dial( ) ATDX_CONNTYPE( ) Returns the connection type for a completed call ATDX_CPERROR( ) Returns call progress analysis error ATDX_CPTERM( ) Returns last call progress analysis termination ATDX_CRTNID( ) Returns tone identifier ATDX_DTNFAIL( ) Returns dial tone fail character ATDX_FRQDUR( ) Returns duration of first frequency detected ATDX_FRQDUR2( ) Returns duration of second frequency detected ATDX_FRQDUR3( ) Returns duration of third frequency detected ATDX_FRQHZ( ) Returns f
dx_dial( ) — dial an ASCIIZ string • Clear the DX_CAP structure using dx_clrcap( ) before the structure is used as an argument in a dx_dial( ) function call. This will prevent parameters from being set unintentionally. ! 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.
dial an ASCIIZ string — dx_dial( ) /* * Change call progress analysis default busy cadence */ if (dx_chgdur( TID_BUSY1, 550, 400, 550, 400 ) < 0) { /* handle error */ } if (dx_chgrepcnt( TID_BUSY1, 4 ) < 0) { /* handle error */ } /* * Now enable call progress analysis with above changed settings.
dx_dial( ) — dial an ASCIIZ string 196 • DX_CAP data structure • call progress analysis topic in the Voice API Programming Guide • ATDX_ANSRSIZ( ) • ATDX_CPERROR( ) • ATDX_FRQDUR( ) • ATDX_FRQDUR2( ) • ATDX_FRQDUR3( ) • ATDX_FRQHZ( ) • ATDX_FRQHZ2( ) • ATDX_FRQHZ3( ) • ATDX_FRQOUT( ) • ATDX_LONGLOW( ) • ATDX_SHORTLOW( ) • ATDX_SIZEHI( ) Voice API for Windows Operating Systems Library Reference — November 2003
disable detection of a user-defined tone — dx_distone( ) dx_distone( ) disable detection of a user-defined tone Name: int dx_distone(chdev, toneid, evt_mask) Inputs: int chdev • valid channel device handle int toneid • tone template identification int evt_mask • event mask Returns: 0 if success -1 if error Includes: srllib.h dxxxlib.
dx_distone( ) — disable detection of a user-defined tone ! 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.
disable detection of a user-defined tone — dx_distone( ) /* * Disable Detection of ToneId TID_1 */ if ( dx_distone( dxxxdev, TID_1, DM_TONEON | DM_TONEOFF ) == -1 ) { printf( "Unable to Disable Detection of Tone %d\n", TID_1 ); printf( "Lasterror = %d Err Msg = %s\n", ATDV_LASTERR( dxxxdev ), ATDV_ERRMSGP( dxxxdev ) ); dx_close( dxxxdev ); exit( 1 ); } /* * Continue Processing * . * . * .
dx_enbtone( ) — enable detection of a user-defined tone dx_enbtone( ) enable detection of a user-defined tone Name: int dx_enbtone(chdev, toneid, evt_mask) Inputs: int chdev • valid channel device handle int toneid • tone template identification int evt_mask • event mask Returns: 0 if success -1 if failure Includes: srllib.h dxxxlib.
enable detection of a user-defined tone — dx_enbtone( ) ! Cautions When using this function in a multi-threaded application, use critical sections or a semaphore around the function call to ensure a thread-safe application. Failure to do so will result in “Bad Tone Template ID” errors. ! 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.
dx_enbtone( ) — enable detection of a user-defined tone printf( "Lasterror = %d Err Msg = %s\n", ATDV_LASTERR( dxxxdev ), ATDV_ERRMSGP( dxxxdev ) ); dx_close( dxxxdev ); exit( 1 ); } /* * Enable Detection of ToneId TID_1 */ if ( dx_enbtone( dxxxdev, TID_1, DM_TONEON | DM_TONEOFF ) == -1 ) { printf( "Unable to Enable Detection of Tone %d\n", TID_1 ); printf( "Lasterror = %d Err Msg = %s\n", ATDV_LASTERR( dxxxdev ), ATDV_ERRMSGP( dxxxdev ) ); dx_close( dxxxdev ); exit( 1 ); } /* * Continue Processing * . * .
close a file — dx_fileclose( ) dx_fileclose( ) close a file Name: int dx_fileclose(handle) Inputs: int handle • handle returned from dx_fileopen( ) Returns: 0 if success -1 if failure Includes: srllib.h dxxxlib.h Category: File Manipulation Mode: synchronous Platform: DM3, Springware ! Description The dx_fileclose( ) function closes a file associated with the device handle returned by the dx_fileopen( ) function.
dx_fileclose( ) — close a file main() { int chdev; DX_IOTT iott; DV_TPT tpt; DV_DIGIT dig; . . /* 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_handle = dx_fileopen("prompt.
return the system error value — dx_fileerrno( ) dx_fileerrno( ) return the system error value Name: int dx_fileerrno(void) Inputs: none Returns: system error value Includes: srllib.h dxxxlib.h Category: File Manipulation Mode: synchronous Platform: DM3, Springware ! Description The dx_fileerrno( ) function returns the global system error value from the operating system. Call dx_fileerrno( ) to obtain the correct system error value, which provides the reason for the error.
dx_fileerrno( ) — return the system error value Table 4. System Error Values Value Description EBADF Bad file number; invalid file descriptor (file is not opened for writing). Possible causes: 1) The specified file handle is not a valid file-handle value or does not refer to an open file. 2) An attempt was made to write to a file or device opened for read-only access or a locked file. EDOM Math argument. EEXIST Files exist. An attempt has been made to create a file that already exists.
return the system error value — dx_fileerrno( ) ! See Also None.
dx_fileopen( ) — open a file dx_fileopen( ) open a file Name: int dx_fileopen(filep, flags, pmode) Inputs: const char *filep • filename int flags • type of operations allowed int pmode • permission mode Returns: file handle if success -1 if failure Includes: srllib.h dxxxlib.h Category: File Manipulation Mode: synchronous Platform: DM3, Springware ! Description The dx_fileopen( ) function opens a file specified by filep, and prepares the file for reading and writing, as specified by flags.
open a file — dx_fileopen( ) main() { int chdev; DX_IOTT iott; DV_TPT tpt; DV_DIGIT dig; . . /* 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_handle = dx_fileopen("prompt.
dx_fileread( ) — read data from a file dx_fileread( ) read data from a file Name: int dx_fileread(handle, buffer, count) Inputs: int handle • handle returned from dx_fileopen( ) void *buffer • storage location for data unsigned int count • maximum number of bytes Returns: number of bytes if success -1 if failure Includes: srllib.h dxxxlib.
read data from a file — dx_fileread( ) int cd; DX_UIO myio; /* channel device descriptor */ /* user definable I/O structure */ /* * User defined I/O functions */ int my_read(fd,ptr,cnt) int fd; char * ptr; unsigned cnt; { printf("My read\n"); return(dx_fileread(fd,ptr,cnt)); } /* * my write function */ int my_write(fd,ptr,cnt) int fd; char * ptr; unsigned cnt; { printf("My write \n"); return(dx_filewrite(fd,ptr,cnt)); } /* * my seek function */ long my_seek(fd,offset,whence) int fd; long offset; int when
dx_fileread( ) — read data from a file /*This block uses my I/O functions */ iottp++; iottp->io_type = IO_DEV|IO_UIO|IO_CONT iottp->io_fhandle = vodat_fd; iott->io_offset = 20001; iott->io_length = 20000; /*This block uses standard I/O functions */ iottp++ iott->io_type = IO_DEV|IO_CONT iott->io_fhandle = vodat_fd; iott->io_offset = 20002; iott->io_length = 20000; /*This block uses my I/O functions */ iott->io_type = IO_DEV|IO_UIO|IO_EOT iott->io_fhandle = vodat_fd; iott->io_offset = 10003; iott->io_length
move a file pointer — dx_fileseek( ) dx_fileseek( ) move a file pointer Name: long dx_fileseek(handle, offset, origin) Inputs: int handle • handle returned from dx_fileopen( ) long offset • number of bytes from the origin int origin • initial position Returns: number of bytes read if success -1 if failure Includes: srllib.h dxxxlib.
dx_fileseek( ) — move a file pointer main() { int cd; DX_UIO myio; /* channel device descriptor */ /* user definable I/O structure */ /* * User defined I/O functions */ int my_read(fd,ptr,cnt) int fd; char * ptr; unsigned cnt; { printf("My read\n"); return(dx_fileread(fd,ptr,cnt)); } /* * my write function */ int my_write(fd,ptr,cnt) int fd; char * ptr; unsigned cnt; { printf("My write \n"); return(dx_filewrite(fd,ptr,cnt)); } /* * my seek function */ long my_seek(fd,offset,whence) int fd; long offset; i
move a file pointer — dx_fileseek( ) /*This block uses my I/O functions */ iottp++; iottp->io_type = IO_DEV|IO_UIO|IO_CONT iottp->io_fhandle = vodat_fd; iott->io_offset = 20001; iott->io_length = 20000; /*This block uses standard I/O functions */ iottp++ iott->io_type = IO_DEV|IO_CONT iott->io_fhandle = vodat_fd; iott->io_offset = 20002; iott->io_length = 20000; /*This block uses my I/O functions */ iott->io_type = IO_DEV|IO_UIO|IO_EOT iott->io_fhandle = vodat_fd; iott->io_offset = 10003; iott->io_length =
dx_filewrite( ) — write data from a buffer into a file dx_filewrite( ) write data from a buffer into a file Name: int dx_filewrite(handle, buffer, count) Inputs: int handle • handle returned from dx_fileopen( ) void *buffer • data to be written unsigned int count • number of bytes Returns: number of bytes if success -1 if failure Includes: srllib.h dxxxlib.
write data from a buffer into a file — dx_filewrite( ) /* * User defined I/O functions */ int my_read(fd,ptr,cnt) int fd; char * ptr; unsigned cnt; { printf("My read\n"); return(dx_fileread(fd,ptr,cnt)); } /* * my write function */ int my_write(fd,ptr,cnt) int fd; char * ptr; unsigned cnt; { printf("My write \n"); return(dx_filewrite(fd,ptr,cnt)); } /* * my seek function */ long my_seek(fd,offset,whence) int fd; long offset; int whence; { printf("My seek\n"); return(dx_fileseek(fd,offset,whence)); } void m
dx_filewrite( ) — write data from a buffer into a file /*This block uses standard I/O functions */ iottp++ iott->io_type = IO_DEV|IO_CONT iott->io_fhandle = vodat_fd; iott->io_offset = 20002; iott->io_length = 20000; /*This block uses my I/O functions */ iott->io_type = IO_DEV|IO_UIO|IO_EOT iott->io_fhandle = vodat_fd; iott->io_offset = 10003; iott->io_length = 20000; devhandle = dx_open("dxxxB1C1", NULL); dx_sethook(devhandle, DX-ONHOOK,EV_SYNC) dx_wtring(devhandle,1,DX_OFFHOOK,EV_SYNC); dx_clrdigbuf; if(
get size of on-board memory for cached prompts — dx_getcachesize( ) dx_getcachesize( ) get size of on-board memory for cached prompts Name: int dx_getcachesize(brdhdl, cachesize, flag) Inputs: int brdhdl • valid physical board device handle int *cachesize • pointer to current cache size unsigned short flag • flag for type of cache size Returns: 0 if successful -1 if failure Includes: srllib.h dxxxlib.
dx_getcachesize( ) — get size of on-board memory for cached prompts obtain a descriptive error message. For a list of error codes returned by ATDV_LASTERR( ), see the Error Codes chapter. ! Example #include #include #include #include "srllib.h" "dxxxlib.h" main() { int brdhdl; /* board handle */ int cachetotal; /* Total size of the on-board memory for storing cache prompts */ int cacheremaining; /* Remaining size of on-board memory */ . . .
get information about a voice device — dx_getctinfo( ) dx_getctinfo( ) get information about a voice device Name: int dx_getctinfo(chdev, ct_devinfop) Inputs: int chdev • valid channel device handle CT_DEVINFO *ct_devinfop • pointer to device information structure Returns: 0 on success -1 on error Includes: srllib.h dxxxlib.
dx_getctinfo( ) — get information about a voice device 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 #include
return the specified current speed and volume settings — dx_getcursv( ) dx_getcursv( ) return the specified current speed and volume settings Name: int dx_getcursv(chdev, curvolp, curspeedp) Inputs: int chdev • valid channel device handle int * curvolp • pointer to current absolute volume setting int * curspeedp • pointer to current absolute speed setting Returns: 0 if success -1 if failure Includes: srllib.h dxxxlib.
dx_getcursv( ) — return the specified current speed and volume settings ! 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.
return the specified current speed and volume settings — dx_getcursv( ) /* * Close the opened Voice Channel Device */ if ( dx_close( dxxxdev ) != 0 ) { perror( "close" ); } /* Terminate the Program */ exit( 0 ); } ! See Also • dx_adjsv( ) • dx_addspddig( ) • dx_addvoldig( ) • dx_setsvmt( ) • dx_getsvmt( ) • dx_setsvcond( ) • dx_clrsvcond( ) • speed and volume modification tables in the Voice API Programming Guide • DX_SVMT data structure Voice API for Windows Operating Systems Library Re
dx_getdig( ) — collect digits from a channel digit buffer dx_getdig( ) collect digits from a channel digit buffer Name: int dx_getdig(chdev, tptp, digitp, mode) Inputs: int chdev • valid channel device handle DV_TPT *tptp • pointer to Termination Parameter Table structure DV_DIGIT *digitp • pointer to User Digit Buffer structure unsigned short mode • asynchronous/synchronous setting Returns: 0 to indicate successful initiation (asynchronous) number of digits (+1 for NULL) if successful (synchronous
collect digits from a channel digit buffer — dx_getdig( ) ! Asynchronous Operation To run this function asynchronously, set the mode parameter to EV_ASYNC. In asynchronous mode, this function returns 0 to indicate success, and generates a TDX_GETDIG termination event to indicate completion. Use the Standard Runtime Library (SRL) Event Management functions to handle the termination event. For more information, see the Standard Runtime Library API Library Reference.
dx_getdig( ) — collect digits from a channel digit buffer corresponding voice channels are listening. This occurs because the network functionality of the voice board cannot be separated from the voice functionality in an analog connection between two callers. In this situation, you are not able to determine which caller sent the DTMF digit.
collect digits from a channel digit buffer — dx_getdig( ) * 10 msec resolution */ tpt[2].tp_type tpt[2].tp_termno tpt[2].tp_length tpt[2].
dx_getdig( ) — collect digits from a channel digit buffer /* process error */ } /* initiate the call */ . . /* Set up the DV_TPT and get the digits */ dx_clrtpt(tpt,3); tpt[0].tp_type tpt[0].tp_termno tpt[0].tp_length tpt[0].tp_flags = = = = IO_CONT; DX_MAXDTMF; 4; TF_MAXDTMF; tpt[1].tp_type tpt[1].tp_termno tpt[1].tp_length tpt[1].tp_flags = = = = IO_CONT; DX_LCOFF; 3; TF_LCOFF|TF_10MS; tpt[2].tp_type tpt[2].tp_termno tpt[2].tp_length tpt[2].
collect digits from a channel digit buffer — dx_getdig( ) • dx_sethook( ) Voice API for Windows Operating Systems Library Reference — November 2003 231
dx_GetDllVersion( ) — retrieve the voice DLL version number dx_GetDllVersion( ) retrieve the voice DLL version number Name: dx_GetDllVersion (dwfileverp, dwprodverp) Inputs: LPDWORD dwfileverp LPDWORD dwprodverp • voice DLL version number • product version of this release Returns: 0 if success -1 if failure Includes: srllib.h dxxxlib.
retrieve the voice DLL version number — dx_GetDllVersion( ) * Initialize all the DLLs required. This will cause the DLLs to be * loaded and entry points to be resolved. Entry points not resolved * are set up to point to a default not implemented function in the * 'C' library. If the DLL is not found all functions are resolved * to not implemented.
dx_getevt( ) — monitor channel events synchronously dx_getevt( ) monitor channel events synchronously Name: int dx_getevt(chdev, eblkp, timeout) Inputs: int chdev • valid channel device handle DX_EBLK *eblkp • pointer to Event Block structure int timeout • timeout value in seconds Returns: 0 if success -1 if failure Includes: srllib.h dxxxlib.
monitor channel events synchronously — dx_getevt( ) ! 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.
dx_getevt( ) — monitor channel events synchronously break; } . .
retrieve feature support information for the device — dx_getfeaturelist( ) dx_getfeaturelist( ) retrieve feature support information for the device Name: int dx_getfeaturelist(dev, feature_tablep) Inputs: int dev • valid board or channel device handle FEATURE_TABLE *feature_tablep • pointer to features information structure Returns: 0 on success -1 on error Includes: srllib.h dxxxlib.
dx_getfeaturelist( ) — retrieve feature support information for the device ! 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.
retrieve feature support information for the device — dx_getfeaturelist( ) printf("\n%s: Play Features:-\n", chname); if (feature_table.ft_play & FT_ADPCM) { printf("ADPCM "); } if (feature_table.ft_play & FT_PCM) { printf("PCM "); } if (feature_table.ft_play & FT_ALAW) { printf("ALAW "); } if (feature_table.ft_play & FT_ULAW) { printf("ULAW "); } if (feature_table.ft_play & FT_LINEAR) { printf("LINEAR "); } if (feature_table.ft_play & FT_ADSI) { printf("ADSI "); } if (feature_table.
dx_getfeaturelist( ) — retrieve feature support information for the device if (feature_table.ft_record & FT_DRT8KHZ) { printf("DRT8KHZ "); } if (feature_table.ft_record & FT_DRT11KHZ) { printf("DRT11KHZ"); } printf("\n\n%s: Tone Features:-\n", chname); if (feature_table.ft_tone & FT_GTDENABLED) { printf("GTDENABLED "); } if (feature_table.ft_tone & FT_GTGENABLED) { printf("GTGENABLED "); } if (feature_table.
retrieve feature support information for the device — dx_getfeaturelist( ) if (feature_table.
dx_getparm( ) — get the current parameter settings dx_getparm( ) get the current parameter settings Name: int dx_getparm(dev, parm, valuep) Inputs: int dev • valid channel or board device handle unsigned long parm • parameter type to get value of void *valuep • pointer to variable for returning parameter value Returns: 0 if success -1 if failure Includes: srllib.h dxxxlib.
get the current parameter settings — dx_getparm( ) Parameter Description parm Specifies the define for the parameter type whose value is to be returned in the variable pointed to by valuep. The voice device parameters allow you to query and control device-level information and settings related to the voice functionality. These parameters are described in the dx_setparm( ) function description. For DM3 boards, board parameter defines are described in Table 12, “Voice Board Parameters (DM3)”, on page 390.
dx_getparm( ) — get the current parameter settings ! Example #include #include #include #include main() { int bddev; unsigned short parmval; /* open the board using dx_open( ). Obtain board device descriptor in * bddev */ if ((bddev = dx_open("dxxxB1",NULL)) == -1) { /* process error */ } parmval = 0; /* CLEAR parmval */ /* get the number of channels on the board.
return assignment status of a shared resource — dx_GetRscStatus( ) dx_GetRscStatus( ) return assignment status of a shared resource Name: int dx_GetRscStatus(chdev, rsctype, status) Inputs: int chdev • valid channel device handle int rsctype • type of resource int *status • pointer to assignment status Returns: 0 if success -1 if failure Includes: srllib.h dxxxlib.
dx_GetRscStatus( ) — return assignment status of a shared resource EDX_SYSTEM Error from operating system; use dx_fileerrno( ) to obtain error value ! Example /* Check #include #include #include #include #include whether a shared Fax resource is assigned to the voice channel */ main() { int chdev ; /* Fax channel device handle */ int status; /*Open the Voice channel resource (device) using dx_open().
retrieve information about the circular stream buffer — dx_GetStreamInfo( ) dx_GetStreamInfo( ) retrieve information about the circular stream buffer Name: int dx_GetStreamInfo(hBuffer, &StreamStatStruct) Inputs: int hBuffer • stream buffer handle DX_STREAMSTAT StreamStatStruct • pointer to stream status structure Returns: 0 if successful -1 if failure Includes: srllib.h dxxxlib.
dx_GetStreamInfo( ) — retrieve information about the circular stream buffer if ((hBuffer = dx_OpenStreamBuffer(nBuffSize)) < 0) { printf("Error opening stream buffer \n" ); } if (dx_GetStreamInfo(hBuffer, &streamStat) < 0) { printf("Error getting stream buffer info \n"); } else { printf("version=%d, bytesIn=%d, bytesOut=%d, headPointer=%d, tailPointer=%d, currentState=%d, numberOfBufferUnderruns=%d, numberOfBufferOverruns=%d, BufferSize=%d, spaceAvailable=%d, highWaterMark=%d, lowWaterMark=%d \n"; streamSt
return the current speed or volume modification table — dx_getsvmt( ) dx_getsvmt( ) return the current speed or volume modification table Name: int dx_getsvmt(chdev, tabletype, svmtp ) Inputs: int chdev • valid channel device handle unsigned short tabletype • type of table to retrieve (speed or volume) DX_SVMT * svmtp • pointer to speed or volume modification table structure to retrieve Returns: 0 if success -1 if failure Includes: srllib.h dxxxlib.
dx_getsvmt( ) — return the current speed or volume modification table EDX_SPDVOL Must specify either SV_SPEEDTBL or SV_VOLUMETBL EDX_SYSTEM Error from operating system; use dx_fileerrno( ) to obtain error value ! Example #include #include #include #include
return the current speed or volume modification table — dx_getsvmt( ) /* * Close the opened Voice Channel Device */ if ( dx_close( dxxxdev ) != 0 ) { perror( "close" ); } /* Terminate the Program */ exit( 0 ); } ! See Also • dx_addspddig( ) • dx_addvoldig( ) • dx_adjsv( ) • dx_clrsvcond( ) • dx_getcursv( ) • dx_setsvcond( ) • dx_setsvmt( ) • speed and volume modification tables in Voice API Programming Guide • DX_SVMT data structure Voice API for Windows Operating Systems Library Referen
dx_getxmitslot( ) — get TDM bus time slot number of voice transmit channel dx_getxmitslot( ) get TDM bus time slot number of voice transmit channel Name: int dx_getxmitslot(chdev, sc_tsinfop) Inputs: int chdev • valid channel device handle SC_TSINFO *sc_tsinfop • pointer to TDM bus time slot information structure Returns: 0 on success -1 on error Includes: srllib.h dxxxlib.
get TDM bus time slot number of voice transmit channel — dx_getxmitslot( ) ! 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.
dx_getxmitslot( ) — get TDM bus time slot number of voice transmit channel /* 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 ...
get echo cancellation resource transmit time slot number — dx_getxmitslotecr( ) dx_getxmitslotecr( ) get echo cancellation resource transmit time slot number Name: int dx_getxmitslotecr(chdev, sc_tsinfop) Inputs: int chdev • valid channel device handle SC_TSINFO *sc_tsinfop • pointer to TDM bus time slot information structure Returns: 0 on success -1 on error Includes: srllib.h dxxxlib.
dx_getxmitslotecr( ) — get echo cancellation resource transmit time slot number EDX_SH_BADCMD Function is not supported in current bus configuration 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 type (voice, analog, etc.
get echo cancellation resource transmit time slot number — dx_getxmitslotecr( ) /* Get TDM bus time slot on which the echo-cancelled signal will be transmitted */ if (dx_getxmitslotecr(chdev, &sc_tsinfo) == -1) { printf("Error message = %s", ATDV_ERRMSGP(chdev)); exit(1); } printf("%s transmits the echo cancelled signal on %d", ATDV_NAMEP(chdev),scts); return(0); } ! See Also • dx_listenecr( ) • dx_listenecrex( ) • dx_unlistenecr( ) • dx_getxmitslot( ) Voice API for Windows Operating Systems Libra
dx_gtcallid( ) — return the calling line Directory Number dx_gtcallid( ) return the calling line Directory Number Name: int dx_gtcallid (chdev, bufferp) Inputs: int chdev • valid channel device handle unsigned char *bufferp • pointer to buffer where calling line Directory Number is returned Returns: 0 success -1 error return code Includes: srllib.h dxxxlib.
return the calling line Directory Number — dx_gtcallid( ) Based on the caller ID options provided by the CO and for applications that require only the calling line Directory Number (DN), issue the dx_gtcallid( ) function to get the calling line DN. Based on the caller ID options provided by the CO and for applications that require additional caller ID information, issue the dx_gtextcallid( ) function for each type of caller ID message required.
dx_gtcallid( ) — return the calling line Directory Number int main() { int numRings = 2; /* In the US */ int ringTimeout = 20; /* 20 seconds */ int chdev; /* Channel descriptor */ unsigned short parmval; unsigned char buffer[81]; /* Open channel */ if ((chdev=dx_open("dxxxB1C1", NULL)) == -1) { /* process error */ exit(0); } /* Enable the caller ID functionality */ parmval = DX_CALLIDENABLE; if (dx_setparm(chdev, DXCH_CALLID, (void *) &parmval) == -1) { /* process error */ exit(0); } /*********************
return the calling line Directory Number — dx_gtcallid( ) if ( dx_gtextcallid(chdev,CLIDINFO_FRAMETYPE, buffer) != -1) { if(buffer[0] == CLASSFRAME_MDM) { /* Get and print the date and time */ if (dx_gtextcallid(chdev, MCLASS_DATETIME, buffer) == -1) { /* process error */ printf("Error: %s\n", ATDV_ERRMSGP(chdev)); } else { printf("Date/Time = %s\n", buffer); } /* Get and print the caller name */ if (dx_gtextcallid(chdev, MCLASS_NAME, buffer) == -1) { /* process error */ printf("Error: %s\n", ATDV_ERRMSGP(
dx_gtextcallid( ) — retrieve a caller ID message dx_gtextcallid( ) retrieve a caller ID message Name: int dx_gtextcallid (chdev, infotype, bufferp) Inputs: int chdev • channel device handle int infotype • message type ID unsigned char *bufferp • pointer to where to return the requested caller ID message Returns: 0 success -1 error return code Includes: srllib.h dxxxlib.
retrieve a caller ID message — dx_gtextcallid( ) ! Cautions • Note: To allow the reception of caller ID information from the central office before answering a call (application channel goes off-hook): • For CLASS and ACLIP, set the ring event to occur on or after the second ring. • For CLIP and JCLIP, set the ring event to occur on or after the first ring. If the call is answered before caller ID information has been received from the CO, caller ID information will not be available.
dx_gtextcallid( ) — retrieve a caller ID message • ACLIP (Single Data Message) • ACLIP (Multiple Data Message) • CLIP • JCLIP All returns are NULL terminated. Table 5. Caller ID Common Message Types Value Definition/Returns CLIDINFO_CMPLT All caller ID information as sent from the CO (maximum of 258 bytes; includes header and length byte at the beginning). Can produce EDX_CLIDINFO error. CLIDINFO_GENERAL Date and time (20 bytes - formatted with / and : characters; padded with spaces).
retrieve a caller ID message — dx_gtextcallid( ) Table 6.
dx_gtextcallid( ) — retrieve a caller ID message Table 8.
retrieve a caller ID message — dx_gtextcallid( ) • MACLIP_NAME can be used to get the calling line subscriber name for ACLIP Caller ID information is available for the call from the moment the ring event is generated (if the ring event is set to occur on or after the second ring (CLASS, ACLIP) or set to occur on or after the first ring (CLIP, JCLIP)) until either of the following occurs: • If the call is answered (the application channel goes off-hook), the caller ID information is available to the appl
dx_gtextcallid( ) — retrieve a caller ID message /* Put the channel onhook */ if (dx_sethook(chdev, DX_ONHOOK, EV_SYNC) == -1) { /* process error */ exit (0); } /* Wait for 2 rings and go offhook (timeout after 20 seconds) */ if (dx_wtring(chdev, numRings, DX_OFFHOOK, ringTimeout) == -1) { /* process error */ } /************************************************************* * If the message is an MDM (Multiple Data Message), then * individual submessages are available.
retrieve a caller ID message — dx_gtextcallid( ) } } dx_close(chdev); return(0); } ! See Also • dx_gtcallid( ) • dx_wtcallid( ) Voice API for Windows Operating Systems Library Reference — November 2003 269
dx_gtsernum( ) — retrieve the board serial number dx_gtsernum( ) retrieve the board serial number Name: int dx_gtsernum (devd, subfcn, buffp ) Inputs: int devd • valid board device handle int subfcn • sub-function void *buffp • pointer to buffer for returned serial number Returns: 0 if success -1 if failure Includes: srllib.h dxxxlib.
retrieve the board serial number — dx_gtsernum( ) ! Cautions None. ! 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_SYSTEM Error from operating system; use dx_fileerrno( ) to obtain error value. The board device is busy. EDX_BADPARM Invalid device handle or sub-function.
dx_initcallp( ) — initialize and activate call progress analysis dx_initcallp( ) initialize and activate call progress analysis Name: int dx_initcallp(chdev) Inputs: int chdev • valid channel device handle Returns: 0 if successful -1 if failure Includes: srllib.h dxxxlib.h Category: Call Progress Analysis Mode: synchronous Platform: Springware ! Description On Springware boards, the dx_initcallp( ) function initializes and activates call progress analysis on the channel identified by chdev.
initialize and activate call progress analysis — dx_initcallp( ) ! Cautions When you issue this function, the channel must be idle. ! Errors For a list of error codes, see the Error Codes chapter. ! Example #include #include #include #include
dx_initcallp( ) — initialize and activate call progress analysis /* * Set off Hook */ if ((dx_sethook( ddd, DX_OFFHOOK, EV_SYNC )) == -1) { /* handle error */ } /* * Dial */ if ((car = dx_dial( ddd, dialstrg,(DX_CAP *)&cap_s, DX_CALLP|EV_SYNC))==-1) { /* handle error */ } switch( car ) { case CR_NODIALTONE: printf(" Unable to get dial tone\n"); break; case CR_BUSY: printf(" %s engaged\n", dialstrg ); break; case CR_CNCT: printf(" Successful connection to %s\n", dialstrg ); break; default: break; } /* * Set
initialize the voice library DLL — dx_libinit( ) dx_libinit( ) initialize the voice library DLL Name: dx_libinit ( flags ) Inputs: unsigned short flags • specifies the programming model Returns: 0 if success -1 if failure Includes: srllib.h dxxxlib.h Category: Configuration Mode: synchronous Platform: DM3, Springware ! Description The dx_libinit( ) function initializes the voice library DLL by loading and resolving all entry points in LIBDXXMT.DLL.
dx_libinit( ) — initialize the voice library DLL { DWORD dwfilever, dwprodver; /************************************************************************ * Initialize all the DLLs required. This will cause the DLLs to be * loaded and entry points to be resolved. Entry points not resolved * are set up to point to a default not implemented function in the * 'C' library. If the DLL is not found all functions are resolved * to not implemented.
connect a voice listen channel to TDM bus time slot — dx_listen( ) dx_listen( ) connect a voice listen channel to TDM bus time slot Name: int dx_listen(chdev, sc_tsinfop) Inputs: int chdev • valid channel device handle SC_TSINFO *sc_tsinfop • pointer to TDM bus time slot information structure Returns: 0 on success -1 on error Includes: srllib.h dxxxlib.
dx_listen( ) — connect a voice listen 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.
connect a voice listen channel to TDM bus time slot — dx_listen( ) /* Open board 1 channel 1 device */ if ((chdev = dx_open("dxxxB1C1", 0)) == -1) { /* process error */ } /* Fill in the TDM bus time slot information */ sc_tsinfo.sc_numts = 1; sc_tsinfo.
dx_listenecr( ) — enable echo cancellation resource mode dx_listenecr( ) enable echo cancellation resource mode Name: int dx_listenecr(chdev, sc_tsinfop) Inputs: int chdev • handle of voice channel device on which echo cancellation is to be performed SC_TSINFO *sc_tsinfop • pointer to TDM bus time slot information structure Returns: 0 on success -1 on error Includes: srllib.h dxxxlib.
enable echo cancellation resource mode — dx_listenecr( ) ! Cautions This function fails when: • An invalid channel device handle is specified. • An invalid TDM bus time-slot number is specified. • The ECR feature is not enabled on the board specified. • The ECR feature is not supported on the board specified.
dx_listenecr( ) — enable echo cancellation resource mode ! Example #include #include #include #include #include
modify characteristics of the echo canceller — dx_listenecrex( ) dx_listenecrex( ) modify characteristics of the echo canceller Name: int dx_listenecrex(chdev, sc_tsinfop, ecrctp) Inputs: int chdev • handle of voice channel device on which echo cancellation will be performed SC_TSINFO *sc_tsinfop • pointer to TDM bus time slot information structure DX_ECRCT void *ecrctp • pointer to ECR characteristic structure Returns: 0 on success -1 on error Includes: srllib.h dxxxlib.
dx_listenecrex( ) — modify characteristics of the echo canceller • An invalid channel device handle is specified. • The ECR feature is not enabled on the board specified. • The ECR feature is not supported on the board specified. • The characteristic table contains invalid fields. ! 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.
modify characteristics of the echo canceller — dx_listenecrex( ) ! Example #include #include #include #include #include
dx_mreciottdata( ) — record voice data from two TDM bus time slots dx_mreciottdata( ) record voice data from two TDM bus time slots Name: dx_mreciottdata (devd, iotp, tptp, xpb, mode, sc_tsinfop) Inputs: int devd • valid channel device handle DX_IOTT *iotp • pointer to I/O transfer table DV_TPT *tptp • pointer to termination control block DX_XPB *xpb • pointer to I/O transfer parameter block USHORT *mode • switch to set audible tone, or DTMF termination SC_TSINFO *sc_tsinfop • pointer to time sl
record voice data from two TDM bus time slots — dx_mreciottdata( ) Parameter Description devd specifies the valid channel device handle on which the recording is to occur. The channel descriptor may be that associated with either of the two TDM bus transmit time slots or a third device also connected to the TDM bus. iotp points to the I/O Transfer Table Structure, DX_IOTT, which specifies the order of recording and the location of voice data.
dx_mreciottdata( ) — record voice data from two TDM bus time slots • On Springware boards, because the DSP sums the PCM values of the two TDM bus time slots before processing them during transaction recording, all voice-related terminating conditions or features such as DTMF detection, Automatic Gain Control (AGC), and sample rate change will apply to both time slots. In other words, for terminating conditions specified by a DTMF digit, either time slot containing the DTMF digit will stop the recording.
record voice data from two TDM bus time slots — dx_mreciottdata( ) EDX_BUSY Busy executing I/O function EDX_SYSTEM Error from operating system; use dx_fileerrno( ) to obtain error value ! Example #include #include #include #include #include #include
dx_mreciottdata( ) — record voice data from two TDM bus time slots /* Set up SC_TSINFO structure */ tsinfo.sc_numts = 2; tsinfo.sc_tsarrayp = &tslots[0]; /* Set up DX_XPB structure */ xpb.wFileFormat = FILE_FORMAT_VOX; xpb.wDataFormat = 0; xpb.nSamplesPerSec = 0L; xpb.wBitsPerSample = 0; /*Set up DV_TPT structure */ dx_clrtpt (&tpt,1); tpt.tp_type = IO_EOT; tpt.tp_termno = DX_MAXDTMF; tpt.tp_length = 1; tpt.tp_flags = TF_MAXDTMF; /* Set up DX_IOTT structure */ iott[0].io_fhandle = fd; iott[0].
record voice data from two TDM bus time slots — dx_mreciottdata( ) • dx_reciottdata( ) • dx_playiottdata( ) Voice API for Windows Operating Systems Library Reference — November 2003 291
dx_open( ) — open a voice device and return a unique device handle dx_open( ) open a voice device and return a unique device handle Name: int dx_open(namep, oflags) Inputs: char *namep • pointer to device name to open Returns: >0 to indicate valid device handle if successful -1 if failure Includes: srllib.h dxxxlib.
open a voice device and return a unique device handle — dx_open( ) ! Cautions • Do not use the Windows open( ) function to open a voice device. Unpredictable results will occur. • In applications that spawn child processes from a parent process, the device handle is not inheritable by the child process. Make sure devices are opened in the child process. ! Errors If this function returns -1 to indicate failure, a system error has occurred; use dx_fileerrno( ) to obtain the system error value.
dx_open( ) — open a voice device and return a unique device handle ! See Also • 294 dx_close( ) Voice API for Windows Operating Systems Library Reference — November 2003
create and initialize a circular stream buffer — dx_OpenStreamBuffer( ) dx_OpenStreamBuffer( ) create and initialize a circular stream buffer Name: int dx_OpenStreamBuffer(BuffSize) Inputs: int BuffSize • size in bytes of circular stream buffer Returns: stream buffer handle if successful -1 if failure Includes: srllib.h dxxxlib.
dx_OpenStreamBuffer( ) — create and initialize a circular stream buffer ! Example #include #include
pause on-going play — dx_pause( ) dx_pause( ) pause on-going play Name: int dx_pause(chdev) Inputs: int chdev • valid channel device handle Returns: 0 if success -1 if failure Includes: srllib.h dxxxlib.h Category: I/O Mode: synchronous Platform: DM3 ! Description The dx_pause( ) function pauses an on-going play until a subsequent dx_resume( ) function is issued. To stop the paused play, use dx_stopch( ). The application will not get an event when dx_pause( ) is issued.
dx_pause( ) — pause on-going play ! Example #include #include main() { int lDevHdl; DX_IOTT iott; /* Open a voice channel */ int lDevHdl = dx_open("dxxxB1C1", 0); /* Set up DX_IOTT */ DX_IOTT iott; /* Fill in the iott structure for the play */ . . . /* Start playing a prompt */ if( dx_playiottdata(lDevHdl, &iott, NULL, NULL, EV_ASYNC) < 0) { /* process error */ } /* Pause the play */ if( dx_pause(lDevHdl) <0 ) { /* process error */ } . . .
play recorded voice data — dx_play( ) dx_play( ) play recorded voice data Name: int dx_play(chdev, iottp, tptp, mode) Inputs: int chdev • valid channel device handle DX_IOTT *iottp • pointer to I/O Transfer Table structure DV_TPT *tptp • pointer to Termination Parameter Table structure unsigned short mode • asynchronous/synchronous playing mode bit mask for this play session Returns: 0 if success -1 if failure Includes: srllib.h dxxxlib.
dx_play( ) — play recorded voice data Parameter Description tptp Points to the Termination Parameter Table structure, DV_TPT, which specifies termination conditions for playing. For more information on this structure, see DV_TPT, on page 485. Note: In addition to DV_TPT terminations, the function can fail due to maximum byte count, dx_stopch( ), or end of file. See ATDX_TERMMSK( ) for a full list of termination reasons. mode Defines the play mode and asynchronous/synchronous mode.
play recorded voice data — dx_play( ) Notes: 1. The rate specified in the last play function applies to the next play function, unless the rate was changed in the parameter DXCH_PLAYDRATE using dx_setparm( ). 2. Specifying PM_SR6 or PM_SR8 changes the setting of the parameter DXCH_PLAYDRATE. DXCH_PLAYDRATE can also be set and queried using dx_setparm( ) and dx_getparm( ). The default setting for DXCH_PLAYDRATE is 6 kHz. 3.
dx_play( ) — play recorded voice data After dx_play( ) terminates, the current channel’s status information, including the reason for termination, can be accessed using extended attribute functions. Use the ATDX_TERMMSK( ) function to determine the reason for termination. Note: The DX_IOTT structure must remain in scope for the duration of the function if running asynchronously.
play recorded voice data — dx_play( ) /* Play a voice file. Terminate on receiving 4 digits or at end of file*/ #include #include #include #include main() { int DX_IOTT DV_TPT DV_DIGIT . . chdev; iott; tpt; dig; /* 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.
dx_play( ) — play recorded voice data #define MAXCHAN 24 int play_handler(); DX_IOTT prompt[MAXCHAN]; DV_TPT tpt; DV_DIGIT dig; main() { int chdev[MAXCHAN], index, index1; char *chname; int i, srlmode, voxfd; /* Set SRL to run in polled mode. */ srlmode = SR_POLLMODE; if (sr_setparm(SRL_DEVICE, SR_MODEID, (void *)&srlmode) == -1) { /* process error */ } /* initialize all the DX_IOTT structures for each individual prompt */ . .
play recorded voice data — dx_play( ) /* play the data */ if (dx_play(chdev[i],&prompt[i],&tpt,EV_ASYNC) == -1) { /* process error */ } } /* Use sr_waitevt to wait for the completion of dx_play(). * On receiving the completion event, TDX_PLAY, control is transferred * to the handler function previously established using sr_enbhdlr(). */ . . } int play_handler() { long term; /* Use ATDX_TERMMSK() to get the reason for termination.
dx_play( ) — play recorded voice data exit(1); } printf("Devices open and waiting .....\n"); /* * Take the phone off-hook to talk to the ADSI phone * This assumes we are connected through a Skutch Box. */ if (dx_sethook( chfd, DX_OFFHOOK, EV_SYNC) == -1) { printf("sethook failed\n"); while (1) { sleep(5); dx_clrdigbuf( chfd ); printf("Digit buffer cleared ..\n); /* * Generate the alert tone */ iott.io_type =IO_DEV|IO_EOT; iott.io_fhandle = dx_fileopen("message.asc",O_RDONLY); iott.
synchronously play voice data — dx_playf( ) dx_playf( ) synchronously play voice data Name: int dx_playf(chdev, fnamep, tptp, mode) Inputs: int chdev • valid channel device handle char *fnamep • pointer to name of file to play DV_TPT *tptp • pointer to Termination Parameter Table structure unsigned short mode • playing mode bit mask for this play session Returns: 0 if success -1 if failure Includes: srllib.h dxxxlib.
dx_playf( ) — synchronously play voice data ! 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.
synchronously play voice data — dx_playf( ) rval = dx_play(devd,&iott,tptp,mode); if (close(iott.io_fhandle) == -1) { return -1; } return rval; } ! Example #include #include #include main() { int chdev; DV_TPT tpt[2]; /* Open the channel using dx_open( ). Get channel device descriptor in * chdev. */ if ((chdev = dx_open("dxxxB1C1",NULL)) == -1) { /* process error */ } /* Set up the DV_TPT structures for MAXDTMF.
dx_playiottdata( ) — play back recorded voice data from multiple sources dx_playiottdata( ) play back recorded voice data from multiple sources Name: short dx_playiottdata(chdev, iottp, tptp, xpbp, mode) Inputs: int chdev • valid channel device handle DX_IOTT *iottp • pointer to I/O Transfer Table DV_TPT *tptp • pointer to Termination Parameter Block DX_XPB *xpbp • pointer to I/O Transfer Parameter Block unsigned short mode • play mode Returns: 0 if success -1 if failure Includes: srllib.
play back recorded voice data from multiple sources — dx_playiottdata( ) Parameter Description chdev Specifies the valid channel device handle obtained when the channel was opened using dx_open( ). iottp Points to the I/O Transfer Table structure, DX_IOTT, which specifies the order of playback and the location of voice data. See DX_IOTT, on page 509, for information about the data structure.
dx_playiottdata( ) — play back recorded voice data from multiple sources the function may fail before starting the play. In such cases, the function returns -1 immediately to indicate failure and no event is queued.
play back recorded voice data from multiple sources — dx_playiottdata( ) /* Set up DX_IOTT */ iott.io_fhandle = fd; iott.io_bufp = 0; iott.io_offset = 0; iott.io_length = -1; iott.io_type = IO_DEV | IO_EOT; /* * Specify VOX file format for ADPCM at 8KHz */ xpb.wFileFormat = FILE_FORMAT_VOX; xpb.wDataFormat = DATA_FORMAT_DIALOGIC_ADPCM; xpb.nSamplesPerSec = DRT_8KHZ; xpb.
dx_playiottdata( ) — play back recorded voice data from multiple sources /* Open VOX file to cache */ if ((fd = dx_fileopen("HELLO.VOX",O_RDONLY|O_BINARY)) == -1) { printf("File open error\n"); exit(2); } /* This specifies the data to cache */ iottp.io_fhandle = fd; iottp.io_bufp = 0; iottp.io_offset = 0; iottp.io_length = -1; iottp.
play tone defined by TN_GEN structure — dx_playtone( ) dx_playtone( ) play tone defined by TN_GEN structure Name: int dx_playtone(chdev, tngenp, tptp, mode) Inputs: int chdev • valid channel device handle TN_GEN *tngenp • pointer to the Tone Generation template structure DV_TPT *tptp • pointer to a Termination Parameter Table structure int mode • asynchronous/synchronous Returns: 0 if success -1 if failure Includes: srllib.h dxxxlib.
dx_playtone( ) — play tone defined by TN_GEN structure Set termination conditions using a DV_TPT structure, which is pointed to by the tptp parameter. After dx_playtone( ) terminates, use the ATDX_TERMMSK( ) function to determine the reason for termination. ! Synchronous Operation By default, this function runs synchronously, and returns a 0 to indicate that it has completed successfully. Set termination conditions using a DV_TPT structure, which is pointed to by the tptp parameter.
play tone defined by TN_GEN structure — dx_playtone( ) ! Example #include #include #include #include #define TID_1 main() { TN_GEN DV_TPT int 101 tngen; tpt[ 5 ]; dxxxdev; /* * Open the Voice Channel Device and Enable a Handler */ if ( ( dxxxdev = dx_open( "dxxxB1C1", NULL) ) == -1 ) { perror( "dxxxB1C1" ); exit( 1 ); } /* * Describe a Simple Dual Tone Frequency Tone of 950* 1050 Hz and 475-525 Hz using leading edge detection.
dx_playtone( ) — play tone defined by TN_GEN structure tpt[0].tp_flags = TF_TONE; tpt[0].tp_data = DX_TONEON; tpt[1].tp_type = IO_CONT; tpt[1].tp_termno = DX_TONE; tpt[1].tp_length = TID_1; tpt[1].tp_flags = TF_TONE; tpt[1].tp_data = DX_TONEOFF; tpt[2].tp_type = IO_EOT; tpt[2].tp_termno = DX_MAXTIME; /* On DM3 boards, DX_MAXTIME not supported */ tpt[2].tp_length = 6000; tpt[2].
play the cadenced tone defined by TN_GENCAD — dx_playtoneEx( ) dx_playtoneEx( ) play the cadenced tone defined by TN_GENCAD Name: int dx_playtoneEx(chdev, tngencadp, tptp, mode) Inputs: int chdev • valid channel device handle TN_GENCAD *tngencadp • pointer to the Cadenced Tone Generation template structure DV_TPT *tptp • pointer to a Termination Parameter Table structure int mode • asynchronous/synchronous Returns: 0 if success -1 if failure Includes: srllib.h dxxxlib.
dx_playtoneEx( ) — play the cadenced tone defined by TN_GENCAD Parameter Description chdev specifies the valid channel device handle obtained when the channel was opened using dx_open( ) tngencadp On DM3 boards, points to a TN_GENCAD structure (which defines a signal by specifying a cycle and its number of repetitions).
play the cadenced tone defined by TN_GENCAD — dx_playtoneEx( ) • If a TN_GEN tone generation template contains an invalid tg_dflag, or the specified amplitude or frequency is outside the valid range, dx_playtoneEx( ) will generate a TDX_ERROR event if asynchronous, or -1 if synchronous. • On DM3 boards, the DX_MAXTIME termination condition is not supported by tone generation functions, which include dx_playtoneEx( ).
dx_playtoneEx( ) — play the cadenced tone defined by TN_GENCAD /* * Set up the Terminating Conditions. * (Play until a digit is pressed or until time-out at 45 seconds.) */ tpt[0].tp_type = IO_CONT; tpt[0].tp_termno = DX_MAXDTMF; tpt[0].tp_length = 1; tpt[0].tp_flags = TF_MAXDTMF; tpt[1].tp_type = IO_EOT; tpt[1].tp_termno = DX_MAXTIME; /* On DM3 boards, DX_MAXTIME not supported */ tpt[1].tp_length = 450; tpt[1].
play the cadenced tone defined by TN_GENCAD — dx_playtoneEx( ) ATDV_LASTERR( dxxxdev ), ATDV_ERRMSGP( dxxxdev ) ); dx_close( dxxxdev ); exit( 1 ); } } /* Terminate the Program */ dx_close( dxxxdev ); exit( 0 ); } ! See Also • dx_playtone( ) • dx_bldtngen( ) • TN_GEN data structure • TN_GENCAD data structure Voice API for Windows Operating Systems Library Reference — November 2003 323
dx_playvox( ) — play voice data stored in a single VOX file dx_playvox( ) play voice data stored in a single VOX file Name: SHORT dx_playvox(chdev, filenamep, tptp, xpbp, mode) Inputs: int chdev • valid channel device handle char *filenamep • pointer to name of file to play DV_TPT *tptp • pointer to Termination Parameter Table structure DX_XPB *xpbp • pointer to I/O Transfer parameter block structure unsigned short mode • play mode Returns: 0 if successful -1 if failure Includes: srllib.
play voice data stored in a single VOX file — dx_playvox( ) ! Errors If this function returns -1 to indicate failure, one of the following reasons will be contained by ATDV_LASTERR( ): EDX_BADIOTT Invalid DX_IOTT setting EDX_BADWAVFILE Invalid WAVE file EDX_BUSY Channel is busy EDX_SH_BADCMD Unsupported command or WAVE file format EDX_SYSTEM Error from operating system; use dx_fileerrno( ) to obtain error value. System I/O errors EDX_XPBPARM Invalid DX_XPB setting ! Example #include "srllib.
dx_playvox( ) — play voice data stored in a single VOX file ! See Also 326 • dx_play( ) • dx_playf( ) • dx_playiottdata( ) • dx_playwav( ) Voice API for Windows Operating Systems Library Reference — November 2003
play voice data stored in a single WAVE file — dx_playwav( ) dx_playwav( ) play voice data stored in a single WAVE file Name: SHORT dx_playwav(chdev, filenamep, tptp, mode) Inputs: int chdev • valid channel device handle char *filenamep • pointer to name of file to play DV_TPT *tptp • pointer to Termination Parameter Table structure unsigned short mode • play mode Returns: 0 if successful -1 if failure Includes: srllib.h dxxxlib.
dx_playwav( ) — play voice data stored in a single WAVE file ! Errors If this function returns -1 to indicate failure, one of the following reasons will be contained by ATDV_LASTERR( ): EDX_BADIOTT Invalid DX_IOTT setting EDX_BADWAVFILE Invalid WAVE file EDX_BUSY Channel is busy EDX_SH_BADCMD Unsupported command or WAVE file format EDX_SYSTEM Error from operating system; use dx_fileerrno( ) to obtain error value EDX_XPBPARM Invalid DX_XPB setting ! Example #include #include
play voice data stored in a single WAVE file — dx_playwav( ) ! See Also • dx_playiottdata( ) • dx_playvox( ) Voice API for Windows Operating Systems Library Reference — November 2003 329
dx_PutStreamData( ) — place data into a circular stream buffer dx_PutStreamData( ) place data into a circular stream buffer Name: int dx_PutStreamData(hBuffer, pNewData, BuffSize, flag) Inputs: int hBuffer • stream buffer handle char* pNewData • pointer to user buffer of data to place in the stream buffer int BuffSize • number of bytes in the user buffer int flag • flag indicating last block of data Returns: 0 if successful -1 if failure Includes: srllib.h dxxxlib.
place data into a circular stream buffer — dx_PutStreamData( ) Unlike other voice API library functions, the streaming to board functions do not use SRL device handles. Therefore, ATDV_LASTERR( ) and ATDV_ERRMSGP( ) cannot be used to retrieve error codes and error descriptions. ! Example #include #include
dx_PutStreamData( ) — place data into a circular stream buffer 332 Voice API for Windows Operating Systems Library Reference — November 2003
get tone information for a specific call progress tone — dx_querytone( ) dx_querytone( ) get tone information for a specific call progress tone Name: int dx_querytone(brdhdl, toneid, tonedata, mode) Inputs: int brdhdl • a valid physical board level device int toneid • tone ID of the call progress tone TONE_DATA *tonedata • pointer to the TONE_DATA structure unsigned short mode • mode Returns: 0 if successful -1 if failure Includes: srllib.h dxxxlib.
dx_querytone( ) — get tone information for a specific call progress tone Parameter Description brdhdl specifies a valid physical board device handle (not a virtual board device) of the format brdBn obtained by a call to dx_open( ) toneid specifies the tone ID of the call progress tone.
get tone information for a specific call progress tone — dx_querytone( ) ! Errors If this function returns -1 to indicate failure, use ATDV_LASTERR( ) and ATDV_ERRMSGP( ) to retrieve one of the following error reasons: EDX_BADPARM invalid parameter EDX_SYSTEM error from operating system EDX_TONEID bad tone template ID ! Example #include "srllib.h" #include "dxxxlib.h" main() { int brdhdl; /* board handle */ . . .
dx_rec( ) — record voice data from a single channel dx_rec( ) record voice data from a single channel Name: int dx_rec(chdev, iottp, tptp, mode) Inputs: int chdev • valid channel device handle DX_IOTT *iottp • pointer to I/O Transfer Table structure DV_TPT *tptp • pointer to Termination Parameter Table structure unsigned short mode • asynchronous/synchronous setting and recording mode bit mask Returns: 0 if successful -1 if failure Includes: srllib.h dxxxlib.
record voice data from a single channel — dx_rec( ) Parameter Description tptp points to the Termination Parameter Table Structure, DV_TPT, which specifies termination conditions for recording. For more information on this structure, see DV_TPT, on page 485. Note: In addition to DV_TPT terminations, the function can fail due to maximum byte count, dx_stopch( ), or end of file. See ATDX_TERMMSK( ) for a full list of termination reasons. mode defines the recording mode.
dx_rec( ) — record voice data from a single channel Table 11 shows recording mode selections. The first column of the table lists all possible combinations of record features, and the first row lists each type of encoding algorithm (ADPCM or PCM) and the data-storage rate for each algorithm/sampling rate combination in parenthesis (24 kbps, 32 kbps, 48 kbps, or 64 kbps).
record voice data from a single channel — dx_rec( ) ! Synchronous Operation By default, this function runs synchronously, and returns a 0 to indicate that it has completed successfully. Set termination conditions using the DV_TPT structure, which is pointed to by the tptp parameter. After dx_rec( ) terminates, use the ATDX_TERMMSK( ) function to determine the reason for termination.
dx_rec( ) — record voice data from a single channel #include #include #include #include #define MAXLEN 10000 main() { DV_TPT tpt; DX_IOTT iott[2]; int chdev; char basebufp[MAXLEN]; /* * open the channel using dx_open( ) */ if ((chdev = dx_open("dxxxB1C1",NULL)) == -1) { /* process error */ } /* * Set up the DV_TPT structures for MAXDTMF */ dx_clrtpt(&tpt,1); tpt.tp_type = IO_EOT; /* last entry in the table */ tpt.
record voice data from a single channel — dx_rec( ) #include #include #include #include #include #define MAXLEN 10000 #define MAXCHAN 24 int record_handler(); DV_TPT tpt; DX_IOTT iott[MAXCHAN]; int chdev[MAXCHAN]; char basebufp[MAXCHAN][MAXLEN]; main() { int i, srlmode; char *chname; /* Set SRL to run in polled mode.
dx_rec( ) — record voice data from a single channel /* Start asynchronous dx_rec() on the channel */ if (dx_rec(chdev[i],&iott[i],&tpt,RM_TONE|EV_ASYNC) == -1) { /* process error */ } } /* Use sr_waitevt to wait for the completion of dx_rec(). * On receiving the completion event, TDX_RECORD, control is transferred * to a handler function previously established using sr_enbhdlr(). */ . . } int record_handler() { long term; /* Use ATDX_TERMMSK() to get the reason for termination.
record voice data to a single file — dx_recf( ) dx_recf( ) record voice data to a single file Name: int dx_recf(chdev, fnamep, tptp, mode) Inputs: int chdev • valid channel device handle char *fnamep • pointer to file to record to DV_TPT *tptp • pointer to Termination Parameter Table structure unsigned short mode • recording mode bit mask for this record session Returns: 0 if success -1 if failure Includes: srllib.h dxxxlib.
dx_recf( ) — record voice data to a single file ! 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.
record voice data to a single file — dx_recf( ) /* Use dx_rec() to do the record */ iott.io_type = IO_EOT | IO_DEV; iott.io_offset = (long)0; iott.io_length = -1; rval = dx_rec(devd,&iott,tptp,mode); if (close(iott.io_fhandle) == -1) { return -1; } return rval; } ! Example #include #include #include main() { int chdev; long termtype; DV_TPT tpt[2]; /* Open the channel using dx_open( ).
dx_recf( ) — record voice data to a single file ! See Also 346 • dx_rec( ) • dx_reciottdata( ) • dx_recm( ) • dx_recmf( ) • dx_recvox( ) • dx_setparm( ) • dx_getparm( ) • ATDX_TERMMSK( ) • DV_TPT data structure (to specify a termination condition) Voice API for Windows Operating Systems Library Reference — November 2003
record voice data to multiple destinations — dx_reciottdata( ) dx_reciottdata( ) record voice data to multiple destinations Name: short dx_reciottdata(chdev, iottp, tptp, xpbp, mode) Inputs: int chdev • valid channel device handle DX_IOTT *iottp • pointer to I/O Transfer Table structure DV_TPT *tptp • pointer to Termination Parameter Table structure DX_XPB *xpbp • pointer to I/O Transfer Parameter block unsigned short mode • play mode Returns: 0 if success -1 if failure Includes: srllib.
dx_reciottdata( ) — record voice data to multiple destinations Parameter Description xpbp points to the I/O Transfer Parameter Block, DX_XPB, which specifies the file format, data format, sampling rate, and resolution for I/O data transfer. For more information on this structure, see Table , “DX_XPB”, on page 520.
record voice data to multiple destinations — dx_reciottdata( ) In synchronous mode, if this function returns -1 to indicate failure, one of the following error codes will be returned by ATDV_LASTERR( ): EDX_BADIOTT Invalid DX_IOTT setting EDX_BADWAVFILE Invalid WAVE file EDX_BUSY Channel is busy EDX_SYSTEM Error from operating system; use dx_fileerrno( ) to obtain error value EDX_XPBPARM Invalid DX_XPB setting EDX_SH_BADCMD Unsupported command or WAVE file format ! Example #include
dx_reciottdata( ) — record voice data to multiple destinations /* * Specify VOX file format for PCM at 8KHz. */ xpb.wFileFormat = FILE_FORMAT_VOX; xpb.wDataFormat = DATA_FORMAT_PCM; xpb.nSamplesPerSec = DRT_8KHZ; xpb.wBitsPerSample = 8; /* Wait forever for phone to ring and go offhook */ if (dx_wtring(chdev,1,DX_OFFHOOK,-1) == -1) { printf("Error waiting for ring - %s\n", ATDV_LASTERR(chdev)); exit(3); } /* Play intro message */ if (dx_playwav(chdev,"HELLO.
record voice data to a single VOX file — dx_recvox( ) dx_recvox( ) record voice data to a single VOX file Name: SHORT dx_recvox(chdev, filenamep, tptp, xpbp, mode) Inputs: int chdev • valid channel device handle char *filenamep • pointer to name of file to record to DV_TPT *tptp • pointer to Termination Parameter Table structure DX_XPB *xpbp • pointer to I/O Transfer Parameter Block structure unsigned short mode • record mode Returns: 0 if successful -1 if failure Includes: srllib.h dxxxlib.
dx_recvox( ) — record voice data to a single VOX file other words, you must issue a dx_listen( ) function call on the device handle before calling any voice streaming function for that device handle. Furthermore, the dx_listen( ) function must be called within the same process as the voice streaming functions. The actual recording operation will start only after the voice channel is listening to the proper external time slot.
record voice data to a single VOX file — dx_recvox( ) /* Start playback */ if (dx_playwav(chdev,"HELLO.WAV",&tpt,EV_SYNC) == -1) { printf("Error playing file - %s\n", ATDV_ERRMSGP(chdev)); exit(4); } /* clear digit buffer */ dx_clrdigbuf(chdev); /* Start 6KHz ADPCM recording */ if (dx_recvox(chdev,"MESSAGE.
dx_recwav( ) — record voice data to a single WAVE file dx_recwav( ) record voice data to a single WAVE file Name: SHORT dx_recwav(chdev, filenamep, tptp, xpbp, mode) Inputs: int chdev • valid channel device handle char *filenamep • pointer to name of file to record to DV_TPT *tptp • pointer to Termination Parameter Table structure DX_XPB *xpbp • pointer to I/O Transfer Parameter Block unsigned short mode • record mode Returns: 0 if successful -1 if failure Includes: srllib.h dxxxlib.
record voice data to a single WAVE file — dx_recwav( ) ! Cautions On DM3 boards using a flexible routing configuration, voice channels must be listening to a TDM bus time slot in order for any voice streaming functions, such as dx_rec( ), to work. In other words, you must issue a dx_listen( ) function call on the device handle before calling any voice streaming function for that device handle. Furthermore, the dx_listen( ) function must be called within the same process as the voice streaming functions.
dx_recwav( ) — record voice data to a single WAVE file /* Wait forever for phone to ring and go offhook */ if (dx_wtring(chdev,1,DX_OFFHOOK,-1) == -1) { printf("Error waiting for ring - %s\n", ATDV_LASTERR(chdev)); exit(3); } /* Start playback */ if (dx_playwav(chdev,"HELLO.WAV",&tpt,EV_SYNC) == -1) { printf("Error playing file - %s\n", ATDV_ERRMSGP(chdev)); exit(4); } /* clear digit buffer */ dx_clrdigbuf(chdev); /* Start 11 kHz PCM recording */ if (dx_recwav(chdev,"MESSAGE.
reset internal data for a circular stream buffer — dx_ResetStreamBuffer( ) dx_ResetStreamBuffer( ) reset internal data for a circular stream buffer Name: int dx_ResetStreamBuffer(hBuffer) Inputs: int hBuffer • stream buffer handle Returns: 0 if successful -1 if failure Includes: srllib.h dxxxlib.
dx_ResetStreamBuffer( ) — reset internal data for a circular stream buffer exit(1); } if (dx_ResetStreamBuffer(hBuffer) < 0) {printf("Error resetting stream buffer \n"); exit (2); } if (dx_CloseStreamBuffer(hBuffer) < 0) { printf("Error closing stream buffer \n"); } } ! See Also 358 • dx_OpenStreamBuffer( ) • dx_CloseStreamBuffer( ) Voice API for Windows Operating Systems Library Reference — November 2003
resume paused play — dx_resume( ) dx_resume( ) resume paused play Name: int dx_resume(chdev) Inputs: int chdev • valid channel device handle Returns: 0 if success -1 if failure Includes: srllib.h dxxxlib.h Category: I/O Mode: synchronous Platform: DM3 ! Description The dx_resume( ) function resumes the play that was paused using dx_pause( ). The play is resumed exactly where the play was paused (that is, no data is lost). The application will not get an event when dx_resume( ) is issued.
dx_resume( ) — resume paused play ! Example #include #include main() { int lDevHdl; DX_IOTT iott; /* Open a voice channel */ int lDevHdl = dx_open("dxxxB1C1", 0); /* Start playing a prompt */ DX_IOTT iott; /* Fill in the iott structure for the play */ . . .
receive data on a specified channel — dx_RxIottData( ) dx_RxIottData( ) receive data on a specified channel Name: int dx_RxIottData(chdev, iottp, lpTerminations, wType, lpParams, mode) Inputs: int chdev • valid channel device handle DX_IOTT *iottp • pointer to I/O Transfer Table DV_TPT *lpTerminations • pointer to Termination Parameter Table int wType • data type LPVOID lpParams • pointer to data type-specific information int mode • function mode Returns: 0 if successful -1 if error Includes: s
dx_RxIottData( ) — receive data on a specified channel TM_USRSTOP Function stopped by user Upon asynchronous completion of dx_RxIottData( ), the TDX_RXDATA event is posted. Parameter Description chdev specifies the valid channel device handle obtained when the channel was opened using dx_open( ) iottp points to the I/O Transfer Table. The iottp parameter specifies the destination for the received data. This is the same DX_IOTT structure used in dx_playiottdata( ) and dx_reciottdata( ).
receive data on a specified channel — dx_RxIottData( ) EDX_BUSY Channel already executing I/O function EDX_SYSTEM Error from operating system; use dx_fileerrno( ) to obtain error value ! Example This example illustrates how to use dx_RxIottData( ) in synchronous mode. // Synchronous receive ADSI data #include "srllib.h" #include "dxxxlib.h" main() { DX_IOTT iott = {0}; char *devnamep = "dxxxB1C1"; char buffer[16]; ADSI_XFERSTRUC adsimode; DV_TPT tpt; int chdev; . . . sprintf(buffer, "RECEIVE.
dx_RxIottData( ) — receive data on a specified channel tpt.tp_termno = DX_MAXTIME; tpt.tp_length = 1000; tpt.tp_flags = TF_MAXTIME; if (dx_RxIottData(chdev, &iott, NULL, DT_ADSI, &adsimode, EV_SYNC) < 0) { fprintf(stderr, "ERROR: dx_TxIottData failed on Channel %s; error: %s\n", ATDV_NAMEP(chdev), ATDV_ERRMSGP(chdev)); } . . .
allow inter-process event communication — dx_sendevt( ) dx_sendevt( ) allow inter-process event communication Name: int dx_sendevt(dev, evttype, evtdatap, evtlen, flags) Inputs: int dev • valid channel device handle long evttype • type of event to be sent void *evtdatap • pointer to data block associated with evttype short evtlen • length of the data block in bytes unsigned short flags • which processes will receive this event Returns: 0 if successful -1 error return code Includes: srllib.
dx_sendevt( ) — allow inter-process event communication The application can define the evttype and evtdata to be any values as long as evttype is greater than 0x1FFFFFF and less than 0x7FFFFFF0. The only exception to this rule is the use of this function to stop dx_wtring( ) and dx_getevt( ) by sending TDX_CST events. To unblock a process waiting in dx_wtring( ) or dx_getevt( ), send an event of type TDX_CST to that process.
set the bulk queue buffer size — dx_setchxfercnt( ) dx_setchxfercnt( ) set the bulk queue buffer size Name: int dx_setchxfercnt(chdev, bufnum, bufsize_identifier) Inputs: int chdev • valid channel device handle int bufnum • allows for smaller driver data transfer buffer size int bufsize_identifier • equate for a buffer size Returns: 0 to indicate successful completion -1 if failure Includes: srllib.h dxxxlib.
dx_setchxfercnt( ) — set the bulk queue buffer size ! Cautions • This function fails if an invalid device handle is specified. • Do not use this function unless it is absolutely necessary to change the bulk queue buffer size between a user application and Intel® telecom hardware. Setting the buffer size to a smaller value can degrade system performance because data is transferred in smaller chunks. • A wrong buffer size can result in loss of data.
install and retrieve user-defined I/O functions — dx_setdevuio( ) dx_setdevuio( ) install and retrieve user-defined I/O functions Name: int dx_setdevuio(chdev, devuiop, retuiop) Inputs: int chdev • valid channel device handle DX_UIO *devuiop • pointer to user I/O routines structure DX_UIO **retuiop • pointer to return pointer for user I/O routines structure Returns: 0 if successful -1 error return code Includes: srllib.h dxxxlib.
dx_setdevuio( ) — install and retrieve user-defined I/O functions ! Cautions • The DX_UIO structure pointed to by devuiop must not be altered until the next call to dx_setdevuio( ) with new values for user-defined I/O functions. • For proper operation, it is the application’s responsibility to properly define the three DX_UIO user routines: u_read, u_write and u_seek. NULL is not permitted for any function. Refer to DX_UIO, on page 519 for more information.
install and retrieve user-defined I/O functions — dx_setdevuio( ) main(argc, argv) int argc; char *argv[]; { /* Open channel */ if ((chdev = dx_open("dxxxB1C1",0)) == -1) { printf("Cannot open channel\n"); /* Perform system error processing */ exit(1); } . . /* Other initialization */ . /* Initialize devio.u_read devio.u_write devio.
dx_setdigbuf( ) — set the digit buffering mode dx_setdigbuf( ) set the digit buffering mode Name: int dx_setdigbuf(chdev, mode) Inputs: int chdev • valid channel device handle int mode • digit buffering mode Returns: 0 if successful -1 if failure Includes: srllib.h dxxxlib.h Category: Configuration Mode: synchronous Platform: Springware ! Description The dx_setdigbuf( ) function sets the digit buffering mode that will be used by the voice driver.
set the digit buffering mode — dx_setdigbuf( ) EDX_TIMEOUT Timeout limit is reached ! Example #include #include #include main() { int chfd; int init_digbuf() { /* open the device using dx_open, chfd has the device handle */ /* * Set up digit buffering to be Cyclic.
dx_setdigtyp( ) — control the types of digits detected by the voice channel dx_setdigtyp( ) control the types of digits detected by the voice channel Name: int dx_setdigtyp(chdev, dmask) Inputs: int chdev • valid channel device handle unsigned short dmask • type of digit the channel will detect Returns: 0 if successful -1 if failure Includes: srllib.h dxxxlib.
control the types of digits detected by the voice channel — dx_setdigtyp( ) Notes: 1. MF detection can only be enabled on systems with MF capability. 2. The digit detection type specified in dmask will remain valid after the channel has been closed and reopened. 3. Global DPD can only be enabled on systems with this capability. 4. The Global DPD feature must be implemented on a call-by-call basis to work correctly. Global DPD must be enabled for each call by calling dx_setdigtyp( ). 5.
dx_setdigtyp( ) — control the types of digits detected by the voice channel /* setup TPT to dx_clrtpt(&tpt, tpt.tp_type = tpt.tp_termno = tpt.tp_length = tpt.
enable detection of call status transition (CST) events — dx_setevtmsk( ) dx_setevtmsk( ) enable detection of call status transition (CST) events Name: int dx_setevtmsk(chdev, mask) Inputs: int chdev unsigned int mask • valid channel device handle • event mask of events to enable Returns: 0 if successful -1 if failure Includes: srllib.h dxxxlib.
dx_setevtmsk( ) — enable detection of call status transition (CST) events Parameter Description chdev specifies the valid channel device handle obtained when the channel was opened using dx_open( ) mask specifies the events to enable. To poll for multiple events, perform an OR operation on the bit masks of the events you want to enable. The first enabled CST event to occur will be returned. If an event is not specified in the mask, the event will be disabled.
enable detection of call status transition (CST) events — dx_setevtmsk( ) /* Set event mask to collect digits */ if (dx_setevtmsk(chdev, DM_DIGITS) == -1) { To disable DM_DIGITS (turn off the digits flag and stop queuing digits): dx_setevtmsk(DM_DIGOFF); dx_clrdigbuf(chdev); /*Clear out queue*/ The following outlines the synchronous or asynchronous handling of CST events: Synchronous Application Asynchronous Application Call dx_setevtmsk( ) to enable CST events.
dx_setevtmsk( ) — enable detection of call status transition (CST) events /* open a channel with chdev as descriptor */ if ((chdev = dx_open("dxxxB1C1",NULL)) == -1) { /* process error */ } . . /* Set event mask to receive ring events */ if (dx_setevtmsk(chdev, DM_RINGS) == -1) { /* error setting event */ } . . /* check for ring event, timeout set to 20 seconds */ if (dx_getevt(chdev,&eblk,20) == -1) { /* error timeout */ } if(eblk.ev_event==DE_RINGS) { printf("Ring event occurred\n"); } . .
enable detection of call status transition (CST) events — dx_setevtmsk( ) /* Use dx_setevtmsk() to enable call status transition events * on this channel. */ if (dx_setevtmsk(chdev[i], DM_LCOFF|DM_LCON|DM_RINGS|DM_SILOFF|DM_SILON|DM_WINK) == -1) { /* process error */ } /* Using sr_enbhdlr(), set up handler function to handle call status * transition events on this channel.
dx_setgtdamp( ) — set up the tone detection amplitudes dx_setgtdamp( ) set up the tone detection amplitudes Name: void dx_setgtdamp(gtd_minampl1, gtd_maxampl1, gtd_minampl2, gtd_maxampl2) Inputs: short int gtd_minampl1 • minimum amplitude of the first frequency short int gtd_maxampl1 • maximum amplitude of the first frequency short int gtd_minampl2 • minimum amplitude of the second frequency short int gtd_maxampl2 • maximum amplitude of the second frequency Returns: void Includes: srllib.h dxxxlib.
set up the tone detection amplitudes — dx_setgtdamp( ) • When using this function in a multi-threaded application, use critical sections or a semaphore around the function call to ensure a thread-safe application. Failure to do so will result in “Bad Tone Template ID” errors. ! Errors If this function returns -1 to indicate failure, call 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.
dx_sethook( ) — provide control of the hook switch status dx_sethook( ) provide control of the hook switch status Name: int dx_sethook(chdev, hookstate, mode) Inputs: int chdev • valid channel device handle int hookstate • hook state (on-hook or off-hook) unsigned short mode • asynchronous/synchronous Returns: 0 if successful -1 if failure Includes: srllib.h dxxxlib.
provide control of the hook switch status — dx_sethook( ) If running asynchronously, termination is indicated by a TDX_SETHOOK event. The cst_event field in the DX_CST data structure will specify one of the following: • DX_ONHOOK if the hookstate has been set to on-hook • DX_OFFHOOK if the hookstate has been set to off-hook Use the Event Management function sr_getevtdatap( ) to return a pointer to the DX_CST structure. ATDX_HOOKST( ) will also return the type of hookstate event.
dx_sethook( ) — provide control of the hook switch status /* take the channel off-hook */ if (dx_sethook(chdev,DX_OFFHOOK,EV_SYNC) == -1) { /* error setting hook state */ } . . } ! Example 2 This example illustrates how to use dx_sethook( ) in asynchronous mode. #include #include #include #include #define MAXCHAN 24 int sethook_hdlr(); main() { int i, chdev[MAXCHAN]; char *chnamep; int srlmode; /* Set SRL to run in polled mode.
provide control of the hook switch status — dx_sethook( ) /* sr_getevtdatap() points to the call status transition * event structure, which contains the hook state of the * device. */ cstp = (DX_CST *)sr_getevtdatap(); switch (cstp->cst_event) { case DX_ONHOOK: printf("Channel %s is ON hook\n", ATDX_NAMEP(sr_getevtdev())); break; case DX_OFFHOOK: printf("Channel %s is OFF hook\n", ATDX_NAMEP(sr_getevtdev())); break; default: /* process error */ break; } /* Kick off next function in the state machine model.
dx_setparm( ) — set physical parameters of a channel or board device dx_setparm( ) set physical parameters of a channel or board device Name: int dx_setparm(dev, parm, valuep) Inputs: int dev • valid channel or board device handle unsigned long parm • parameter type to set void *valuep • pointer to parameter value Returns: 0 if successful -1 if failure Includes: srllib.h dxxxlib.
set physical parameters of a channel or board device — dx_setparm( ) The dxxxlib.h file contains defined masks for parameters that can be examined and set using dx_getparm( ) and dx_setparm( ). The voice device parameters fall into two classes: • Board parameters, which apply to all channels on the board; voice board parameter defines have a DXBD_ prefix. • Channel parameters, which apply to individual channels on the board; voice channel parameter defines have a DXCH_ prefix.
dx_setparm( ) — set physical parameters of a channel or board device Table 12. Voice Board Parameters (DM3) Bytes Read/ Write DXBD_CHNUM 1 R - Channel Number. Number of channels on the board DXBD_HWTYPE 1 R - Hardware Type. On DM3 boards, TYP_D41 DXBD_SYSCFG 1 R - System Configuration. On DM3 boards, 1 is always returned Define Default Description For Springware boards, the supported board parameter defines are shown in Table 13. Table 13.
set physical parameters of a channel or board device — dx_setparm( ) Table 13. Voice Board Parameters (Springware) (Continued) Bytes Read/ Write DXBD_OFFHDLY 2 R/W 50 Offhook Delay. Period after offhook, during which no events are generated; that is, no DTMF digits will be detected during this period (10 msec units). DXBD_P_BK 2 R/W 6 Pulse Dial Break. Duration of pulse dial off-hook interval (10 msec units) DXBD_P_IDD 2 R/W 100 Pulse Interdigit Delay.
dx_setparm( ) — set physical parameters of a channel or board device Table 14. Voice Channel Parameters (DM3) (Continued) Bytes Read/ Write DXCH_AGC_MEMORY SILENCERESET 2 W 50 Automatic Gain Control. Specifies the size of memory after each long silence between words or sentences measured in 1 msec units. DXCH_AGC_NOISE THRESHOLD 2 W -780 Automatic Gain Control. AGC noise threshold level. Specifies the lower threshold for noise level estimate: below is considered noise. Measured in 0.1 dB units.
set physical parameters of a channel or board device — dx_setparm( ) Table 14. Voice Channel Parameters (DM3) (Continued) Define Bytes Read/ Write Default DXCH_FSKMARKLENGTH Description ADSI two-way FSK. For a given FSK protocol standard specified in DXCH_FSKSTANDARD, the DXCH_FSKMARKLENGTH parameter allows the application to set the mark length. If the FSK protocol standard is set to Bellcore, the default value for the mark length when transmitting data is 180 bits.
dx_setparm( ) — set physical parameters of a channel or board device Table 15. Voice Channel Parameters (Springware) Define Bytes Read/ Write Default DXCH_AUDIOLINEIN Description Enables or disables the ProLine/2V audio jack line-in on voice channel 2 DXCH_CALLID disabled Enables or disables caller ID for the channel.
set physical parameters of a channel or board device — dx_setparm( ) Table 15. Voice Channel Parameters (Springware) (Continued) Define DXCH_MFMODE Bytes Read/ Write 2 R/W Default 2 Description Specifies a word-length bit mask that selects the minimum length of KP tones to be detected. The possible values of this field are: • 0 – detect KP tone > 40 msec • 2 – detect KP tone > 65 msec If the value is set to 2, any KP tone greater than 65 msec will be returned to the application during MF detection.
dx_setparm( ) — set physical parameters of a channel or board device Table 15. Voice Channel Parameters (Springware) (Continued) Bytes Read/ Write DXCH_T_IDD 2 R/W 5 Specifies DTMF Interdigit delay (time between digits in DTMF dialing) DXCH_TTDATA 1 R/W 10 Specifies DTMF length (duration) for dialing. DXCH_TXDATABUFSIZE 4 R/W 32 kbytes Sets the size of the play buffers only that are used to transfer data between the application on the host and the driver.
set physical parameters of a channel or board device — dx_setparm( ) ! 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 Invalid parameter EDX_SYSTEM Error from operating system; use dx_fileerrno( ) to obtain error value ! Example #include #include #include
dx_setparm( ) — set physical parameters of a channel or board device 398 Voice API for Windows Operating Systems Library Reference — November 2003
specify the template of the cadenced tone — dx_SetRecordNotifyBeepTone( ) dx_SetRecordNotifyBeepTone( ) specify the template of the cadenced tone Name: int dx_SetRecordNotifyBeepTone(chdev, tngencadp) Inputs: int chdev • voice channel device handle const TN_GENCAD *tngencadp • pointer to the cadenced tone generation data structure Returns: 0 if success -1 if failure Includes: srllib.h dxxxlib.
dx_SetRecordNotifyBeepTone( ) — specify the template of the cadenced tone ! 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. ! Example For an example of how to use this function, see the example code for dx_playtoneEx( ).
set conditions that adjust speed or volume of play — dx_setsvcond( ) dx_setsvcond( ) set conditions that adjust speed or volume of play Name: int dx_setsvcond( chdev, numblk, svcbp) Inputs: int chdev • valid channel device handle unsigned short numblk • number of DX_SVCB blocks DX_SVCB * svcbp • pointer to array of DX_SVCB structures Returns: 0 if success -1 if failure Includes: srllib.h dxxxlib.
dx_setsvcond( ) — set conditions that adjust speed or volume of play Parameter Description chdev specifies the valid channel device handle obtained when the channel was opened using dx_open( ) numblk specifies the number of DX_SVCB blocks in the array. Set to a value between 1 and 20.
set conditions that adjust speed or volume of play — dx_setsvcond( ) ! Example #include #include #include #include
dx_setsvcond( ) — set conditions that adjust speed or volume of play ! See Also 404 • dx_clrsvcond( ) • DX_SVCB structure • dx_pause( ) • dx_resume( ) • dx_setsvmt( ) • dx_getcursv( ) • dx_getsvmt( ) • dx_adjsv( ) • speed and volume modification tables in Voice API Programming Guide Voice API for Windows Operating Systems Library Reference — November 2003
change default values of the speed or volume modification table — dx_setsvmt( ) dx_setsvmt( ) change default values of the speed or volume modification table Name: int dx_setsvmt(chdev, tabletype, svmtp, flag) Inputs: int chdev • valid channel device handle unsigned short tabletype • type of table to update (speed or volume) DX_SVMT * svmtp • pointer to speed or volume modification table to modify unsigned short flag • optional modification flag Returns: 0 if success -1 if failure Includes: srllib.
dx_setsvmt( ) — change default values of the speed or volume modification table Parameter Description svmtp points to the DX_SVMT structure whose contents are used to update either the speed or volume modification table This structure is not used when SV_SETDEFAULT has been set in the flag parameter. flag Specifies one of the following: • SV_SETDEFAULT – reset the table to its default values. See the Voice API Programming Guide for a list of default values.
change default values of the speed or volume modification table — dx_setsvmt( ) ! Example #include #include #include #include /* * Global Variables */ main() { DX_SVMT int svmt; dxxxdev, index; /* * Open the Voice Channel Device and Enable a Handler */ if ( ( dxxxdev = dx_open( "dxxxB1C1", NULL) ) == -1 ) { perror( "dxxxB1C1" ); exit( 1 ); } /* * Set up the Speed/Volume Modification */ memset( &svmt, 0, sizeof( DX_SVMT ) ); svmt.decrease[ 0 ] = -128; svmt.
dx_setsvmt( ) — change default values of the speed or volume modification table /* * Close the opened Voice Channel Device */ if ( dx_close( dxxxdev ) != 0 ) { perror( "close" ); } /* Terminate the Program */ exit( 0 ); } ! See Also 408 • dx_adjsv( ) • dx_getcursv( ) • dx_getsvmt( ) • speed and volume modification tables in Voice API Programming Guide • DX_SVMT data structure Voice API for Windows Operating Systems Library Reference — November 2003
change the duration of the built-in beep tone — dx_settonelen( ) dx_settonelen( ) change the duration of the built-in beep tone Name: int dx_settonelen(tonelength) Inputs: int tonelength • tone duration Returns: 0 if successful Includes: srllib.h dxxxlib.
dx_settonelen( ) — change the duration of the built-in beep tone ! Example #include "srllib.h" #include "dxxxlib.h" int chdev; DV_TPT tpt; DX_XPB xpb; . . . /* channel descriptor */ /* termination parameter table */ /* I/O transfer parameter block */ /* Increase beep tone len to 800ms */ dx_settonelen (4); /* Open channel */ if ((chdev = dx_open("dxxxB1C1",0)) == -1) { printf("Cannot open channel\n"); /* Perform system error processing */ exit(1); } /* Set to terminate play on 1 digit */ tpt.
change the duration of the built-in beep tone — dx_settonelen( ) • dx_playvox( ) • dx_rec( ) • dx_reciottdata( ) • dx_recvox( ) Voice API for Windows Operating Systems Library Reference — November 2003 411
dx_setuio( ) — install user-defined I/O functions dx_setuio( ) install user-defined I/O functions Name: int dx_setuio(uioblk) Inputs: uioblk • DX_UIO data structure Returns: 0 if success -1 if failure Includes: srllib.h dxxxlib.h Category: I/O Mode: synchronous Platform: DM3, Springware ! Description The dx_setuio( ) function installs user-defined read( ), write( ), and lseek( ) functions in your application.
install user-defined I/O functions — dx_setuio( ) ! Example #include #include #include #include
dx_setuio( ) — install user-defined I/O functions /*This block uses standard I/O functions */ iott->io_type = IO_DEV|IO_CONT iott->io_fhandle = vodat_fd; iott->io_offset = 0; iott->io_length = 20000; /*This block uses my I/O functions */ iottp++; iottp->io_type = IO_DEV|IO_UIO|IO_CONT iottp->io_fhandle = vodat_fd; iott->io_offset = 20001; iott->io_length = 20000; /*This block uses standard I/O functions */ iottp++ iott->io_type = IO_DEV|IO_CONT iott->io_fhandle = vodat_fd; iott->io_offset = 20002; iott->io
set water mark for the circular stream buffer — dx_SetWaterMark( ) dx_SetWaterMark( ) set water mark for the circular stream buffer Name: int dx_SetWaterMark(hBuffer, parm_id, value) Inputs: int hBuffer • circular stream buffer handle int parm_id • LOW_MARK or HIGH_MARK int value • value of water mark in bytes Returns: 0 if successful -1 if failure Includes: srllib.h dxxxlib.
dx_SetWaterMark( ) — set water mark for the circular stream buffer ! Errors This function returns -1 in case of error. Unlike other voice API library functions, the streaming to board functions do not use SRL device handles. Therefore, ATDV_LASTERR( ) and ATDV_ERRMSGP( ) cannot be used to retrieve error codes and error descriptions. ! Example #include #include
force termination of currently active I/O functions — dx_stopch( ) dx_stopch( ) force termination of currently active I/O functions Name: int dx_stopch(chdev, mode) Inputs: int chdev unsigned short mode • valid channel device handle • mode flag Returns: 0 if success -1 if failure Includes: srllib.h dxxxlib.h Category: I/O Mode: asynchronous or synchronous Platform: DM3, Springware ! Description The dx_stopch( ) function forces termination of currently active I/O functions on a channel.
dx_stopch( ) — force termination of currently active I/O functions Parameter Description chdev specifies the valid channel device handle obtained when the channel was opened using dx_open( ) mode a bit mask that specifies the mode: • EV_SYNC – synchronous mode • EV_ASYNC – asynchronous mode. The stop will be issued, but the driver does not “sleep” and wait for the channel to become idle before dx_stopch( ) returns.
force termination of currently active I/O functions — dx_stopch( ) EDX_SYSTEM Error from operating system; use dx_fileerrno( ) to obtain error value ! Example #include #include #include main() { int chdev, srlmode; /* Set SRL to run in polled mode. */ srlmode = SR_POLLMODE; if (sr_setparm(SRL_DEVICE, SR_MODEID, (void *)&srlmode) == -1) { /* process error */ } /* Open the channel using dx_open( ). Get channel device descriptor in * chdev.
dx_stopch( ) — force termination of currently active I/O functions • 420 ATDX_CPTERM( ) - dx_dial( ) with call progress analysis Voice API for Windows Operating Systems Library Reference — November 2003
return the status of tone set file loading — dx_TSFStatus( ) dx_TSFStatus( ) return the status of tone set file loading Name: int dx_TSFStatus ( void ) Inputs: None Returns: 0 if TSF loading was successful non-zero value if TSF loading failed; see EDX error codes for reason Includes: srllib.h dxxxlib.h Category: Configuration Mode: synchronous Platform: Springware ! Description The dx_TSFStatus( ) function returns the status of tone set file loading.
dx_TSFStatus( ) — return the status of tone set file loading EDX_FEATUREDISABLED The TSF feature is disabled in the configuration manager (DCM). ! Example /*$ dx_TSFStatus( ) example $*/ #include #include main ( ) { int rc; rc = dx_TSFStatus ( ); switch ( rc ) { case 0: break; case EDX_SYSTEM: printf ( "General system error loading PBXpert.
transmit data on a specified channel — dx_TxIottData( ) dx_TxIottData( ) transmit data on a specified channel Name: int dx_TxIottData(chdev, iottp, lpTerminations, wType, lpParams, mode) Inputs: int chdev • valid channel device handle DX_IOTT *iottp • pointer to I/O Transfer Table DV_TPT *lpTerminations • pointer to Termination Parameter Table int wType • data type LPVOID lpParams • pointer to data type-specific information int mode • function mode Returns: 0 if successful -1 if error Includes:
dx_TxIottData( ) — transmit data on a specified channel Parameter Description chdev Specifies the valid channel device handle obtained when the channel was opened using dx_open( ). iottp Points to the I/O Transfer Table structure. The source of message(s) to be transmitted is specified by this transfer table. This is the same DX_IOTT structure used in dx_playiottdata( ) and dx_reciottdata( ). See DX_IOTT, on page 509, for more information on this data structure.
transmit data on a specified channel — dx_TxIottData( ) #include "srllib.h" #include "dxxxlib.h" main() { DX_IOTT iott = {0}; char *devnamep = "dxxxB1C1"; char buffer[16]; ADSI_XFERSTRUC adsimode; int chdev; . . . sprintf(buffer, "MENU.ADSI"); if ((iott.io_fhandle = dx_fileopen(buffer, _O_RDONLY|O_BINARY)) == -1) { /* Perform system error processing */ exit(1); } if ((chdev = dx_open(devnamep, 0)) == -1) { fprintf(stderr, "Error opening channel %s\n",devnamep); dx_fileclose(iott.
dx_TxRxIottData( ) — start a transmit-initiated reception of data dx_TxRxIottData( ) start a transmit-initiated reception of data Name: int dx_TxRxIottData(chdev, lpTxIott, lpTxTerminations, lpRxIott, lpRxTerminations.
start a transmit-initiated reception of data — dx_TxRxIottData( ) Parameter Description lpTxTerminations Points to the Termination Parameter Table structure, DV_TPT, which specifies termination conditions for the device handle. Supported values are: • DX_MAXTIME • DX_MAXDATA (valid values are 1 - 65535 for tp_length field) For more information on this structure, see DV_TPT, on page 485. lpRxIott Points to the I/O Transfer Table structure.
dx_TxRxIottData( ) — start a transmit-initiated reception of data If the channel detects end of FSK data during the receive portion, the function is terminated. Use ATDX_TERMMSK( ) to return the reason for the last I/O function termination on the channel.
start a transmit-initiated reception of data — dx_TxRxIottData( ) ! Example // Synchronous transmit initiated receive ADSI data #include "srllib.h" #include "dxxxlib.h" main() { DX_IOTT TxIott = {0}; DX_IOTT RxIott = {0}; DV_TPT tpt; char *devnamep = "dxxxB1C1"; char buffer[16]; ADSI_XFERSTRUC adsimode; int chdev; . . . sprintf(buffer, "MENU.ADSI"); if ((TxIott.io_fhandle = dx_fileopen(buffer, _O_RDONLY|O_BINARY)) == -1) { /* Perform system error processing */ exit(1); } sprintf(buffer, "RECEIVE.
dx_TxRxIottData( ) — start a transmit-initiated reception of data if (dx_clrtpt(&tpt, 1) == -1) { // Process error } tpt.tp_termno = DX_MAXTIME; tpt.tp_length = 1000; tpt.tp_flags = TF_MAXTIME; printf("Waiting for incoming ring\n"); dx_wtring(chdev, 2, DX_OFFHOOK, -1); if (dx_TxRxIottData(chdev, &TxIott, NULL, &RxIott, &tpt, DT_ADSI, &adsimode, EV_SYNC) < 0) { fprintf(stderr, "ERROR: dx_TxIottData failed on Channel %s; error: %s\n", ATDV_NAMEP(chdev), ATDV_ERRMSGP(chdev)); } . . .
disconnect voice receive channel from TDM bus — dx_unlisten( ) dx_unlisten( ) disconnect voice receive channel from TDM bus Name: int dx_unlisten(chdev) Inputs: int chdev • voice channel device handle Returns: 0 on success -1 on error Includes: srllib.h dxxxlib.h Category: TDM Routing Mode: synchronous Platform: DM3, Springware ! Description The dx_unlisten( ) function disconnects the voice receive (listen) channel from the TDM bus.
dx_unlisten( ) — disconnect voice receive channel from TDM bus 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 type (voice, analog, etc.
disable echo cancellation resource (ECR) mode — dx_unlistenecr( ) dx_unlistenecr( ) disable echo cancellation resource (ECR) mode Name: int dx_unlistenecr(chdev) Inputs: int chdev • voice channel device handle Returns: 0 on success -1 on error Includes: srllib.h dxxxlib.
dx_unlistenecr( ) — disable echo cancellation resource (ECR) mode EDX_SH_BADCMD Function 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 type (voice, analog, etc.
disable echo cancellation resource (ECR) mode — dx_unlistenecr( ) /* Disconnect echo-reference receive of board 1, channel 1 from the TDM bus, and stop the ECR feature */ if (dx_unlistenecr(chdev) == -1) { printf("Error message = %s", ATDV_ERRMSGP(chdev)); exit(1); } return(0); } ! See Also • dx_listenecr( ) • dx_listenecrex( ) Voice API for Windows Operating Systems Library Reference — November 2003 435
dx_wink( ) — generate an outbound wink dx_wink( ) generate an outbound wink Name: int dx_wink(chdev, mode) Inputs: int chdev • valid channel device handle unsigned short mode • synchronous/asynchronous setting Returns: 0 if successful -1 if failure Includes: srllib.h dxxxlib.h Category: I/O Mode: asynchronous or synchronous Platform: Springware ! Description The dx_wink( ) function generates an outbound wink on the specified channel.
generate an outbound wink — dx_wink( ) a TDX_WINK termination event to indicate completion. Use the Standard Runtime Library (SRL) Event Management functions to handle the termination event. For more information on wink signaling, such as how to set delay prior to wink, see the Voice API Programming Guide. ! Cautions Make sure the channel is on-hook when dx_wink( ) is called.
dx_wink( ) — generate an outbound wink /* get digits while on-hook */ if (dx_getdig(chdev,&tpt, &digitp, EV_SYNC) == -1) { /* error getting digits */ } /* now we can go off-hook and continue */ if ( dx_sethook(chdev,DX_OFFHOOK,EV_SYNC)== -1) { /* process error */ } . . } ! Example 2 This example illustrates how to use dx_wink( ) in asynchronous mode. #include #include #include #include
generate an outbound wink — dx_wink( ) /* Use sr_waitevt() to wait for the completion of wink. * On receiving the completion event, TDX_WINK, control is transferred * to the handler function previously established using sr_enbhdlr(). */ . .
dx_wtcallid( ) — wait for rings and report caller ID dx_wtcallid( ) wait for rings and report caller ID Name: int dx_wtcallid (chdev, nrings, timeout, bufferp) Inputs: int chdev • valid channel device handle int nrings • number of rings to wait short timeout • time to wait for rings (in seconds) unsigned char *bufferp • pointer to where to return the caller ID information Returns: 0 success -1 error return code Includes: srllib.h dxxxlib.
wait for rings and report caller ID — dx_wtcallid( ) Parameter Description timeout specifies the maximum length of time to wait for a ring Valid values (0.1-second units): • ≥0 • -1 waits forever; never times out If timeout is set to 0 and a ring event does not already exist, the function returns immediately. bufferp pointer to buffer where the calling line Directory Number (DN) is to be stored Note: The application must allocate a buffer large enough to accommodate the DN.
dx_wtcallid( ) — wait for rings and report caller ID EDX_CLIDBLK Caller ID is blocked or private or withheld (other information may be available using dx_gtextcallid( )) EDX_CLIDINFO Caller ID information not sent, sub-message(s) requested not available or caller ID information invalid EDX_CLIDOOA Caller ID is out of area (other information may be available using dx_gtextcallid( )) EDX_SYSTEM Error from operating system; use dx_fileerrno( ) to obtain error value EDX_TIMEOUT Time out limit is reached ! Exam
wait for a specified number of rings — dx_wtring( ) dx_wtring( ) wait for a specified number of rings Name: int dx_wtring(chdev, nrings, hstate, timeout) Inputs: int chdev • valid channel device handle int nrings • number of rings to wait for int hstate • hook state to set after rings are detected int timeout • timeout, in seconds Returns: 0 if successful -1 if failure Includes: srllib.h dxxxlib.
dx_wtring( ) — wait for a specified number of rings Parameter Description chdev specifies the valid channel device handle obtained when the channel was opened using dx_open( ) function nrings specifies the number of rings to wait for before setting the hook state hstate sets the hookstate of the channel after the number of rings specified in nrings are detected.
wait for a specified number of rings — dx_wtring( ) ! Example #include #include #include main() { int chdev; . . /* channel descriptor */ /* Open Channel */ if ((chdev = dx_open("dxxxB1C1",NULL)) == -1) { /* process error */ } /* Wait for two rings on this channel - no timeout */ if (dx_wtring(chdev,2,DX_OFFHOOK,-1) == -1) { /* process error */ } . .
li_attendant( ) — perform the actions of an automated attendant li_attendant( ) perform the actions of an automated attendant Name: int li_attendant(pAtt) Inputs: DX_ATTENDANT *pAtt • pointer to DX_ATTENDANT data structure Returns: 0 if success EDX_BADPARM, EDX_BADPROD, EDX_SYSTEM, or -1 if failure Includes: syntellect.
perform the actions of an automated attendant — li_attendant( ) ! Cautions • This function must supply values for all required fields in the DX_ATTENDANT structure. • This function must supply an extension mapping function even if no extension translation is required. You should prefix the extension to be dialed with the “flash hook” character and possibly the “pause” character as well. • The function does not return when a non fatal error occurs during operation.
li_attendant( ) — perform the actions of an automated attendant #include #include #include #include #include #include #include #include "syntellect.
perform the actions of an automated attendant — li_attendant( ) // start the first attendant thread if ((hThread[0] = (HANDLE) _beginthread( li_attendant, 0, (void *) &Att[0] )) == (HANDLE) -1) { printf("Cannot create thread 1.\n"); exit(0); } // start the second attendant thread if ((hThread[1] = (HANDLE) _beginthread( li_attendant, 0, (void *) &Att[1] )) == (HANDLE) -1) { printf("Cannot create thread 2.
li_islicensed_syntellect( ) — verify Syntellect patent license on board li_islicensed_syntellect( ) verify Syntellect patent license on board Name: BOOL li_is licensed_syntellect(chdev) Inputs: int chdev • valid device handle Returns: TRUE if board is enabled with Syntellect license FALSE if board is not enabled with Syntellect license Includes: syntellect.
make a full or half-duplex connection — nr_scroute( ) nr_scroute( ) make a full or half-duplex connection Name: int nr_scroute(devh1, devtype1, devh2, devtype2, mode) Inputs: int devh1 • valid channel device handle unsigned short devtype1 • type of device for devh1 int devh2 • valid channel device handle unsigned short devtype2 • type of device for devh2 unsigned char mode • half or full duplex connection Returns: 0 on success -1 on error Includes: stdio.h varargs.h srllib.h dxxxlib.h dtilib.
nr_scroute( ) — make a full or half-duplex connection Parameter Description devh1 specifies the valid channel device handle obtained when the channel was opened for the first device (the transmitting device for half duplex) devtype1 specifies the type of device for devh1: • SC_VOX – voice channel device • SC_LSI – analog network (loop start interface) channel device • SC_DTI – digital network interface device • SC_MSI – MSI station device • SC_FAX – fax channel device On DM3 boards, the SC_LSI value i
make a full or half-duplex connection — nr_scroute( ) #include #include #include #include #ifdef DTISC #include #endif #ifdef FAXSC #include #endif #include "sctools.
nr_scroute( ) — make a full or half-duplex connection #ifdef FAXSC case SC_FAX: if (fx_getxmitslot(devh1, &sc_tsinfo) == -1) { nr_scerror("nr_scroute: %s: fx_getxmitslot ERROR: %s\n", ATDV_NAMEP(devh1),ATDV_ERRMSGP(devh1)); return -1; } break; #endif default: nr_scerror("nr_scroute: %s: ERROR: Invalid 1st device type\n", ATDV_NAMEP(devh1)); return -1; } /* * Make the second device type listen to the time slot that the first * device is transmitting on. If a half duplex connection is desired, * then return.
make a full or half-duplex connection — nr_scroute( ) if (dt_getxmitslot(devh2, &sc_tsinfo) == -1) { nr_scerror("nr_scroute: %s: dt_getxmitslot ERROR: %s\n", ATDV_NAMEP(devh2),ATDV_ERRMSGP(devh2)); return -1; } break; #endif #ifdef FAXSC case SC_FAX: if (fx_listen(devh2, &sc_tsinfo) == -1) { nr_scerror("nr_scroute: %s: fx_listen ERROR: %s\n", ATDV_NAMEP(devh2),ATDV_ERRMSGP(devh2)); return -1; } if (mode == SC_HALFDUP) { return 0; } if (fx_getxmitslot(devh2, &sc_tsinfo) == -1) { nr_scerror("nr_scroute: %s:
nr_scroute( ) — make a full or half-duplex connection #ifdef FAXSC case SC_FAX: if (fx_listen(devh1, &sc_tsinfo) == -1) { nr_scerror("nr_scroute: %s: fx_listen ERROR: %s\n", ATDV_NAMEP(devh1),ATDV_ERRMSGP(devh1)); return -1; } break; #endif } return 0; } static void nr_scerror(va_alist) va_dcl { #ifdef PRINTON va_list args; char *fmt; /* * Make args point to the 1st unnamed argument and then print * to stderr.
break a full or half-duplex connection — nr_scunroute( ) nr_scunroute( ) break a full or half-duplex connection Name: int nr_scunroute(devh1, devtype1, devh2, devtype2, mode) Inputs: int devh1 • valid channel device handle unsigned short devtype1 • type of device for devh1 int devh2 • valid channel device handle unsigned short devtype2 • type of device for devh2 unsigned char mode • half or full duplex connection Returns: 0 on success -1 on error Includes: stdio.h varargs.h srllib.h dxxxlib.
nr_scunroute( ) — break a full or half-duplex connection Parameter Description devh1 specifies the valid channel device handle obtained when the channel was opened for the first device (the transmitting device for half duplex) devtype1 specifies the type of device for devh1: • SC_VOX – voice channel device • SC_LSI – analog (loop start interface) channel device • SC_DTI – digital network interface device • SC_MSI – MSI station device • SC_FAX – fax channel device On DM3 boards, the SC_LSI value is not
break a full or half-duplex connection — nr_scunroute( ) #include #include #include #include #ifdef DTISC #include #endif #ifdef FAXSC #include #endif #include "sctools.
nr_scunroute( ) — break a full or half-duplex connection default: nr_scerror("nr_scunroute: %s: ERROR: Invalid 2nd device type\n", ATDV_NAMEP(devh2)); return -1; } /* * A half duplex connection has already been broken. * that is required, then return now.
break a full or half-duplex connection — nr_scunroute( ) static void nr_scerror(va_alist) va_dcl { #ifdef PRINTON va_list args; char *fmt; /* * Make args point to the 1st unnamed argument and then print * to stderr.
r2_creatfsig( ) — create R2/MF forward signal tone r2_creatfsig( ) create R2/MF forward signal tone Name: int r2_creatfsig(chdev, forwardsig) Inputs: int chdev • channel device handle int forwardsig • group I/II forward signal Returns: 0 if success -1 if failure Includes: srllib.h dxxxlib.
create R2/MF forward signal tone — r2_creatfsig( ) SIGI_8 SIGII_8 108 SIGI_9 SIGII_9 109 SIGI_10 SIGII_10 110 SIGI_11 SIGII_11 111 SIGI_12 SIGII_12 112 SIGI_13 SIGII_13 113 SIGI_14 SIGII_14 114 SIGI_15 SIGII_15 115 Note: Either the Group I or the Group II define can be used to specify the forward signal, because the Group I and Group II defines correspond to the same set of 15 forward signals, and the same user-defined tones are used for Group I and Group II.
r2_creatfsig( ) — create R2/MF forward signal tone EDX_MAXTMPLT Maximum number of user-defined tones for the board EDX_SYSTEM Error from operating system; use dx_fileerrno( ) to obtain error value EDX_TONEID Invalid tone template ID ! Example #include #include #include #include main() { int
create R2/MF forward signal tone — r2_creatfsig( ) • R2/MF Signaling in Voice API Programming Guide Voice API for Windows Operating Systems Library Reference — November 2003 465
r2_playbsig( ) — play R2/MF backward signal tone r2_playbsig( ) play R2/MF backward signal tone Name: int r2_playbsig(chdev, backwardsig, forwardsig, mode) Inputs: int chdev • channel device handle int backwardsig • group A/B backward signal int forwardsig • group I/II forward signal int mode • asynchronous/synchronous Returns: 0 if success error return code Includes: srllib.h dxxxlib.
play R2/MF backward signal tone — r2_playbsig( ) Parameter forwardsig Description SIGA_3 SIGB_3 103 SIGA_4 SIGB_4 104 SIGA_5 SIGB_5 105 SIGA_6 SIGB_6 106 SIGA_7 SIGB_7 107 SIGA_8 SIGB_8 108 SIGA_9 SIGB_9 109 SIGA_10 SIGB_10 110 SIGA_11 SIGB_11 111 SIGA_12 SIGB_12 112 SIGA_13 SIGB_13 113 SIGA_14 SIGB_14 114 SIGA_15 SIGB_15 115 specifies the name of the Group I or Group II forward signal for which a tone-on event was detected, and for which a tone-off event will termi
r2_playbsig( ) — play R2/MF backward signal tone ! 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.
play R2/MF backward signal tone — r2_playbsig( ) /* * Continue Processing * . * . * . * * Detect an incoming call using dx_wtring() * * Enable the detection of all forward signals using * dx_enbtone(). In this example, only the first * forward signal will be enabled.
r2_playbsig( ) — play R2/MF backward signal tone 470 Voice API for Windows Operating Systems Library Reference — November 2003
3 Events 3. This chapter provides information on events that may be returned by the voice software. The following topics are discussed: • Overview of Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471 • Termination Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471 • Unsolicited Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Events The following termination events may be returned by the voice library: TDX_CACHEPROMPT Termination event. Indicates that downloading a cached prompt using dx_cacheprompt( ) completed. TDX_CALLP Termination event. Returned by dx_dial( ) to indicate that dialing with call progress analysis completed. Use ATDX_CPTERM( ) to determine the reason for termination. TDX_CST Termination event. Specifies a call status transition (CST) event. See Section 3.
Events TDX_RECORD Termination event. Returned by record functions such as dx_rec( ) to indicate completion of record. TDX_RXDATA Termination event. Returned by dx_RxIottData( ) and dx_TxRxIottData( ) to indicate completion of ADSI two-way FSK data reception. TDX_SETHOOK Termination event. Returned by dx_sethook( ) to indicate completion of this function in asynchronous mode.
Events The dx_setevtmsk( ) function enables detection of CST events. User-defined tones are CST events, but detection for these events is enabled using dx_addtone( ) or dx_enbtone( ). The dx_getevt( ) function retrieves CST events in a synchronous environment. Events are returned to DX_EBLK, on page 506. To retrieve CST events in an asynchronous environment, use the Standard Runtime Library (SRL) Event Management functions such as sr_getevtdatap( ). Events are returned to the DX_CST structure.
Events DE_LCON Call status transition event. Indicates loop current on. DE_LCREV Call status transition event. Indicates loop current reversal. DE_RINGS Call status transition event. Indicates rings received. DE_RNGOFF Call status transition event. Specifies ring off event. DE_SILOFF Call status transition event. Indicates non-silence detected on the channel. DE_SILON Call status transition event. Indicates silence detected on the channel. DE_STOPGETEVT Call status transition event.
Events 476 Voice API for Windows Operating Systems Library Reference — November 2003
Data Structures 4. 4 This chapter provides an alphabetical reference to the data structures used by voice library functions. The following data structures are discussed: • ADSI_XFERSTRUC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478 • CT_DEVINFO. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479 • DV_DIGIT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ADSI_XFERSTRUC — ADSI 2-way FSK data transfer buffer ADSI_XFERSTRUC ADSI 2-way FSK data transfer buffer typedef struct_ADSI_XFERSTRUC { UINT cbSize; DWORD dwTxDataMode; DWORD dxRxDataMode; } ADSI_XFERSTRUC; ! Description The ADSI_XFERSTRUC data structure stores information for the reception and transmission of Analog Display Services Interface (ADSI) 2-way frequency shift keying (FSK) data. This structure is used by the dx_RxIottData( ), dx_TxIottData( ), and dx_TxRxIottData( ) functions.
channel/time slot device information — CT_DEVINFO CT_DEVINFO channel/time slot device information typedef struct ct_devinfo { unsigned long ct_prodid; /* product ID */ unsigned char ct_devfamily; /* device family */ unsigned char ct_devmode; /* device mode */ unsigned char ct_nettype; /* network interface */ unsigned char ct_busmode; /* bus architecture */ unsigned char ct_busencoding; /* bus encoding */ union { unsigned char ct_RFU[7]; /* reserved */ struct { unsigned char ct_prottype; } ct_net_devinfo; }
CT_DEVINFO — channel/time slot device information • CT_IPT – IP connectivity • CT_NTANALOG – analog interface. Analog and voice devices on board are handling call processing CT_NTT1 – T-1 digital network interface CT_NTE1 – E-1 digital network interface CT_NTMSI – MSI/SC station interface CT_NTHIZ – high impedance (HiZ) interface. This value is bitwise-ORed with the type of network interface. A digital HiZ T-1 board would return CT_NTHIZ | CT_NTT1. A digital HiZ E-1 board would return CT_NTHIZ | CT_NTE1.
channel/time slot device information — CT_DEVINFO Springware Boards On Springware boards, the fields of the CT_DEVINFO data structure are described as follows: ct_prodid Contains a valid product identification number for the device [length: 4 (unsigned long)]. ct_devfamily Specifies the device family [length: 1 (unsigned char)].
CT_DEVINFO — channel/time slot device information ct_ext_devinfo.ct_net_devinfo.ct_prottype Contains information about the protocol used on the specified digital network interface device. Possible values are: • CT_CAS – channel associated signaling • CT_CLEAR – clear channel signaling • CT_ISDN – ISDN • CT_R2MF – R2/MF signaling ! Example For an example of how to use the CT_DEVINFO structure, see the Example section for dx_getctinfo( ).
user digit buffer — DV_DIGIT DV_DIGIT user digit buffer typedef struct DV_DIGIT { char dg_value[DG_MAXDIGS +1]; char dg_type[DG_MAXDIGS +1]; } DV_DIGIT; /* ASCII values of digits */ /* Type of digits */ ! Description The DV_DIGIT data structure stores an array of digits.When a dx_getdig( ) is performed, the digits are collected from the firmware and transferred to the user’s digit buffer. The digits are stored as an array inside the DV_DIGIT structure. The DG_MAXDIGS define in dxxxlib.
DV_DIGIT — user digit buffer ! Example For an example of how to use this data structure, see the Example section for dx_getdig( ).
termination parameter table — DV_TPT DV_TPT termination parameter table typedef struct unsigned unsigned unsigned unsigned unsigned unsigned DV_TPT DV_TPT { short tp_type; short tp_termno; short tp_length; short tp_flags; short tp_data; short rfu; *tp_nextp; /* /* /* /* /* /* /* * Flags describing this entry */ Termination Parameter number */ Length of terminator */ Parameter attribute flag */ Optional additional data */ Reserved */ Pointer to next termination parameter if IO_LINK set */ }DV_TPT; ! De
DV_TPT — termination parameter table • DX_MAXNOSIL – maximum length of non-silence. The range is 10 msec to 250 sec (25000 in 10 msec units). • DX_MAXSIL – maximum length of silence. The range is 10 msec to 250 sec (25000 in 10 msec units). • DX_MAXTIME – maximum function time. On DM3 boards, this termination condition is not supported by tone generation functions such as dx_playtone( ) and dx_playtoneEx( ).
termination parameter table — DV_TPT • digit type description – Applies when using DX_DIGTYPE, which specifies termination on a user-specified digit. Specify the digit type in the high byte and the ASCII digit value in the low byte. See the global tone detection topic in the Voice API Programming Guide for information. • digit bit mask – Applies to DX_DIGMASK, which specifies a bit mask of digits to terminate on.
DV_TPT — termination parameter table • • • • • the table later in this section to see which termination conditions can be edge-sensitive and which can be level-sensitive. This bit has no effect on DM3 boards and will be ignored. TF_FIRST – This bit is only used for DX_IDDTIME termination. If set, start looking for termination condition (interdigit delay) to be satisfied after first digit is received. TF_IMMEDIATE – This bit is only used for DX_MAXSIL and DX_MAXNOSIL termination.
termination parameter table — DV_TPT Notes: 1. The TF_SETINIT termination flag cannot be used with RM_TONE record mode on Springware boards with analog front-ends. 2. DX_PMOFF does not have a default tp_flags value. The tp_flags value for DX_PMOFF is set in tp_length. See the tp_length field description and also the Example section for more information. 3. If you specify TF_IDDTIME in tp_flags, then you must specify DX_IDDTIME in tp_termno.
DV_TPT — termination parameter table • If tp_termno contains DX_PMON, tp_data can specify the maximum time of silence on. • If tp_termno contains DX_TONEOFF, tp_data can specify termination after a tone-off event. • If tp_termno contains DX_TONEON, tp_data can specify termination after a tone-on event. tp_nextp Points to the next DV_TPT structure in a linked list if the tp_type field is set to IO_LINK. Table 16 indicates how DV_TPT fields should be filled.
termination parameter table — DV_TPT Table 16.
DV_TPT — termination parameter table ! Example This section provides an example of how to use DX_PMOFF and DX_PMON. The DX_PMOFF and DX_PMON termination conditions must be used in tandem. The DX_PMON termination condition must directly follow the DX_PMOFF termination condition. Each condition is specified in a DV_TPT structure. A combination of both DV_TPT structures is used to form a single termination condition. In the first block of the example code below, tp_termno is set to DX_PMOFF.
Syntellect License Automated Attendant — DX_ATTENDANT DX_ATTENDANT Syntellect License Automated Attendant typedef int (*PWAITFUNC)(int dev, BOOL *bWaiting); typedef int (*PFUNC)(int dev); typedef BOOL (*PMAPFUNC) (char *, char *); typedef struct { int nSize; char szDevName[15]; PFUNC pfnDisconnectCall; PWAITFUNC pfnWaitForRings; PFUNC pfnAnswerCall; PMAPFUNC pfnExtensionMap; char szEventName[MAX_PATH+1]; int nExtensionLength; int nTimeOut; // in seconds int nDialStringLength; } DX_ATTENDANT, *PDX_ATTENDANT
DX_ATTENDANT — Syntellect License Automated Attendant a T-1 interface a function that manipulates the A and B bits can be used instead to answer a call. pfnExtensionMap Required. Specifies the address of a function that translates the extension digits as received for the caller to a digit string, representing the physical extension, to actually dial. For example, when a caller enters “0” (usually for operator) the extension for the operator may actually be “1500”. szEventName Required.
Syntellect License Automated Attendant — DX_ATTENDANT Voice API for Windows Operating Systems Library Reference — November 2003 495
DX_CAP — call progress analysis parameters DX_CAP call progress analysis parameters * DX_CAP * call progress analysis parameters */ typedef struct DX_CAP { unsigned short ca_nbrdna; unsigned short ca_stdely; unsigned short ca_cnosig; unsigned short ca_lcdly; unsigned short ca_lcdly1; unsigned short ca_hedge; unsigned short ca_cnosil; unsigned short ca_lo1tola; unsigned short ca_lo1tolb; unsigned short ca_lo2tola; unsigned short ca_lo2tolb; unsigned short ca_hi1tola; unsigned short ca_hi1tolb; unsigned shor
call progress analysis parameters — DX_CAP ! Description The DX_CAP data structure contains call progress analysis parameters. The DX_CAP structure modifies parameters that control frequency detection, cadence detection, loop current, positive voice detection (PVD), and positive answering machine detection (PAMD). The DX_CAP structure is used to modify call progress analysis channel parameters when using dx_dial( ).
DX_CAP — call progress analysis parameters ca_noanswer No Answer. Length of time to wait after first ringback before deciding that the call is not answered. Default: 3000 Units: 10 msec ca_pamd_failtime PAMD Fail Time. Maximum time to wait for positive answering machine detection or positive voice detection after a cadence break. Default: 400 Units: 10 msec ca_pamd_spdval PAMD Speed Value.
call progress analysis parameters — DX_CAP ca_hedge Hello Edge. The point at which a “connect” will be returned to the application (CPA) • 1 – Rising Edge (immediately when a connect is detected) • 2 – Falling Edge (after the end of the salutation) Length: 1 Default: 2 ca_cnosil Continuous Non-silence. The maximum length of the first or second period of non-silence allowed. If exceeded, a “no ringback” is returned. (CPA) Length: 2. Default: 650 Units: 10 msec ca_lo1tola Low 1 Tolerance Above.
DX_CAP — call progress analysis parameters ca_nsbusy Non-silence Busy. The number of non-silence periods in addition to nbrdna to wait before returning a “busy” (Basic CPA only) Length: 1 Default: 0 Negative values are valid ca_logltch Low Glitch. The maximum silence period to ignore. Used to help eliminate spurious silence intervals. (CPA) Length: 2 Default: 15 Units: 10 msec ca_higltch High Glitch. The maximum nonsilence period to ignore. Used to help eliminate spurious nonsilence intervals.
call progress analysis parameters — DX_CAP ca_nbrbeg Number Before Beginning. Number of non-silence periods before analysis begins (Basic CPA only) Length: 1 Default: 1 Units: rings ca_hi1ceil High 1 Ceiling. Maximum 2nd high duration for a retrain (Basic CPA only) Length: 2 Default: 78 Units: 10 msec ca_lo1ceil Low 1 Ceiling. Maximum 1st low duration for a retrain (Basic CPA only) Length: 2 Default: 58 Units: 10 msec ca_lowerfrq Lower Frequency.
DX_CAP — call progress analysis parameters ca_time2frq Time for 2nd Frequency. Minimum time for 2nd tone in an SIT to remain in bounds Default: 0 Units: 10 msec ca_mxtime2frq Maximum Time for 2nd Frequency. Maximum allowable time for 2nd tone in an SIT to be present Default: 0 Units: 10 msec ca_lower3frq Lower Bound for 3rd Frequency. Lower bound for 3rd tone in an SIT Default: 0 Units: Hz ca_upper3frq Upper Bound for 3rd Frequency.
call progress analysis parameters — DX_CAP • PAMD_FULL – Full evaluation of response • PAMD_QUICK – Quick look at connect circumstances (PerfectCall CPA only) • PAMD_ACCU – Recommended setting. Does the most accurate evaluation detecting live voice as accurately as PAMD_FULL but is more accurate than PAMD_FULL (although slightly slower) in detecting an answering machine. Use PAMD_ACCU when accuracy is more important than speed. Default: PAMD_FULL ca_pamd_qtemp PAMD Qualification Template.
DX_CST — call status transition (CST) information DX_CST call status transition (CST) information typedef struct DX_CST { unsigned short cst_event; unsigned short cst_data; } DX_CST; ! Description The DX_CST data structure contains parameters for call status transition. DX_CST contains call status transition information after an asynchronous TDX_CST termination or TDX_SETHOOK event occurs. Use Standard Runtime Library (SRL) Event Management function, sr_getevtdatap( ), to retrieve the structure.
call status transition (CST) information — DX_CST • DX_ONHOOK – N/A ! Example For an example of how to use the DX_CST structure, see the Example section for dx_sendevt( ) and dx_setevtmsk( ).
DX_EBLK — call status transition event block DX_EBLK call status transition event block typedef struct unsigned unsigned unsigned }DX_EBLK; DX_EBLK { short ev_event; short ev_data; char ev_rfu[12]; /* Event that occurred */ /* Event specific data */ /* Reserved for future use*/ ! Description The DX_EBLK data structure contains parameters for the Call Status Event Block. This structure is returned by dx_getevt( ) and indicates which call status transition event occurred.
call status transition event block — DX_EBLK • • • • DE_TONEON – user-specified tone ID for the tone-on event DE_WINK – (no data) DX_OFFHOOK – (no data) DX_ONHOOK – (no data) ! Example For an example of how to use the DX_EBLK structure, see the Example section for dx_getevt( ) and dx_setevtmsk( ).
DX_ECRCT — echo cancellation resource (ECR) characteristics DX_ECRCT echo cancellation resource (ECR) characteristics typedef struct dx_ecrct { int ct_length; unsigned char ct_NLPflag } DX_ECRCT; /* size of this structure */ /* ECR with NLP requested or not */ #define SIZE_OF_ECR_CT sizeof (DX_ECRCT) #define ECR_CT_ENABLE 0 #define ECR_CT_DISABLE 1 /* size of DX_ECRCT */ ! Description The DX_ECRCT data structure describes echo cancellation resource (ECR) characteristics.
input/output transfer table — DX_IOTT DX_IOTT input/output transfer table typedef struct unsigned unsigned int char * unsigned long int DX_IOTT DX_IOTT }DX_IOTT; dx_iott { short io_type; short rfu; io_fhandle; io_bufp; long io_offset; io_length; *io_nextp; *io_prevp; /* /* /* /* /* /* /* /* Transfer type */ Reserved */ File descriptor */ Pointer to base memory */ File/Buffer offset */ Length of data */ Pointer to next DX_IOTT if IO_LINK set */ (Optional) Pointer to previous DX_IOTT */ ! Description The
DX_IOTT — input/output transfer table • IO_UIO – nonstandard storage media data using the dx_setuio( ) function; must be ORed with IO_DEV Specify the structure linkage as follows: • IO_CONT – the next DX_IOTT structure is contiguous (default) • IO_LINK – the next DX_IOTT structure is part of a linked list • IO_EOT – this is the last DX_IOTT structure in the chain If no value is specified, IO_CONT is assumed.
input/output transfer table — DX_IOTT #include #include DX_IOTT iott[3]; /* first iott: voice data in a file with descriptor fd1*/ iott[0].io_fhandle = fd1; iott[0].io_offset = 0; iott[0].io_length = -1; iott[0].io_type = IO_DEV; /* second iott: voice data in a file with descriptor fd2 */ iott[1].io_fhandle = fd2; iott[1].io_offset = 0; iott[1].io_length = -1; iott[1].io_type = IO_DEV; /* third iott: voice data in a file with descriptor fd3 */ iott[2].io_fhandle = fd3; iott[2].
DX_STREAMSTAT — status of stream buffer DX_STREAMSTAT status of stream buffer typedef struct streamStat { unsigned int version; // version of the structure unsigned int bytesIn; // total number of bytes put into stream buffer unsigned int bytesOut; // total number of bytes sent to board unsigned int headPointer; // internal pointer to position in stream buffer unsigned int tailPointer; // internal pointer to position in stream buffer unsigned int currentState; // idle, streaming etc.
status of stream buffer — DX_STREAMSTAT numberOfBufferOverruns Represents the number of times the application tries to write the data into the buffer beyond the circular stream buffer limit. BufferSize Contains the total size of the circular stream buffer. spaceAvailable Specifies the space, in bytes, available in the circular stream buffer. highWaterMark Specifies the high point in the circular stream buffer used to signal an event.
DX_SVCB — speed and volume adjustment condition block DX_SVCB speed and volume adjustment condition block typedef struct DX_SVCB { unsigned short type; short adjsize; unsigned char digit; unsigned char digtype; } DX_SVCB; /* /* /* /* Bit Mask */ Adjustment Size */ ASCII digit value that causes the action */ Digit Type (e.g., 0 = DTMF) */ ! Description The DX_SVCB data structure contains parameters for the speed and volume adjustment condition block.
speed and volume adjustment condition block — DX_SVCB • SV_ABSPOS – Index Mode: Sets adjsize field to specify an absolute adjustment position (index) in the speed or volume modification table. The index value can be from -10 to +10, based on position 0, the origin, or center, of the table. Note: In the speed modification table, the default entries for index values -10 to -6 and +6 to +10 are -128 which represent a null-entry.
DX_SVCB — speed and volume adjustment condition block • SV_TOGORIGIN – sets the digit to toggle between the origin and the last modified speed or volume level (for example, between the -5 and 0 levels) • SV_CURORIGIN – resets the current speed or volume level to the origin (same effect as SV_ABSPOS with adjsize 0) • SV_CURLASTMOD – sets the current speed or volume to the last modified speed volume level (swaps the current and last-modified settings) • SV_RESETORIG – resets the current speed or volume to
speed and volume modification tables — DX_SVMT DX_SVMT speed and volume modification tables typedef struct DX_SVMT{ char decrease[10]; char origin; char increase[10]; } DX_SVMT; /* Ten Downward Steps */ /* Regular Speed or Volume */ /* Ten Upward Steps */ ! Description The DX_SVMT data structure contains parameters for the speed modification table and volume modification table.
DX_SVMT — speed and volume modification tables If you use dx_setsvmt( ) to customize the DX_SVMT, the changes are saved permanently. You can obtain the manufacturer’s original defaults by specifying SV_SETDEFAULT for the dx_setsvmt( ) function. ! Example For an example of how to use the DX_SVMT structure, see the Example section for dx_setsvmt( ).
user-defined input/output — DX_UIO DX_UIO user-defined input/output typedef struct DX_UIO { int (*u_read) ( ); int (*u_write) ( ); int (*u_seek) ( ); } DX_UIO; ! Description The DX_UIO data structure contains parameters for user-defined input/output. This structure, returned by dx_setuio( ), contains pointers to user-defined I/O functions for accessing non-standard storage devices.
DX_XPB — input/output transfer parameter block DX_XPB input/output transfer parameter block typedef struct { USHORT USHORT ULONG ULONG } DX_XPB; wFileFormat; wDataFormat; nSamplesPerSec; wBitsPerSample; // // // // file format audio data format sampling rate bits per sample ! Description The DX_XPB data structure contains parameters for the input/output transfer parameter block.
input/output transfer parameter block — DX_XPB • DATA_FORMAT_GSM610_MICROSOFT – GSM 6.10 full-rate coder (Microsoft Windows compatible format) (Microsoft Windows Media Recorder Audio Compression Codec: GSM 6.10 Audio CODEC) • DATA_FORMAT_GSM610_TIPHON – GSM 6.
DX_XPB — input/output transfer parameter block Table 18. G.721 Voice Coder Support Fields (DM3) DX_XPB Field DX_XPB Field Value wFileFormat FILE_FORMAT_WAV or FILE_FORMAT_VOX wDataFormat DATA_FORMAT_G721 nSamplesPerSec DRT_8KHZ wBitsPerSample 4 Note 32 kbps Table 19.
input/output transfer parameter block — DX_XPB Table 22. GSM Voice Coder Support Fields (DM3) DX_XPB Field wFileFormat DX_XPB Field Value FILE_FORMAT_WAV FILE_FORMAT_VOX wDataFormat Note WAVE format supported only with DATA_FORMAT_GSM 610_MICROSOFT DATA_FORMAT_GSM610_MICROSOFT DATA_FORMAT_GSM610_TIPHON nSamplesPerSec DRT_8KHZ wBitsPerSample 0 13 kbps Table 23.
DX_XPB — input/output transfer parameter block Table 26. GSM Voice Coder Support Fields (Springware) DX_XPB Field DX_XPB Field Value wFileFormat FILE_FORMAT_WAV wDataFormat DATA_FORMAT_GSM610_MICROSOFT Note DATA_FORMAT_GSM610_TIPHON nSamplesPerSec DRT_8KHZ wBitsPerSample 0 This field can be any numeric value; it is ignored. However, the recommended setting is 0.
feature information — FEATURE_TABLE FEATURE_TABLE feature information typedef struct feature_table { unsigned short ft_play; unsigned short ft_record; unsigned short ft_tone; unsigned short ft_e2p_brd_cfg; unsigned short ft_fax; unsigned short ft_front_end; unsigned short ft_misc; unsigned short ft_send; unsigned short ft_receive; unsigned int ft_play_ext; unsigned int ft_record_ext; unsigned short ft_device; unsigned short ft_rfu[8]; } FEATURE_TABLE; ! Description The FEATURE_TABLE data structure provide
FEATURE_TABLE — feature information • • • • • • • • • • • • • • • FT_ADPCM – supports ADPCM encoding FT_ADSI – supports Analog Display Services Interface (ADSI) FT_ALAW – supports A-law encoding FT_DRT6KHZ – supports 6 kHz sampling rate FT_DRT8KHZ – supports 8 kHz sampling rate FT_DRT11KHZ – supports 11 kHz sampling rate FT_FFT – FT_FSK_OH – FT_G729A – supports G.
feature information — FEATURE_TABLE • FT_ROUTEABLE – supports flexible routing configuration For fixed routing, the FT_ROUTEABLE is not set, so none of the other bits is set. For flexible routing, the FT_ROUTEABLE bit is set, and the other three bits are set based on cluster contents. For example, if the ft_front_end bitmask is FT_ROUTEABLE | FT_ISDN | FT_CAS, then the channel is capable of flexible routing and can also work with an ISDN or a CAS (T1) frontend.
FEATURE_TABLE — feature information • FT_RXLINEMMR – supports MMR encoded file format over the phone line • FT_RXECM – capable of fax line reception with error correction mode ft_play_ext Contains a bitmask of extended play features supported on the specified device. • FT_TRUSPEECH – supports TrueSpeech decoding (supported on DM3 boards only) ft_record_ext Contains a bitmask of extended record features supported on the specified device.
TDM bus time slot information — SC_TSINFO SC_TSINFO TDM bus time slot information typedef struct { unsigned long long } SC_TSINFO; sc_numts; *sc_tsarrayp; ! Description The SC_TSINFO data structure contains the number of time division multiplexing (TDM) bus time slots associated with a particular device and a pointer to an array that holds the actual TDM bus time slot number(s).
TN_GEN — tone generation template TN_GEN tone generation template typedef struct unsigned unsigned unsigned short short short { short tg_dflag; short tg_freq1; short tg_freq2; tg_ampl1; tg_ampl2; tg_dur; /* /* /* /* /* /* /* Dual Tone - 1, Single Tone - 0 Frequency for Tone 1 (HZ) Frequency for Tone 2 (HZ) Amplitude for Tone 1 (dB) Amplitude for Tone 2 (dB) Duration of the Generated Tone Units = 10 msec */ */ */ */ */ */ */ } TN_GEN; ! Description The TN_GEN data structure contains parameters for the
cadenced tone generation template — TN_GENCAD TN_GENCAD cadenced tone generation template typedef struct { unsigned char cycles; unsigned char numsegs; short offtime[4]; TN_GEN } TN_GENCAD; tone[4]; /* /* /* /* /* Number of cycles Number of tones Array of off-times one for each tone Array of tone templates */ */ */ */ */ ! Description The TN_GENCAD data structure contains parameters for the cadenced tone generation template.
TN_GENCAD — cadenced tone generation template tone[4] The tone[ ] array contains four elements that specify TN_GEN single- or dual-tone definitions (frequency, amplitude, & duration). The tone[ ] element is ignored if the segment is not specified in numsegs. The dx_bldtngen( ) function can be used to set up the TN_GEN tone[ ] elements. At least one tone definition, tone[0], is required for each segment used, and you must specify a valid frequency (tg_freq1); otherwise an EDX_FREQGEN error is produced.
tone information — TONE_DATA TONE_DATA tone information typedef struct { unsigned unsigned unsigned unsigned unsigned unsigned unsigned unsigned unsigned unsigned unsigned unsigned } TONE_SEG; int structver; short tn_dflag; short tn1_min; short tn1_max; short tn2_min; short tn2_max; short tn_twinmin; short tn_twinmax; short tnon_min; short tnon_max; short tnoff_min; short tnoff_max; typedef struct { unsigned int structver; unsigned short tn_rep_cnt; unsigned int numofseg; TONE_SEG toneseg[6]; } TONE_DATA
TONE_DATA — tone information TONE_SEG.tn2_max Specifies the maximum frequency in Hz for tone 2. TONE_SEG.tn_twinmin Specifies the minimum frequency in Hz of the single tone proxy for the dual tone. TONE_SEG.tn_twinmax Specifies the maximum frequency in Hz of the single tone proxy for the dual tone. TONE_SEG.tnon_min Specifies the debounce minimum ON time in 10 msec units. TONE_SEG.tnon_max Specifies the debounce maximum ON time in 10 msec units. TONE_SEG.
Error Codes 5. 5 This chapter lists the error codes that may be returned for the voice library functions. If a library function fails, use the standard attribute function ATDV_LASTERR( ) to return the error code and ATDV_ERRMSGP( ) to return the error description. These functions are described in the Standard Runtime Library API Library Reference.
Error Codes EDX_CLIDBLK Caller ID is blocked, or private, or withheld (other information may be available using dx_gtextcallid( )) EDX_CLIDINFO Caller ID information is not sent or caller ID information invalid EDX_CLIDOOA Caller ID is out of area (other information may be available using dx_gtextcallid( )) EDX_DIGTYPE Invalid dg_type value in user digit buffer, DV_DIGIT data structure EDX_FEATUREDISABLED Feature disabled EDX_FLAGGEN Invalid tg_dflag field in tone generation template, TN_GEN data structure
Error Codes 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_BADCLTS Invalid channel number EDX_SH_BADMODE Function is not supported in current bus configuration EDX_SH_BADTYPE Invalid channel type (voice, analog, etc.
Error Codes EDX_UNSUPPORTED Function is not supported EDX_WTRINGSTOP Wait-for-Rings stopped by user EDX_XBPARM Bad XPB structure 538 Voice API for Windows Operating Systems Library Reference — November 2003
Supplementary Reference Information 6. 6 This chapter provides reference information on the following topics: • DTMF and MF Tone Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539 • DTMF and MF Detection Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 540 6.1 DTMF and MF Tone Specifications Table 27 provides information on DTMF specifications. Table 28 provides information on MF tone specifications. Table 27.
Supplementary Reference Information Table 28.
Supplementary Reference Information Table 29. Detecting MF Digits MF Digit Sent String Received Only MF Detection Enabled Only DTMF Detection Enabled MF and DTMF Detection Enabled 1 1 1 2 2 2 3 3 4 4 5 5 6 6 3 2 * 4,2* 5 6 3 * 7,3* 7 7 8 8 8 9 9 9 0 0 0 * * * # # # a a a b b b c c c * = detection error Table 30.
Supplementary Reference Information Table 30.
Glossary A-law: Pulse Code Modulation (PCM) algorithm used in digitizing telephone audio signals in E-1 areas. See also mu-law. ADPCM (Adaptive Differential Pulse Code Modulation): A sophisticated compression algorithm for digitizing audio that stores the differences between successive samples rather than the absolute value of each sample. This method of digitization reduces storage requirements from 64 kilobits/second to as low as 24 kilobits/second.
board locator technology (BLT): Operates in conjunction with a rotary switch to determine and set nonconflicting slot and IRQ interrupt-level parameters, thus eliminating the need to set confusing jumpers or DIP switches. buffer: A block of memory or temporary storage device that holds data until it can be processed. It is used to compensate for the difference in the rate of the flow of information (or time occurrence of events) when transmitting data from one device to another.
network.
download: The process where board level program instructions and routines are loaded during board initialization to a reserved section of shared RAM. downloadable Springware firmware: Software features loaded to Intel® voice hardware. Features include voice recording and playback, enhanced voice coding, tone detection, tone generation, dialing, call progress analysis, voice detection, answering machine detection, speed control, volume control, ADSI support, automatic gain control, and silence detection.
G.726: An international standard for encoding 8 kHz sampled audio signals for transmission over 16, 24, 32 and 40 kbps channels. The G.726 standard specifies an adaptive differential pulse code modulation (ADPCM) system for coding and decoding samples. GSM: A speech compression algorithm developed for the Global System for Mobile telecommunication (GSM), Europe’s popular protocol suite for digital cellular communication.
on-hook: Condition or state of a telephone line when a handset on the line is returned to its cradle (or an equivalent condition occurs). See also hook state. PBX: Private Branch Exchange. A small version of the phone company’s larger central switching office. A local premises or campus switch. PCM (Pulse Code Modulation): A technique used in DSP voice boards for reducing voice data storage requirements.
silence threshold: The level that sets whether incoming data to the voice board is recognized as silence or nonsilence. SIT: (1) Standard Information Tones: tones sent out by a central office to indicate that the dialed call has been answered by the distant phone. (2) Special Information Tones: detection of a SIT sequence indicates an operator intercept or other problem in completing the call. solicited event: An expected event. It is specified using one of the device library’s asynchronous functions.
TDM bus: Time division multiplexing bus. A resource sharing bus such as the SCbus or CT Bus that allows information to be transmitted and received among resources over multiple data lines. termination condition: An event or condition which, when present, causes a process to stop. termination event: An event that is generated when an asynchronous function terminates. See also asynchronous function. time division multiplexing (TDM): See TDM (Time Division Multiplexing).
Index A ACLIP message types 265 adjusting speed and volume explicitly 133 using conditions 401 using digits 401 adjustment conditions digits 402 maximum number 402 setting 401 ADPCM 300, 337 ADSI 20 functions 20 two-way 426 ADSI_XFERSTRUC data structure 478 ag_getctinfo( ) 36 ag_getxmitslot( ) 38 ag_listen( ) 41 ag_unlisten( ) 44 AGC 337 ai_close( ) 46 ai_getxmitslot( ) 48 ai_open( ) 50 A-law 300, 520 alowmax 500 analog devices connecting to time slot 41 disconnecting from TDM bus 44 get time slot number 38
base memory address 510 beep tone record notification 399 beep tone, pre-record 409 bits per sample 521 blowmax 500 board device 76, 292 device name 54 parameters 389, 390, 391, 393 setting 54 physical address 103 board device handle 60 opening 292 breaking connection to a time slot 431 buffer firmware digit 173 buffer size bulk queue 367 buffer, ADSI data 478 busy channel forcing to idle state 417 C ca_dtn_deboff 502 ca_dtn_npres 502 ca_dtn_pres 502 ca_lowerfrq 93 ca_maxintering 503 ca_noanswer 498, 503 c
call status transition event functions 21 dx_getevt( ) 234 dx_setevtmsk( ) 377 call status transition structure 504 caller ID common message types 263 caller ID functions 26 dx_gtcallid( ) 258 dx_gtextcallid( ) 262 dx_wtcallid( ) 440 channel bulk queue buffer sizing function 367 current state 109 device 76, 292 digit buffer 226 monitoring activity 99 names 60 number 62 number of processes 234 parameters 391, 393 status dial 109 DTMF signal 99 get digit 109 idle 109 no loop current 99 no ringback 99 onhook 9
CS_GTDIG 109 CS_HOOK 109 CS_IDLE 109 CS_PLAY 109 CS_RECD 109 CS_RECVFAX 110 CS_SENDFAX 110 CS_STOPD 109 CS_TONE 109 CS_WINK 110 CSP 26 cst_data 504 cst_event 504 CT bus references to 22 CT_DEVINFO data structure 36, 221, 479 current parameter settings 242 cycles 531 D D_APD 374 D_DPD 374 D_DPDZ 374 D_DTMF 374 D_MF 374 data formats 520 data structure user digit buffer 483 data structures cadenced tone generation template 531 call progress analysis parameters 497 call status transition 504 clearing 27 echo c
dialing ASCIIZ string 188 asynchronous 189, 191 DTMF 190, 191 enabling call progress analysis 189 flash 190, 191 flash character 191 MF 190, 191 pause 190, 191 pause character 191 pulse 190, 191 specifying dial string 188, 190 stopping 193 synchronous 189, 191 synchronous termination 191 termination events TDX_CALLP 191, 472 TDX_DIAL 191, 472 with call progress analysis 189, 191 digit buffer 226, 227 flushing 173 digit buffer, user 483 digit collection 226 asynchronous 227 DTMF digits 226 MF digits 226 sync
dx_clrsvcond( ) 175, 401 dx_clrtpt( ) 177 dx_createtone( ) 179 DX_CST data structure 504 hook state terminations 385 dx_deltones( ) 186 dx_dial( ) 52, 112, 171, 194, 417 dx_distone( ) 124, 197 DX_EBLK data structure 234, 506 DX_ECRCT data structure 508 dx_enbtone( ) 124, 200 dx_fileclose( ) 203 dx_fileerrno( ) 205 dx_fileopen( ) 208 dx_fileread( ) 210 dx_fileseek( ) 213 dx_filewrite( ) 216 dx_getcachesize( ) 219 dx_getctinfo( ) 221 dx_getcursv( ) 223 dx_getdig( ) 58, 173, 226, 483 dx_GetDllVersion( ) 232 dx
DX_XPB data structure 520 examples (DM3) 521 examples (Springware) 523 DXBD_R_ON 378 DXCH_PLAYDRATE 301 DXCH_RECRDRATE 337 dxxxlib.
flash character 191 flexible routing configuration bitmask 527 flushing digit buffer 173 forward signal specifying 462 FSK two-way 426 full-duplex connection 41, 451, 457 functions ADSI 20 ATDX_ 27 cached prompt management 21 call progress analysis 25 call status transition Event 21 caller ID 26 configuration 16 device management 15 extended attribute 27 global tone detection 23 global tone generation 23 I/O 17 I/O convenience 19 R2/MF convenience 24 speed and volume 24 speed and volume convenience 24 struc
I I/O function 111 transfer parameter block structure 520 transfer table 509 user-defined structure for 519 I/O convenience functions 19 I/O functions 17 dx_dial( ) 188 dx_getdig( ) 226 dx_mreciottdata( ) 286 dx_play( ) 299 dx_playiottdata( ) 310 dx_rec( ) 336 dx_reciottdata( ) 347 dx_RxIottData( ) 361 dx_setdigbuf( ) 372 dx_stopch( ) 417 dx_TxIottData( ) 423 dx_TxRxIottData( ) 426 dx_wink( ) 436 IMA ADPCM voice coder 521 inter-process event communication 365 intflg 497, 500 io_bufp 510 IO_CACHED 509 IO_CON
play mu-law 520 mxtime2frq 502 mxtime3frq 502 mxtimefrq 501 N names board device 54 nbrbeg 501 nbrdna 498 non-standard I/O devices dx_setdevuio( ) 369 dx_setuio( ) 412 nr_scroute( ) 451 nr_scunroute( ) 457 nsbusy 500 numsegs 531 O offset 510 offtime 531 off-hook 97 off-hook state 384 OKI ADPCM voice coder 520 on-hook 97 on-hook state 384 open( ) function 293 opening devices 50, 292 operator intercept 81 P parameter settings getting current 242 parameters board and channel 389, 391, 393, 395 call progres
processes per channel 234 Pulse Code Modulation 300, 337 R R2/MF compelled signaling 466 convenience functions 24 enabling signal detection 462 playing backward signal 466 specifying forward signal 462 user-defined tone IDs 462, 463 R2/MF convenience functions 24 r2_creatfsig( ) 462 r2_playbsig( ) 466 r2_creatfsig( ) 462 r2_playbsig( ) 466 record notification beep tone 399 recording algorithm 337 asynchronous 338 asynchronous termination event TDX_RECORD 338 bytes transferred 118 convenience function 343 d
speed and volume convenience functions dx_addspddig( ) 120 dx_addvoldig( ) 129 speed and volume function dx_setsvmt( ) 405 speed and volume functions 24 dx_adjsv( ) 133 dx_clrsvcond( ) 175 dx_getcursv( ) 223 dx_getsvmt( ) 249 dx_setsvcond( ) 401 speed and volume modification table resetting to defaults 405, 406 retrieving contents 249 specifying speed 405 specifying volume 405 updating 405 speed control 517 sr_getevtdatap( ) 379 stop I/O functions dial 417 termination reason TM_USRSTOP 417 wink 418 stopping
TDX_RXDATA event 428, 473 TDX_SETHOOK 506 TDX_SETHOOK event 385, 473, 504 TDX_TXDATA event 428, 473 TDX_UNDERRUN event 473 TDX_WINK event 473 termination call progress analysis 70 stop I/O function 417 synchronous record 339 termination conditions 17 termination events 471 DX_CST data structure 385 TDX_SETHOOK 385 TDX_WINK 436 termination parameter table structure 485 terminations asynchronous play 301 ATDX_TERMMSK( ) 111 end of data 111, 112, 361, 423, 428 function stopped 112, 362, 423, 428 I/O device err
user-defined digits collection 226 user-defined functions installing 369, 412 user-defined input/output data structure 519 user-defined Tone ID R2/MF 462 user-defined tone ID 115 user-defined tones 124 cadence repetition 140 disabling detection 197 dual frequency 136 dual frequency cadence 139 enabling detection 200 first frequency 136 first frequency deviation 136 ID 136 leading or trailing edge notification 136 playing 319 also see playing tone 315 removing 186 second frequency 136 second frequency deviat
