Microsoft Windows CE 3.0  

NdisMIndicateStatus

Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

This function indicates changes in the status of an NIC to higher-level NDIS drivers.

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

Parameters

MiniportAdapterHandle
Handle originally input to the MiniportInitializefunction.
GeneralStatus
Specifies the NDIS_STATUS_ XXXvalue that indicates the general change in status for the NIC.
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.
StatusBufferSize
Specifies the size, in bytes, of the buffer at StatusBuffer.

Remarks

When a miniport calls this function, NDIS calls each bound protocol's ProtocolStatusfunction. 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 the NdisResetfunction, depending on the NDIS_STATUS_ XXXindicated.

When a miniport calls this function to report a change in NIC status, NDIS can call the MiniportResetfunction to try to restore 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 GeneralStatusindicated by the miniport.

This function 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 can also call this function to indicate problems, such as cables that have been accidentally removed and then reinserted, or a ring that has temporarily failed. For example, both the following conditions might occur:

    • The miniport calls this function with NDIS_STATUS_RING_STATUS.
    • The StatusBuffercontains 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.

        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 this function:

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

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

          The WAN miniport makes this indication with this function 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 StatusBufferis formatted as an NDIS_MAC_LINE_UPstructure.

          A WAN miniport makes a line-down indication whenever a link goes down. When this occurs, bound protocols should reduce their timer 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 StatusBufferis formatted as an NDIS_MAC_LINE_DOWNstructure.

          A WAN miniport makes a fragment indication whenever it receives a partial packet from the remote node. When this occurs, a bound protocol sends frames to the remote that 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 StatusBufferis formatted as an NDIS_MAC_FRAGMENTstructure.

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

          A WAN miniport must use a GeneralStatusvalue of NDIS_STATUS_TAPI_INDICATION for TAPI status indications .The buffer at StatusBufferis formatted as an NDIS_TAPI_EVENTstructure.

          A driver that calls this function runs at IRQL DISPATCH_LEVEL.

          Requirements

          Runs on Versions Defined in Include Link to
          Windows CE OS 2.0 and later Ndis.h    
          Note   This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

          See Also

          NdisMIndicateStatusComplete



           Last updated on Tuesday, July 13, 2004

          © 2004 Microsoft Corporation. All rights reserved.