NdisClCloseCall (NDIS 5.1) function
Note NDIS 5. x has been deprecated and is superseded by NDIS 6. x. For new NDIS driver development, see Network Drivers Starting with Windows Vista. For information about porting NDIS 5. x drivers to NDIS 6. x, see Porting NDIS 5.x Drivers to NDIS 6.0.
NdisClCloseCall requests that a call on the specified VC be torn down.
Syntax
NDIS_STATUS NdisClCloseCall(
_In_ NDIS_HANDLE NdisVcHandle,
_In_opt_ NDIS_HANDLE NdisPartyHandle,
_In_opt_ PVOID Buffer,
_In_ UINT Size
);
Parameters
NdisVcHandle [in]
Handle to the VC of the call being closed or disconnected. This handle was supplied by NDIS when the VC was originally created with NdisCoCreateVc, whether by the client in preparation for making an outgoing call or by the call manager in preparation for dispatching an incoming call to the client.NdisPartyHandle [in, optional]
Handle to the last party to be dropped on a multipoint VC or NULL. If this is a multipoint VC, the client obtained this handle either from a preceding call to NdisClMakeCall or NdisClAddParty.Buffer [in, optional]
Pointer to a caller-allocated buffer containing any data to be transmitted to the party on the remote node when the connection is closed. Depending on the underlying medium, this pointer can be NULL. For example, this parameter is NULL on ATM networks.Size [in]
Specifies the size, in bytes, at Buffer, zero if Buffer is NULL.
Return value
When NdisClCloseCall returns anything other than NDIS_STATUS_PENDING, the client should make an internal call to its ProtocolClCloseCallComplete function. Otherwise, NDIS calls the client's ProtocolClCloseCallComplete function when this operation is completed.
Remarks
Clients usually call NdisClCloseCall in any one of the following circumstances:
To close an established call, whether the call was initiated by the client with NdisClMakeCall or was offered by a remote peer and accepted by the client's ProtocolClIncomingCall function
From the ProtocolClIncomingCloseCall function to tear down an established call
This occurs when the remote party closes an incoming call that the remote party originally initiated and that the client accepted. For client-initiated outgoing calls, this occurs either when the remote party closes the point-to-point connection on the remote node or when the last remaining party on a multipoint VC closes the call on the remote node.
From the ProtocolClMakeCallComplete function to tear down a client-initiated attempt to make an outgoing call
This occurs if the call manager has modified the client-specified call parameters passed to NdisClMakeCall and the client finds these modifications unacceptable.
From the ProtocolClIncomingCallQoSChange function to tear down an established call
This occurs if a QoS change proposed by the other party on the VC is unacceptable to the client.
From the ProtocolClModifyCallQoSComplete function to tear down an established call
This occurs if a client-proposed QoS change on the VC is not accepted and the CM-modified QoS returned to ProtocolClModifyCallQoSComplete is unacceptable to the client.
Before calling NdisClCloseCall, a protocol must ensure that all its outstanding send packets have been returned to its ProtocolCoSendComplete function. (Packets sent via NdisCoSendPackets are always returned asynchronously to ProtocolCoSendComplete.) After calling NdisClCloseCall, a protocol must not call NdisCoSendPackets to send packets on the VC referenced by NdisClCloseCall.
A client's call to NdisClCloseCall causes NDIS to mark the NdisVcHandle as closing and to call the CM's ProtocolCmCloseCall function.
To tear down an established call on a client-created multipoint VC, the client must call NdisClDropParty one or more times to release all but the last party on the VC before it calls NdisClCloseCall. The call manager will fail any client's request to close a multipoint call if the given VC still has more than one party connected. The NdisPartyHandle passed to NdisClCloseCall can be any valid handle that the client obtained from its preceding calls to NdisClAddParty or NdisClMakeCall with the given NdisVcHandle.
As remote parties to a client-initiated multipoint call request that their connections be closed, NDIS calls that client's ProtocolClDropPartyComplete function as long as more than one outstanding party exists on the client-created multipoint VC. When the last remaining remote party closes its connection, NDIS calls the client's ProtocolClIncomingCloseCall function instead. Consequently, the ProtocolClIncomingCloseCall function of any client that sets up multipoint connections must identify the last remaining party on its multipoint VCs and pass the appropriate NdisPartyHandle to NdisClCloseCall.
After the client releases an NdisPartyHandle with NdisClCloseCall, it can release (or reinitialize for reuse) the resources for the per-party state it was maintaining. However, the client cannot release or reuse its per-VC resources in a similar manner on completion of the operation it initiated with NdisClCloseCall because the NdisVcHandle, which cannot be reused to make another call because it is marked as closing, is still valid until the VC is destroyed. Either the client must call NdisCoDeleteVc if it created the VC for an outgoing call before it releases or reinitializes its per-VC resources, or the client must defer the release or reinitialization of these resources until its ProtocolCoDeleteVc function is called.
Requirements
Target platform |
Universal |
Version |
See NdisClCloseCall. |
Header |
Ndis.h (include Ndis.h) |
Library |
Ndis.lib |
IRQL |
<= DISPATCH_LEVEL |
See also
ProtocolClIncomingCallQoSChange
ProtocolClModifyCallQoSComplete