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

Artigo
03/08/2023

A função ProtocolCoOidRequest manipula solicitações OID que clientes CoNDIS ou gerenciadores de chamadas autônomos iniciam por chamadas para a função NdisCoOidRequest ou que um driver MCM (gerenciador de chamadas de miniporto) inicia por chamadas para a função NdisMCmOidRequest .

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

Sintaxe

PROTOCOL_CO_OID_REQUEST ProtocolCoOidRequest;

NDIS_STATUS ProtocolCoOidRequest(
  [in]      NDIS_HANDLE ProtocolAfContext,
  [in]      NDIS_HANDLE ProtocolVcContext,
  [in]      NDIS_HANDLE ProtocolPartyContext,
  [in, out] PNDIS_OID_REQUEST OidRequest
)
{...}

Parâmetros

[in] ProtocolAfContext

Um identificador que identifica uma área de contexto af (família de endereços). Se o driver for um cliente, ele forneceu esse identificador quando chamou o Função NdisClOpenAddressFamilyEx para se conectar ao gerenciador de chamadas. Se o driver for um gerenciador de chamadas, ele forneceu esse identificador de sua função ProtocolCmOpenAf .

[in] ProtocolVcContext

Um identificador que identifica a VC (conexão virtual) para consultar ou definir informações, se a solicitação for específica de VC. Caso contrário, esse parâmetro será NULL.

[in] ProtocolPartyContext

Um identificador que identifica a parte em uma VC de vários pontos para consultar ou definir informações, se a solicitação for específica da parte. Caso contrário, esse parâmetro será NULL.

[in, out] OidRequest

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

Retornar valor

ProtocolCoOidRequest pode retornar um dos seguintes:

Código de retorno	Descrição
NDIS_STATUS_SUCCESS	O cliente ou o gerenciador de chamadas realizou a operação solicitada.
NDIS_STATUS_PENDING	O cliente ou o gerenciador de chamadas está tratando essa solicitação de forma assíncrona e chamará o Função NdisCoOidRequestComplete ou o Função NdisMCmOidRequestComplete quando a operação solicitada é concluída.
NDIS_STATUS_INVALID_LENGTH ou NDIS_STATUS_BUFFER_TOO_SHORT	O driver está falhando na solicitação porque o chamador da função NdisCoOidRequest ou NdisMCmOidRequest não forneceu um valor adequado para o membro InformationBuffer da estrutura NDIS_OID_REQUEST para a solicitação fornecida. O driver define o membro BytesNeeded de NDIS_OID_REQUEST no buffer no parâmetro OidRequest para o valor específico do OID do membro InformationBufferLength necessário para executar a operação solicitada.
NDIS_STATUS_XXX	O cliente ou o gerenciador de chamadas falhou na solicitação por algum motivo determinado pelo driver, como dados de entrada inválidos especificados para um conjunto.
NDIS_STATUS_NOT_SUPPORTED	O cliente ou gerenciador de chamadas falhou nessa solicitação porque não reconheceu o código OID_GEN_CO_XXX no membro Oid no buffer em NdisRequest.

Comentários

A função ProtocolCoOidRequest é necessária para clientes CoNDIS, gerenciadores de chamadas e MCMs. ProtocolCoOidRequest é semelhante à função MiniportCoOidRequest do driver de miniport.

Clientes coNDIS e gerenciadores de chamadas enviam informações uns aos outros especificando um valor não NULL no parâmetro NdisAfHandle quando chamam a função NdisCoOidRequest . Da mesma forma, os MCMs chamam o NdisMCmOidRequest com valores explícitos para NdisAfHandle para comunicar informações aos clientes. Essas chamadas para NdisCoOidRequest ou NdisMCmOidRequest fazem com que o NDIS chame a função ProtocolCoOidRequest do cliente de destino, gerenciador de chamadas ou MCM associado ao identificador af especificado.

Para registrar ProtocolCoOidRequest como um cliente, um driver inicializa um NDIS_CO_CLIENT_OPTIONAL_HANDLERS estrutura e a passa no parâmetro OptionalHandlers da função NdisSetOptionalHandlers . Para registrar ProtocolCoOidRequest como um gerenciador de chamadas, um driver inicializa um NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS estrutura e a passa no parâmetro OptionalHandlers .

Se os parâmetros NdisVcHandle e NdisPartyHandle de NdisCoOidRequest ou NdisMCmOidRequest forem NULL, a solicitação será global por natureza. Ou seja, um valor explícito para NdisVcHandle ou NdisPartyHandle indica que ProtocolCoOidRequest deve atender à solicitação fornecida por VC ou por parte, respectivamente.

O buffer no parâmetro OidRequest foi alocado do pool nãopagado e, portanto, é acessível no IRQL gerado. O chamador de NdisCoOidRequest(ou NdisMCmOidRequest) deve liberar esse buffer e o buffer interno no membro InformationBuffer da estrutura NDIS_OID_REQUEST para a qual OidRequest aponta.

Se ProtocolCoOidRequest retornar NDIS_STATUS_PENDING, o driver deverá chamar o Função NdisCoOidRequestComplete ou o Função NdisMCmOidRequestComplete para um driver MCM, quando o driver conclui a solicitação.

Exemplos

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

PROTOCOL_CO_OID_REQUEST MyCoOidRequest;

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

_Use_decl_annotations_
NDIS_STATUS
 MyCoOidRequest(
    NDIS_HANDLE  ProtocolAfContext,
    NDIS_HANDLE  ProtocolVcContext,
    NDIS_HANDLE  ProtocolPartyContext,
    PNDIS_OID_REQUEST  OidRequest
    )
  {...}

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