ProtocolStatus

ProtocolStatus

VOID
   ProtocolStatus(
       IN NDIS_HANDLE ProtocolBindingContext,
       IN NDIS_STATUS GeneralStatus,
       IN PVOID StatusBuffer,
       IN UINT StatusBufferSize
       );

ProtocolStatus is a required driver function that handles status-change notifications raised by an underlying driver or by NDIS.

Parameters

ProtocolBindingContext

Specifies the handle to a protocol-allocated context area in which the protocol driver maintains per-binding runtime state. The driver supplied this handle when it called NdisOpenAdapter.

GeneralStatus

Indicates the general status code, either raised by NDIS or propagated from the underlying driver’s call to NdisMIndicateStatus.

StatusBuffer

Points to a buffer containing medium-specific data that depends on the value of GeneralStatus.

For example, if the GeneralStatus argument is NDIS_STATUS_RING_STATUS, this parameter points to a ULONG-sized bitmask and StatusBufferSize is four. As another example, if GeneralStatus is NDIS_STATUS_WAN_LINE_UP, this parameter points to an NDIS_WAN_LINE_UP structure and StatusBufferSize is sizeof(NDIS_STATUS_WAN_LINE_UP).

For some NDIS_STATUS_XXX values, this pointer is NULL and StatusBufferSize is set to zero.

StatusBufferSize

Specifies the number of bytes at StatusBuffer.

Comments

A call to ProtocolStatus notifies the protocol about changes in status of the underlying NIC or its driver.

ProtocolStatus interprets two basic pieces of information:

1.A general status code, defined by NDIS as an NDIS_STATUS_XXX value, indicating a change 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’s call to NdisMIndicateStatus.

2.Depending on the status at GeneralStatus, additional information about the specific reason for the change in status, which can be medium-specific

For example, ring-insert failures are specific to Token Ring (802.5) networks and do not apply for Ethernet (802.3) networks.

NDIS always notifies all bound protocols when an underlying driver is resetting its NIC by calling their ProtocolStatus 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 ProtocolStatus function, NDIS also calls the driver’s ProtocolStatusComplete function if NDIS or the underlying miniport initiated the reset.

Since NDIS will not accept protocol-initiated sends and requests to a miniport while a reset is in progress, the NDIS_STATUS_RESET_START notification warns bound protocols to hold off on their calls to NdisSendPackets, NdisSend, and NdisRequest on the binding designated by the respective ProtocolBindingContext given to their ProtocolStatus 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 ProtocolStatus 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 ProtocolStatus function should take whatever action is required to prevent that protocol from submitting sends and requests as soon as ProtocolStatus receives the NDIS_STATUS_RESET_START notification and should re-enable subsequent sends and requests when ProtocolStatus receives the NDIS_STATUS_RESET_END notification. Usually, ProtocolStatus 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.

As another example, the ProtocolStatus function of any protocol bound above NDISWAN receives a line-up notification whenever the underlying WAN NIC miniport is establishing a new link. After such a protocol has traded link-specific context handles with NDISWAN, its ProtocolStatus function can receive additional link-specific line-up, line-down, and fragment indications, which the protocol can use to optimize throughput and/or performance on the link.

The ProtocolStatus function of an NDIS intermediate driver cannot simply forward status indications to still higher-level protocols. Such an attempt can cause a deadlock. Instead, such a driver must call NdisIMSwitchToMiniport to forward the indication from the appropriate context. If NdisIMSwitchToMiniport returns FALSE, the driver must call NdisIMQueueMiniportCallback and forward the indication from the protocol-supplied MiniportCallback function.

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

By default, ProtocolStatus runs at IRQL DISPATCH_LEVEL in an arbitrary thread context.