NdisMIndicateStatus

NdisMIndicateStatus

VOID
NdisMIndicateStatus(
IN NDIS_HANDLE MiniportAdapterHandle,
IN NDIS_STATUS GeneralStatus,
IN PVOID StatusBuffer,
IN UINT StatusBufferSize
);

NdisMIndicateStatus indicates changes in the status of a NIC to higher-level NDIS drivers.

Parameters

MiniportAdapterHandle

Specifies the handle originally input to MiniportInitialize.

GeneralStatus

Specifies the NDIS_STATUS_XXX value that indicates the general change in status for the NIC.

StatusBuffer

Points to a caller-allocated buffer containing data that is medium-specific and dependent on the value of GeneralStatus. It indicates detailed information about the change in status.

StatusBufferSize

Specifies the size in bytes of the buffer at StatusBuffer.

Comments

When a miniport calls NdisMIndicateStatus, NDIS calls each bound protocol's ProtocolStatus function. This allows a bound protocol driver or, possibly, the configuration manager to log the change in status of an underlying NIC or to take corrective action. For example, a protocol might call NdisReset, depending on the NDIS_STATUS_XXX indicated.

When a miniport calls NdisMIndicateStatus to report a change in NIC status, NDIS can call the MiniportReset function to try restoring the NIC to a working condition. In these circumstances, NDIS can call bound protocols only with NDIS_STATUS_RESET_START and later with NDIS_STATUS_RESET_END, rather than with the GeneralStatus indicated by the miniport.

NdisMIndicateStatus provides two pieces of information:

·An overall status value indicating the general change in status.

·A specific reason for the general change, which can be network-specific. For example, ring-insertion failures are particular to Token Ring (802.5) networks, but are irrelevant to Ethernet (802.3) NICs and their drivers.

A miniport also can call NdisMIndicateStatus to indicate problems such as cables that have been accidentally removed and then reinserted, or a ring that has temporarily failed. For example, suppose both the following conditions occur:

·The miniport calls NdisMIndicateStatus with NDIS_STATUS_RING_STATUS.

·The StatusBuffer contains one of the following status values:
NDIS_RING_LOBE_WIRE_FAULT
NDIS_RING_HARD_ERROR
NDIS_RING_SIGNAL_LOSS

After such a change in status has been signaled with an indication, any associated thresholds or statistics counters remain unchanged.

Callers of NdisMIndicateStatus run at IRQL DISPATCH_LEVEL.

WAN Miniport Calls to NdisMIndicateStatus

Most WAN NIC drivers indicate status with some special status codes and buffer contents. These status indications are generated by WAN NIC drivers, and NDIS protocol drivers bound to such a miniport can ignore these indications. However, processing these indications correctly usually results in improved performance for protocols and for WAN NIC drivers.

The following four types of WAN-specific indications can be sent to bound protocol drivers with NdisMIndicateStatus:

1.Line up

2.Line down

3.Fragment

4.TAPI line event

NDIS_STATUS_WAN_LINE_UP

A WAN miniport makes a line-up indication whenever a new link becomes active. Until this occurs, the NIC will accept frames and let them succeed or fail, but it is unlikely that they will actually be received by any remote. Until this occurs, protocols should reduce their timers and retry counts so as to quickly fail any outgoing connection attempts.

The WAN miniport makes this indication with NdisMIndicateStatus before it returns from the OID_TAPI_GET_ID request.

The status code for the line-up indication is NDIS_STATUS_WAN_LINE_UP. The buffer at StatusBuffer is formatted as an NDIS_MAC_LINE_UP structure.

NDIS_STATUS_WAN_LINE_DOWN

A WAN miniport makes a line-down indication whenever a link goes down. When this occurs, bound protocols should reduce their timers and retry counts until the next line-up indication.

The status code for the line-down indication is NDIS_STATUS_WAN_LINE_DOWN. The buffer at StatusBuffer is formatted as an NDIS_MAC_LINE_DOWN structure.

NDIS_STATUS_WAN_FRAGMENT

A WAN miniport makes a fragment indication whenever it receives a partial packet from the remote node. When this occurs, a bound protocol should send frames to the remote that will notify it of this situation, rather than waiting for a timeout to occur.

The status code for the fragment indication is NDIS_STATUS_WAN_FRAGMENT. The buffer at StatusBuffer is formatted as an NDIS_MAC_FRAGMENT structure.

NDISWAN monitors dropped packets by counting the number of fragment indications on each link.

NDIS_TAPI_EVENT

A WAN miniport must use a GeneralStatus value of NDIS_STATUS_TAPI_INDICATION for TAPI status indications. The buffer at StatusBuffer is formatted as an NDIS_TAPI_EVENT structure.