NdisCmDispatchIncomingCloseCall function (ndis.h)

Article
04/18/2022

NdisCmDispatchIncomingCloseCall tells a client to tear down an active or offered call, usually because the call manager has received a request from the network to close the connection.

Syntax

void NdisCmDispatchIncomingCloseCall(
  [in]           NDIS_STATUS CloseStatus,
  [in]           NDIS_HANDLE NdisVcHandle,
  [in, optional] PVOID       Buffer,
  [in]           UINT        Size
);

Parameters

[in] CloseStatus

Specifies a CM-determined NDIS_STATUS_XXX, indicating the reason for the disconnect request. During normal network operations, a call manager passes NDIS_STATUS_SUCCESS to indicate that it has received a request, initiated by the remote party, to close an active call.

[in] NdisVcHandle

Specifies the handle to the VC of the call being disconnected. This handle was supplied by NDIS when the VC was originally created, whether by the call manager or client, with NdisCoCreateVc.

[in, optional] Buffer

Pointer to a caller-allocated resident buffer containing additional protocol-specific disconnect data, if any. Depending on the underlying medium, this pointer can be NULL

[in] Size

Specifies the size in bytes of the buffer, zero if Buffer is NULL.

Return value

None

Remarks

In the course of normal network operations, a stand-alone CM calls NdisCmDispatchIncomingCloseCall with the CloseStatus set to NDIS_STATUS_SUCCESS because the corresponding client on the remote node has called NdisClCloseCall.

However, a call manager also can call NdisCmDispatchIncomingCloseCall if either of the following occurs:

The call manager has notified a client of an incoming call offer. When the CM's ProtocolCmIncomingCallComplete function is called with the client's acceptance, it validates the input call parameters, which that client has modified. ProtocolCmIncomingCallComplete determines that the client is proposing unsupportable call parameters for the connection, so it calls NdisCmDispatchIncomingCloseCall.
Abnormal network conditions force the call manager to tear down active calls. For example, if the call manager is notified when any link on the connection between this client and the remote party to the connection goes down, the CM would call NdisCmDispatchIncomingCloseCall to prevent the client from attempting (or expecting) further data transfers on such a broken connection.

After tearing down any call, the original creator of the VC is responsible for calling NdisCoDeleteVc after releasing any additional resources it had associated with the VC.

A call to NdisCmDispatchIncomingCloseCall causes NDIS to call the client's ProtocolClIncomingCloseCall function.

Only stand-alone call managers, which register themselves with NDIS as protocol drivers, can call NdisCmDispatchIncomingCloseCall. Connection-oriented miniport drivers that provide call-management support call NdisMCmDispatchIncomingCall instead.

Requirements

Requirement	Value
Minimum supported client	Supported for NDIS 6.0 and NDIS 5.1 drivers (see NdisCmDispatchIncomingCloseCall (NDIS 5.1)) in Windows Vista. Supported for NDIS 5.1 drivers (see NdisCmDispatchIncomingCloseCall (NDIS 5.1)) in Windows XP.
Target Platform	Desktop
Header	ndis.h (include Ndis.h)
Library	Ndis.lib
IRQL	<= DISPATCH_LEVEL
DDI compliance rules	Irql_CallManager_Function(ndis)