PROTOCOL_NET_PNP_EVENT función de devolución de llamada (ndis.h)

Artículo
08/07/2023

NDIS llama a la función ProtocolNetPnPEvent para indicar un evento de Plug and Play de red, un evento PnP de NDIS o un evento de administración de energía a un controlador de protocolo.

Nota Debe declarar la función mediante el tipo PROTOCOL_NET_PNP_EVENT . Para obtener más información, consulte la sección Ejemplos siguientes.

Sintaxis

PROTOCOL_NET_PNP_EVENT ProtocolNetPnpEvent;

NDIS_STATUS ProtocolNetPnpEvent(
  [in] NDIS_HANDLE ProtocolBindingContext,
  [in] PNET_PNP_EVENT_NOTIFICATION NetPnPEventNotification
)
{...}

Parámetros

[in] ProtocolBindingContext

Identificador de un área de contexto asignada por el controlador de protocolo en la que este controlador mantiene información de estado en tiempo de ejecución por enlace. El controlador de protocolo proporcionó este identificador cuando llamó a la función NdisOpenAdapterEx . Un evento NetEventXxx que se indica con un ProtocolBindingContextNULL se aplica a todos los enlaces. NetEventBindList y NetEventBindsComplete siempre se indican con un ProtocolBindingContextNULL. NetEventReconfigure se puede indicar con un ProtocolBindingContext especificado o con un ProtocolBindingContextNULL.

[in] NetPnPEventNotification

Puntero a NET_PNP_EVENT_NOTIFICATION estructura que describe el evento Plug and Play o el evento de administración de energía que NDIS indica al controlador de protocolo.

Valor devuelto

ProtocolNetPnPEvent puede devolver cualquiera de las siguientes opciones:

Código devuelto	Descripción
NDIS_STATUS_SUCCESS	El controlador de protocolo controló correctamente el evento de Plug and Play de red indicado, el evento PnP de NDIS o el evento de administración de energía. El significado de este código de estado depende del código netEvent en el almacenado en búfer. NET_PNP_EVENT_NOTIFICATION estructura en NetPnPEvent: NetEventSetPower El controlador de protocolo ha realizado todas las acciones específicas del controlador necesarias para preparar la transición del dispositivo al estado de alimentación del dispositivo solicitado. NetEventQueryPower El adaptador subyacente puede pasar al estado de alimentación del dispositivo solicitado. NetEventQueryRemoveDevice Se puede quitar el adaptador subyacente. NetEventCancelRemoveDevice El controlador de protocolo ha realizado cualquier acción específica del controlador necesaria para prepararse para la eliminación cancelada del adaptador subyacente. NetEventReconfigure El controlador de protocolo ha aceptado la configuración modificada. NetEventBindList El controlador de protocolo tiene la nueva lista de enlaces y ha realizado el procesamiento relacionado. NetEventBindsComplete El controlador de protocolo ha confirmado la indicación de NDIS de que el controlador de protocolo está enlazado a todos los adaptadores subyacentes disponibles. NetEventPnPCapabilities El controlador de protocolo ha confirmado que ha recibido las funcionalidades de reactivación actuales del adaptador subyacente asociado al enlace especificado. NetEventPause El enlace de protocolo especificado ha entrado en el estado de pausa . El enlace entrará en el estado Pausado después de que NDIS haya completado todas las solicitudes de envío pendientes para el enlace. Para obtener más información sobre las operaciones de pausa, consulte Pausar un enlace. NetEventRestart El enlace de protocolo especificado ha entrado en el estado Reinicio . Después de que el controlador de protocolo esté listo para reanudar las operaciones de envío y recepción del enlace, el enlace entra en estado En ejecución . NetEventPortActivation El controlador de protocolo ha confirmado la activación de un puerto asociado al enlace especificado. Para obtener más información sobre la activación de puertos, consulte Activación de un puerto NDIS. NetEventPortDeactivation El controlador de protocolo ha confirmado la activación de un puerto asociado al enlace especificado.
NDIS_STATUS_PENDING	El controlador de protocolo devolverá su respuesta al evento indicado de forma asincrónica con una llamada a . Función NdisCompleteNetPnPEvent .
NDIS_STATUS_RESOURCES	El controlador de protocolo no pudo obtener los recursos del sistema necesarios para satisfacer el evento indicado Plug and Play o Administración de energía.
NDIS_STATUS_NOT_SUPPORTED	Los controladores de protocolo NDIS 6.0 y versiones posteriores no deben devolver este estado. NDIS 5. El controlador de protocolo x que no admite Plug and Play puede devolver este estado en respuesta a netEventSetPower para indicar que NDIS debe desenlacerlo del adaptador subyacente.
NDIS_STATUS_FAILURE	El controlador de protocolo produjo un error en el evento indicado por motivos distintos de los indicados en la lista anterior.

Un controlador de protocolo puede producir un error en los eventos NetEventQueryRemoveDevice y NetEventPortActivation .

Si un controlador de protocolo produce un error en el evento NetEventPortActivation , no debe usar ningún puerto asociado en las operaciones posteriores.

Un controlador de protocolo siempre debe tener éxito en los eventos NetEventRestart, NetEventIMReEnableDevice, NetEventCancelRemoveDevice, NetEventReconfigure, NetEventBindsComplete, NetEventPause, NetEventPortDeactivation y NetEventPnPCapabilities devolviendo NDIS_STATUS_SUCCESS.

Comentarios

La función ProtocolNetPnPEvent es necesaria en los controladores de protocolo para admitir Plug and Play y administración de energía. NDIS llama a ProtocolNetPnPEvent para notificar a un controlador de protocolo que se ha producido un evento de Plug and Play de red, un evento PnP de NDIS o un evento de administración de energía.

The NET_PNP_EVENT_NOTIFICATION estructura que se pasa a ProtocolNetPnPEvent describe el evento. ProtocolNetPnPEvent interpreta dos fragmentos básicos de información en la estructura de NET_PNP_EVENT_NOTIFICATION:

Código del miembro NetEvent que identifica el tipo de Plug and Play o evento de administración de energía.
Información específica del evento. Por ejemplo, con un evento NetEventSetPower , el miembro Buffer contiene el estado de alimentación del dispositivo al que realiza la transición el dispositivo.

El controlador de protocolo debe guardar el puntero NetPnPEvent . Este puntero es un parámetro de entrada necesario para la función NdisCompleteNetPnPEvent , que el controlador de protocolo debe llamar posteriormente si ProtocolNetPnPEvent devuelve NDIS_STATUS_PENDING.

Un controlador de protocolo siempre debe tener éxito en un evento NetEventQueryPower . Después de establecer una conexión activa, un controlador de protocolo puede llamar a la función PoRegisterSystemState para registrar un estado ocupado continuamente. Siempre que el registro de estado esté en vigor, el administrador de energía no intenta poner el sistema en suspensión. Una vez inactiva la conexión, el controlador de protocolo cancela el registro de estado mediante una llamada a la función PoUnregisterSystemState . Un controlador de protocolo nunca debe intentar evitar que el sistema realice la transición al estado de suspensión mediante un error en un evento NetEventQueryPower . Tenga en cuenta que un evento NetEventQueryPower siempre va seguido de un evento NetEventSetPower . Un evento NetEventSetPower que especifica el estado de energía actual del dispositivo subyacente en vigor cancela el evento NetEventQueryPower .

Si un controlador de protocolo no puede liberar un dispositivo (por ejemplo, porque el dispositivo está en uso), debe producir un error en un evento NetEventQueryRemoveDevice devolviendo NDIS_STATUS_FAILURE.

Un controlador de protocolo siempre debe tener éxito en netEventCancelRemoveDevice, netEventReconfigure, NetEventBindList, NetEventBindsComplete, NetEventPnPCapabilities, NetEventPause o NetEventPortDeactivation devolviendo NDIS_STATUS_SUCCESS.

Al controlar netEventReconfigure o NetEventBindList, un controlador de protocolo debe validar los datos asociados al evento. Para obtener más información sobre estos datos, consulte NET_PNP_EVENT_NOTIFICATION.

NDIS llama a ProtocolNetPnPEvent en IRQL = PASSIVE_LEVEL.

Ejemplos

Para definir una función ProtocolNetPnPEvent , primero debe proporcionar una declaración de función que identifique el tipo de función que va a definir. Windows proporciona un conjunto de tipos de función para controladores. Declarar una función mediante los tipos de función ayuda a Code Analysis for Drivers, Static Driver Verifier (SDV) y otras herramientas de comprobación a encontrar errores y es un requisito para escribir controladores para el sistema operativo Windows.

Por ejemplo, para definir una función ProtocolNetPnPEvent denominada "MyNetPnPEvent", use el tipo de PROTOCOL_NET_PNP_EVENT como se muestra en este ejemplo de código:

PROTOCOL_NET_PNP_EVENT MyNetPnPEvent;

A continuación, implemente la función de la siguiente manera:

_Use_decl_annotations_
NDIS_STATUS
 MyNetPnPEvent(
    NDIS_HANDLE  ProtocolBindingContext,
    PNET_PNP_EVENT_NOTIFICATION  NetPnPEvent
    )
  {...}

El tipo de función PROTOCOL_NET_PNP_EVENT se define en el archivo de encabezado Ndis.h. Para identificar con más precisión los errores al ejecutar las herramientas de análisis de código, asegúrese de agregar la anotación Use_decl_annotations a la definición de función. La anotación Use_decl_annotations garantiza que se usen las anotaciones que se aplican al tipo de función PROTOCOL_NET_PNP_EVENT en el archivo de encabezado. Para obtener más información sobre los requisitos de las declaraciones de función, consulte Declaración de funciones mediante el uso de tipos de roles de función para controladores NDIS.

Para obtener información sobre Use_decl_annotations, consulte Anotación del comportamiento de la función.

Requisitos

Requisito	Value
Cliente mínimo compatible	Compatible con NDIS 6.0 y versiones posteriores.
Plataforma de destino	Windows
Encabezado	ndis.h (incluya Ndis.h)
IRQL	PASSIVE_LEVEL