lineDrop
The lineDrop
function drops or disconnects the specified call. The application has the
option to specify user-to-user information to be transmitted as part of the
call disconnect.
LONG lineDrop(
|
HCALL hCall, |
|
|
LPCSTR lpsUserUserInfo, |
|
|
DWORD dwSize |
|
|
); |
|
Parameters
hCall
A 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
A pointer to
a string containing user-to-user information to be sent to the remote party as
part of the call disconnect. This pointer can be left NULL if no user-to-user
information is to be sent. User-to-user information is only sent if supported
by the underlying network (see LINEDEVCAPS). The protocol discriminator field for the
user-to-user information, if required, should appear as the first byte of the
buffer pointed to by lpsUserUserInfo, and must be accounted for in dwSize.
dwSize
The size in
bytes of the user-to-user information in lpsUserUserInfo. If lpsUserUserInfo
is NULL, no user-to-user information is sent to the calling party and dwSize
is ignored.
Return Values
Returns a
positive request ID if the function will be completed asynchronously, or a
negative error number if an error has occurred. The dwParam2 parameter
of the corresponding LINE_REPLY
message is zero if the function is successful or it is a negative error number
if an error has occurred. Possible return values are:
LINEERR_INVALCALLHANDLE,
LINEERR_OPERATIONUNAVAIL, LINEERR_NOMEM, LINEERR_OPERATIONFAILED,
LINEERR_NOTOWNER, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_USERUSERINFOTOOBIG,
LINEERR_INVALCALLSTATE, LINEERR_UNINITIALIZED.
Remarks
When invoking
lineDrop, related calls may sometimes be affected as well. For example,
dropping a conference call may 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 will typically revert 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) may release the conference bridge and revert the call
back to a normal two-party call. If this is the case, hConfCall transitions
to the idle state, and the only remaining participating call will
transition to the connected state. Some switches automatically
"unhold" the other call.
The
application has the option to send user-to-user information at the time of the
drop. Even if user-to-user information can be sent, there is no guarantee that
the network will deliver this information to the remote party.
Note that 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 possibly 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.
See Also