Edit

Share via

NdisMIndicateStatus function (ndis.h)

  • Article

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.

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

Syntax

void NdisMIndicateStatus(
  [in] NDIS_HANDLE MiniportHandle,
  [in] NDIS_STATUS GeneralStatus,
  [in] PVOID       StatusBuffer,
  [in] UINT        StatusBufferSize
);

Parameters

[in] MiniportHandle

Specifies the handle originally input to MiniportInitialize.

[in] GeneralStatus

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

[in] StatusBuffer

Pointer 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.

[in] StatusBufferSize

Specifies the size in bytes of the buffer at StatusBuffer.

Return value

None

Remarks

When a miniport driver 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 driver 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 driver.

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 driver 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 driver 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.

A miniport driver cannot call NdisMIndicateStatus in the context of its MiniportISR, MiniportHalt, or MiniportShutdown function. Only a deserialized miniport driver can call NdisMIndicateStatus in the context of its MiniportInitialize function.

A miniport driver must release any spin lock that it is holding before calling NdisMIndicateStatus.

Serialized callers of NdisMIndicateStatus must run at IRQL = DISPATCH_LEVEL. Deserialized callers of NdisMIndicateStatus must run at IRQL <= DISPATCH_LEVEL.

Indicating the Loss and Restoration of a Network Connection

When a miniport driver senses that the network connection has been lost, it should call NdisMIndicateStatus with NDIS_STATUS_MEDIA_DISCONNECT. When the connection is restored, the miniport driver should call NdisMIndicateStatus with NDIS_STATUS_MEDIA_CONNECT.

Note   802.11 miniport drivers must follow the media status guidelines for wireless LANs when generating network connection indications. For more information about these guidelines, see Media Status Indications for 802.11 Networks.

802.11 Wireless LAN Miniport Driver Calls to NdisMIndicateStatus

802.11 wireless LAN (WLAN) miniport drivers can make various indications specific to the WLAN media. For example, the miniport driver can make a WLAN-specific indication when the following occur:

  • The driver detects that the received signal strength of its current BSS association has changed.
  • The driver detects a TKIP MIC failure on a received packet.

The following types of WLAN-specific indications can be made by 802.11 miniport drivers with NdisMIndicateStatus:

For more information about these media specific indications, see 802.11 Media-Specific Status Indications.

WAN Miniport Driver 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 driver 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:

  • Line up
  • Line down
  • Fragment
  • TAPI line event

NDIS_STATUS_WAN_LINE_UP

A WAN miniport driver 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 node. Until this occurs, protocols should reduce their timers and retry counts to quickly fail any outgoing connection attempts.

The WAN miniport driver 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 driver 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 driver 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 node that will notify it of this situation, rather than waiting for a time-out 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 driver 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.

  • Target platform: Universal
  • Version: Not supported for NDIS 6.0 drivers in Windows Vista. Use NdisMIndicateStatusExinstead. Supported for NDIS 5.1 drivers in Windows Vista and Windows XP.

Requirements

Requirement Value
Header ndis.h (include Ndis.h)
Library Ndis.lib

See also