CO_STATUS_HANDLER callback function

Article
06/19/2017

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.

The ProtocolCoStatus function is required in connection-oriented protocol drivers that handles status-change notifications raised by an underlying driver or by NDIS.

Syntax

CO_STATUS_HANDLER ProtocolCoStatus;

VOID ProtocolCoStatus(
  _In_     NDIS_HANDLE ProtocolBindingContext,
  _In_opt_ NDIS_HANDLE ProtocolVcContext,
  _In_     NDIS_STATUS GeneralStatus,
  _In_     PVOID       StatusBuffer,
  _In_     UINT        StatusBufferSize
)
{ ... }

Parameters

ProtocolBindingContext [in]
Specifies the handle to a protocol-allocated context area in which the protocol driver maintains per-binding run-time state. The driver supplied this handle when it called NdisOpenAdapter.
ProtocolVcContext [in, optional]
Specifies the handle to a protocol-allocated context area in which the protocol driver maintains per-VC run-time state. This parameter is NULL when ProtocolCoStatus is called if the status-change indication is not VC-specific in nature. Otherwise, the protocol originally supplied this handle either when it called NdisCoCreateVc or from its ProtocolCoCreateVc function.
GeneralStatus [in]
Indicates the general status code, either raised by NDIS or propagated from the underlying driver's call to NdisMCoIndicateStatus.
StatusBuffer [in]
Pointer to a buffer containing medium-specific data that depends on the value of GeneralStatus.

For some NDIS_STATUS_XXX values, this pointer is NULL and StatusBufferSize is set to zero.
StatusBufferSize [in]
Specifies the number of bytes at StatusBuffer.

Return value

None

Remarks

A call to ProtocolCoStatus notifies the protocol about changes in status of an active VC, of the underlying connection-oriented NIC, or of its driver.

ProtocolCoStatus interprets two basic pieces of information:

A general status code, defined by NDIS as an NDIS_STATUS_XXX value, indicating a change on the VC, on the NIC, or in the underlying driver.

If NDIS has called the underlying driver's MiniportReset function in an attempt to restore the NIC to an operational state, NDIS can substitute NDIS_STATUS_RESET_START for the GeneralStatus indicated in the miniport driver's call to NdisMCoIndicateStatus.
Depending on the status at GeneralStatus, additional information about the specific reason for the change in status, which can be medium-specific.

NDIS always notifies all bound protocols when an underlying connection-oriented driver is resetting its NIC by calling their ProtocolCoStatus functions, first with NDIS_STATUS_RESET_START and later, when the reset operation is done, with NDIS_STATUS_RESET_END. After each such call to a ProtocolCoStatus function, NDIS also calls the driver's ProtocolStatusComplete function.

Since NDIS will not accept protocol-initiated sends and requests to a miniport driver while a reset is in progress, the NDIS_STATUS_RESET_START notification warns bound protocols to hold off on their calls to NdisCoSendPackets and NdisCoRequest on the binding designated by the respective ProtocolBindingContext given to their ProtocolCoStatus functions until they receive the corresponding NDIS_STATUS_RESET_END notification.

If the protocol itself initiated the reset operation with a call to NdisReset, its ProtocolCoStatus function receives the NDIS_STATUS_RESET_START and NDIS_STATUS_RESET_END notifications like any other protocol bound to the same underlying driver. However, if NdisReset returns NDIS_STATUS_PENDING, only the ProtocolStatusComplete function of the driver that initiated the reset operation is called.

Consequently, every protocol's ProtocolCoStatus function should take whatever action is required to prevent that protocol from submitting sends and requests as soon as ProtocolCoStatus receives the NDIS_STATUS_RESET_START notification and should reenable subsequent sends and requests when ProtocolCoStatus receives the NDIS_STATUS_RESET_END notification. Usually, ProtocolCoStatus simply sets and clears a ResetInProgress flag in the ProtocolBindingContext area that other driver functions check before they initiate sends or requests on the binding.

When the underlying NIC driver signals a status change, it does not change associated event counters and thresholds.

Requirements

Target platform	Desktop
Version	Not supported for NDIS 6.0 drivers in Windows Vista. Use ProtocolCoStatusExinstead. Supported for NDIS 5.1 drivers in Windows Vista and Microsoft Windows XP
Header	Ndis.h (include Ndis.h)
IRQL	<= DISPATCH_LEVEL

Share via