EZTapiAPI Functions

LONG EZTapiInitialize(EZAppType appType, DWORD *pdwNumEZLineDev, EZ_CALLBACK *pCallback, void *pUserInfo)

Parameters:

appType – Client application type. Should be set to EZ_CONSOLE, or EZ_WINDOWS.

pdwNumEZLineDev – Pointer to a DWORD that will be set to the number of discovered EZLine devices.

pCallback – Pointer to a user implemented callback function to receive asynchronous events from the EZTapiAPI engine. This parameter can be set to NULL if all EZTapiAPI functions are called with EZCallType set to EZ_SYNC.

pUserInfo – Void pointer to user defined data. Should be set to NULL if pCallback is NULL.

EZTapiInitialize is called to initialize the EZTapiAPI engine. During initialization a search of the computer system is performed to discover all EZLine devices that can then be opened and controlled using the EZTapiAPI SDK.

The parameter appType should be set to EZ_CONSOLE, or EZ_WINDOWS. If the client application provides a Windows Message Pump for retrieving Windows Messages then appType can be set to EZ_WINDOWS. If the client application does not have a separate thread to process Windows Messages then EZ_CONSOLE should be specified. When specifying EZ_CONSOLE, the client application must be compiled with Microsoft’s TAPI API version 2.0 or greater.

The second parameter pdwNumEZLineDev will be initialized by the EZTapiAPI engine and will hold the total number of EZLine devices discovered in the computer system. EZLine device ids are zero based. When calling other EZTapiAPI functions to open or otherwise control an EZLine device, the EZLine device id should be specified as a value from 0 to (dwNumEZLineDev – 1).

The third parameter pCallback should point to a user defined EZ_CALLBACK function that has been implemented in the client application. A valid pointer must be specified if any EZTapiAPI functions will be called asynchronously. This callback function receives completion events from the EZTapiAPI engine for EZTapiAPI functions that are alled asynchronously. In addition to completion events for asynchronous function calls, the EZTapiAPI engine sends EZ_EVENT messages to signal dynamic events observed on open EZLine devices. If all other EZTapiAPI functions are called synchronously then this parameter may be set to NULL.

The last parameter to EZTapiInitialize is a pointer to user-defined data type. This value will be passed back to the client application as the last parameter of the user defined callback function pCallback when EZ_EVENTS are reported.

This function runs synchronously and has no asynchronous equivalent.

If this function call is successful the return value is EZ_SUCCESS. Otherwise the return value is negative. Possible return values include: EZ_PARAM_ERROR, EZ_MEMORY_ERROR, EZ_TSP_ERROR, EZ_TAPIVERSION_ERROR, and EZ_EVENTMGMT_ERROR.

none

LONG VBVBEZTapiInitialize(DWORD *pdwNumEZLineDev, HWND hWnd)

Parameters:

pdwNumEZLineDev – Pointer to a DWORD that will be set to the number of discovered EZLine devices.

hWnd – A handle to a VB Form. The EZTapiAPI engine will post EZTapiAPI event messages back to the VB Client application in response to asynchronous function calls. This parameter can be set to NULL if all EZTapiAPI functions are called with EZCallType set to EZ_SYNC.

VBEZTapiInitialize is called to initialize the EZTapiAPI engine. During initialization a search of the computer system is performed to discover all EZLine devices that can then be opened and controlled using the EZTapiAPI SDK. This function should be called by Visual Basic client applications as an alternative to the C client initialization call EZTapiInitialize.

The parameter pdwNumEZLineDev will be initialized by the EZTapiAPI SDK and will hold the total number of EZLine devices discovered in the computer system. EZLine device ids are zero based. When calling other EZTapiAPI functions to open or otherwise control an EZLine device, the EZLine device id should be specified as a value from 0 to (dwNumEZLineDev – 1).

The parameter hWnd should be set to the Window Handle of an active VB Form. A valid window handle must be specified if any EZTapiAPI functions will be called asynchronously. Completion events for EZTapiAPI functions called asynchronously are reported back to the calling client application through this Window Handle interface. The EZTapiAPI engine will post messages back to the client application through this Window Handle interface, similar to the way native C applications receive completion events for asynchronous function calls through a user defined EZ_CALLBACK function (See EZTapiInitialize function call above.) The EZTapiAPI engine will also post EZ_EVENT messages to signal dynamic events observed on open EZLine devices. (See the VB Sample application for more information on using the EZTapiAPI in asynchronous mode.) This parameter can be set to NULL if all other EZTapiAPI functions are made as type EZ_SYNC.

This function runs synchronously and has no asynchronous equivalent.

If this function call is successful the return value is EZ_SUCCESS. Otherwise the return value is negative. Possible return values include: EZ_PARAM_ERROR, EZ_MEMORY_ERROR, EZ_TSP_ERROR, EZ_TAPIVERSION_ERROR, and EZ_EVENTMGMT_ERROR.

none

typedef VOID (__stdcall *EZ_CALLBACK) (EZLine aLine, EZ_EVENT EZEvent, VOID *pEventData, VOID pUsrData)

Parameters:

aLine – EZLine device on which the callback function is being signaled. 

EZEvent – The EZ_EVENT that caused the callback function to be signaled. 

pEventData – void pointer to additional data associated with the EZ_EVENT. 

pUsrData – void pointer to user defined data.

EZ_CALLBACK provides the definition for a callback function that needs to be defined and implemented by client EZTapiAPI application if other EZTapiAPI functions are to be called asynchronously.

The user defined and implemented EZ_CALLBACK will be called by the EZTapiAPI engine to report completion events for asynchronous function calls, as well as other EZ_EVENT messages to signal dynamic events observed on open EZLine devices. (Visual Basic client applications will use the VBEZTapiInitialize function to initialize the EZTapiAPI engine and will not need to define an EZ_CALLBACK function.)

The first parameter aLine is set to the EZLine device id on which the EZ_EVENT is being signaled.

The second parameter EZEvent is the actual EZ_EVENT that occurred on the EZLine device. If additional data is available for a particular EZ_EVENT it will be passed in the void pointer pEventData. For more information on EZ_EVENT values and associated data see Appendix A of this manual.

The value pUsrData is a pointer to any user-supplied data specified during initialization of the EZTapiAPI engine. It is the responsibility of the client application to make sure that this data does not go out of scope.

none

none

LONG EZTapiFree()

Parameters:

none

EZTapiFree is called to shut down the EZTapiAPI engine. This function closes all EZLine devices opened by the client application, and frees all EZTapiAPI resources. The client application should call this function before exiting.

If this function call is successful the return value is EZ_SUCCESS, otherwise the return value is negative. Possible return values include: EZ_RESOURCE_ERROR.

none

LONG EZOpenLine(EZLine aLine, EZCallPrivilege callPrivilege, EZModemType *pModemType)

Parameters:

aLine – EZLine device to be opened.

callPrivilege – EZCallPrivilege for the EZLine device. Should be set to EZ_OWNER or EZ_MONITOR.

pModemType – Pointer to an EZModemType value indicating if the modem was opened for voice or data operations. Will be set to either EZ_MODEMTYPE_VOICE, or EZ_MODEMTYPE_DATA.

The function EZLineOpen is called to open an EZLine device associated with a modem device configured in a computer system. Prior to calling EZLineOpen, the client application must first initialize the EZTapiAPI engine to discover all EZLine devices in the computer system. EZLine device ids are zero based. (See EZTapiInitialize for more information).

The parameter callPrivilege is used to specify the amount of control the application will have over the EZLine device being opened. If EZLineOpen is called with this parameter set to EZ_OWNER, the client application has complete control over the line and can issue further commands on that EZLine device. If EZLineOpen is called with callPrivilege set to EZ_MONITOR, the client application is not allowed direct control over the EZLine device and will merely receive status events for lines opened with this type of privilege.

The parameter pModemType will be initialized by the EZTapiAPI engine. It is used to indicate the type of operations allowed on the EZLine device. The EZTapiAPI SDK is a primarily a voice modem API, although limited support is available for data modems.

This function runs synchronously and has no asynchronous equivalent.

If this function call is successful the return value is EZ_SUCCESS. Otherwise the return value is negative. Possible return values include: EZ_TSP_ERROR, EZ_RESOURCE_ERROR, and EZ_PARAM_ERROR.

none

LONG EZCloseLine(EZLine aLine)

Parameters:

aLine – EZLine device to be closed.

The function EZCloseLine is called to close an EZLine device associated with a modem device configured in a computer system. The EZLine device must have been previously opened with a call to EZOpenLine. Additionally the EZLine device must be in the EZ_CALLSTATE_ONHOOK state in order to be closed. EZLine device ids are zero based. (See EZTapiInitialize for more information).

This function runs synchronously and has no asynchronous equivalent.

If this function call is successful the return value is EZ_SUCCESS. Otherwise the return value is negative. Possible return values include: EZ_PARAM_ERROR, EZ_CALLSTATE_ERROR, and EZ_RESOURCE_ERROR.

none

LONG EZWaitForCall(EZLine aLine, DWORD num_rings, EZCallInfo *pcallInfo)

Parameters:

aLine – EZLine device on which an incoming call is to be answered.

num_rings – Number of rings to wait before answering the incoming call. This value must be greater than 0.

pCallInfo – Pointer to an EZCallInfo structure that will contain caller id information if available for the incoming call.

The function EZWaitForCall is called to answer incoming phone calls on an EZLine device. The EZLine device specified by aLine must be in the EZ_CALLSTATE_ONHOOK state. EZWaitForCall will block and only return after an incoming call has been successfully answered or some error occurred.

The parameter num_rings is used to specify how many rings the EZLine device should receive before answering the incoming call.

The third parameter pCallInfo will hold caller id information for the incoming call if this service is provisioned on the phone line and supported by the underlying modem hardware.

This function runs synchronously and has no asynchronous equivalent.

If this function call is successful the return value is EZ_SUCCESS. Otherwise the return value is negative. Possible return values include: EZ_PARAM_ERROR, EZ_CALLSTATE_ERROR, EZ_RESOURCE_ERROR, and EZ_EVENTMGMT_ERROR.

none

LONG EZAnswerCall(EZLine aLine, EZCallType callType)

Parameters:

aLine – EZLine device on which an incoming call is to be answered.

callType – Function call type, should be set to EZ_SYNC, or EZ_ASYNC.

The function EZAnswerCall is called to answer an incoming call on an EZLine device. The EZLine device specified by aLine must be in the EZ_CALLSTATE_ONHOOK state.

Client applications would call this function in response to EZ_RING_EVENT messages being sent to a user defined EZ_CALLBACK function. The EZTapiAPI engine must be initialized with a valid pointer to a user defined EZ_CALLBACK function in order for the client application to be alerted to new incoming calls through EZ_RING_EVENT messages.

If EZAnswerCall is called with callType set to EZ_SYNC, the function will not return until it has completed and the call has been successfully answered or an error occurred. If EZAnswerCall is called with callType set to EZ_ASYNC, the function will return immediately to indicate whether or not the function was successfully started. The client application will be alerted to the overall success or failure of the function through the user defined EZ_CALLBACK function.

If this function call is successful the return value is EZ_SUCCESS. Otherwise the return value is negative. Possible return values include: EZ_PARAM_ERROR, EZ_CALLSTATE_ERROR, EZ_HANGUP_ERROR, EZ_RESOURCE_ERROR, and EZ_EVENTMGMT_ERROR.

EZ_CALLANSWER_EVENT, EZ_UNEXPECTED_EVENT

LONG EZMakeCall(EZLine aLine, char *szDialString, EZCallType callType)

Parameters:

aLine – EZLine device on which an outbound call is to be placed.

pszDialString – Pointer to a NULL terminated character string containing DTMF digits to be dialed.

callType – Function call type, should be set to EZ_SYNC, or EZ_ASYNC.

The function EZMakeCall is called to initiate a new phone call over an opened EZLine device. The EZLine device specified by aLine must be in the EZ_CALLSTATE_ONHOOK state.

The second parameter pszDialString is used to specify the phone number to be dialed.

If EZMakeCall is called with callType set to EZ_SYNC, the function will not return until it has completed and a new call has been successfully connected or an error occurred. If EZMakeCall is called with callType set to EZ_ASYNC, the function will return immediately to indicate whether or not the function was successfully started. The client application will be alerted to the overall success or failure of the function through the user defined EZ_CALLBACK function.

If this function call is successful the return value is EZ_SUCCESS. Otherwise the return value is negative. Possible return values include: EZ_PARAM_ERROR, EZ_CALLSTATE_ERROR, EZ_RESOURCE_ERROR, EZ_CALLNOANSWER_ERROR, EZ_CALLBUSY_ERROR, and EZ_EVENTMGMT_ERROR.

EZ_CALLCONNECT_EVENT, EZ_CALLBUSY_EVENT, EZ_CALLNOANSWER_EVENT, and EZ_UNEXPECTED_EVENT

LONG EZHangupCall(EZLine aLine)

Parameters:

aLine – The EZLine device to be placed on-hook.

The function EZHangupCall is called to put an EZLine device in the EZ_CALLSTATE_ONHOOK state. The EZLine device specified by aLine must be in the EZ_CALLSTATE_CONNECTED state.

This function runs synchronously and has no asynchronous equivalent.

If this function call is successful the return value is EZ_SUCCESS. Otherwise the return value is negative. Possible return values include: EZ_PARAM_ERROR, EZ_CALLSTATE_ERROR, EZ_RESOURCE_ERROR, and EZ_EVENTMGMT_ERROR.

none

LONG EZPlayPrompt(EZLine aLine, char *pszFileName, EZCallType callType)

Parameters:

aLine – EZLine device over which an audio prompt is to be played.

pszFileName – Pointer to a NULL terminated character string containing the name of the wave file to be played

callType – Function call type, should be set to EZ_SYNC, or EZ_ASYNC.

The function EZPlayPrompt is called to initiate playback of a voice prompt over an EZLine device that is currently connected in an active call. The EZLine device specified by aLine must be in the EZ_CALLSTATE_CONNECTED state.

The parameter pszFileName is used to specify the voice prompt to be played. This file should exist and be in wave file format.

If EZPlayPrompt is called with callType EZ_SYNC, the function will not return until playback has completed, playback is stopped, or some error has occurred. If EZPlayPrompt is called with callType set to EZ_ASYNC, the function will return immediately to indicate whether or not the function was successfully started. The client application will be alerted to the overall success or failure of the function through the user defined EZ_CALLBACK function.

By default, EZPlayPrompt will stop prompt playback when the EZTapiAPI engine recognizes a DTMF or Pulse digit. This skip-ahead feature is controlled by the EZTapiAPI system parameter EZ_DIGITSTOP_PARAM. Changing the value of this parameter via the EZSetParameter function can disable this behavior. See Appendix C for more information on EZ_PARAMETER system variables and their default settings.

If this function call is successful the return value is EZ_SUCCESS. Otherwise the return value is negative. Possible return values include: EZ_PARAM_ERROR, EZ_HANGUP_ERROR, EZ_CALLSTATE_ERROR, EZ_RESOURCE_ERROR, EZ_EVENTMGMT_ERROR, EZ_STOP_ERROR, EZ_FILENOTFOUND_ERROR, EZ_BADFORMAT_ERROR, and EZ_MEMORY_ERROR.

EZ_PLAYBEGIN_EVENT, EZ_PLAYSTOP_EVENT, EZ_PLAYEND_EVENT, and EZ_UNEXPECTED_EVENT

If EZPlayPrompt returns the error EZ_BADFORMAT_ERROR, this can mean one of two things: either the wave file to be played is corrupt, and cannot be properly read by the EZTapiAPI library, or the modem is not capable of playback of wave audio data in the current wave format. If file specified by filename is known to be in valid wave file format, and the EZ_BADFORMAT_ERROR is returned, the developer should try converting the prompt to a different wave file format. Most voice modems will accept 8 kHz, Mono, 16 (or 8) bit wave files for playback and recording.

LONG EZRecordPrompt(EZLine aLine, char *pszFileName, size_t bufferSize, EZWaveFormat *pWaveFmt, bool beep, EZCallType callType)

Parameters:

aLine – EZLine device over which the prompt is to be recorded.

pszFileName – Pointer to a NULL terminated character string containing the name that the wave file recording will be saved as. No .wav extension is required. May be set to NULL, or a NULL character string if EZTapiAPI engine is to generate a unique filename for the recording. (See below description for more information on this feature.)

bufferSize – The size of the character string buffer pointed to by pszFileName.

pWaveFmt – Pointer to an EZWaveFormat structure which defines the recording/sample rate information for wave recording.

beep – Boolean value which specifies whether a beep tone should be played before recording begins.

callType – Function call type, should be set to EZ_SYNC, or EZ_ASYNC.

The function EZRecordPrompt is called to record PCM voice data over an EZLine device that is currently connected in an active call. The EZLine device specified by aLine must be in the EZ_CALLSTATE_CONNECTED state.

The second parameter pszFileName is used to specify a name for the wave file recording. Although the developer does not need to include the “.wav” extension in the initial character string passed, the string buffer must be large enough to hold the four character “.wav” extension that will be appended to the character string pointer pszFileName by the EZTapiAPI engine.

If the client application specifies a pointer to a NULL terminated character string for the filename parameter, the EZTapiAPI engine saves the PCM voice data to a new unique file name based on the computer system data and time. The new file name will be copied to the filename pointer pszFileName and returned to the client application. If the client application wishes to pass a NULL terminated string to the EZTapiAPI, it is the responsibility of the client application to make sure that this character string is large enough to hold the file name created by the EZTapiAPI engine.

The parameter bufferSize should be set to the total size in memory of the character string buffer pszFileName.

The fourth parameter pWaveFmt is a pointer to an EZWaveFormat structure. This parameter is used to specify the audio format for the new wave recording. See Appendix D of this manual for more information on this structure.

The boolean parameter beep controls whether or not a short Beep Tone is to be played just before recording begins.

If EZRecordPrompt is called with callType EZ_SYNC, the function will not return until recording has completed, recording has been stopped, or some error has occured. If EZRecordPrompt is called with callType EZ_ASYNC, the function will return immediately to indicate whether or not the function was successfully started. The client application will be alerted to the overall success or failure of the function through the user defined EZ_CALLBACK function.

By default EZRecordPrompt will stop prompt recording when the EZTapiAPI engine recognizes a DTMF or Pulse digit. This skip-ahead feature is controlled by the EZTapiAPI system parameter EZ_DIGITSTOP_PARAM. This feature can be disabled using the EZSetParameter function. See Appendix C for more information on EZ_PARAMETER system variables and their default settings.

If this function call is successful the return value is EZ_SUCCESS. Otherwise the return value is negative. Possible return values include: EZ_PARAM_ERROR, EZ_HANGUP_ERROR, EZ_CALLSTATE_ERROR, EZ_RESOURCE_ERROR, EZ_BEEP_ERROR, EZ_STOP_ERROR, EZ_BADFORMAT_ERROR, and EZ_MEMORY_ERROR.

EZ_RECORDBEGIN_EVENT, EZ_RECORDSTOP_EVENT, EZ_RECORDEND_EVENT, and EZ_UNEXPECTED_EVENT

If EZRecordPrompt returns the error EZ_BADFORMAT_ERROR, this can mean one of two things: either the EZWaveFormat specified is invalid, or the modem is not capable of recording wave audio data in the specified wave format. If the EZWaveFormat specified by pWaveFmt is found to be valid, and EZ_BADFORMAT_ERROR is returned, the developer should try changing the value of EZWaveFormat to a different sample rate. Most voice modems will accept 8 kHz, Mono, 16 (or 8) bit wave files for playback and recording.

LONG EZStopPrompt(EZLine aLine)

Parameters:

aLine – EZLine device over which audio is being played or recorded.

The function EZStopPrompt is called to stop playback or recording of wave file data. The EZLine device specified by aLine must be in the EZ_CALLSTATE_PLAYMESSAGE or EZ_CALLSTATE_RECORDMESSAGE state.

This function runs synchronously and has no asynchronous equivalent.

If this function call is successful the return value is EZ_SUCCESS. Otherwise the return value is negative. Possible return values include: EZ_PARAM_ERROR, EZ_CALLSTATE_ERROR, EZ_RESOURCE_ERROR, and EZ_EVENTMGMT_ERROR.

none

LONG EZSendDigits(EZLine aLine, char *pszDigits, EZCallType callType)

Parameters:

aLine – EZLine device over which digits are to be sent.

pszDigits – Pointer to a NULL terminated character string containing digits to be dialed.

callType – Function call type, should be set to EZ_SYNC, or EZ_ASYNC.

The function EZSendDigits is called to generate DTMF or Pulse digits over an EZLine device that is currently connected in an active call. The EZLine device specified by aLine must be in the EZ_CALLSTATE_CONNECTED state.

The parameter pszDigits should contain the digits to be generated over the EZLine device. These must be valid digits that can be generated by the user modem. Valid digits include 0-9, #, *, ! (for hook-flash), and ‘,’ (comma for short delay).

If EZSendDigits is called with callType EZ_SYNC, the function will not return until it the digits have been successfully sent, or some error has occurred. If EZSendDigits is called with callType EZ_ASYNC, the function will return immediately to indicate whether or not the function was successfully started. The client application will be alerted to the overall success or failure of the function through the user defined EZ_CALLBACK function.

By default EZSendDigits will generate DTMF digits. This functionality can be controlled through the EZTapiAPI system parameter EZ_DIGITMODE_PARAM. The EZSetParameter function can be used to change the default digit generation type from DTMF to Pulse. See Appendix C for more information on EZ_PARAMETER system variables and their default settings.

If this function call is successful the return value is EZ_SUCCESS. Otherwise the return value is negative. Possible return values include: EZ_PARAM_ERROR, EZ_HANGUP_ERROR, EZ_CALLSTATE_ERROR, EZ_RESOURCE_ERROR, and EZ_EVENTMGMT_ERROR.

EZ_SENDDIGITBEGIN_EVENT, EZ_SENDDIGITSTOP_EVENT, EZ_SENDDIGITEND_EVENT, and EZ_UNEXPECTED_EVENT

LONG EZCollectDigits(EZLine aLine, char *pszDigitBuff, DWORD dwNumDigits, char *pszStopDigits, EZCallType callType)

Parameters:

aLine – EZLine device on which digit collection is to be performed.

pszDigitBuff – Pointer to a NULL terminated character string large enough to hold the total number of digits to be collected. This parameter can be set to NULL if function is called with callType EZ_ASYNC.

dwNumDigits – The total number of digits to collect. Must be greater than zero and less than or equal to EZ_DIGITBUFFERSIZE.

pszStopDigits – Pointer to a NULL terminated character string containing digits that will cause digit collection to terminate. This parameter should be set to NULL if stop digits are not used.

callType – Function call type, should be set to EZ_SYNC, or EZ_ASYNC.

The function EZCollectDigits is called to collect digits over an EZLine device that is currently connected in an active call. The EZLine device specified by aLine must be in the EZ_CALLSTATE_CONNECTED state.

The second parameter pszDigitBuff will contain the digits collected by the EZTapiAPI engine on function completion.

EZCollectDigits will terminate when the number of digits specified by dwNumDigits has been collected, when a digit matching an entry in the character string pszStopDigits is recognized, or a timeout occurs. If pszStopDigits is set to NULL, then no stop digits are valid for this function call, and the function will not return until the number of specified digits have been collected or a timeout occurs.

A timeout will occur if the no digit is collected within the time period specified by the system variable EZ_FIRSTDIGITTIMEOUT_PARAM, or if subsequent digits are not recognized within the time period specified by the system variable EZ_INTERDIGITTIMEOUT_PARAM. By default EZ_FIRSTDIGITTIMEOUT_PARAM is set to 10000 msec, and EZ_INTERDIGITTIMEOUT_PARAM is set to 8000 msec. These values can be modified via the EZSetParameter function. See Appendix C for more information on EZ_PARAMETER system variables and their default settings.

Each EZLine device maintains its own internal digit buffer of size EZ_DIGITBUFFERSIZE. It is the responsibility of the client application to clear this digit buffer between calls to EZCollectDigits. If the number of digits specified for digit collection already exist in the EZLine’s digit buffer then the function will return immediately with those digits previously collected.

If EZCollectDigits is called with callType EZ_SYNC, the function will not return until digit collection is complete, or some error occurs. If EZCollectDigits is called with callType EZ_ASYNC, the function will return immediately to indicate whether or not the function was successfully started. The client application will be alerted to the overall success or failure of the function through the user defined EZ_CALLBACK function.

By default EZSendDigits will collect DTMF digits. This functionality can be controlled through the EZTapiAPI system parameter EZ_DIGITMODE_PARAM. The EZSetParameter function can be used to change the default digit collection type from DTMF to Pulse. See Appendix C for more information on EZ_PARAMETER system variables and their default settings.

If this function call is successful the return value is EZ_SUCCESS. Otherwise the return value is negative. Possible return values include: EZ_PARAM_ERROR, EZ_HANGUP_ERROR, EZ_CALLSTATE_ERROR, EZ_RESOURCE_ERROR, EZ_EVENTMGMT_ERROR, EZ_MEMORY_ERROR, and EZ_TIMEOUT_ERROR.

EZ_COLLECTDIGITBEGIN_EVENT, EZ_COLLECTDIGITEND_EVENT, EZ_COLLECTDIGITSTOP_EVENT, EZ_DIGITTIMEOUT_EVENT, and EZ_UNEXPECTED_EVENT

If EZCollectDigits terminates due to a timeout, even though DTMF digits were sent to the EZLine device, the device may not be in the correct listening mode for digit collection. Calling the function EZPlayPrompt or EZRecordPrompt before attempting digit collection should correct this problem.

LONG EZFlushDigitBuffer(EZLine aLine)

Parameters:

aLine – EZLine device digit buffer to be cleared.

The function EZFlushDigitBuffer is called to clear the digit buffer associated with an EZLine device specified by the parameter aLine.

The EZTapiAPI engine maintains an internal digit buffer for all initialized EZLine devices. Recognized DTMF or Pulse digits are appended to this buffer whenever digits are recognized while digit monitoring is active.

Digit monitoring is active during calls to EZCollectDigits, and calls to EZPlayPrompt and EZRecordPrompt with EZTapiAPI system variable EZ_DIGITSTOP_PARAM set to 1.

This function runs synchronously and has no asynchronous equivalent.

If this function call is successful the return value is EZ_SUCCESS. Otherwise the return value is negative. Possible return values include: EZ_PARAM_ERROR, and EZ_MEMORY_ERROR.

none

LONG EZGetCallState(EZLine aLine)

Parameters:

aLine – EZLine obect being queried for its current EZ_CALLSTATE

The function EZGetCallState is called to retrieve EZ_CALLSTATE information for an EZLine device.

The parameter aLine is used to specify the EZLine device being queried for its current EZ_CALLSTATE.

This function runs synchronously and has no asynchronous equivalent.

If this function call is successful the return value is a valid EZ_CALLSTATE_ constant. Otherwise the return value is negative. Possible return values include: EZ_PARAM_ERROR.

none

LONG EZGetCallInfo(EZLine aLine, EZCallInfo *pCallInfo)

Parameters:

aLine – EZLine device being queried for EZCallInfo data.

pCallInfo – Pointer to an EZCallInfo structure to hold caller id information for an answered call.

The function EZGetCallInfo is called to retrieve EZCallInfo data for an incoming call. This service must be provisioned on the phone line and supported by the underlying modem hardware.

The parameter aLine is used to specify the EZLine device on which caller id information is being requested. If this function completes successfully, the parameter pCallInfo will point to an EZCallInfo structure that will hold the returned caller id information for the last incoming call received on the EZLine device.

This function runs synchronously and has no asynchronous equivalent.

If this function call is successful the return value is EZ_SUCCESS. Otherwise the return value is negative. Possible return values include: EZ_PARAM_ERROR.

none

LONG EZTestRecordFormat(EZLine aLine, EZWaveFormat *pstWaveFormat)

Parameters:

aLine – EZLine device being queried for the name of its last recorded wave file.

pstWaveFormat – Pointer to an EZWaveFormat structure being tested.

The function EZTestRecordFormat is called to test the audio capabilities of the voice modem connected to the EZLine device. The EZLine device specified by aLine must be in the EZ_CALLSTATE_CONNECTED state.

The parameter aLine is used to specify the voice modem via its connected EZLine device. The parameter pstEZWaveFormat is used to specify the wave file format being checked. See Appendix D of this manual for more information on the EZWaveFormat structure.

This function runs synchronously and has no asynchronous equivalent.

If the specified EZWaveFormat is supported by the voice modem device then the return value is EZ_SUCCESS. If the EZWaveFormat is not supported the return value is EZ_BADFORMAT_ERROR. Possible other return values include: EZ_PARAM_ERROR, and EZ_RESOURCE_ERROR.

none

LONG EZTestPlayFormat(EZLine aLine, EZWaveFormat *pstWaveFormat)

Parameters:

aLine – EZLine device being queried for the name of its last recorded wave file.

pstWaveFormat – Pointer to an EZWaveFormat structure being tested.

The function EZTestPlayFormat is called to test the audio capabilities of the voice modem connected to the EZLine device. The EZLine device specified by aLine must be in the EZ_CALLSTATE_CONNECTED state.

The parameter aLine is used to specify the voice modem via its connected EZLine device. The parameter pstEZWaveFormat is used to specify the wave file format being checked. See Appendix D of this manual for more information on the EZWaveFormat structure.

This function runs synchronously and has no asynchronous equivalent.

If the specified EZWaveFormat is supported by the voice modem device then the return value is EZ_SUCCESS. If the EZWaveFormat is not supported the return value is EZ_BADFORMAT_ERROR. Possible other return values include: EZ_PARAM_ERROR, and EZ_RESOURCE_ERROR.

none

LONG EZGetRecordPromptFileName(EZLine aLine, char *pszFileName)

Parameters:

aLine – EZLine device being queried for the name of its last recorded wave file.

pszFileName – Pointer to a NULL terminated character string to hold the name of the last recorded wave file.

The function EZGetRecordPromptFileName is called to retrieve the file name of the last recorded wave file on an EZLine device.

The parameter aLine is used to specify the EZLine device on which EZRecordPrompt has completed. If this function completes successfully, the parameter pszFileName will hold the name of the last recorded wave file on the EZLine device.

This function runs synchronously and has no asynchronous equivalent.

If this function call is successful the return value is EZ_SUCCESS. Otherwise the return value is negative. Possible return values include: EZ_PARAM_ERROR.

none

LONG EZGetCollectDigitsBuffer(EZLine aLine, char *pszBuffer)

Parameters:

aLine – EZLine device being queried for its digit buffer.

pszBuffer – Pointer to a NULL terminated character string to hold digits collected.

The function EZGetCollectDigitsBuffer is called to retrieve collected digits for an EZLine device.

The parameter aLine is used to specify the EZLine device on which digit monitoring was active. If this function completes successfully, the parameter pszBuffer will hold the collected digit buffer for the EZLine device.

Calling EZGetCollectDigitsBuffer will not clear the digit buffer for an EZLine. This is accomplished by calling EZFlushDigitBuffer.

This function runs synchronously and has no asynchronous equivalent.

If this function call is successful the return value is EZ_SUCCESS. Otherwise the return value is negative. Possible return values include: EZ_PARAM_ERROR.

none

LONG EZGetParameter(EZ_PARAMETER ezParam, DWORD *pdwValue)

Parameters:

ezParam – EZ_PARAMETER value to be retrieved.

pdwValue – Pointer to DWORD that is gets set to the current value of the specified EZ_PARAMETER.

The function EZGetTapiAPIParam is called to get the current setting for a specified EZ_PARAMETER. Supported EZ_PARAMETER(s) along with their default system values are listed in Appendix C of this manual.

This function runs synchronously and has no asynchronous equivalent.

If this function call is successful the return value is EZ_SUCCESS, otherwise the return value is negative. Possible return values include: EZ_PARAM_ERROR.

none

LONG EZSetParameter(EZ_PARAMETER ezParam, DWORD ezValue)

Parameters:

ezParam – EZ_PARAMETER to be set.

ezValue – Value that EZ_PARAMETER should be set to.

The function EZSetTapiAPIParam is used to change the setting for a specified EZ_PARAMETER. Supported EZ_PARAMETER(s) along with their default system values are listed in Appendix C of this manual. Changing system variables will change the behavior of the EZTapiAPI.

This function runs synchronously and has no asynchronous equivalent.

If this function call is successful the return value is EZ_SUCCESS, otherwise the return value is negative. Possible return values include: EZ_PARAM_ERROR.

none