FILTER_OID_REQUEST função de retorno de chamada (ndis.h)
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.
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 |
|---|---|
|
FilterOidRequest concluiu com êxito a consulta do driver de filtro ou a operação de definição para este módulo de filtro. |
|
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. |
|
Indica que a solicitação, especificada em OidRequest, é inválida ou não é reconhecida. |
|
FilterOidRequest não dá suporte ao OID, o OID é opcional. |
|
Indica que o buffer, fornecido em OidRequest, é muito pequeno para conter os dados solicitados. |
|
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. |
|
Para uma operação de conjunto, os dados fornecidos no membro InformationBuffer da estrutura NDIS_OID_REQUEST eram inválidos para o OID fornecido. |
|
FilterOidRequest tentou coletar as informações solicitadas, mas não teve êxito. |
|
Falha em FilterOidRequest devido a recursos insuficientes. |
|
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 |