NDIS_OID_REQUEST estrutura (ndis/oidrequest.h)

  • Artigo

Para consultar ou definir informações de OID, o NDIS envia estruturas NDIS_OID_REQUEST para filtrar drivers e drivers de miniporto.

Sintaxe

typedef struct _NDIS_OID_REQUEST {
  NDIS_OBJECT_HEADER       Header;
  NDIS_REQUEST_TYPE        RequestType;
  NDIS_PORT_NUMBER         PortNumber;
  UINT                     Timeout;
  PVOID                    RequestId;
  NDIS_HANDLE              RequestHandle;
  union {
    NDIS_OID Oid;
    struct {
      NDIS_OID Oid;
      PVOID    InformationBuffer;
      UINT     InformationBufferLength;
      UINT     BytesWritten;
      UINT     BytesNeeded;
    } QUERY_INFORMATION;
    struct {
      NDIS_OID Oid;
      PVOID    InformationBuffer;
      UINT     InformationBufferLength;
      UINT     BytesRead;
      UINT     BytesNeeded;
    } SET_INFORMATION;
    struct {
      NDIS_OID Oid;
      PVOID    InformationBuffer;
      ULONG    InputBufferLength;
      ULONG    OutputBufferLength;
      ULONG    MethodId;
      UINT     BytesWritten;
      UINT     BytesRead;
      UINT     BytesNeeded;
    } METHOD_INFORMATION;
  } DATA;
  _REQUEST_DATA            _REQUEST_DATA;
  UCHAR                    *NdisReserved[NDIS_OID_REQUEST_NDIS_RESERVED_SIZE  sizeof(PVOID)];
  UCHAR                    *MiniportReserved[2  sizeof(PVOID)];
  UCHAR                    *SourceReserved[2  sizeof(PVOID)];
  UCHAR                    SupportedRevision;
  UCHAR                    Reserved1;
  USHORT                   Reserved2;
  NDIS_NIC_SWITCH_ID       SwitchId;
  NDIS_NIC_SWITCH_VPORT_ID VPortId;
  ULONG                    Flags;
} NDIS_OID_REQUEST, *PNDIS_OID_REQUEST;

Membros

Header

A estrutura NDIS_OBJECT_HEADER para a estrutura NDIS_OID_REQUEST. Defina o membro tipo como NDIS_OBJECT_TYPE_OID_REQUEST. Para indicar a versão da estrutura NDIS_OID_REQUEST, defina o membro Revision como um dos seguintes valores:

NDIS_OID_REQUEST_REVISION_2

Foram adicionados osswitchid , VPortId e de sinalizadores para o NDIS 6.50.

Defina o membro tamanho do cabeçalho como NDIS_SIZEOF_OID_REQUEST_REVISION_2.

NDIS_OID_REQUEST_REVISION_1

Versão original do NDIS 6.0.

Defina o membro tamanho dodo cabeçalho como NDIS_SIZEOF_OID_REQUEST_REVISION_1.

RequestType

O tipo de solicitação como um dos valores de enumeração NDIS_REQUEST_TYPE.

PortNumber

A porta para a qual a solicitação é enviada. Se a porta for desconhecida ou padrão, esse membro será zero.

Timeout

Um tempo limite, em segundos, para a solicitação. O NDIS pode redefinir o driver ou cancelar a solicitação se o tempo limite expirar antes que o driver conclua a solicitação.

RequestId

Um identificador para a solicitação. Se um driver de miniporto precisar concluir uma solicitação imediatamente e concluir a solicitação com um status de NDIS_STATUS_INDICATION_REQUIRED, o driver de miniporto usará esse valor RequestId para definir o membro RequestId da estrutura de NDIS_STATUS_INDICATION associada.

O NDIS ou drivers sobrepostos também podem usar o RequestId para cancelar uma solicitação. Quando um driver de miniporto recebe uma solicitação de cancelamento, o driver de miniporto cancela todas as solicitações pendentes com um RequestIdcorrespondente. Se RequestId for zero, o driver de miniporto poderá ignorar esse membro. Para obter mais informações sobre indicações de status, consulte a seção Comentários a seguir.

RequestHandle

Um identificador que identifica a origem que emitiu a solicitação OID. Se um driver de miniporto precisar concluir a solicitação imediatamente e concluir a solicitação com um status de NDIS_STATUS_INDICATION_REQUIRED, o driver de miniporto usará esse valor RequestHandle para definir o DestinationHandle membro da estrutura de NDIS_STATUS_INDICATION associada. Nesse caso, o NDIS enviará apenas a indicação de status subsequente à origem que emitiu a solicitação OID.

Para obter mais informações sobre indicações de status, consulte a seção Comentários a seguir.

DATA

Uma união que define os dados da solicitação. As informações nos dados variam de acordo com o tipo de solicitação, conforme especificado pelo membro RequestType. As estruturas de membro a seguir são especificadas:

DATA.Oid

DATA.QUERY_INFORMATION

Essa estrutura contém os parâmetros de um tipo de solicitação NdisRequestQueryInformation ou NdisRequestQueryStatistics. Essa estrutura é especificada da seguinte maneira:


struct _QUERY
  {
    NDIS_OID    Oid;
    PVOID       InformationBuffer;
    UINT        InformationBufferLength;
    UINT        BytesWritten;
    UINT        BytesNeeded;
  } QUERY_INFORMATION;

DATA.QUERY_INFORMATION.Oid

O identificador de objeto da operação solicitada. O valor é um código XXX OID_ .

DATA.QUERY_INFORMATION.InformationBuffer

Um ponteiro para um buffer no qual o driver subjacente ou o NDIS retorna as informações solicitadas para solicitações de informações de consulta.

DATA.QUERY_INFORMATION.InformationBufferLength

O tamanho, em bytes, do buffer em do InformationBuffer. O valor em Oid determina o valor apropriado para esse membro.

DATA.QUERY_INFORMATION.BytesWritten

O número de bytes que o driver subjacente ou o NDIS transfere para o buffer em do InformationBuffer para solicitações de informações de consulta. Se a função NdisOidRequest retornar NDIS_STATUS_INVALID_LENGTH, o valor desse membro não será sentido.

DATA.QUERY_INFORMATION.BytesNeeded

O número de bytes necessários para retornar informações de consulta solicitadas pelo código de XXX OID_ determinado.

Se NdisOidRequest retornar NDIS_STATUS_SUCCESS, o valor desse membro não será sentido. Se o InformationBufferLength for muito pequeno para o OID_ XXX fornecido em uma solicitação de consulta, esse membro indicará o tamanho de um buffer necessário para atender à solicitação.

DATA.SET_INFORMATION

Essa estrutura contém os parâmetros de um tipo de solicitação NdisRequestSetInformation . Essa estrutura é especificada da seguinte maneira:


struct _SET
  {
    NDIS_OID    Oid;
    PVOID       InformationBuffer;
    UINT        InformationBufferLength;
    UINT        BytesRead;
    UINT        BytesNeeded;
  } SET_INFORMATION;

DATA.SET_INFORMATION.Oid

O identificador de objeto da operação solicitada. O valor é um código XXX OID_ .

DATA.SET_INFORMATION.InformationBuffer

Um ponteiro para um buffer do qual o driver subjacente lê informações fornecidas pelo chamador para solicitações de set-information.

DATA.SET_INFORMATION.InformationBufferLength

O tamanho, em bytes, do buffer em do InformationBuffer. O valor em Oid determina o valor apropriado para esse membro.

DATA.SET_INFORMATION.BytesRead

O número de bytes que o driver subjacente leu do buffer em do InformationBuffer para solicitações de informações definidas.

DATA.SET_INFORMATION.BytesNeeded

O número de bytes necessários para executar a operação de conjunto solicitada pelo código de XXX OID_ determinado.

Se NdisOidRequest retornar NDIS_STATUS_SUCCESS, o valor desse membro não será sentido. Se o buffer em o InformationBuffer não contiver dados suficientes para o XXX OID_ fornecido em uma solicitação definida, esse membro indicará a quantidade de dados necessária.

DATA.METHOD_INFORMATION

Essa estrutura contém os parâmetros de um tipo de solicitação NdisRequestMethod . Essa estrutura é especificada da seguinte maneira:


struct _METHOD
  {
    NDIS_OID            Oid;
    PVOID               InformationBuffer;
    ULONG               InputBufferLength;
    ULONG               OutputBufferLength;
    ULONG               MethodId;
    UINT                BytesWritten;
    UINT                BytesRead;
    UINT                BytesNeeded;
  } METHOD_INFORMATION;

DATA.METHOD_INFORMATION.Oid

O identificador de objeto da operação solicitada. O valor é um código XXX OID_ .

DATA.METHOD_INFORMATION.InformationBuffer

Um ponteiro para um buffer no qual o driver subjacente ou o NDIS retorna as informações solicitadas para operações de consulta ou do qual o driver subjacente lê informações fornecidas pelo chamador para operações definidas. Essas operações são específicas para o tipo de solicitação NdisRequestMethod que está sendo feita.

Observação esse buffer é usado para solicitações de set-information e de informações de consulta. Como resultado, os dados no buffer para a solicitação set-information seriam substituídos por dados retornados para a solicitação de informações de consulta. O uso exato depende da operação solicitada, conforme especificado pelo membro Oid .
 

DATA.METHOD_INFORMATION.InputBufferLength

O tamanho, em bytes, dos dados legíveis no buffer em do InformationBuffer. O valor em Oid determina o valor apropriado para esse membro.

DATA.METHOD_INFORMATION.OutputBufferLength

O número de bytes no buffer em do InformationBuffer que o driver pode gravar.

DATA.METHOD_INFORMATION.MethodId

O método a ser executado para um método OID. Uma solicitação OID de método pode dar suporte a várias operações conforme definido por MethodId. Pode ser qualquer valor maior ou igual a zero. Zero indica o método padrão. O NDIS pode definir OIDs de método público com alguns métodos predefinidos. Os drivers de miniport podem definir OIDs de método personalizado. Para obter mais informações sobre OIDs personalizados, consulte OID_GEN_SUPPORTED_GUIDS.

DATA.METHOD_INFORMATION.BytesWritten

O número de bytes que o driver subjacente ou o NDIS transfere para o buffer em do InformationBuffer para solicitações de informações de consulta. Se a função NdisOidRequest retornar NDIS_STATUS_INVALID_LENGTH, o valor desse membro não será sentido.

Para OIDs de método, bytesWritten deve ser menor ou igual ao valor no membro OutputBufferLength.

DATA.METHOD_INFORMATION.BytesRead

O número de bytes que o driver subjacente leu do buffer em do InformationBuffer para solicitações de informações definidas.

Para OIDs de método, bytesRead deve ser menor ou igual ao valor no membro InputBufferLength.

DATA.METHOD_INFORMATION.BytesNeeded

O número de bytes necessários para retornar informações de consulta ou para executar a operação de conjunto solicitada pelo código de XXX OID_ determinado.

Se NdisOidRequest retornar NDIS_STATUS_SUCCESS, o valor desse membro não será sentido. Se o InformationBufferLength for muito pequeno para o XXX OID_ fornecido em uma consulta, esse membro indicará o tamanho de um buffer necessário para atender à solicitação. Se o buffer em do InformationBuffer não contiver dados suficientes para o XXX OID_ fornecido em um conjunto, esse membro indicará a quantidade de dados necessária.

_REQUEST_DATA

NdisReserved[NDIS_OID_REQUEST_NDIS_RESERVED_SIZE * sizeof(PVOID)]

Uma área reservada para NDIS.

MiniportReserved[2 * sizeof(PVOID)]

Uma área reservada para o driver de miniporto.

SourceReserved[2 * sizeof(PVOID)]

Uma área reservada para o driver de origem. Reservado para o alocador da estrutura de NDIS_OID_REQUEST. Geralmente, esse é um driver de protocolo NDIS ou um driver de filtro NDIS.

SupportedRevision

A revisão de uma estrutura NDIS com suporte por um driver NDIS 6.0 ou posterior quando ele lidou com uma solicitação OID. Uma estrutura revisão é qualquer estrutura NDIS 6.0 que tenha uma estrutura NDIS_OBJECT_HEADER dentro dela. Quando o driver consegue definir uma OID, ele deve definir SupportedRevision para o número de revisão da estrutura com suporte. Para obter mais informações sobre informações sobre a versão do NDIS, consulte Especificando informações de versão do NDIS.

Reserved1

Reservado para uso futuro.

Reserved2

Reservado para uso futuro.

SwitchId

Um valor NDIS_NIC_SWITCH_ID que identifica a opção na qual o VPort de destino, especificado por VPortId, está em execução.

Nota

Esse campo tem suporte no NDIS 6.50 e posterior.

VPortId

Um valor NDIS_NIC_SWITCH_VPORT_ID que identifica o VPort que essa solicitação OID está direcionando. Esse campo será considerado válido somente se o sinalizador de NDIS_OID_REQUEST_FLAGS_VPORT_ID_VALID estiver definido.

Nota

Esse campo tem suporte no NDIS 6.50 e posterior.

Flags

Um valor ULONG que contém um OR bit a bit de sinalizadores para essa solicitação OID. Atualmente, há suporte para esses sinalizadores:

Bandeira Valor Descrição
NDIS_OID_REQUEST_FLAGS_VPORT_ID_VALID 0x0001 Quando esse sinalizador é definido, o VportId membro é considerado válido e identifica o VPort ao qual a OID é direcionada. Se esse sinalizador não estiver definido, o OID será para o adaptador de miniporto em si.

Nota

Esse campo tem suporte no NDIS 6.50 e posterior.

Observações

Um driver de protocolo ou um driver de filtro deve alocar memória nãopagada para o buffer em do InformationBuffer e para a estrutura de NDIS_OID_REQUEST. O uso de dados alocados da memória paginada pode causar falhas de página fatais porque os drivers subjacentes são executados em IRQL = DISPATCH_LEVEL realizar a operação solicitada.

NDIS_OID_REQUEST contém uma subestrutura DATA para cada tipo de operação que um driver de protocolo pode solicitar de um driver subjacente. Antes de chamar NdisOidRequest, o driver de protocolo preenche os membros relevantes da subestrutura que representa a operação de consulta ou de conjunto especificada no membro Oid . O NDIS ou o driver subjacente preenche os membros restantes antes de retornar o controle ao chamador.

Algumas solicitações de OID permitem que um driver de miniporto forneça um status de conclusão de OID com uma indicação de status. Nesse caso, o driver de miniporto retorna NDIS_STATUS_INDICATION_REQUIRED para o status de conclusão da solicitação OID. Um driver de miniporto não pode retornar esse status, a menos que o OID específico o permita. Para determinar se esse status é permitido, consulte a página de referência OID.

Se uma indicação de status estiver associada a uma solicitação OID em que o driver de miniporto retornou NDIS_STATUS_INDICATION_REQUIRED, o driver que está fazendo a indicação de status deverá definir os membros DestinationHandle e RequestId membros na estrutura NDIS_STATUS_INDICATION.

Nesse caso, o driver define os membros DestinationHandle e RequestId para os valores dos membros RequestHandle e RequestId membros na estrutura NDIS_OID_REQUEST, respectivamente.

Por exemplo, na rede sem fio, o processamento de uma solicitação OID pode levar muito tempo para ser concluído. Nesse caso, o driver de miniporto pode concluir a solicitação OID imediatamente e fornecer uma indicação de status posteriormente para fornecer o resultado final da solicitação OID.

Os tipos NdisRequestGenericn(1-4) estão disponíveis para drivers de miniporto que criam suas próprias solicitações internas. Para implementar essa solicitação, um driver de miniporto atribui uma variável interna a um desses tipos genéricos.

Requisitos

Requisito Valor
de cliente com suporte mínimo Com suporte no NDIS 6.0 e posterior.
cabeçalho ndis/oidrequest.h (inclua ndis.h)

Consulte também

NDIS_OBJECT_HEADER

NDIS_REQUEST_TYPE

NDIS_STATUS_INDICATION

NdisOidRequest

OID_GEN_SUPPORTED_GUIDS