Partager via

ProtocolNetPnPEvent (Compact 2013)

  • Article

3/26/2014

NDIS calls this function to indicate a network Plug and Play event, an NDIS PnP event, or a power management event to a protocol driver.

Syntax

NDIS_STATUS
  ProtocolNetPnPEvent(
    IN NDIS_HANDLE  ProtocolBindingContext,
    IN PNET_PNP_EVENT_NOTIFICATION  NetPnPEvent
    );

Parameters

  • ProtocolBindingContext
    The handle to a protocol-driver-allocated context area in which this driver maintains per-binding run-time state information. The protocol driver supplied this handle when it called the NdisOpenAdapterEx function. A NetEventXxx event that is indicated with a NULL ProtocolBindingContext applies to all bindings. NetEventBindList and NetEventBindsComplete are always indicated with a NULL ProtocolBindingContext. NetEventReconfigure can be indicated with a specified ProtocolBindingContext or with a NULL ProtocolBindingContext.
  • NetPnPEvent
    A pointer to a NET_PNP_EVENT_NOTIFICATION structure which describes the Plug and Play event or Power Management event that NDIS is indicating to the protocol driver.

Return Value

ProtocolNetPnPEvent can return any of the following:

Value

Description

NDIS_STATUS_SUCCESS

The protocol driver successfully handled the indicated network Plug and Play event, NDIS PnP event, or power management event. The meaning of this status code depends on the NetEvent code in the buffered NET_PNP_EVENT_NOTIFICATION structure at NetPnPEvent:

NetEventSetPower

The protocol driver has performed any driver-specific actions that are required to prepare for the device's transition to the requested device power state.

NetEventQueryPower

The underlying adapter can transition to the requested device power state.

NetEventQueryRemoveDevice

The underlying adapter can be removed.

NetEventCancelRemoveDevice

The protocol driver has performed any driver-specific actions that are required to prepare for the canceled removal of the underlying adapter.

NetEventReconfigure

The protocol driver has accepted the changed configuration.

NetEventBindList

The protocol driver has the new bind list and has performed related processing.

NetEventBindsComplete

The protocol driver has acknowledged the indication from NDIS that the protocol driver is bound to all available underlying adapters.

NetEventPnPCapabilities

The protocol driver has acknowledged that the wake-up capabilities of the underlying adapter that is associated with the specified binding have changed.

NetEventPause

The specified protocol binding has entered the Pausing state. The binding will enter the Paused state after NDIS has completed all the outstanding send requests for the binding.

NetEventRestart

The specified protocol binding has entered the Restarting state. After the protocol driver is ready to resume send and receive operations for the binding, the binding enters the Running state.

NetEventPortActivation

The protocol driver has acknowledged the activation of a port that is associated with the specified binding.

NetEventPortDeactivation

The protocol driver has acknowledged the activation of a port that is associated with the specified binding.

NDIS_STATUS_PENDING

The protocol driver will return its response to the indicated event asynchronously with a call to the NdisCompleteNetPnPEvent function.

NDIS_STATUS_RESOURCES

The protocol driver could not obtain the necessary system resources to satisfy the indicated Plug and Play or Power Management event.

NDIS_STATUS_NOT_SUPPORTED

NDIS 6.0 protocol drivers must not return this status. A pre-NDIS 6.0 protocol driver that does not support Plug and Play can return this status in response to a NetEventSetPower to indicate that NDIS should unbind it from the underlying adapter.

NDIS_STATUS_FAILURE

The protocol driver failed the indicated event for reasons other than those stated in the previous list.

A protocol driver can fail the NetEventQueryRemoveDevice, NetEventRestart, or NetEventPortActivation events.

If a protocol driver fails the NetEventRestart event for a binding, the binding remains in the Paused state. The protocol driver should support only the operations that are allowed in the Paused state.

If a protocol driver fails the NetEventPortActivation event, it should not use any associated ports in later operations.

A protocol driver should always succeed the NetEventIMReEnableDevice, NetEventCancelRemoveDevice, NetEventReconfigure, NetEventBindList¸ NetEventBindsComplete, NetEventPause, NetEventPortDeactivation, or NetEventPnPCapabilities events by returning NDIS_STATUS_SUCCESS.

Remarks

The ProtocolNetPnPEvent function is required in protocol drivers to support Plug and Play and Power Management. NDIS calls ProtocolNetPnPEvent to notify a protocol driver that a network Plug and Play event, an NDIS PnP event, or Power Management event has occurred.

The NET_PNP_EVENT_NOTIFICATION structure that is passed to ProtocolNetPnPEvent describes the event. ProtocolNetPnPEvent interprets two basic pieces of information in the NET_PNP_EVENT_NOTIFICATION structure:

  • A code in the NetEvent member that identifies the type of Plug and Play or Power Management event.
  • Event-specific information. For example, with a NetEventSetPower event the Buffer member contains the device power state to which the device is transitioning.

The protocol driver should save the NetPnPEvent pointer. This pointer is a required input parameter to the NdisCompleteNetPnPEvent function, which the protocol driver must subsequently call if ProtocolNetPnPEvent returns NDIS_STATUS_PENDING.

A protocol driver should always succeed a NetEventQueryPower event. After establishing an active connection, a protocol driver can call the PoRegisterSystemState function to register a continuously busy state. As long as the state registration is in effect, the power manager does not attempt to put the system to sleep. After the connection becomes inactive, the protocol driver cancels the state registration by calling the PoUnregisterSystemState function. A protocol driver should never try to prevent the system from transitioning to the sleeping state by failing a NetEventQueryPower event. Note that a NetEventQueryPower event is always followed by a NetEventSetPower event. A NetEventSetPower event that specifies the underlying device's current power state in effect cancels the NetEventQueryPower event.

If a protocol driver cannot release a device (for example, because the device is being used) it must fail a NetEventQueryRemoveDevice event by returning NDIS_STATUS_FAILURE.

A protocol driver should always succeed a NetEventCancelRemoveDevice, a NetEventReconfigure, NetEventBindList¸ NetEventBindsComplete, NetEventPnPCapabilities, NetEventPause, or NetEventPortDeactivation by returning NDIS_STATUS_SUCCESS.

When handling a NetEventReconfigure or a NetEventBindList, a protocol driver should validate the data associated with the event. For more information about such data, see NET_PNP_EVENT_NOTIFICATION.

NDIS calls ProtocolNetPnPEvent at IRQL = PASSIVE_LEVEL.

See Also

Reference

NDIS Protocol Driver Functions
NET_PNP_EVENT_NOTIFICATION
NdisCompleteNetPnPEvent
NdisOpenAdapterEx