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

Artigo
03/08/2023

O NDIS chama a função FilterAttach de um driver de filtro para alocar e inicializar as estruturas de dados de um módulo de filtro.

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

Sintaxe

FILTER_ATTACH FilterAttach;

NDIS_STATUS FilterAttach(
  [in] NDIS_HANDLE NdisFilterHandle,
  [in] NDIS_HANDLE FilterDriverContext,
  [in] PNDIS_FILTER_ATTACH_PARAMETERS AttachParameters
)
{...}

Parâmetros

[in] NdisFilterHandle

Um identificador NDIS que identifica um módulo de filtro. O driver de filtro deve salvar esse identificador. O identificador é necessário em chamadas subsequentes para funções NdisFXxx .

[in] FilterDriverContext

O identificador que o driver passou para o Função NdisFRegisterFilterDriver que identifica a área de contexto do driver.

[in] AttachParameters

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

Retornar valor

FilterAttach retorna um dos seguintes valores de status:

Código de retorno	Descrição
NDIS_STATUS_SUCCESS	FilterAttach alocou e inicializou estruturas de dados com êxito para este módulo de filtro.
NDIS_STATUS_RESOURCES	Falha em FilterAttach devido a recursos insuficientes.
NDIS_STATUS_FAILURE	FilterAttach retornará NDIS_STATUS_FAILURE se nenhum dos valores anteriores se aplicar. O driver de filtro deve chamar a função NdisWriteEventLogEntry junto com parâmetros que especificam o motivo da falha.

Comentários

FilterAttach é uma função necessária. O NDIS chama a função FilterAttach de um driver de filtro quando o módulo de filtro especificado está no estado Desanexado . O NDIS pode chamar FilterAttach a qualquer momento após a chamada para a função FilterSetOptions retornar.

No início da execução em FilterAttach, o módulo de filtro entra no estado Anexando .

Os drivers de filtro devem evitar a emissão de consultas OID desnecessárias. Em vez disso, use as informações em NDIS_FILTER_ATTACH_PARAMETERS, quando disponível, obter informações sobre drivers subjacentes.

Um driver de filtro executa as seguintes operações quando o NDIS chama FilterAttach.

Cria uma área de contexto para o módulo de filtro e aloca pools de buffers e outros recursos.
Chama a função NdisFSetAttributes junto com o NdisFilterHandle que o NDIS passou para FilterAttach. O parâmetro FilterModuleContext de NdisFSetAttributes especifica a área de contexto do driver de filtro para este módulo de filtro. O NDIS passa essa área de contexto para as funções FilterXxx do driver de filtro.
Opcionalmente, lê parâmetros de configuração do registro.
Se as operações anteriores forem concluídas com êxito, o módulo de filtro entrará no estado Pausado .
Se as operações anteriores falharem, o driver de filtro deverá liberar todos os recursos alocados na função FilterAttach e retornar o módulo de filtro para o estado Desanexado .
Retorna NDIS_STATUS_SUCCESS ou um código de falha apropriado.

Um driver de filtro não deve fazer solicitações de envio, indicar dados recebidos, fazer solicitações OID ou fazer status indicações do estado Anexação.

O NDIS chama a função FilterDetach de um driver de filtro para liberar todos os recursos associados a um módulo de filtro e retornar o módulo de filtro para o estado Desanexado .

O NDIS chama FilterAttach em IRQL = PASSIVE_LEVEL.

Exemplos

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

FILTER_ATTACH MyAttach;

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

_Use_decl_annotations_
NDIS_STATUS
 MyAttach(
    NDIS_HANDLE  NdisFilterHandle,
    NDIS_HANDLE  FilterDriverContext,
    PNDIS_FILTER_ATTACH_PARAMETERS  AttachParameters
    )
  {...}

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