Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This function drops or disconnects the specified call. User-user information can optionally be transmitted as part of the call disconnect. This function can be called by the application at any time. When TSPI_ lineDropreturns, the call should be idle.

Syntax 

LONG TSPIAPI TSPI_lineDrop(
  DRV_REQUESTID 
dwRequestID,  
  HDRVCALL 
hdCall, 
  LPCSTR 
lpsUserUserInfo,  
  DWORD 
dwSize 
);

Parameters

dwRequestID

Iidentifier of the asynchronous request.

hdCall

Service provider's handle to the call to be dropped. The call state of hdCallcan be any state except idle.

lpsUserUserInfo

Pointer to a null-terminated string containing user-user information to be sent to the remote party as part of the call disconnect. This pointer is only valid if dwUserUserInfoSizeis nonzero. It is NULL if no user-user information is to be sent. User-user information is only sent if supported by the underlying network (see LINEDEVCAPS).

dwSize

Size, in bytes, of the user-user information in lpsUserUserInfo. If lpsUserUserInfois NULL, dwSizeis ignored.

Return Value

Returns dwRequestIDor an error number if an error occurs. The lResultactual parameter of the corresponding ASYNC_COMPLETIONis zero if the function succeeds or an 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 is invalid.

LINEERR_OPERATIONFAILED

The operation failed.

LINEERR_INVALCALLSTATE

The call state is invalid.

LINEERR_RESOURCEUNAVAIL

The resource is unavailable.

LINEERR_NOMEM

Not enough memory is available.

LINEERR_USERUSERINFOTOOBIG

The user user information is too big.

LINEERR_OPERATIONUNAVAIL

The operation is unavailable.

Remarks

The service provider returns LINEERR_INVALCALLSTATE if the current state of the call does not allow the call to be dropped.

When invoking TSPI_lineDrop, related calls can sometimes be affected as well. For example, dropping a conference call may drop all individual participating calls. LINE_CALLSTATEmessages are sent to TAPI for all calls whose call state is affected. Typically, a dropped call transitions to the idle state. Invoking TSPI_ lineDropon a call in the offering state rejects the call. Not all telephone networks provide this capability.

In situations where the call to be dropped is a consultation call established during transfer or conference call establishment, the original call that was placed in the OnHoldPending state is reconnected to and it typically re-enters the connected call state.

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

Note:
In various bridged or party line configurations when multiple parties are on the call, TSPI_ lineDropmay not actually clear the call.

Requirements

Header tapicomn.h
Library coredll.lib
Windows Embedded CE Windows CE 3.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also