FILTER_DIRECT_OID_REQUEST funzione di callback (ndis.h)

Articolo
08/07/2023

NDIS chiama la funzione FilterDirectOidRequest di un driver di filtro per elaborare una richiesta OID diretta associata al modulo di filtro specificato.

Nota È necessario dichiarare la funzione usando il tipo di FILTER_DIRECT_OID_REQUEST . Per altre informazioni, vedere la sezione Esempi seguenti.

Sintassi

FILTER_DIRECT_OID_REQUEST FilterDirectOidRequest;

NDIS_STATUS FilterDirectOidRequest(
  [in] NDIS_HANDLE FilterModuleContext,
  [in] PNDIS_OID_REQUEST OidRequest
)
{...}

Parametri

[in] FilterModuleContext

Handle per l'area di contesto per il modulo di filtro di destinazione di questa richiesta. Il driver di filtro creato e inizializzato questa area di contesto nella funzione FilterAttach .

[in] OidRequest

Puntatore a una struttura NDIS_OID_REQUEST che specifica l'operazione richiesta, incluso il codice xx OID_. La struttura può specificare una richiesta di query o una richiesta impostata

Valore restituito

FilterDirectOidRequest restituisce uno dei valori di stato seguenti:

Codice restituito	Descrizione
NDIS_STATUS_SUCCESS	FilterDirectOidRequest ha completato correttamente l'operazione di query o set del driver di filtro per questo modulo di filtro.
NDIS_STATUS_PENDING	Il driver di filtro completa la richiesta in modo asincrono. Al termine della richiesta, il driver deve chiamare Funzione NdisFDirectOidRequestComplete per informare NDIS che la richiesta è stata completata.
NDIS_STATUS_INVALID_OID	Richiesta specificata da OidRequest non valida o non riconosciuta.
NDIS_STATUS_NOT_SUPPORTED	FilterDirectOidRequest non supporta l'OID; l'OID è facoltativo.
NDIS_STATUS_BUFFER_TOO_SHORT	Il buffer fornito da OidRequest era troppo piccolo per contenere i dati richiesti.
NDIS_STATUS_INVALID_LENGTH	Per un'operazione di query, il membro InformationBufferLength della struttura NDIS_OID_REQUEST non corrisponde alla lunghezza richiesta dall'OID specificato. FilterDirectOidRequest ha restituito le dimensioni del buffer necessarie, in byte, nel membro ByteNeeded della struttura NDIS_OID_REQUEST.
NDIS_STATUS_INVALID_DATA	Per un'operazione impostata, i dati forniti nel membro InformationBuffer della struttura NDIS_OID_REQUEST non sono validi per l'OID specificato.
NDIS_STATUS_NOT_ACCEPTED	FilterDirectOidRequest ha tentato di raccogliere le informazioni richieste, ma non è riuscito.
NDIS_STATUS_RESOURCES	FilterDirectOidRequest non è riuscito a causa di risorse insufficienti.
NDIS_STATUS_FAILURE	N uno dei valori restituiti precedenti si applica. Il driver di filtro deve chiamare la funzione NdisWriteErrorLogEntry con parametri che specificano il motivo dell'errore.

Commenti

FilterDirectOidRequest è una funzione facoltativa. Se un driver di filtro non usa richieste OID dirette, può impostare il punto di ingresso per questa funzione su NULL quando chiama la funzione NdisFRegisterFilterDriver . Se un driver di filtro definisce un La funzione FilterDirectOidRequestComplete deve fornire la funzione FilterDirectOidRequest .

NDIS chiama la funzione FilterDirectOidRequest del driver di filtro per elaborare le richieste OID dirette che sono originati da driver overlying. I driver di filtro possono inoltrare tali richieste ai driver sottostanti chiamando la funzione NdisFDirectOidRequest . Come opzione, un driver di filtro può anche completare immediatamente una richiesta senza inoltrare la richiesta.

Prima che il driver chiami NdisFDirectOidRequest, il driver deve allocare una struttura NDIS_OID_REQUEST e trasferire le informazioni sulla richiesta alla nuova struttura chiamando Funzione NdisAllocateCloneOidRequest .

Per completare una richiesta in modo sincrono, il driver di filtro restituisce NDIS_STATUS_SUCCESS o uno stato di errore. Se il driver restituisce NDIS_STATUS_PENDING, deve chiamare Funzione NdisFDirectOidRequestComplete per informare NDIS che la richiesta è stata completata.

Per un'operazione di query , FilterDirectOidRequest restituisce le informazioni richieste nel membro InformationBuffer e imposta la variabile nel membro ByteScritto della struttura NDIS_OID_REQUEST per la quantità di informazioni restituite. I driver sottostanti eseguono questa operazione se il driver di filtro ha passato la richiesta con NdisFDirectOidRequest.

Per un'operazione set , FilterDirectOidRequest può usare i dati nel membro InformationBuffer della struttura NDIS_OID_REQUEST per impostare le informazioni necessarie per l'OID specificato. In questo caso FilterDirectOidRequest imposta la variabile in ByteRead sulla quantità dei dati specificati usati. I driver sottostanti impostano BytesRead in questo modo se il driver di filtro ha passato la richiesta con NdisFDirectOidRequest.

NDIS non serializza le richieste inviate a FilterDirectOidRequest con altre richieste OID. Il driver di filtro deve essere in grado di gestire più chiamate a FilterDirectOidRequest quando altre richieste inviate a FilterOidRequest o FilterDirectOidRequest sono in sospeso.

NDIS chiama FilterDirectOidRequest in IRQL <= DISPATCH_LEVEL.

Esempi

Per definire una funzione FilterDirectOidRequest , è prima necessario fornire una dichiarazione di funzione che identifica il tipo di funzione che si sta definendo. Windows fornisce un set di tipi di funzione per i driver. La dichiarazione di una funzione usando i tipi di funzione consente l'analisi del codice per i driver, il verifica driver statico (SDV) e altri strumenti di verifica trovano errori ed è un requisito per la scrittura di driver per il sistema operativo Windows.

Ad esempio, per definire una funzione FilterDirectOidRequest denominata "MyDirectOidRequest ", usare il tipo di FILTER_DIRECT_OID_REQUEST come illustrato nell'esempio di codice seguente:

FILTER_DIRECT_OID_REQUEST MyDirectOidRequest;

Implementare quindi la funzione come indicato di seguito:

_Use_decl_annotations_
NDIS_STATUS
 MyDirectOidRequest(
    NDIS_HANDLE  FilterModuleContext,
    PNDIS_OID_REQUEST  OidRequest
    )
  {...}

Il tipo di funzione FILTER_DIRECT_OID_REQUEST è definito nel file di intestazione Ndis.h. Per identificare in modo più accurato gli errori durante l'esecuzione degli strumenti di analisi del codice, assicurarsi di aggiungere l'annotazione Use_decl_annotations alla definizione della funzione. L'annotazione Use_decl_annotations garantisce che vengano usate le annotazioni applicate al tipo di funzione FILTER_DIRECT_OID_REQUEST nel file di intestazione. Per altre informazioni sui requisiti per le dichiarazioni di funzione, vedere Dichiarazione di funzioni tramite tipi di ruolo per i driver NDIS.

Per informazioni su Use_decl_annotations, vedere Annotazione del comportamento della funzione.

Requisiti

Requisito	Valore
Client minimo supportato	Supportato in NDIS 6.1 e versioni successive.
Piattaforma di destinazione	Windows
Intestazione	ndis.h (includere Ndis.h)
IRQL	<= DISPATCH_LEVEL