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

Artigo
02/27/2024

A função FilterRestart inicia uma operação de reinicialização para o módulo de filtro especificado.

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

Sintaxe

FILTER_RESTART FilterRestart;

NDIS_STATUS FilterRestart(
  [in] NDIS_HANDLE FilterModuleContext,
  [in] PNDIS_FILTER_RESTART_PARAMETERS RestartParameters
)
{...}

Parâmetros

[in] FilterModuleContext

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

[in] RestartParameters

Um ponteiro para um NDIS_FILTER_RESTART_PARAMETERS estrutura que define os parâmetros de reinicialização para o módulo de filtro.

Retornar valor

FilterRestart retorna um dos seguintes valores de status:

Código de retorno	Descrição
NDIS_STATUS_SUCCESS	FilterRestart reiniciou com êxito o 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 NdisFRestartComplete depois de concluir a operação de reinicialização.
NDIS_STATUS_RESOURCES	Falha de FilterRestart devido a recursos insuficientes.
NDIS_STATUS_FAILURE	Nenhum dos valores de status anteriores se aplica. O driver de filtro deve chamar a função NdisWriteEventLogEntry junto com parâmetros que especificam o motivo da falha.

Comentários

FilterRestart é uma função necessária para drivers de filtro. O NDIS pode chamar FilterRestart quando um módulo de filtro está no estado Pausado . O módulo de filtro entra no estado Reiniciando no início da execução de FilterRestart.

Quando o NDIS chama FilterRestart, um driver de filtro:

Deve concluir as operações necessárias para reiniciar as operações normais de envio e recebimento.
Opcionalmente, lê ou grava parâmetros de configuração.
Opcionalmente, realoca pools de buffers.
Opcionalmente, modifica os atributos de reinicialização especificados no membro RestartAttributes do NDIS_FILTER_RESTART_PARAMETERS estrutura. Se o ponteiro em RestartAttributes for NULL, o driver de filtro não deverá modificar nem adicionar à lista de atributos de reinicialização. Se o ponteiro em RestartAttributes não for NULL, ele apontará para o primeiro NDIS_RESTART_ATTRIBUTES estrutura na lista de atributos de reinicialização. Se um driver de filtro não for reiniciado, ele não deverá modificar nenhum atributo.
Opcionalmente, usa solicitações OID para consultar ou definir informações nos drivers subjacentes. Os drivers de filtro não devem emitir solicitações de OID para obter informações que já estão fornecidas na lista de atributos de reinicialização.
Retorna NDIS_STATUS_SUCCESS ou uma status de falha.

Se um driver de filtro modificar a lista de atributos de reinicialização, o driver de filtro:

Não deve modificar nenhum atributo específico de mídia se ele não reconhecer o OID no membro Oid do NDIS_RESTART_ATTRIBUTES estrutura.
Pode adicionar novos atributos específicos de mídia à lista de atributos de reinicialização. Nessa situação, o driver de filtro deve alocar uma nova estrutura de NDIS_RESTART_ATTRIBUTES , por exemplo, com o Função NdisAllocateMemoryWithTagPriority e fornecem espaço de memória para os novos atributos. Depois de propagar os atributos de reinicialização para drivers de sobreposição, o NDIS libera a memória de atributos para drivers de filtro.
Pode modificar os atributos específicos da mídia na lista de atributos de reinicialização. Se o driver de filtro exigir mais espaço de memória, ele poderá liberar a estrutura NDIS_RESTART_ATTRIBUTES com a função NdisFreeMemory e alocar uma nova estrutura para conter as informações modificadas. Depois de propagar os atributos de reinicialização para drivers de sobreposição, o NDIS libera a memória de atributos para drivers de filtro.
Deve, se o membro Oid na estrutura NDIS_RESTART_ATTRIBUTES for OID_GEN_MINIPORT_RESTART_ATTRIBUTES, certifique-se de que o NDIS_RESTART_GENERAL_ATTRIBUTES estrutura contém as informações que o driver de filtro requer. Para garantir que a estrutura NDIS_RESTART_GENERAL_ATTRIBUTES contenha as informações necessárias, você deve marcar o membro Revision na estrutura NDIS_OBJECT_HEADER especificada no membro Header da estrutura NDIS_RESTART_GENERAL_ATTRIBUTES.
Nota Um driver de filtro pode modificar qualquer membro na estrutura NDIS_RESTART_GENERAL_ATTRIBUTES. Se alguns atributos que o driver de filtro deve modificar não forem incluídos na revisão da estrutura fornecida pelo NDIS, o driver de filtro deverá depender de drivers sobrepostos para emitir solicitações OID para os atributos ausentes. O driver de filtro pode modificar os atributos quando conclui a solicitação OID.
Deve, se o driver de filtro alterar os atributos de reinicialização, fornecer uma função FilterOidRequest . O driver de filtro deve garantir que as informações que os drivers sobrepostos recebem nos atributos de reinicialização sejam consistentes com as informações recebidas em resposta às solicitações de OID.

Depois que o driver de filtro retorna seu status ou chama a função NdisFRestartComplete, a operação de reinicialização é concluída. Se a operação for concluída com êxito, o módulo de filtro estará no estado Em execução e o processamento normal de envio e recebimento será retomado. Se a operação de reinicialização falhar, o módulo de filtro retornará ao estado Pausado .

O NDIS chama FilterRestart em IRQL = PASSIVE_LEVEL.

Exemplos

Para definir uma função FilterRestart , 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 escrever drivers para o sistema operacional Windows.

Por exemplo, para definir uma função FilterRestart chamada "MyRestart", use o tipo FILTER_RESTART conforme mostrado neste exemplo de código:

FILTER_RESTART MyRestart;

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

_Use_decl_annotations_
NDIS_STATUS
 MyRestart(
    NDIS_HANDLE  FilterModuleContext,
    PNDIS_FILTER_RESTART_PARAMETERS  FilterRestartParameters
    )
  {...}

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