PROTOCOL_NET_PNP_EVENT función de devolución de llamada (ndis.h)
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.
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 |
|---|---|
|
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:
|
|
El controlador de protocolo devolverá su respuesta al evento indicado de forma asincrónica con una llamada a . Función NdisCompleteNetPnPEvent . |
|
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. |
|
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. |
|
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.
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 |