struttura NDIS_OID_REQUEST (ndis/oidrequest.h)

Articolo
07/16/2024

Per eseguire query o impostare informazioni OID, NDIS invia NDIS_OID_REQUEST strutture per filtrare i driver e i driver miniport.

Sintassi

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;

Membri

Header

Struttura NDIS_OBJECT_HEADER per la struttura NDIS_OID_REQUEST. Impostare il membro type su NDIS_OBJECT_TYPE_OID_REQUEST. Per indicare la versione della struttura di NDIS_OID_REQUEST, impostare il membro revisione su uno dei valori seguenti:

NDIS_OID_REQUEST_REVISION_2

È stato aggiunto il SwitchId, VPortIde i membri Flag per NDIS 6.50.

Impostare il membroIntestazione NDIS_SIZEOF_OID_REQUEST_REVISION_2 .

NDIS_OID_REQUEST_REVISION_1

Versione originale per NDIS 6.0.

Impostare membro Dimensioniintestazione su NDIS_SIZEOF_OID_REQUEST_REVISION_1.

RequestType

Tipo di richiesta come uno dei valori di enumerazione NDIS_REQUEST_TYPE.

PortNumber

Porta a cui viene inviata la richiesta. Se la porta è sconosciuta o predefinita, questo membro è zero.

Timeout

Timeout, espresso in secondi, per la richiesta. NDIS può reimpostare il driver o annullare la richiesta se il timeout scade prima che il driver completi la richiesta.

RequestId

Identificatore della richiesta. Se un driver miniport deve completare immediatamente una richiesta e completa la richiesta con stato NDIS_STATUS_INDICATION_REQUIRED, il driver miniport usa questo valore RequestId per impostare il RequestId membro della struttura di NDIS_STATUS_INDICATION associata.

I driver NDIS o overlying possono anche usare il RequestId per annullare una richiesta. Quando un driver miniport riceve una richiesta di annullamento, il driver miniport annulla tutte le richieste in sospeso con un RequestId corrispondente. Se RequestId è zero, il driver miniport può ignorare questo membro. Per altre informazioni sulle indicazioni sullo stato, vedere la sezione Osservazioni seguente.

RequestHandle

Handle che identifica l'origine che ha emesso la richiesta OID. Se un driver miniport deve completare immediatamente la richiesta e completa la richiesta con lo stato di NDIS_STATUS_INDICATION_REQUIRED, il driver miniport utilizza questo valore RequestHandle per impostare il DestinationHandle membro della struttura di NDIS_STATUS_INDICATION associata. In questo caso, NDIS invierà solo l'indicazione di stato successiva all'origine che ha emesso la richiesta OID.

Per altre informazioni sulle indicazioni sullo stato, vedere la sezione Osservazioni seguente.

DATA

Unione che definisce i dati della richiesta. Le informazioni nei dati variano in base al tipo di richiesta specificato dal membro RequestType. Vengono specificate le strutture membro seguenti:

DATA.Oid

DATA.QUERY_INFORMATION

Questa struttura contiene i parametri per un NdisRequestQueryInformation o NdisRequestQueryStatistics tipo di richiesta. Questa struttura viene specificata nel modo seguente:


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

DATA.QUERY_INFORMATION.Oid

Identificatore dell'oggetto dell'operazione richiesta. Il valore è un codice XXX OID_ .

DATA.QUERY_INFORMATION.InformationBuffer

Puntatore a un buffer in cui il driver sottostante o NDIS restituisce le informazioni richieste per le richieste di informazioni sulle query.

DATA.QUERY_INFORMATION.InformationBufferLength

Dimensioni, in byte, del buffer in InformationBuffer. Il valore in corrispondenza Oid determina il valore appropriato per questo membro.

DATA.QUERY_INFORMATION.BytesWritten

Numero di byte che il driver o l'NDIS sottostante trasferisce nel buffer in corrispondenza InformationBuffer per le richieste di informazioni sulle query.The number of bytes that the underlying driver or NDIS transfer into the buffer at InformationBuffer for query-information requests. Se la funzione NdisOidRequest restituisce NDIS_STATUS_INVALID_LENGTH, il valore di questo membro è privo di significato.

DATA.QUERY_INFORMATION.BytesNeeded

Numero di byte necessari per restituire le informazioni sulle query richieste dal codice OID_ XXX specificato.

Se NdisOidRequest restituisce NDIS_STATUS_SUCCESS, il valore di questo membro è privo di significato. Se il InformationBufferLength è troppo piccolo per il OID_ XXX specificato in una richiesta di query, questo membro indica la quantità di buffer necessaria per soddisfare la richiesta.

DATA.SET_INFORMATION

Questa struttura contiene i parametri per un tipo di richiesta NdisRequestSetInformation. Questa struttura viene specificata nel modo seguente:


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

DATA.SET_INFORMATION.Oid

Identificatore dell'oggetto dell'operazione richiesta. Il valore è un codice XXX OID_ .

DATA.SET_INFORMATION.InformationBuffer

Puntatore a un buffer da cui il driver sottostante legge le informazioni fornite dal chiamante per le richieste set-information.

DATA.SET_INFORMATION.InformationBufferLength

Dimensioni, in byte, del buffer in InformationBuffer. Il valore in corrispondenza Oid determina il valore appropriato per questo membro.

DATA.SET_INFORMATION.BytesRead

Numero di byte letti dal driver sottostante dal buffer in InformationBuffer per le richieste di informazioni impostate.

DATA.SET_INFORMATION.BytesNeeded

Numero di byte necessari per eseguire l'operazione impostata richiesta dal codice OID_ XXX specificato.

Se NdisOidRequest restituisce NDIS_STATUS_SUCCESS, il valore di questo membro è privo di significato. Se il buffer in InformationBuffer non contiene dati sufficienti per l'OID_ XXX in una richiesta impostata, questo membro indica la quantità di dati necessari.

DATA.METHOD_INFORMATION

Questa struttura contiene i parametri per un tipo di richiesta NdisRequestMethod. Questa struttura viene specificata nel modo seguente:


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

Identificatore dell'oggetto dell'operazione richiesta. Il valore è un codice XXX OID_ .

DATA.METHOD_INFORMATION.InformationBuffer

Puntatore a un buffer in cui il driver sottostante o NDIS restituisce le informazioni richieste per le operazioni di query o da cui il driver sottostante legge le informazioni fornite dal chiamante per le operazioni set. Queste operazioni sono specifiche del tipo di NdisRequestMethod tipo di richiesta in corso.

Nota Questo buffer viene usato sia per le richieste di informazioni sui set che per le richieste di informazioni sulle query. Di conseguenza, i dati nel buffer per la richiesta set-information verrebbero sovrascritti dai dati restituiti per la richiesta di informazioni sulle query. L'utilizzo esatto dipende dall'operazione richiesta come specificato dal membro Oid .

DATA.METHOD_INFORMATION.InputBufferLength

Dimensioni, in byte, dei dati leggibili nel buffer in corrispondenza di InformationBuffer. Il valore in corrispondenza Oid determina il valore appropriato per questo membro.

DATA.METHOD_INFORMATION.OutputBufferLength

Numero di byte nel buffer in corrispondenza InformationBuffer che il driver può scrivere.

DATA.METHOD_INFORMATION.MethodId

Metodo da eseguire per un OID del metodo. Una richiesta OID del metodo può supportare più operazioni definite da MethodId. Può essere qualsiasi valore maggiore o uguale a zero. Zero indica il metodo predefinito. NDIS può definire gli ID dei metodi pubblici con alcuni metodi predefiniti. I driver Miniport possono definire ID di metodo personalizzati. Per altre informazioni sugli ID personalizzati, vedere OID_GEN_SUPPORTED_GUIDS.

DATA.METHOD_INFORMATION.BytesWritten

Per gli OID del metodo, byte scritti deve essere minore o uguale al valore nel membro OutputBufferLength.

DATA.METHOD_INFORMATION.BytesRead

Numero di byte letti dal driver sottostante dal buffer in InformationBuffer per le richieste di informazioni impostate.

Per gli OID del metodo, byteRead deve essere minore o uguale al valore nel membro InputBufferLength.

DATA.METHOD_INFORMATION.BytesNeeded

Numero di byte necessari per restituire informazioni sulle query o per eseguire l'operazione impostata richiesta dal codice OID_ XXX specificato.

Se NdisOidRequest restituisce NDIS_STATUS_SUCCESS, il valore di questo membro è privo di significato. Se il InformationBufferLength è troppo piccolo per l'OID_ XXX in una query, questo membro indica la quantità di buffer necessaria per soddisfare la richiesta. Se il buffer in InformationBuffer non contiene dati sufficienti per il OID_ XXX specificato in un set, questo membro indica la quantità di dati necessari.

_REQUEST_DATA

NdisReserved[NDIS_OID_REQUEST_NDIS_RESERVED_SIZE * sizeof(PVOID)]

Area riservata per NDIS.

MiniportReserved[2 * sizeof(PVOID)]

Area riservata al conducente miniport.

SourceReserved[2 * sizeof(PVOID)]

Area riservata al driver di origine. Riservato per l'allocatore della struttura NDIS_OID_REQUEST. Si tratta in genere di un driver di protocollo NDIS o di un driver di filtro NDIS.

SupportedRevision

Revisione di una struttura NDIS supportata da un driver NDIS 6.0 o versione successiva quando ha gestito una richiesta OID. Una struttura revisionata è qualsiasi struttura NDIS 6.0 con una struttura NDIS_OBJECT_HEADER al suo interno. Quando il driver ha esito positivo nell'impostazione di un OID, deve impostare SupportedRevision sul numero di revisione della struttura supportata. Per altre informazioni sulla versione di NDIS, vedere Specifica delle informazioni sulla versione NDIS.

Reserved1

Riservato per uso futuro.

Reserved2

Riservato per uso futuro.

SwitchId

Valore NDIS_NIC_SWITCH_ID che identifica l'opzione su cui è in esecuzione il VPort di destinazione, specificato da VPortId.

Nota

Questo campo è supportato in NDIS 6.50 e versioni successive.

VPortId

Valore NDIS_NIC_SWITCH_VPORT_ID che identifica il VPort di destinazione della richiesta OID. Questo campo viene considerato valido solo se è impostato il flag NDIS_OID_REQUEST_FLAGS_VPORT_ID_VALID.

Nota

Questo campo è supportato in NDIS 6.50 e versioni successive.

Flags

Valore ULONG che contiene un OR bit per bit di flag per questa richiesta OID. Attualmente, questi flag sono supportati:

Bandiera	Valore	Descrizione
NDIS_OID_REQUEST_FLAGS_VPORT_ID_VALID	0x0001	Quando questo flag è impostato, il membro VportId viene considerato valido e identifica il VPort a cui è destinato l'OID. Se questo flag non è impostato, l'OID è per l'adattatore miniport stesso.

Nota

Questo campo è supportato in NDIS 6.50 e versioni successive.

Osservazioni

Un driver di protocollo o un driver di filtro deve allocare memoria non di paging per il buffer in InformationBuffer e per la struttura NDIS_OID_REQUEST. L'uso di dati allocati dalla memoria di paging può causare errori di pagina irreversibili perché i driver sottostanti vengono eseguiti in IRQL = DISPATCH_LEVEL per eseguire l'operazione richiesta.

NDIS_OID_REQUEST contiene una sottostruttura DATA per ogni tipo di operazione che un driver di protocollo può richiedere di un driver sottostante. Prima di chiamare NdisOidRequest, il driver del protocollo compila i membri pertinenti della sottostruttura che rappresenta l'operazione di query o set specificata nel membro Oid . NDIS o il driver sottostante riempie i membri rimanenti prima di restituire il controllo al chiamante.

Alcune richieste OID consentono a un driver miniport di fornire uno stato di completamento OID con un'indicazione di stato. In questo caso, il driver miniport restituisce NDIS_STATUS_INDICATION_REQUIRED per lo stato di completamento della richiesta OID. Un driver miniport non può restituire questo stato a meno che l'OID specifico non lo consenta. Per determinare se questo stato è consentito, vedere la pagina di riferimento dell'OID.

Se un'indicazione di stato è associata a una richiesta OID in cui il driver miniport ha restituito NDIS_STATUS_INDICATION_REQUIRED, il driver che indica lo stato deve impostare il DestinationHandle e i membri RequestId nella struttura NDIS_STATUS_INDICATION.

In questo caso, il driver imposta i membri DestinationHandle e RequestId sui valori del RequestHandle e i membri RequestId nella struttura NDIS_OID_REQUEST.

Ad esempio, nella rete wireless, l'elaborazione di una richiesta OID può richiedere molto tempo per il completamento. In questo caso, il driver miniport può completare immediatamente la richiesta OID e fornire un'indicazione di stato in un secondo momento per fornire il risultato finale per la richiesta OID.

I tipi NdisRequestGenericn(1-4) sono disponibili per i driver miniport che creano richieste interne. Per implementare tale richiesta, un driver miniport assegna una variabile interna a uno di questi tipi generici.