OpenRxIvrChannel

 

The OpenRxIvrChannel API procedure allows application software to access phone line received audio data. The primary purpose is to allow speech recognition or other special signal processing of received audio data. The audio data from this interface can be used for whatever your application demands.

 

 

TELEPHONY_RETURN_VALUE OpenRxIvrChannel(

SIPHANDLE hStateMachine,

int PhoneLine,

IVRCALLBACKPROC pRxIvrCallback,

void *pRxIvrCallbackUserData,

BOOL PerformConversion,
AUDIO_BANDWIDTH ReceiveIvrDataType,
IVRRXHANDLE *pIvrRxHandle,

int *pSamplesPerIvrBuffer,
int *pBytesPerIvrBuffer,

BOOL *pSamplesInByteArray

);

 

 

Parameters:

 

hStateMachine

[in] The handle to the telephony engine. This is the handle that was returned by a previous call to the StartSipTelephony procedure.

 

PhoneLine

[in] The zero based phone line to access. A callback procedure can be registered for any or all of the phone lines supported by the telephony engine.

 

pRxIvrCallback

[in] The address of a user supplied callback procedure of type IVRCALLBACKPROC. This callback procedure will be executed whenever audio sample data has been received on the phone line. The callback procedure is not required to return a value. The callback will be passed a pointer to a variable of type IVR_RECOGNITION_DATA.

 

pRxIvrCallbackUserData

[in] User specified instance data. This value will be passed to the user’s callback procedure unmodified.

 

PerformConversion

[in] If TRUE, the telephony engine will perform format and rate conversion from the telephone line rate/format to the user specified rate and format. If setting this parameter to TRUE, you must also specify appropriate value for parameter ReceiveIvrDataType.

 

If FALSE, the phone line data is passed to the application using the rate and format the telephony engine negotiated with the far end of the call. The application will receive streaming audio data in the same rate and format as that being transacted between the call points. When setting this parameter to FALSE, the parameter ReceiveIvrDataType is ignored.

 

ReceiveIvrDataType

[in] The user specified data type (rate/format) the application expects to receive from the receive IVR interface. You can specify any of the 20Ms AUDIO_BANDWIDTH data types defined except for Speex. Also, do not specify any of the 30Ms data types.
 

 

pIvrRxHandle

[out] This parameter specifies the location that will receive the handle to the open receiver IVR channel. This parameter must not be NULL.

 

pSamplesPerIvrBuffer

[out] A pointer that will receive a value that represents the number of samples the application will receive in each received IVR sample block.

 

pBytesPerIvrBuffer

[out] A pointer that will receive a value that represents the number of sample bytes the application will receive in each received IVR sample block.

 

pSamplesInByteArray

[out] This parameter will allow application software to easily determine if received IVR sample data will be passed back to the application as a byte (8 bit) element buffer or a short (16 bit) element buffer.

 

 

Return Value:

 

If the function succeeds, the return value will be SipSuccess.

 

If the function fails, the return value will be one of the following values as specified by the TELEPHONY_RETURN_VALUE data type.

 

 

 

Value

Description

SipCallFailure

This is a generic "catch all" API error. If an error condition is not specified by any other API error value, this error will be returned.

 

SipBadParameter

For API procedures that receive pointers from user software, this error indicates that a NULL pointer condition was detected. Make sure all pointers your software passes to the telephony API are valid.

 

SipInvalidHandle

An API procedure was passed an invalid handle. The telephony engine attempts to verify user specified telephony handles and returns this error when an invalid handle is detected.

 

SipBadPhoneLine

A telephony operation was specified using an invalid phone line. Phone lines are numbered starting from zero.

 

SipBadAudioDataType

A telephony operation was attempted using an invalid audio data type specification. See the AUDIO_BANDWIDTH data type for details. Verify that an acceptable value has been specified for the ReceiveIvrDataType parameter.

 

SipMemoryError

Indicates a critical internal memory error within the telephony engine. User application software should not continue if this error is detected. Make sure the host machine is configured properly and is adequate for the intended application.

 

SipIvrAlreadyOpened

The receive or transmit IVR channel is already open. Do not open IVR channels more than once.

 

 

 

Remarks:

 

If your application uses receiver IVR channels, you must open and prepare all required receiver IVR channels before any of the phone lines are allowed to leave the off hook state. Under normal operations, your software should open and configure all receiver IVR channels before finally enabling the telephony engine using the SipTelephonyEnable API procedure.

 

This is in contrast to how an application opens and manages transmit IVR channels. For further information, see the OpenTxIvrChannel API procedure.