HoldLine

The HoldLine procedure is used to place a phone call on hold. Calling this procedure also notifies the far end of the call with the appropriate hold state. Any number of phone lines that are active can independently be place into or removed from the hold state.

When you place a call on hold, you have the ability to stream audio data to the far end for the duration of the hold operation. For more information regarding streaming audio data to a line that is on hold, see API procedure TransmitOnHoldIvrData.

TELEPHONY_RETURN_VALUE HoldLine(

SIPHANDLE hStateMachine,

int PhoneLine,

BOOL HoldState

);

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 put on hold.

HoldState

[in] Specifies the hold state of the phone line. If TRUE, the phone line is on hold. If FALSE, the phone line characteristics are normal.

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.
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.
SipConferenceActive	Indicates that an attempt was made to take a call off hold but taking the call off hold is not allowed. This error occurs when other phone lines are in a conference session and you attempt to bring another line out of the hold state using the HoldLine API. When a conference session is established, add the line in question to the conference using the ConferenceLine API procedure. Also, remove any lines from the conference session by putting them on hold using the HoldLine API or remove them from the conference using the ConferenceLine API procedure.