lineHold (Compact 2013)

3/26/2014

This function places the specified call on hold.

Syntax

LONG WINAPI lineHold(
  HCALL hCall 
);

Parameters

• hCall
  Handle to the call to be placed on hold. The application must be an owner of the call. The call state of hCall must be connected.

Return Value

Returns a positive request identifier if the function is completed asynchronously or a negative error number if an error occurs. The dwParam2 parameter of the corresponding LINE_REPLY message is zero if the function succeeds or it is a negative error number if an error occurs. The following table shows the return values for this function.

Value	Description
LINEERR_INVALCALLHANDLE	The handle to the call to be placed on hold is invalid.
LINEERR_OPERATIONUNAVAIL	The operation is unavailable because this function is not supported by code division multiple access (CDMA). CDMA does not provide the necessary functionality to support the following TAPI functions: lineAccept lineAnswer lineClose lineCompleteTransfer lineDial lineDrop lineHold lineMakeCall linePark linePickup lineSwapHold Some cellular carriers provide equivalent functionality through the flash feature, which with TAPI 2.2 can be accessed with the lineGenerateDigits function. Because the exact flash sequences are controlled by the cellular providers, the application must be completely aware of the necessary codes implemented by the cellular providers.
LINEERR_INVALCALLSTATE	The call state of hCall is something other than connected.
LINEERR_OPERATIONFAILED	The operation failed.
LINEERR_NOMEM	Not enough memory is available.
LINEERR_RESOURCEUNAVAIL	The resources are unavailable.
LINEERR_NOTOWNER	The application is not the owner of this call.
LINEERR_UNINITIALIZED	A parameter is uninitialized.

Remarks

The call on hold is temporarily disconnected allowing the application to use the line device for making or answering other calls. The lineHold function performs a so-called "hard hold" of the specified call (as opposed to a "consultation call"). A call on hard hold typically cannot be transferred or included in a conference call, but a consultation call can. Consultation calls are initiated using the lineSetupTransfer, lineSetupConference, or linePrepareAddToConference functions.

After a call has been successfully placed on hold, the call state typically transitions to onHold. A held call is retrieved by the lineUnhold function. While a call is on hold, the application can receive LINE_CALLSTATE messages about state changes of the held call. For example, if the held party hangs up, the call state can transition to disconnected.

In a bridged situation, a lineHold operation may possibly not actually place the call on hold, because the status of other stations on the call can govern (for example, attempting to "hold" a call when other stations are participating is not be possible); instead, the call can simply be changed to the LINECONNECTEDMODE_INACTIVE mode if it remains connected at other stations.

Requirements

Header	tapi.h
Library	TAPI32.dll

See Also

Reference

TAPI Line Device Functions
linePrepareAddToConference
lineSetupConference
lineSetupTransfer
lineUnhold
LINE_CALLSTATE (TAPI)