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

Artigo
02/29/2024

A função ProtocolDirectOidRequestComplete conclui o processamento de uma solicitação OID direta iniciada pelo driver de protocolo para a qual a função NdisDirectOidRequest retornou NDIS_STATUS_PENDING.

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

Sintaxe

PROTOCOL_DIRECT_OID_REQUEST_COMPLETE ProtocolDirectOidRequestComplete;

void ProtocolDirectOidRequestComplete(
  [in] NDIS_HANDLE ProtocolBindingContext,
  [in] PNDIS_OID_REQUEST OidRequest,
  [in] NDIS_STATUS Status
)
{...}

Parâmetros

[in] ProtocolBindingContext

Um identificador para uma área de contexto alocada pelo driver de protocolo na qual o driver de protocolo mantém o estado de tempo de execução por associação. O driver forneceu esse identificador quando chamou a função NdisOpenAdapterEx .

[in] OidRequest

Um ponteiro para a estrutura de NDIS_OID_REQUEST fornecida pelo driver de protocolo que foi passada anteriormente para a função NdisDirectOidRequest .

[in] Status

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

Retornar valor

Nenhum

Comentários

ProtocolDirectOidRequestComplete é uma função opcional. Se um driver de protocolo não usar solicitações OID diretas, ele poderá definir o ponto de entrada dessa função como NULL quando chamar o Função NdisRegisterProtocolDriver .

ProtocolDirectOidRequestComplete usa o valor de entrada do parâmetro Status da seguinte maneira:

Se Status for NDIS_STATUS_SUCCESS, o membro BytesRead ou BytesWritten da estrutura NDIS_OID_REQUEST foi definido pelo NDIS ou pelo driver subjacente. Esses valores especificam quanta informação fornecida pelo driver de protocolo foi transferida do buffer no InformationBuffer para a NIC em uma operação de conjunto ou quantas informações foram retornadas no InformationBuffer em resposta a uma operação de consulta.
Se o driver de protocolo tiver feito uma consulta, ProtocolDirectOidRequestComplete poderá usar os dados retornados no InformationBuffer de qualquer maneira que o driver de protocolo determinar, dependendo do valor do membro Oid .

Por exemplo, se o driver de protocolo iniciou originalmente um OID_GEN_MAXIMUM_SEND_PACKETS consulta, ProtocolDirectOidRequestComplete pode configurar variáveis de estado na área ProtocolBindingContext para limitar o número de envios pendentes que o driver configurará para chamadas subsequentes para o Função NdisSendNetBufferLists .
Se Status for NDIS_STATUS_INVALID_LENGTH ou NDIS_STATUS_BUFFER_TOO_SHORT, o membro BytesNeeded especificará o valor específico do OID do membro InformationBufferLength necessário para executar a operação solicitada.
Nessas circunstâncias, ProtocolDirectOidRequestComplete pode alocar espaço de buffer suficiente para a solicitação, configurar outra estrutura NDIS_OID_REQUEST com o valor InformationBufferLength necessário e o mesmo valor Oid e repetir a chamada para a função NdisDirectOidRequest .

ProtocolDirectOidRequestComplete também pode repetir solicitações para determinados outros argumentos NDIS_STATUS_ Xxx , conforme descrito em NdisDirectOidRequest.
Se Status for um valor xxx NDIS_STATUS_ que é um erro irrecuperável, ProtocolDirectOidRequestComplete deverá liberar a memória alocada para a estrutura NDIS_OID_REQUEST e 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.

ProtocolDirectOidRequestComplete pode ser chamado antes que o driver de protocolo tenha tempo para inspecionar o código status que NdisDirectOidRequest retorna em Status.

O NDIS chama ProtocolDirectOidRequestComplete em IRQL <= DISPATCH_LEVEL.

Exemplos

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

PROTOCOL_DIRECT_OID_REQUEST_COMPLETE MyDirectOidRequestComplete;

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

_Use_decl_annotations_
VOID
 MyDirectOidRequestComplete(
    NDIS_HANDLE  ProtocolBindingContext,
    PNDIS_OID_REQUEST  OidRequest,
    NDIS_STATUS  Status
    )
  {...}

O tipo de função PROTOCOL_DIRECT_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_DIRECT_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.1 e posterior.
Plataforma de Destino	Windows
Cabeçalho	ndis.h (inclua Ndis.h)
IRQL	<= DISPATCH_LEVEL