OpenTxIvrChannel

The OpenTxIvrChannel API procedure allows application software to open a transmit IVR channel to the specified phone line. By opening a transmit IVR channel to the phone line, the application can stream sampled audio data directly to the phone line.

TELEPHONY_RETURN_VALUE OpenTxIvrChannel(

SIPHANDLE hStateMachine,

int PhoneLine,

int ChannelNumber,

IVRTXHANDLE *pIvrTxHandle

);

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.

ChannelNumber

[in] The zero based transmit channel number. Currently up to four independent transmit IVR outputs may be opened per phone line. Each opened IVR transmit channel may use any of the data rates and formats supported by the media engine.

pIvrTxHandle

[out] The address of a user variable that will receive the handle to the transmit IVR channel of the phone line.

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.
SipNoCallActive	An API operation was being performed on a phone line. However, there is no active call on the specified phone line.
SipIvrAlreadyOpened	The receive or transmit IVR channel is already open. Do not open IVR channels more than once.
SipIvrBadChannel	A bad channel number value was specified. Currently four transmit IVR output channels are supported per phone line.

Remarks:

If your application uses transmit IVR channels, you must open and prepare the required transmit IVR channels only when a phone line has completed its call setup and has entered the "in call" state (SipInCall). A transmit IVR channel can then be closed any time after it is opened while the call is still active (not in the SipOnHook state). If the application does not close the transmit IVR channel and the call terminates, the media engine will automatically close the transmit IVR channel for you. In this case, your application will have to re-open the transmit IVR channel by calling this API procedure before streaming additional sample block data to the phone line.

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