lineDrop (Compact 2013)

3/26/2014

This function drops or disconnects the specified call. The application has the option to specify user-to-user data to be transmitted as part of the call disconnect.

Syntax

LONG lineDrop(
  HCALL hCall, 
  LPCTSTR lpsUserUserInfo, 
  DWORD dwSize
);

Parameters

• hCall
  [in] Handle to the call to be dropped. The application must be an owner of the call. The call state of hCall can be any state except idle.

• lpsUserUserInfo
  [in] Pointer to a string that contains user data to be sent to the remote party as part of the call disconnect. This pointer can be left NULL if no user-to-user data is to be sent. User-to-user data is only sent if supported by the underlying network. For more information, see LINEDEVCAPS. The protocol field for the user-to-user data, if required, should appear as the first byte of the buffer pointed to by lpsUserUserInfo, and must be accounted for in the dwSize parameter.

• dwSize
  [in] Value that specifies the size, in bytes, of the user-to-user data in lpsUserUserInfo. If lpsUserUserInfo is NULL, no user-to-user data is sent to the calling party and dwSize is ignored.

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	Invalid call handle
LINEERR_OPERATIONUNAVAIL	The operation is unavailable. With code division multiple access (CDMA), this function may terminate all active calls. 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_RESOURCEUNAVAIL	The resource is unavailable
LINEERR_INVALPOINTER	Invalid pointer
LINEERR_NOMEM	Not enough memory
LINEERR_USERUSERINFOTOOBIG	The string containing user data is too large
LINEERR_OPERATIONFAILED	The operation failed
LINEERR_INVALCALLSTATE	Call is not in the idle state
LINEERR_NOTOWNER	Application is not the owner of the call
LINEERR_UNINITIALIZED	The parameter is uninitialized

Remarks

When invoking lineDrop, related calls can sometimes be affected as well. For example, dropping a conference call can drop all individual participating calls. LINE_CALLSTATE messages are sent to the application for all calls whose call state is affected. A dropped call typically transitions to the idle state. Invoking lineDrop on a call in the offering state rejects the call. Not all telephone networks provide this capability.

A call in the onholdpending state typically reverts to the connected state. When dropping the consultation call to the third party for a conference call or when removing the third party in a previously established conference call, the provider, and switch, can release the conference bridge and revert the call back to a normal two-party call. If this is the case, hConfCall shifts to the idle state, and the only remaining participating call transitions to the connected state. Some switches automatically release the hold on the other call.

The application has the option to send user-to-user data at the time of the drop. Even if user-to-user data can be sent, there is no guarantee that the network will deliver this data to the remote party.

In various bridged or party-line configurations, when multiple parties are on the call, lineDrop may not actually clear the call. For example, in a bridged situation, a lineDrop operation may not actually drop the call because the status of other stations on the call may govern; instead, the call may 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
LINE_CALLSTATE (TAPI)
LINE_REPLY
LINEDEVCAPS