função MINIPORT_SYNCHRONOUS_OID_REQUEST (ndis.h)

Artigo
08/07/2023

O NDIS chama a função de retorno de chamada MiniportSynchronousOidRequest de um driver de miniport para emitir uma solicitação OID síncrona.

Sintaxe

NDIS_STATUS MINIPORT_SYNCHRONOUS_OID_REQUEST(
  [in] NDIS_HANDLE      MiniportAdapterContext,
  [in] NDIS_OID_REQUEST *OidRequest
);

Parâmetros

[in] MiniportAdapterContext

Um identificador para uma área de contexto que o driver de miniporto alocou em sua função MiniportInitializeEx . O driver de miniporto usa essa área de contexto para manter informações de estado para um adaptador de miniporte.

[in] OidRequest

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

Retornar valor

MiniportSynchronousOidRequest pode retornar um dos seguintes valores status:

Código de retorno	Descrição
NDIS_STATUS_SUCCESS	O driver de miniporte definiu ou obteve os dados conforme solicitado.
NDIS_STATUS_INVALID_OID	A solicitação especificada por OidRequest era inválida ou não reconhecida.
NDIS_STATUS_NOT_SUPPORTED	A solicitação especificada por OidRequest foi reconhecida, mas o driver de miniporte não dá suporte a ela.
NDIS_STATUS_BUFFER_TOO_SHORT	O buffer que o OidRequest fornece era muito pequeno para armazenar os dados solicitados.
NDIS_STATUS_INVALID_LENGTH	O valor especificado no membro InformationBufferLength da estrutura NDIS_OID_REQUEST em OidRequest está incorreto para o código OID_Xxx especificado.
NDIS_STATUS_INVALID_DATA	Um ou mais dos parâmetros especificados para a solicitação em OidRequest eram inválidos.
NDIS_STATUS_INDICATION_REQUIRED	O driver de miniporto fornecerá uma status de conclusão de OID com uma indicação de status subsequente. Um driver de miniporte não pode retornar NDIS_STATUS_INDICATION_REQUIRED a menos que o OID específico permita isso. Para determinar se esse status é permitido, consulte a página de referência OID. Para obter mais informações sobre NDIS_STATUS_INDICATION_REQUIRED, consulte NDIS_OID_REQUEST e NDIS_STATUS_INDICATION.
NDIS_STATUS_NOT_ACCEPTED	Depois de chamar o Função MiniportDevicePnPEventNotify para indicar uma remoção surpresa, o NDIS chamou a função MiniportHaltEx do driver. Se o driver recebeu solicitações OID antes de chamar o NDIS MiniportHaltEx, ele deverá concluir imediatamente essas solicitações com um valor status de NDIS_STATUS_NOT_ACCEPTED. Os drivers de miniporto nem sempre são necessários para retornar NDIS_STATUS_NOT_ACCEPTED para todos os OIDs após uma remoção surpresa, mas isso ajuda a explicar por que a chamada falhou.

Comentários

MiniportSynchronousOidRequest é uma função opcional. Um driver de miniporte registrará essa função se ela manipular solicitações OID síncronas. O driver especifica o ponto de entrada MiniportSynchronousOidRequest quando chama a função NdisMRegisterMiniportDriver , usando o membro SynchronousOidRequestHandler da estrutura NDIS_MINIPORT_DRIVER_CHARACTERISTICS .

Os drivers de miniport não devem retornar NDIS_STATUS_PENDING ou NDIS_STATUS_REQUEST_ABORTED de MiniportSynchronousOidRequest. As solicitações OID síncronas não podem ser pendentes ou canceladas.

Os drivers de miniport podem retornar NDIS_STATUS_NOT_ACCEPTED após o NDIS chamar MiniportDevicePnPEventNotify para notificar o driver sobre a remoção surpresa do dispositivo. No entanto, os drivers de miniporto ainda poderão concluir a solicitação OID com um código de status diferente, se for possível fazê-lo. Para obter mais informações, consulte a documentação específica de cada OID.

Espera-se que os drivers de miniporte concluam solicitações OID síncronas rapidamente sem bloquear, aguardar ou dormir. Solicitações OID síncronas são usadas apenas para operações de baixa latência, e os drivers de miniporto devem se esforçar para concluí-las em vários milissegundos. A maioria das solicitações de OID é entregue ao MiniportOidRequest, que tem permissão para aguardar ou aguardar por durações mais longas.

O NDIS não serializa solicitações OID síncronas entre si, em relação a outras solicitações OID, contra MiniportPause, em MiniportResetEx ou em transições de energia. É responsabilidade do driver de miniporto implementar sua própria sincronização e falhar nas solicitações que são entregues em um momento em que a solicitação não pode ser tratada com êxito.

O NDIS serializa solicitações OID síncronas no MiniportHaltEx; O NDIS garante que nenhuma solicitação OID síncrona estará ativa quando MiniportHaltEx for invocado.

Os drivers de miniport que implementam a Suspensão Seletiva do NDIS são incompatíveis com OIDs síncronos e não devem registrar um manipulador MiniportSynchronousOidRequest .