estructura NDIS_OID_REQUEST (ndis/oidrequest.h)

Artículo
07/16/2024

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

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 de 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 SwitchId , VPortIdy Flags miembros para NDIS 6.50.

Establezca el miembro EncabezadoTamaño en NDIS_SIZEOF_OID_REQUEST_REVISION_2.

NDIS_OID_REQUEST_REVISION_1

Versión original de NDIS 6.0.

Establezca el miembro encabezado encabezadoen NDIS_SIZEOF_OID_REQUEST_REVISION_1.

RequestType

Tipo de solicitud como uno de los valores de enumeración de 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 miniporte debe completar inmediatamente una solicitud y completa la solicitud con un estado de NDIS_STATUS_INDICATION_REQUIRED, el controlador de miniporte usa este valor de RequestId para establecer el requestId miembro de la estructura de NDIS_STATUS_INDICATION asociada.

Los controladores NDIS o el uso excesivo también pueden usar el RequestId de para cancelar una solicitud. Cuando un controlador de miniporte recibe una solicitud de cancelación, el controlador de minipuerto cancela las solicitudes pendientes con un requestId de coincidente. Si requestId es cero, el controlador de miniporte 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 OID. Si un controlador de miniporte debe completar la solicitud inmediatamente y completa la solicitud con un estado de NDIS_STATUS_INDICATION_REQUIRED, el controlador de miniporta usa este valor de 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 de miembro:

DATA.Oid

DATA.QUERY_INFORMATION

Esta estructura contiene los parámetros de un NdisRequestQueryInformation o tipo de solicitud 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 de XXX OID_ .

DATA.QUERY_INFORMATION.InformationBuffer

Puntero a un búfer en el que el controlador subyacente o NDIS devuelve 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 de 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 información de consulta solicitada por el código de XXX especificado OID_ .

Si NdisOidRequest devuelve NDIS_STATUS_SUCCESS, el valor de este miembro no tiene sentido. Si el informationBufferLength de es demasiado pequeño para el OID_ XXX dado en una solicitud de consulta, este miembro indica el tamaño de un búfer para satisfacer la solicitud.

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 de XXX OID_ .

DATA.SET_INFORMATION.InformationBuffer

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

DATA.SET_INFORMATION.InformationBufferLength

Tamaño, en bytes, del búfer en InformationBuffer. El valor de 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 código XXX especificado OID_ .

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 especificado en una solicitud establecida, este miembro indica la cantidad de datos que se requieren.

DATA.METHOD_INFORMATION

Esta estructura contiene los parámetros de un tipo de solicitud de 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 de XXX OID_ .

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 NdisRequestMethod tipo de solicitud 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 de Oid.

DATA.METHOD_INFORMATION.InputBufferLength

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

DATA.METHOD_INFORMATION.OutputBufferLength

El 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 de miniport pueden definir OID de método personalizado. Para obtener más información sobre los OID personalizados, vea OID_GEN_SUPPORTED_GUIDS.

DATA.METHOD_INFORMATION.BytesWritten

Para 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.

Para 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 de XXX especificado OID_ XXX.

Si NdisOidRequest devuelve NDIS_STATUS_SUCCESS, el valor de este miembro no tiene sentido. Si el informationBufferLength de es demasiado pequeño para el OID_ XXX especificado 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 miniport.

SourceReserved[2 * sizeof(PVOID)]

Área reservada para el controlador de origen. Reservado para el asignador de la estructura NDIS_OID_REQUEST. Normalmente, se trata de 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 OID. Una estructura revisada es cualquier estructura NDIS 6.0 que tenga una estructura NDIS_OBJECT_HEADER dentro de ella. Cuando el controlador se establece correctamente en la configuración de 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 uso futuro.

Reserved2

Reservado para uso futuro.

SwitchId

Valor NDIS_NIC_SWITCH_ID que identifica el conmutador en el que se ejecuta el VPort de destino, especificado por VPortId.

Nota

Este campo se admite en NDIS 6.50 y versiones posteriores.

VPortId

Valor de NDIS_NIC_SWITCH_VPORT_ID que identifica el VPort que esta solicitud de OID tiene como destino. Este campo solo se considera válido 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 OID. Actualmente, se admiten estas marcas:

Bandera	Valor	Descripción
NDIS_OID_REQUEST_FLAGS_VPORT_ID_VALID	0x0001	Cuando se establece esta marca, el VportId miembro 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 miniport.

Nota

Este campo se admite en NDIS 6.50 y versiones posteriores.

Observaciones

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 de página irrecuperables 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 establecida que especificó en el miembro Oid de . 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 miniporte 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 miniport no puede devolver este estado a menos que el OID concreto lo permita. Para determinar si se permite este estado, consulte la página de referencia del OID.

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

En este caso, el controlador establece los miembros DestinationHandle y RequestId en los valores de la RequestHandle y miembros requestId de la estructura de 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 miniporte puede completar la solicitud OID inmediatamente y proporcionar una indicación de estado más adelante para proporcionar el resultado final para la solicitud OID.

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