NDIS_OID_REQUEST estructura (ndis/oidrequest.h)

Artículo
08/07/2023

Para consultar o establecer información de OID, NDIS envía NDIS_OID_REQUEST estructuras para filtrar los controladores y los controladores de minipuerto.

Sintaxis

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;

Miembros

Header

Estructura NDIS_OBJECT_HEADER de la estructura NDIS_OID_REQUEST. Establezca el miembro Type en NDIS_OBJECT_TYPE_OID_REQUEST. Para indicar la versión de la estructura de NDIS_OID_REQUEST, establezca el miembro Revision en uno de los valores siguientes:

NDIS_OID_REQUEST_REVISION_2

Se agregaron los miembros SwitchId, VPortId y Flags para NDIS 6.50.

Establezca el miembro Tamaño de encabezado en NDIS_SIZEOF_OID_REQUEST_REVISION_2.

NDIS_OID_REQUEST_REVISION_1

Versión original de NDIS 6.0.

Establezca el miembro Tamaño de encabezado en NDIS_SIZEOF_OID_REQUEST_REVISION_1.

RequestType

Tipo de solicitud como uno de los valores de enumeración NDIS_REQUEST_TYPE .

PortNumber

Puerto al que se envía la solicitud. Si el puerto es desconocido o predeterminado, este miembro es cero.

Timeout

Tiempo de espera, en segundos, para la solicitud. NDIS puede restablecer el controlador o cancelar la solicitud si expira el tiempo de espera antes de que el controlador complete la solicitud.

RequestId

Identificador de la solicitud. Si un controlador de minipuerto debe completar inmediatamente una solicitud y completa la solicitud con un estado de NDIS_STATUS_INDICATION_REQUIRED, el controlador de minipuerto usa este valor RequestId para establecer el miembro RequestId de la estructura de NDIS_STATUS_INDICATION asociada.

Los controladores NDIS o de exceso también pueden usar RequestId para cancelar una solicitud. Cuando un controlador de minipuerto recibe una solicitud de cancelación, el controlador de minipuerto cancela las solicitudes pendientes con un RequestId coincidente. Si RequestId es cero, el controlador de minipuerto puede omitir este miembro. Para obtener más información sobre las indicaciones de estado, vea la siguiente sección Comentarios.

RequestHandle

Identificador que identifica el origen que emitió la solicitud de OID. Si un controlador de minipuerto debe completar la solicitud inmediatamente y completa la solicitud con un estado de NDIS_STATUS_INDICATION_REQUIRED, el controlador de miniporte usa este valor RequestHandle para establecer el miembro DestinationHandle de la estructura de NDIS_STATUS_INDICATION asociada. En este caso, NDIS enviará solo la indicación de estado posterior al origen que emitió la solicitud OID.

Para obtener más información sobre las indicaciones de estado, vea la siguiente sección Comentarios.

DATA

Unión que define los datos de solicitud. La información de los datos varía según el tipo de solicitud especificado por el miembro RequestType . Se especifican las siguientes estructuras miembro:

DATA.Oid

DATA.QUERY_INFORMATION

Esta estructura contiene los parámetros de un tipo de solicitud NdisRequestQueryInformation o NdisRequestQueryStatistics . Esta estructura se especifica de la siguiente manera:


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

DATA.QUERY_INFORMATION.Oid

Identificador de objeto de la operación solicitada. El valor es un código OID_ XXX .

DATA.QUERY_INFORMATION.InformationBuffer

Puntero a un búfer en el que el controlador o NDIS subyacente devuelven la información solicitada para las solicitudes de información de consulta.

DATA.QUERY_INFORMATION.InformationBufferLength

Tamaño, en bytes, del búfer en InformationBuffer. El valor en Oid determina el valor adecuado para este miembro.

DATA.QUERY_INFORMATION.BytesWritten

Número de bytes que el controlador subyacente o NDIS transfiere al búfer en InformationBuffer para las solicitudes de información de consulta. Si la función NdisOidRequest devuelve NDIS_STATUS_INVALID_LENGTH, el valor de este miembro no tiene sentido.

DATA.QUERY_INFORMATION.BytesNeeded

Número de bytes necesarios para devolver la información de consulta solicitada por el código OID_ XXX especificado.

DATA.SET_INFORMATION

Esta estructura contiene los parámetros de un tipo de solicitud NdisRequestSetInformation . Esta estructura se especifica de la siguiente manera:


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

DATA.SET_INFORMATION.Oid

Identificador de objeto de la operación solicitada. El valor es un código OID_ XXX .

DATA.SET_INFORMATION.InformationBuffer

Puntero a un búfer desde el que el controlador subyacente lee la información proporcionada por el autor de la llamada para las solicitudes de información establecida.

DATA.SET_INFORMATION.InformationBufferLength

Tamaño, en bytes, del búfer en InformationBuffer. El valor en Oid determina el valor adecuado para este miembro.

DATA.SET_INFORMATION.BytesRead

Número de bytes que el controlador subyacente leyó del búfer en InformationBuffer para las solicitudes de información establecida.

DATA.SET_INFORMATION.BytesNeeded

Número de bytes necesarios para llevar a cabo la operación de conjunto solicitada por el OID_ código XXX especificado.

Si NdisOidRequest devuelve NDIS_STATUS_SUCCESS, el valor de este miembro no tiene sentido. Si el búfer de InformationBuffer no contiene datos suficientes para el OID_ XXX dado en una solicitud establecida, este miembro indica la cantidad de datos necesarios.

DATA.METHOD_INFORMATION

Esta estructura contiene los parámetros de un tipo de solicitud NdisRequestMethod . Esta estructura se especifica de la siguiente manera:


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

Identificador de objeto de la operación solicitada. El valor es un código OID_ XXX .

DATA.METHOD_INFORMATION.InformationBuffer

Puntero a un búfer en el que el controlador subyacente o NDIS devuelve la información solicitada para las operaciones de consulta o desde la que el controlador subyacente lee información proporcionada por el autor de la llamada para las operaciones establecidas. Estas operaciones son específicas del tipo de solicitud NdisRequestMethod que se está realizando.

Nota Este búfer se usa para las solicitudes set-information y query-information. Como resultado, los datos del búfer de la solicitud set-information se sobrescribirían mediante los datos que se devuelven para la solicitud de información de consulta. El uso exacto depende de la operación solicitada según lo especificado por el miembro Oid .

DATA.METHOD_INFORMATION.InputBufferLength

Tamaño, en bytes, de los datos legibles en el búfer en InformationBuffer. El valor en Oid determina el valor adecuado para este miembro.

DATA.METHOD_INFORMATION.OutputBufferLength

Número de bytes del búfer en InformationBuffer que el controlador puede escribir.

DATA.METHOD_INFORMATION.MethodId

Método que se va a ejecutar para un OID de método. Una solicitud de OID de método puede admitir varias operaciones definidas por MethodId. Puede ser cualquier valor mayor o igual que cero. Cero indica el método predeterminado. NDIS puede definir OID de método público con algunos métodos predefinidos. Los controladores miniport pueden definir los OID de método personalizados. Para obtener más información sobre los OID personalizados, consulte OID_GEN_SUPPORTED_GUIDS.

DATA.METHOD_INFORMATION.BytesWritten

En el caso de los OID de método, BytesWritten debe ser menor o igual que el valor del miembro OutputBufferLength .

DATA.METHOD_INFORMATION.BytesRead

Número de bytes que el controlador subyacente leyó del búfer en InformationBuffer para las solicitudes de información establecida.

En el caso de los OID de método, BytesRead debe ser menor o igual que el valor del miembro InputBufferLength .

DATA.METHOD_INFORMATION.BytesNeeded

Número de bytes necesarios para devolver información de consulta o para llevar a cabo la operación de conjunto solicitada por el código xxx de OID_ especificado.

Si NdisOidRequest devuelve NDIS_STATUS_SUCCESS, el valor de este miembro no tiene sentido. Si InformationBufferLength es demasiado pequeño para el OID_ XXX dado en una consulta, este miembro indica el tamaño de un búfer para satisfacer la solicitud. Si el búfer de InformationBuffer no contiene datos suficientes para el OID_ XXX especificado en un conjunto, este miembro indica la cantidad de datos necesarios.

_REQUEST_DATA

NdisReserved[NDIS_OID_REQUEST_NDIS_RESERVED_SIZE * sizeof(PVOID)]

Área reservada para NDIS.

MiniportReserved[2 * sizeof(PVOID)]

Área reservada para el controlador de minipuerto.

SourceReserved[2 * sizeof(PVOID)]

Área reservada para el controlador de origen. Reservado para el asignador de la estructura NDIS_OID_REQUEST. Suele ser un controlador de protocolo NDIS o un controlador de filtro NDIS.

SupportedRevision

Revisión de una estructura NDIS compatible con un controlador NDIS 6.0 o posterior cuando controló una solicitud de OID. Una estructura revisada es cualquier estructura NDIS 6.0 que tenga una estructura NDIS_OBJECT_HEADER dentro de ella. Cuando el controlador se realiza correctamente al establecer un OID, debe establecer SupportedRevision en el número de revisión de la estructura que admitía. Para obtener más información sobre la información de la versión de NDIS, vea Especificación de la información de versión de NDIS.

Reserved1

Reservado para un uso futuro.

Reserved2

Reservado para un uso futuro.

SwitchId

Valor de NDIS_NIC_SWITCH_ID que identifica el conmutador en el que se está ejecutando la VPort de destino, especificada por VPortId.

Nota

Este campo se admite en NDIS 6.50 y versiones posteriores.

VPortId

Valor de NDIS_NIC_SWITCH_VPORT_ID que identifica la VPort a la que se dirige esta solicitud de OID. Este campo se considera válido solo si se establece la marca NDIS_OID_REQUEST_FLAGS_VPORT_ID_VALID .

Nota

Este campo se admite en NDIS 6.50 y versiones posteriores.

Flags

Valor de ULONG que contiene un OR bit a bit de marcas para esta solicitud de OID. Actualmente, se admiten estas marcas:

Marca	Value	Descripción
NDIS_OID_REQUEST_FLAGS_VPORT_ID_VALID	0x0001	Cuando se establece esta marca, el miembro VportId se considera válido e identifica el VPort al que se dirige el OID. Si no se establece esta marca, el OID es para el propio adaptador de minipuerto.

Nota

Este campo se admite en NDIS 6.50 y versiones posteriores.

Comentarios

Un controlador de protocolo o un controlador de filtro debe asignar memoria no paginada para el búfer en InformationBuffer y para la estructura de NDIS_OID_REQUEST. El uso de datos asignados desde la memoria paginada puede provocar errores irrecuperables de página porque los controladores subyacentes se ejecutan en IRQL = DISPATCH_LEVEL para llevar a cabo la operación solicitada.

NDIS_OID_REQUEST contiene una subestructura DATA para cada tipo de operación que un controlador de protocolo puede solicitar de un controlador subyacente. Antes de llamar a NdisOidRequest, el controlador de protocolo rellena los miembros pertinentes de la subestructura que representa la consulta o la operación de establecimiento especificada en el miembro Oid . NDIS o el controlador subyacente rellena los miembros restantes antes de devolver el control al autor de la llamada.

Algunas solicitudes de OID permiten que un controlador de minipuerto proporcione un estado de finalización de OID con una indicación de estado. En este caso, el controlador de minipuerto devuelve NDIS_STATUS_INDICATION_REQUIRED para el estado de finalización de la solicitud OID. Un controlador de minipuerto no puede devolver este estado a menos que el OID determinado lo permita. Para determinar si se permite este estado, consulte la página de referencia de OID.

Si una indicación de estado está asociada a una solicitud de OID en la que el controlador de miniporte devolvió NDIS_STATUS_INDICATION_REQUIRED, el controlador que realiza la indicación de estado debe establecer los miembros DestinationHandle y RequestId en la estructura NDIS_STATUS_INDICATION .

En este caso, el controlador establece los miembros DestinationHandle y RequestId en los valores de los miembros RequestHandle y RequestId de la estructura NDIS_OID_REQUEST, respectivamente.

Por ejemplo, en redes inalámbricas, el procesamiento de una solicitud OID puede tardar mucho tiempo en completarse. En este caso, el controlador de minipuerto puede completar la solicitud de OID inmediatamente y proporcionar una indicación de estado más adelante para proporcionar el resultado final de la solicitud OID.

Los tipos NdisRequestGenericn(1-4) están disponibles para los controladores de miniporte que crean sus propias solicitudes internas. Para implementar este tipo de solicitud, un controlador de minipuerto asigna una variable interna a uno de estos tipos genéricos.