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

Artigo
08/07/2023

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.

Nota 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 NDIS_OID_REQUEST que especifica a operação solicitada, incluindo o código OID_XXX . 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.

Retornar valor

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 de definição 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 foi 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 ao OID, o OID é opcional.
NDIS_STATUS_BUFFER_TOO_SHORT	Indica que o buffer, fornecido em OidRequest, é muito pequeno para conter os dados solicitados.
NDIS_STATUS_INVALID_LENGTH	Para uma operação de consulta, o membro InformationBufferLength da estrutura NDIS_OID_REQUEST não corresponde ao comprimento exigido pelo OID fornecido. 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 membro InformationBuffer da estrutura NDIS_OID_REQUEST eram inválidos para o OID fornecido.
NDIS_STATUS_NOT_ACCEPTED	FilterOidRequest tentou coletar as informações solicitadas, mas não teve êxito.
NDIS_STATUS_RESOURCES	Falha em FilterOidRequest 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.

Comentários

FilterOidRequest é uma função opcional. Se um driver de filtro não usar solicitações OID, ele poderá definir o ponto de entrada dessa função como NULL quando 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 uma falha status. Se o driver retornar NDIS_STATUS_PENDING, ele deverá chamar a função NdisFOidRequestComplete para informar ao NDIS que a solicitação foi 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 para a 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 de conjunto, FilterOidRequest pode usar os dados no membro InformationBuffer da estrutura NDIS_OID_REQUEST para definir as informações exigidas pelo OID fornecido. Nesse caso, FilterOidRequest define a variável em BytesRead como 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 miniporta, os drivers de filtro podem receber apenas uma solicitação por vez. O NDIS serializa as solicitações que envia para um driver de filtro. O NDIS não pode chamar FilterOidRequest antes que um driver de filtro conclua a solicitação atual.

O NDIS chama FilterOidRequest em IRQL <= DISPATCH_LEVEL.

Exemplos

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 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 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
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	<= DISPATCH_LEVEL