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

Artigo
08/07/2023

A função MiniportCoOidRequest manipula uma solicitação OID para consultar ou definir informações no driver de miniporto CoNDIS.

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

Sintaxe

MINIPORT_CO_OID_REQUEST MiniportCoOidRequest;

NDIS_STATUS MiniportCoOidRequest(
  [in] NDIS_HANDLE MiniportAdapterContext,
  [in] NDIS_HANDLE MiniportVcContext,
       PNDIS_OID_REQUEST NdisRequest
)
{...}

Parâmetros

[in] MiniportAdapterContext

Um identificador para uma área de contexto que o driver de miniporto alocou em sua função MiniportInitializeEx . O driver de miniporto usa essa área de contexto para manter informações de estado para um adaptador de miniporte.

[in] MiniportVcContext

Um identificador para uma área de contexto alocada pelo driver de miniporto na qual o driver de miniporto mantém seu estado de VC (conexão por virtual). O driver de miniporto forneceu esse identificador para o NDIS de sua função MiniportCoCreateVc . Se a solicitação não for específica de VC, esse parâmetro será NULL.

NdisRequest

Um ponteiro para uma estrutura NDIS_OID_REQUEST que contém o buffer e o pacote de solicitação para o driver de miniporto manipular. Dependendo da solicitação, o driver retorna informações solicitadas na estrutura para a qual esse parâmetro aponta.

Retornar valor

MiniportCoOidRequest pode retornar um dos seguintes valores de status:

Código de retorno	Descrição
NDIS_STATUS_SUCCESS	O driver de miniporte definiu ou obteve os dados conforme solicitado.
NDIS_STATUS_PENDING	O driver de miniporte concluirá a solicitação de forma assíncrona. Depois que o driver de miniporto tiver concluído todo o processamento, ele deverá chamar o Função NdisMCoOidRequestComplete para informar ao NDIS que a solicitação foi concluída.
NDIS_STATUS_INVALID_OID	A solicitação de que o parâmetro OidRequest especificado era inválida ou não foi reconhecida.
NDIS_STATUS_NOT_SUPPORTED	A solicitação que o parâmetro OidRequest especificou foi reconhecida, mas não é compatível com o driver de miniport.
NDIS_STATUS_BUFFER_TOO_SHORT	O buffer que o parâmetro OidRequest forneceu era muito pequeno para armazenar os dados solicitados.
NDIS_STATUS_INVALID_LENGTH	O valor especificado no membro InformationBufferLength da estrutura NDIS_OID_REQUEST em OidRequest está incorreto para o código OID_XXX especificado.
NDIS_STATUS_INVALID_DATA	Um ou mais dos parâmetros especificados para a solicitação em OidRequest iwas invalid.
NDIS_STATUS_NOT_ACCEPTED	Após o NDIS chamar o Função MiniportDevicePnPEventNotify para indicar uma remoção surpresa, o NDIS chama a função MiniportHaltEx do driver. Se o driver receber solicitações OID antes de chamar o NDIS MiniportHaltEx, ele deverá concluir imediatamente essas solicitações com um valor status de NDIS_STATUS_NOT_ACCEPTED.
NDIS_STATUS_REQUEST_ABORTED	O driver de miniporto parou de processar a solicitação. Por exemplo, o NDIS chamou o MiniportResetEx ou Função MiniportCancelOidRequest .

Comentários

O NDIS chama a função MiniportCoOidRequest para lidar com uma solicitação OID para consultar ou definir informações em um driver de miniporto CoNDIS.

Para registrar MiniportCoOidRequest, os drivers de miniport chamam a função NdisSetOptionalHandlers da função MiniportSetOptions . Em MiniportSetOptions, o driver de miniporto inicializa um NDIS_MINIPORT_CO_CHARACTERISTICS estrutura e a passa no parâmetro OptionalHandlers de NdisSetOptionalHandlers.

O NDIS chama a função MiniportCoOidRequest em seu próprio nome ou em nome de um driver de protocolo associado que chamou a função NdisCoOidRequest . Os drivers de miniport devem examinar a solicitação fornecida em OidRequest e executar a ação solicitada. Para obter mais informações sobre os OIDs que os drivers de miniporto lidam, consulte OIDs do NDIS.

Observe que o NDIS não valida o conteúdo específico do OID em OidRequest . Portanto, o driver em si deve validar esse conteúdo. Se o driver determinar que o valor a ser definido está fora dos limites, ele deverá falhar na solicitação e retornar NDIS_STATUS_INVALID_DATA.

Se MiniportCoOidRequest retornar NDIS_STATUS_PENDING, o NDIS poderá chamar MiniportCoOidRequest com outra solicitação para o adaptador de miniporto especificado em MiniportAdapterContext, antes que a solicitação pendente seja concluída. O NDIS não serializa solicitações OID orientadas a conexão.

Exemplos

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

Por exemplo, para definir uma função MiniportCoOidRequest chamada "MyCoOidRequest", use o tipo MINIPORT_CO_OID_REQUEST conforme mostrado neste exemplo de código:

MINIPORT_CO_OID_REQUEST MyCoOidRequest;

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

_Use_decl_annotations_
NDIS_STATUS
 MyCoOidRequest(
    NDIS_HANDLE  MiniportAdapterContext,
    NDIS_HANDLE  MiniportVcContext,
    PNDIS_OID_REQUEST  OidRequest
    )
  {...}

O tipo de função MINIPORT_CO_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 MINIPORT_CO_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