Função NdisCoOidRequest (ndis.h)

Artigo
03/08/2023

A função NdisCoOidRequest encaminha uma solicitação para drivers CoNDIS de destino 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 que a função NdisOpenAdapterEx retornou 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 gerenciador de chamadas autônomo ou mcm (gerenciador de chamadas de miniporto) que está fazendo uma solicitação a um cliente, o gerenciador de chamadas ou MCM obteve originalmente 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 a VC, enquanto NdisAfHandle e NdisPartyHandle são NULL.

[in, optional] NdisPartyHandle

Um identificador que identifica a parte em uma VC de vários pontos para a qual o chamador está solicitando ou definindo informações, se a solicitação for específica da parte. Caso contrário, se esse parâmetro for NULL, a solicitação não será específica da 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ódigo OID_XXX para consultar ou definir informações.

Retornar valor

O driver de destino determina qual código NDIS_STATUS_XXXretornado por NdisCoOidRequest , 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ódigo OID_XXX especificado no membro Oid 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 membro InformationBufferLength do buffer estruturado NDIS_OID_REQUEST em OidRequest não corresponde aos requisitos do código OID_XXX fornecido. Se o buffer de informações for muito pequeno, o membro BytesNeeded de NDIS_OID_REQUEST conterá o valor correto para InformationBufferLength, quando NdisCoOidRequest retornar.
NDIS_STATUS_INVALID_DATA	Os dados fornecidos no InformationBuffer na estrutura de NDIS_OID_REQUEST fornecida são inválidos para o código OID_XXX 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 foi bem-sucedida, 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 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 miniporta parou de processar a solicitação. Por exemplo, o NDIS chamou miniportresetEx de um miniportor subjacente ou Função MiniportCancelOidRequest .

Comentários

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 retornados por NdisCoOidRequest 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ódigo OID_XXX ou o tamanho ou o conteúdo do buffer em InformationBuffer e reenviar o pacote de solicitação para NdisCoOidRequest. O mesmo pacote poderá ser atendido quando o driver o reenviar para NdisCoOidRequest se a chamada original indicasse uma redefinição em andamento ou que uma escassez 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 comunicar entre si ou com o driver de miniporto orientado a conexões subjacente.

Se um driver passar NULL para NdisVcHandle, a solicitação será global por natureza, independentemente de a solicitação ser direcionada ao cliente, ao gerenciador de chamadas ou ao driver de miniporte. Por exemplo, se o chamador fornecer um valor não NULL para NdisVcHandle, uma solicitação OID OID_GEN_CO_RCV_CRC_ERROR para um driver de miniporto orientado a conexão subjacente retornará o número de erros de CRC (marcar de redundância cíclica) que foram 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.

Os clientes e os gerenciadores de chamadas autônomos 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 normalmente é 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 do driver Função ProtocolCoOidRequestComplete quando a solicitação é concluída. Se NdisCoOidRequest retornar qualquer outra 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 do 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
Cliente mínimo com suporte	Com suporte no NDIS 6.0 e posterior.
Plataforma de Destino	Área de Trabalho
Cabeçalho	ndis.h (inclua Ndis.h)
Biblioteca	Ndis.lib
IRQL	<= DISPATCH_LEVEL
Regras de conformidade da DDI	Irql_Connection_Function(ndis)