PROTOCOL_NET_PNP_EVENT função de retorno de chamada (ndis.h)

Artigo
08/07/2023

O NDIS chama a função ProtocolNetPnPEvent para indicar um evento de Plug and Play de rede, um evento NDIS PnP ou um evento de gerenciamento de energia para um driver de protocolo.

Nota Você deve declarar a função usando o tipo PROTOCOL_NET_PNP_EVENT . Para obter mais informações, consulte a seção Exemplos a seguir.

Sintaxe

PROTOCOL_NET_PNP_EVENT ProtocolNetPnpEvent;

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

Parâmetros

[in] ProtocolBindingContext

O identificador para uma área de contexto alocada pelo driver de protocolo na qual esse driver mantém informações de estado de tempo de execução por associação. O driver de protocolo forneceu esse identificador quando chamou a função NdisOpenAdapterEx . Um evento NetEventXxx que é indicado com um Protocolo NULLBindingContext se aplica a todas as associações. NetEventBindList e NetEventBindsComplete são sempre indicados com um Protocolo NULLBindingContext. NetEventReconfigure pode ser indicado com um ProtocolBindingContext especificado ou com um Protocolo NULLBindingContext.

[in] NetPnPEventNotification

Um ponteiro para um NET_PNP_EVENT_NOTIFICATION estrutura que descreve o evento Plug and Play ou o evento de Gerenciamento de Energia que o NDIS está indicando para o driver de protocolo.

Retornar valor

ProtocolNetPnPEvent pode retornar qualquer um dos seguintes:

Código de retorno	Descrição
NDIS_STATUS_SUCCESS	O driver de protocolo lidou com êxito com o evento de Plug and Play de rede indicado, o evento NDIS PnP ou o evento de gerenciamento de energia. O significado desse código status depende do código NetEvent no buffer NET_PNP_EVENT_NOTIFICATION estrutura no NetPnPEvent: NetEventSetPower O driver de protocolo executou todas as ações específicas do driver necessárias para se preparar para a transição do dispositivo para o estado de energia do dispositivo solicitado. NetEventQueryPower O adaptador subjacente pode fazer a transição para o estado de energia do dispositivo solicitado. NetEventQueryRemoveDevice O adaptador subjacente pode ser removido. NetEventCancelRemoveDevice O driver de protocolo executou todas as ações específicas do driver necessárias para se preparar para a remoção cancelada do adaptador subjacente. NetEventReconfigure O driver de protocolo aceitou a configuração alterada. NetEventBindList O driver de protocolo tem a nova lista de associações e executou o processamento relacionado. NetEventBindsComplete O driver de protocolo reconheceu a indicação do NDIS de que o driver de protocolo está associado a todos os adaptadores subjacentes disponíveis. NetEventPnPCapabilities O driver de protocolo reconheceu que recebeu os recursos atuais de ativação do adaptador subjacente associado à associação especificada. NetEventPause A associação de protocolo especificada inseriu o estado Pausar . A associação entrará no estado Pausado depois que o NDIS concluir todas as solicitações de envio pendentes para a associação. Para obter mais informações sobre operações de pausa, consulte Pausando uma associação. NetEventRestart A associação de protocolo especificada inseriu o estado De reinicialização . Depois que o driver de protocolo estiver pronto para retomar as operações de envio e recebimento da associação, a associação entrará no estado Em execução. NetEventPortActivation O driver de protocolo reconheceu a ativação de uma porta associada à associação especificada. Para obter mais informações sobre ativação de porta, consulte Ativando uma porta NDIS. NetEventPortDeactivation O driver de protocolo reconheceu a ativação de uma porta associada à associação especificada.
NDIS_STATUS_PENDING	O driver de protocolo retornará sua resposta ao evento indicado de forma assíncrona com uma chamada para o Função NdisCompleteNetPnPEvent .
NDIS_STATUS_RESOURCES	O driver de protocolo não pôde obter os recursos do sistema necessários para atender ao evento indicado Plug and Play ou Power Management.
NDIS_STATUS_NOT_SUPPORTED	Os drivers de protocolo NDIS 6.0 e posteriores não devem retornar esse status. Um NDIS 5. O driver de protocolo x que não dá suporte a Plug and Play pode retornar esse status em resposta a um NetEventSetPower para indicar que o NDIS deve desassociá-lo do adaptador subjacente.
NDIS_STATUS_FAILURE	O driver de protocolo falhou no evento indicado por motivos diferentes daqueles indicados na lista anterior.

Um driver de protocolo pode falhar nos eventos NetEventQueryRemoveDevice e NetEventPortActivation .

Se um driver de protocolo falhar no evento NetEventPortActivation , ele não deverá usar nenhuma porta associada em operações subsequentes.

Um driver de protocolo sempre deve ter sucesso nos eventos NetEventRestart, NetEventIMReEnableDevice, NetEventCancelRemoveDevice, NetEventReconfigure, NetEventBindList, NetEventBindsComplete, NetEventPause, NetEventPortDeactivation e NetEventPnPCapabilities retornando NDIS_STATUS_SUCCESS.

Comentários

A função ProtocolNetPnPEvent é necessária em drivers de protocolo para dar suporte a Plug and Play e Ao Gerenciamento de Energia. O NDIS chama ProtocolNetPnPEvent para notificar um driver de protocolo de que ocorreu um evento de Plug and Play de rede, um evento NDIS PnP ou power management.

O NET_PNP_EVENT_NOTIFICATION estrutura passada para ProtocolNetPnPEvent descreve o evento. ProtocolNetPnPEvent interpreta duas informações básicas na estrutura NET_PNP_EVENT_NOTIFICATION:

Um código no membro NetEvent que identifica o tipo de evento Plug and Play ou Power Management.
Informações específicas do evento. Por exemplo, com um evento NetEventSetPower , o membro Buffer contém o estado de energia do dispositivo para o qual o dispositivo está em transição.

O driver de protocolo deve salvar o ponteiro NetPnPEvent . Esse ponteiro é um parâmetro de entrada necessário para a função NdisCompleteNetPnPEvent , que o driver de protocolo deve chamar posteriormente se ProtocolNetPnPEvent retornar NDIS_STATUS_PENDING.

Um driver de protocolo sempre deve ter êxito em um evento NetEventQueryPower . Depois de estabelecer uma conexão ativa, um driver de protocolo pode chamar a função PoRegisterSystemState para registrar um estado continuamente ocupado. Enquanto o registro de estado estiver em vigor, o power manager não tentará colocar o sistema em suspensão. Depois que a conexão se torna inativa, o driver de protocolo cancela o registro de estado chamando a função PoUnregisterSystemState . Um driver de protocolo nunca deve tentar impedir que o sistema faça a transição para o estado de suspensão falhando em um evento NetEventQueryPower . Observe que um evento NetEventQueryPower é sempre seguido por um evento NetEventSetPower . Um evento NetEventSetPower que especifica o estado de energia atual do dispositivo subjacente, na verdade, cancela o evento NetEventQueryPower .

Se um driver de protocolo não puder liberar um dispositivo (por exemplo, porque o dispositivo está em uso), ele deverá falhar em um evento NetEventQueryRemoveDevice retornando NDIS_STATUS_FAILURE.

Um driver de protocolo sempre deve ter sucesso em Um NetEventCancelRemoveDevice, um NetEventReconfigure, NetEventBindList, NetEventBindsComplete, NetEventPnPCapabilities, NetEventPause ou NetEventPortDeactivation retornando NDIS_STATUS_SUCCESS.

Ao manipular um NetEventReconfigure ou um NetEventBindList, um driver de protocolo deve validar os dados associados ao evento. Para obter mais informações sobre esses dados, consulte NET_PNP_EVENT_NOTIFICATION.

O NDIS chama ProtocolNetPnPEvent em IRQL = PASSIVE_LEVEL.

Exemplos

Para definir uma função ProtocolNetPnPEvent , primeiro você deve fornecer uma declaração de função que identifique o tipo de função que você está definindo. O Windows fornece um conjunto de tipos de função para drivers. Declarar uma função usando os tipos de função ajuda a Análise de Código para Drivers, SDV ( Verificador de Driver Estático ) e outras ferramentas de verificação a encontrar erros e é um requisito para gravar drivers para o sistema operacional Windows.

Por exemplo, para definir uma função ProtocolNetPnPEvent chamada "MyNetPnPEvent", use o tipo PROTOCOL_NET_PNP_EVENT conforme mostrado neste exemplo de código:

PROTOCOL_NET_PNP_EVENT MyNetPnPEvent;

Em seguida, implemente sua função da seguinte maneira:

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

O tipo de função PROTOCOL_NET_PNP_EVENT é definido no arquivo de cabeçalho Ndis.h. Para identificar erros com mais precisão ao executar as ferramentas de análise de código, adicione a anotação Use_decl_annotations à sua definição de função. A anotação Use_decl_annotations garante que as anotações aplicadas ao tipo de função PROTOCOL_NET_PNP_EVENT no arquivo de cabeçalho sejam usadas. Para obter mais informações sobre os requisitos para declarações de função, consulte Declarando funções usando tipos de função de função para drivers NDIS.

Para obter informações sobre Use_decl_annotations, consulte Anotando o comportamento da função.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Com suporte no NDIS 6.0 e posterior.
Plataforma de Destino	Windows
Cabeçalho	ndis.h (inclua Ndis.h)
IRQL	PASSIVE_LEVEL