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 is a required driver function that handles status-change notifications raised by an underlying connectionless network adapter driver or by NDIS.
VOID ProtocolStatus( IN NDIS_HANDLE ProtocolBindingContext, IN NDIS_STATUS GeneralStatus, IN PVOID StatusBuffer IN UINT StatusBufferSize );
ProtocolStatusis a required driver function that handles status-change notifications raised by an underlying connectionless network adapter driver or by NDIS.
Parameters
For example, if the GeneralStatusargument is NDIS_STATUS_RING_STATUS, this parameter points to a ULONG-sized bitmask and StatusBufferSizeis four. As another example, if GeneralStatusis NDIS_STATUS_WAN_LINE_UP, this parameter points to an NDIS_WAN_LINE_UPstructure and StatusBufferSizeis sizeof(NDIS_STATUS_WAN_LINE_UP ).
For some NDIS_STATUS_ XXXvalues, this pointer is NULL and StatusBufferSizeis set to zero.
Comments
A call to ProtocolStatusnotifies the protocol about changes in status of the underlying network adapter or its driver.
ProtocolStatusinterprets two basic pieces of information:
NDIS notifies all bound protocols when an underlying driver is resetting its network adapter by calling their ProtocolStatusfunctions, 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 ProtocolStatusfunction, NDIS also calls the driver's ProtocolStatusCompletefunction.
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 NdisRequeston the binding designated by the respective ProtocolBindingContextgiven to their ProtocolStatusfunctions until they receive the corresponding NDIS_STATUS_RESET_END notification.
If the protocol itself initiated the reset operation with a call to NdisReset, its ProtocolStatusfunction receives the NDIS_STATUS_RESET_START and NDIS_STATUS_RESET_END notifications like any other protocol bound to the same underlying driver. However, if NdisResetreturns NDIS_STATUS_PENDING, only the ProtocolStatusCompletefunction of the driver that initiated the reset operation is called.
Consequently, every protocol's ProtocolStatusfunction should take whatever action is required to prevent that protocol from submitting sends and requests as soon as ProtocolStatusreceives the NDIS_STATUS_RESET_START notification and should re-enable subsequent sends and requests when ProtocolStatusreceives the NDIS_STATUS_RESET_END notification. Usually, ProtocolStatussimply sets and clears a ResetInProgress flag in the ProtocolBindingContextarea that other driver functions check before they initiate sends or requests on the binding.
As another example, the ProtocolStatusfunction of any protocol bound above NDISWAN receives a line-up notification whenever the underlying WAN network adapter miniport is establishing a new link. After such a protocol has traded link-specific context handles with NDISWAN, its ProtocolStatusfunction 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.
When the underlying network adapter driver signals a status change, it does not change associated event counters and thresholds.
Requirements
Runs on | Versions | Defined in | Include | Link to |
---|---|---|---|---|
Windows CE OS | 2.0 and later | Ndis.h | Ndislib.lib |
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
MiniportReset, NdisMIndicateStatus, NdisOpenAdapter, NdisRequest , NdisReset, NdisSend, ProtocolStatus, ProtocolStatusComplete