NDIS_OID_REQUEST struttura (ndis/oidrequest.h)

Articolo
02/26/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;

Members

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 NDIS_OID_REQUEST, impostare il membro Revision su uno dei valori seguenti:

NDIS_OID_REQUEST_REVISION_2

Aggiunta dei membri SwitchId, VPortId e Flag per NDIS 6.50.

Impostare il membro Dimensioneintestazione su NDIS_SIZEOF_OID_REQUEST_REVISION_2.

NDIS_OID_REQUEST_REVISION_1

Versione originale per NDIS 6.0.

Impostare il membro Dimensioneintestazione 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, 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 lo stato di NDIS_STATUS_INDICATION_REQUIRED, il driver miniport usa questo valore RequestId per impostare il membro RequestIddella struttura NDIS_STATUS_INDICATION associata.

I driver NDIS o overlying possono anche usare RequestId per annullare una richiesta. Quando un driver miniport riceve una richiesta di annullamento, il driver miniport annulla 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 seguenti.

RequestHandle

Handle che identifica l'origine che ha rilasciato 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 usa questo valore RequestHandle per impostare il membro DestinationHandle della struttura NDIS_STATUS_INDICATION associata. In questo caso, NDIS invierà solo l'indicazione di stato successiva all'origine che ha rilasciato la richiesta OID.

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

DATA

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

DATA.Oid

DATA.QUERY_INFORMATION

Questa struttura contiene i parametri per un tipo di richiesta NdisRequestQueryInformation o NdisRequestQueryStatistics. Questa struttura viene specificata come indicato di seguito:


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

DATA.QUERY_INFORMATION.InformationBufferLength

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

DATA.QUERY_INFORMATION.BytesWritten

Numero di byte che il driver sottostante o NDIS trasferisce nel buffer in InformationBuffer per le richieste di query. Se la funzione NdisOidRequest restituisce NDIS_STATUS_INVALID_LENGTH, il valore di questo membro è senza significato.

DATA.QUERY_INFORMATION.BytesNeeded

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

DATA.SET_INFORMATION

Questa struttura contiene i parametri per un tipo di richiesta NdisRequestSetInformation . Questa struttura viene specificata come indicato di seguito:


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 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 set-information.

DATA.SET_INFORMATION.BytesNeeded

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

Se NdisOidRequest restituisce NDIS_STATUS_SUCCESS, il valore di questo membro è senza senso. Se il buffer in InformationBuffer non contiene dati sufficienti per il OID_ XXX specificato 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 come indicato di seguito:


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 impostate. Queste operazioni sono specifiche del tipo di richiesta NdisRequestMethod da effettuare.

Nota Questo buffer viene usato sia per le richieste set-information che per le query. Di conseguenza, i dati nel buffer per la richiesta set-information verranno 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 InformationBuffer. Il valore in Oid determina il valore appropriato per questo membro.

DATA.METHOD_INFORMATION.OutputBufferLength

Numero di byte nel buffer in 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, come definito da MethodId. Può essere qualsiasi valore maggiore o uguale a zero. Zero indica il metodo predefinito. NDIS può definire OID del metodo pubblico con alcuni metodi predefiniti. I driver Miniport possono definire OID di metodo personalizzati. Per altre informazioni sugli ID personalizzati, vedere OID_GEN_SUPPORTED_GUIDS.

DATA.METHOD_INFORMATION.BytesWritten

Per gli OID del metodo , BytesWritten 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 set-information.

Per gli OID del metodo , BytesRead 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 XXX specificato OID_.

Se NdisOidRequest restituisce NDIS_STATUS_SUCCESS, il valore di questo membro è senza senso. Se InformationBufferLength è troppo piccolo per il OID_ XXX specificato in una query, questo membro indica la dimensione necessaria per soddisfare la richiesta. Se il buffer in InformationBuffer non contiene dati sufficienti per l'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. Questo è in genere un driver del protocollo NDIS o un driver di filtro NDIS.

SupportedRevision

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

Reserved1

Riservato per usi futuri.

Reserved2

Riservato per usi futuri.

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 destinato a questa richiesta OID. Questo campo viene considerato valido solo se il flag di NDIS_OID_REQUEST_FLAGS_VPORT_ID_VALID è impostato.

Nota

Questo campo è supportato in NDIS 6.50 e versioni successive.

Flags

Valore ULONG contenente un or bit per bit di flag per questa richiesta OID. Attualmente, questi flag sono supportati:

Flag	valore	Descrizione
NDIS_OID_REQUEST_FLAGS_VPORT_ID_VALID	0x0001	Quando questo flag viene 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.

Commenti

Un driver di protocollo o un driver di filtro deve allocare memoria non di pagina per il buffer in InformationBuffer e per la struttura NDIS_OID_REQUEST. L'uso dei dati allocati dalla memoria con pagina 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 del protocollo può richiedere di un driver sottostante. Prima di chiamare NdisOidRequest, il driver del protocollo riempie i membri pertinenti della sottostruttura che rappresenta la query o imposta l'operazione 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 restituito NDIS_STATUS_INDICATION_REQUIRED, il driver che effettua l'indicazione di stato deve impostare i membri DestinationHandle e RequestId nella struttura NDIS_STATUS_INDICATION .

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

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

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