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

Artigo
02/07/2025

O NDIS chama a função FilterOidRequest de um driver de filtro para processar uma solicitação OID associada ao módulo de filtro especificado.

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

Sintaxe

FILTER_OID_REQUEST FilterOidRequest;

NDIS_STATUS FilterOidRequest(
  [in] NDIS_HANDLE FilterModuleContext,
  [in] PNDIS_OID_REQUEST OidRequest
)
{...}

Parâmetros

[in] FilterModuleContext

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

[in] OidRequest

Um ponteiro para uma estrutura de NDIS_OID_REQUEST que especifica a operação solicitada, incluindo o códigoXXX OID_. A estrutura pode especificar uma solicitação de consulta OID ou uma solicitação de conjunto de OID. Para obter mais informações sobre OIDs, consulte OIDs do NDIS.

Valor de retorno

FilterOidRequest retorna um dos seguintes valores de status:

Código de retorno	Descrição
NDIS_STATUS_SUCCESS	FilterOidRequest concluiu com êxito a consulta do driver de filtro ou a operação definida para este módulo de filtro.
NDIS_STATUS_PENDING	Indica que o driver de filtro concluirá a solicitação de forma assíncrona. Depois que o driver concluir a solicitação, ele deverá chamar o função NdisFOidRequestComplete para informar ao NDIS que a solicitação está concluída.
NDIS_STATUS_INVALID_OID	Indica que a solicitação, especificada em OidRequest, é inválida ou não reconhecida.
NDIS_STATUS_NOT_SUPPORTED	FilterOidRequest não dá suporte à OID, o OID é opcional.
NDIS_STATUS_BUFFER_TOO_SHORT	Indica que o buffer, fornecido em OidRequest, é muito pequeno para armazenar os dados solicitados.
NDIS_STATUS_INVALID_LENGTH	Para uma operação de consulta, o InformationBufferLength membro da estrutura NDIS_OID_REQUEST não corresponde ao comprimento exigido pela OID fornecida. FilterOidRequest retornou o tamanho do buffer necessário, em bytes, no membro bytesNeeded da estrutura NDIS_OID_REQUEST.
NDIS_STATUS_INVALID_DATA	Para uma operação de conjunto, os dados fornecidos no InformationBuffer membro da estrutura NDIS_OID_REQUEST era inválido para o OID fornecido.
NDIS_STATUS_NOT_ACCEPTED	FilterOidRequest tentou coletar as informações solicitadas, mas não teve êxito.
NDIS_STATUS_RESOURCES	FilterOidRequest falhou devido a recursos insuficientes.
NDIS_STATUS_FAILURE	FilterOidRequest retornará NDIS_STATUS_FAILURE se nenhum dos valores anteriores se aplicar. O driver de filtro deve chamar a função NdisWriteErrorLogEntry com parâmetros que especificam o motivo da falha.

Observações

FilterOidRequest é uma função opcional. Se um driver de filtro não usar solicitações OID, ele poderá definir o ponto de entrada para essa função para NULL ao chamar a função NdisFRegisterFilterDriver. Se um driver de filtro definir uma função FilterOidRequestComplete, ele deverá fornecer a função FilterOidRequest.

O NDIS chama a função FilterOidRequest do driver de filtro para processar solicitações OID originadas por drivers sobrepostos. Os drivers de filtro podem encaminhar essas solicitações para drivers subjacentes chamando a função NdisFOidRequest.

Antes que o driver chame NdisFOidRequest, o driver deve alocar uma estrutura NDIS_OID_REQUEST e transferir as informações de solicitação para a nova estrutura chamando NdisAllocateCloneOidRequest. Como opção, um driver de filtro pode concluir uma solicitação imediatamente sem encaminhar a solicitação.

Para concluir uma solicitação de forma síncrona, o driver de filtro retorna NDIS_STATUS_SUCCESS ou um status de falha. Se o driver retornar NDIS_STATUS_PENDING, ele deverá chamar a função NdisFOidRequestComplete para informar ao NDIS que a solicitação está concluída.

Para uma operação de consulta, FilterOidRequest retorna as informações solicitadas no membro InformationBuffer e define a variável no membro BytesWritten da estrutura NDIS_OID_REQUEST à quantidade de informações retornadas. Os drivers subjacentes fazem isso se o driver de filtro passou a solicitação com NdisFOidRequest.

Para uma operação definida, FilterOidRequest pode usar os dados no InformationBuffer membro da estrutura NDIS_OID_REQUEST para definir as informações necessárias para o OID fornecido. Nesse caso, FilterOidRequest define a variável em bytesRead para a quantidade dos dados fornecidos que ele usou. Os drivers subjacentes fazem isso se o driver de filtro passou a solicitação com NdisFOidRequest.

Assim como os drivers de miniporto, os drivers de filtro podem receber apenas uma solicitação por vez. O NDIS serializa as solicitações enviadas a um driver de filtro. O NDIS não pode chamar FilterOidRequest antes que um driver de filtro conclua a solicitação atual.

Chamadas de NDIS FilterOidRequest no IRQL <= DISPATCH_LEVEL.

exemplos de

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

FILTER_OID_REQUEST MyOidRequest;

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

_Use_decl_annotations_
NDIS_STATUS
 MyOidRequest(
    NDIS_HANDLE  FilterModuleContext,
    PNDIS_OID_REQUEST  OidRequest
    )
  {...}

O tipo de função FILTER_OID_REQUEST é 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_OID_REQUEST 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
de cliente com suporte mínimo	Com suporte no NDIS 6.0 e posterior.
da Plataforma de Destino	Windows
cabeçalho	ndis.h (inclua Ndis.h)
IRQL	<= DISPATCH_LEVEL