Função NdisCoOidRequest (ndis.h)

Artigo
02/07/2025

A função NdisCoOidRequest encaminha uma solicitação para drivers CoNDIS direcionados para consultar ou definir informações especificadas por OID do driver de destino.

Sintaxe

NDIS_STATUS NdisCoOidRequest(
  [in]           NDIS_HANDLE       NdisBindingHandle,
  [in, optional] NDIS_HANDLE       NdisAfHandle,
  [in, optional] NDIS_HANDLE       NdisVcHandle,
  [in, optional] NDIS_HANDLE       NdisPartyHandle,
  [in, out]      PNDIS_OID_REQUEST OidRequest
);

Parâmetros

[in] NdisBindingHandle

Um identificador retornado pela função NdisOpenAdapterEx que identifica o adaptador de destino para a associação.

[in, optional] NdisAfHandle

Um identificador que identifica a AF (família de endereços) que é compartilhada entre o cliente, o gerenciador de chamadas e o NDIS. Esse identificador foi obtido da seguinte maneira:

Se o chamador for um cliente que está fazendo uma solicitação para o gerenciador de chamadas, o cliente originalmente obteve esse identificador de uma chamada bem-sucedida para o função NdisClOpenAddressFamilyEx.
Se o chamador for um MCM (gerenciador de chamadas) autônomo ou um MCM (gerenciador de chamadas de miniporto) que está fazendo uma solicitação a um cliente, o gerenciador de chamadas ou MCM originalmente obteve esse identificador como um parâmetro de entrada para sua função ProtocolCmOpenAf.

Para fazer uma solicitação de um cliente ou de um gerenciador de chamadas autônomo para o driver de miniporto subjacente, esse parâmetro deve ser NULL.

[in, optional] NdisVcHandle

Um identificador que identifica a VC (conexão virtual) para a qual o chamador está solicitando ou definindo informações, se a solicitação for específica de VC. Caso contrário, se esse parâmetro for NULL, a solicitação não será específica de VC. Para qualquer solicitação específica de VC, o chamador originalmente obteve esse identificador quando criou a VC com a função NdisCoCreateVc ou como um parâmetro de entrada para sua função ProtocolCoCreateVc. Para uma solicitação específica de VC que é direcionada para o driver de miniporto subjacente, esse identificador identifica o VC, enquanto NdisAfHandle e NdisPartyHandle são NULL.

[in, optional] NdisPartyHandle

Um identificador que identifica a parte em um VC de vários pontos para o qual o chamador está solicitando ou definindo informações, se a solicitação for específica à parte. Caso contrário, se esse parâmetro for NULL, a solicitação não será específica à parte. Para qualquer solicitação específica de parte, um cliente obteve originalmente esse identificador de uma chamada bem-sucedida para a função NdisClAddParty ou a função NdisClMakeCall ou o gerenciador de chamadas obteve esse identificador como um parâmetro de entrada para sua função ProtocolCmAddParty. Se NdisAfHandle for NULL, NdisPartyHandle também será NULL.

[in, out] OidRequest

Um ponteiro para uma estrutura NDIS_OID_REQUEST que especifica a operação solicitada com um determinado códigoXXX OID_ para consultar ou definir informações.

Valor de retorno

O driver de destino determina quais NDIS_STATUS_código de XXX NdisCoOidRequest retorna, geralmente um dos seguintes valores:

Código de retorno	Descrição
NDIS_STATUS_SUCCESS	A operação de solicitação foi concluída com êxito.
NDIS_STATUS_PENDING	A solicitação está sendo tratada de forma assíncrona e o NDIS chamará o chamador função ProtocolCoOidRequestComplete quando a solicitação é concluída.
NDIS_STATUS_INVALID_OID	O códigoXXX OID_ especificado no Oid membro da estrutura NDIS_OID_REQUEST no parâmetro OidRequest é inválido ou sem suporte pelo driver subjacente.
NDIS_STATUS_INVALID_LENGTH ou NDIS_STATUS_BUFFER_TOO_SHORT	O valor especificado no InformationBufferLength membro do buffer estruturado em NDIS_OID_REQUEST em OidRequest não corresponde aos requisitos para o código deXXX OID_ fornecido. Se o buffer de informações for muito pequeno, o bytesNeeded membro do NDIS_OID_REQUEST contém o valor correto para InformationBufferLength, quando NdisCoOidRequest retorna.
NDIS_STATUS_INVALID_DATA	Os dados fornecidos em do InformationBuffer na estrutura de NDIS_OID_REQUEST fornecida são inválidos para o código deXXX OID_ fornecido.
NDIS_STATUS_NOT_SUPPORTED ou NDIS_STATUS_NOT_RECOGNIZED	O driver subjacente não dá suporte à operação solicitada.
NDIS_STATUS_RESOURCES	A solicitação não pôde ser atendida devido a uma escassez de recursos. Normalmente, esse valor retornado indica que uma tentativa de alocar memória não teve êxito, mas não indica necessariamente que a mesma solicitação, se enviada posteriormente, falhará pelo mesmo motivo.
NDIS_STATUS_NOT_ACCEPTED	O driver subjacente tentou a operação solicitada, geralmente uma solicitação definida, mas a operação falhou. Por exemplo, uma tentativa de definir muitos endereços multicast pode fazer com que NdisCoOidRequest retorne esse valor.
NDIS_STATUS_CLOSING ou NDIS_STATUS_CLOSING_INDICATING	O driver subjacente falhou na operação solicitada porque uma operação de fechamento está em andamento.
NDIS_STATUS_RESET_IN_PROGRESS	O driver de miniporto subjacente não pode atender à solicitação no momento porque está redefinindo a NIC afetada no momento. A função ProtocolStatusEx do chamador foi ou será chamada com NDIS_STATUS_RESET_START para indicar que uma redefinição está em andamento. Esse valor retornado não indica necessariamente que a mesma solicitação, se enviada posteriormente, falhará pelo mesmo motivo.
NDIS_STATUS_FAILURE	Esse valor geralmente é um valor padrão não específico que é retornado quando nenhum dos NDIS_STATUS_XXX mais específicos fez com que o driver subjacente falhasse na solicitação.
NDIS_STATUS_REQUEST_ABORTED	O driver de miniporto parou de processar a solicitação. Por exemplo, o NDIS chamou um MiniportResetEx de um driver de miniport subjacente ou função MiniportCancelOidRequest.

Observações

Clientes coNDIS e gerenciadores de chamadas autônomos podem chamar a função NdisCoOidRequest para enviar uma solicitação OID para consultar ou definir informações especificadas por OID em um driver de destino. O driver de destino pode ser outro driver de protocolo CoNDIS ou um driver subjacente.

O chamador de NdisCoOidRequest deve alocar memória suficiente para manter o buffer de informações associado ao OID especificado. O chamador também deve alocar e configurar o buffer em OidRequest antes de chamar NdisCoOidRequest. Ambos os buffers devem ser alocados do pool nãopagado porque o driver de destino pode ser executado no IRQL gerado enquanto processa a solicitação.

Alguns erros que NdisCoOidRequest retorna são recuperáveis, incluindo o seguinte:

NDIS_STATUS_INVALID_OID
NDIS_STATUS_INVALID_LENGTH
NDIS_STATUS_BUFFER_TOO_SHORT
NDIS_STATUS_INVALID_DATA
NDIS_STATUS_RESOURCES
NDIS_STATUS_RESET_IN_PROGRESS

Ou seja, um driver pode modificar o pacote em OidRequest adequadamente para corrigir o códigoXXX OID_ ou o tamanho ou o conteúdo do buffer em do InformationBuffer e reenviar o pacote de solicitação para NdisCoOidRequest. O mesmo pacote pode ser satisfeito quando o driver o reenvia para NdisCoOidRequest se a chamada original indicasse uma redefinição em andamento ou se uma falta de recursos, que poderia ser temporária, impedisse que essa solicitação fosse realizada.

Dependendo do valor do parâmetro NdisAfHandle, clientes e gerenciadores de chamadas autônomos chamam NdisCoOidRequest para se comunicarem entre si ou com o driver de miniporto orientado a conexão subjacente.

Se um driver passar NULL para NdisVcHandle, a solicitação será global por natureza, se a solicitação for direcionada ao cliente, ao gerenciador de chamadas ou ao driver de miniportuário. Por exemplo, se o chamador fornecer um valor deNULL não para NdisVcHandle, uma solicitação OID OID_GEN_CO_RCV_CRC_ERROR para um driver de miniporto orientado para conexão subjacente retornará o número de erros de CRC (verificação de redundância cíclica) encontrados para uma VC específica. Para a mesma solicitação com NULL para NdisVcHandle, o driver de miniporto subjacente retorna o número total de erros de CRC encontrados para todos os VCs.

Clientes e gerenciadores de chamadas autônomas devem chamar a função NdisOidRequest para todos os OIDs que não são orientados à conexão, como aqueles que são retornados em uma consulta OID_GEN_SUPPORTED_LIST, que geralmente é emitida durante a inicialização depois que o driver de protocolo se vincula ao driver NIC subjacente.

Se NdisCoOidRequest retornar NDIS_STATUS_PENDING, a solicitação será tratada de forma assíncrona e o NDIS chamará o driver de função ProtocolCoOidRequestComplete quando a solicitação é concluída. Se NdisCoOidRequest retornar qualquer outro status, a solicitação será concluída quando NdisCoOidRequest retornar e o NDIS não chamar ProtocolCoOidRequestComplete.

Para obter mais informações sobre os conjuntos de OIDs definidos para uso com NdisCoOidRequest e NdisOidRequest, consulte OIDs NDIS.

Somente clientes e gerenciadores de chamadas autônomos, que são drivers de protocolo, podem chamar NdisCoOidRequest. Os MCMs chamam a função NdisMCmOidRequest para se comunicar com seus clientes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Com suporte no NDIS 6.0 e posterior.
da Plataforma de Destino	Área de trabalho
cabeçalho	ndis.h (inclua Ndis.h)
biblioteca	Ndis.lib
IRQL	<= DISPATCH_LEVEL
regras de conformidade de DDI	Irql_Connection_Function(ndis)