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

Artigo
02/26/2024

O NDIS chama a função FilterPause de um driver de filtro para iniciar uma operação de pausa para o módulo de filtro especificado.

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

Sintaxe

FILTER_PAUSE FilterPause;

NDIS_STATUS FilterPause(
  [in] NDIS_HANDLE FilterModuleContext,
  [in] PNDIS_FILTER_PAUSE_PARAMETERS PauseParameters
)
{...}

Parâmetros

[in] FilterModuleContext

Um identificador para a área de contexto do módulo de filtro que o driver de filtro deve pausar. O driver de filtro criou e inicializou essa área de contexto na função FilterAttach .

[in] PauseParameters

Um ponteiro para um NDIS_FILTER_PAUSE_PARAMETERS estrutura que define os parâmetros de pausa para o módulo de filtro.

Retornar valor

Os drivers NDIS não podem falhar em uma solicitação de pausa. O driver de filtro deve chamar a função NdisWriteEventLogEntry junto com parâmetros que especificam o motivo de quaisquer erros que ocorram.

Código de retorno	Descrição
NDIS_STATUS_SUCCESS	FilterPause fez uma pausa com êxito no módulo de filtro especificado.
NDIS_STATUS_PENDING	O driver de filtro concluirá a solicitação de forma assíncrona com uma chamada para a função NdisFPauseComplete .

Comentários

FilterPause é uma função necessária. O NDIS pode chamar FilterPause quando o módulo de filtro estiver no estado Em execução . O módulo de filtro entra no estado Pausar no início da execução na função FilterPause .

Um driver de filtro executa as seguintes operações quando o NDIS chama FilterPause:

Deve chamar o Função NdisFSendNetBufferListsComplete para todos os buffers de envio enfileirados criados por um driver sobreposto.
Deve chamar o A função NdisFReturnNetBufferLists para todos os buffers de recebimento enfileirados criados por um driver subjacente.
Deve aguardar o NDIS retornar todas as solicitações de envio pendentes que o driver originou para o Função FilterSendNetBufferListsComplete .
Deve aguardar o NDIS retornar todas as indicações de recebimento pendentes de que o driver se originou para o Função FilterReturnNetBufferLists .

Depois que o driver de filtro retorna NDIS_STATUS_SUCCESS de FilterPause ou chama a função NdisFPauseComplete , a operação de pausa é concluída. O módulo de filtro está no estado Pausado .

Nos estados Pausar ou Pausar, um driver de filtro deve continuar a lidar com solicitações OID ou status indicações. O driver deve rejeitar chamadas para sua Função FilterSendNetBufferLists . O driver pode passar chamadas para sua Função FilterReceiveNetBufferLists . No entanto, o driver não pode passar nenhum buffer criado. O driver não deve originar nenhuma indicação de recebimento ou enviar solicitações.

No estado Pausado , o módulo de filtro não deve gerar solicitações de envio nem receber indicações.

O NDIS chama a função FilterRestart para iniciar uma solicitação de reinicialização para um módulo de filtro que está no estado Pausado .

O NDIS chama FilterPause em IRQL = PASSIVE_LEVEL.

Exemplos

Para definir uma função FilterPause , 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 FilterPause chamada "MyPause", use o tipo FILTER_PAUSE conforme mostrado neste exemplo de código:

FILTER_PAUSE MyPause;

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

_Use_decl_annotations_
NDIS_STATUS
 MyPause(
    NDIS_HANDLE  FilterModuleContext,
    PNDIS_FILTER_PAUSE_PARAMETERS  FilterPauseParameters
    )
  {...}

O tipo de função FILTER_PAUSE é 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 FILTER_PAUSE 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