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

Artigo
08/07/2023

A função ProtocolCoOidRequestComplete conclui o processamento de uma solicitação OID condis assíncrona.

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

Sintaxe

PROTOCOL_CO_OID_REQUEST_COMPLETE ProtocolCoOidRequestComplete;

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

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 ou um MCM (gerenciador de chamadas de miniporto), ele forneceu esse identificador de sua função ProtocolCmOpenAf .

[in] ProtocolVcContext

Um identificador que identifica a VC (conexão virtual) ativa para a qual o driver solicitou ou definiu informações, se a solicitação fosse 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 a qual o driver solicitou ou definiu informações, se a solicitação for específica à parte. Caso contrário, esse parâmetro será NULL.

[in, out] OidRequest

Um ponteiro para a estrutura de NDIS_OID_REQUEST fornecida pelo driver que foi passada anteriormente para a função NdisCoOidRequest ou NdisMCmOidRequest .

[in] Status

O status final da solicitação. O driver de destino ou o NDIS determina esse status final. Esse parâmetro determina o que ProtocolCoOidRequestComplete faz com as informações em OidRequest.

Retornar valor

Nenhum

Comentários

O NDIS chama a função ProtocolCoOidRequestComplete para concluir o processamento do cliente CoNDIS, do gerenciador de chamadas ou da solicitação OID do MCM para a qual a função NdisCoOidRequest ou a função NdisMCmOidRequest retornaram NDIS_STATUS_PENDING.

Para registrar ProtocolCoOidRequestComplete 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 ProtocolCoOidRequestComplete como um gerenciador de chamadas, um driver inicializa um NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS estrutura e a passa no parâmetro OptionalHandlers de NdisSetOptionalHandlers.

O driver de destino é o driver que acionou a solicitação de informações de OID. Uma chamada de driver de destino para NdisMCoOidRequestComplete, NdisCoOidRequestComplete ouA função NdisMCmOidRequestComplete fez com que o NDIS chamasse a função ProtocolCoOidRequestComplete. O NDIS encaminha o valor do parâmetro Status que foi passado para essas funções como o parâmetro status de entrada para ProtocolCoOidRequestComplete.

ProtocolCoOidRequestComplete usa o valor de entrada de Status da seguinte maneira:

Se Status for NDIS_STATUS_SUCCESS, o membro BytesRead ou BytesWritten da estrutura NDIS_OID_REQUEST para a qual o parâmetro OidRequest aponta especificará quantas informações foram transferidas do buffer no membro do InformationBuffer do NDIS_OID_REQUEST para o driver de destino ou quantas informações foram retornadas no InformationBuffer, respectivamente.
Se o driver fez uma solicitação de consulta, ProtocolCoOidRequestComplete poderá usar os dados retornados no InformationBuffer conforme apropriado para o valor especificado no membro Oid do NDIS_OID_REQUEST.
Se Status for NDIS_STATUS_INVALID_LENGTH ou NDIS_STATUS_BUFFER_TOO_SHORT, o membro BytesNeeded da estrutura NDIS_OID_REQUEST para a qual o OidRequest aponta especifica o valor específico do OID do membro InformationBufferLength do NDIS_OID_REQUEST necessário para executar a operação solicitada.
Nessas circunstâncias, ProtocolCoOidRequestComplete pode alocar espaço de buffer suficiente para a solicitação, configurar outra estrutura NDIS_OID_REQUEST com o valor necessário para InformationBufferLength e repetir a solicitação OID.
Se Status for um valor XXX NDIS_STATUS_ que seja um erro irrecuperável, ProtocolCoOidRequestComplete deverá liberar a memória da estrutura NDIS_OID_REQUEST. ProtocolCoOidRequestComplete também deve determinar se o driver deve fechar a associação ou ajustar suas informações de estado específicas de associação para lidar com operações de E/S de rede contínuas na associação.

Para obter mais informações sobre OIDs definidos pelo sistema, consulte OIDs do NDIS.

ProtocolCoOidRequestComplete pode ser chamado antes que o driver tenha tempo para inspecionar o código status que NdisCoOidRequest ou NdisMCmOidRequest retorna.

O NDIS chama ProtocolCoOidRequestComplete em IRQL <= DISPATCH_LEVEL.

Exemplos

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

PROTOCOL_CO_OID_REQUEST_COMPLETE MyCoOidRequestComplete;

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

_Use_decl_annotations_
VOID
 MyCoOidRequestComplete(
    NDIS_HANDLE  ProtocolAfContext,
    NDIS_HANDLE  ProtocolVcContext,
    NDIS_HANDLE  ProtocolPartyContext,
    PNDIS_OID_REQUEST  OidRequest,
    NDIS_STATUS  Status
    )
  {...}

O tipo de função PROTOCOL_CO_OID_REQUEST_COMPLETE é 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_COMPLETE 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 (consulte a seção Comentários)