FILTER_OID_REQUEST funzione di callback (ndis.h)
NDIS chiama la funzione FilterOidRequest di un driver di filtro per elaborare una richiesta OID associata al modulo di filtro specificato.
Sintassi
FILTER_OID_REQUEST FilterOidRequest;
NDIS_STATUS FilterOidRequest(
[in] NDIS_HANDLE FilterModuleContext,
[in] PNDIS_OID_REQUEST OidRequest
)
{...}
Parametri
[in] FilterModuleContext
Handle per l'area di contesto per il modulo di filtro che rappresenta la destinazione di questa richiesta. Il driver di filtro ha 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 OID_XXX . La struttura può specificare una richiesta di query OID o una richiesta di set OID. Per altre informazioni sugli OID, vedere NDIS OID.
Valore restituito
FilterOidRequest restituisce uno dei valori di stato seguenti:
| Codice restituito | Descrizione |
|---|---|
|
FilterOidRequest ha completato correttamente la query o l'operazione di impostazione del driver di filtro per questo modulo di filtro. |
|
Indica che il driver di filtro completerà la richiesta in modo asincrono. Al termine della richiesta, il driver deve chiamare il Funzione NdisFOidRequestComplete per informare NDIS che la richiesta è stata completata. |
|
Indica che la richiesta, specificata in OidRequest, non è valida o non è riconosciuta. |
|
FilterOidRequest non supporta l'OID, l'OID è facoltativo. |
|
Indica che il buffer, fornito in OidRequest, è troppo piccolo per contenere i dati richiesti. |
|
Per un'operazione di query, il membro InformationBufferLength della struttura NDIS_OID_REQUEST non corrisponde alla lunghezza richiesta dall'OID specificato. FilterOidRequest ha restituito le dimensioni del buffer necessarie, in byte, nel membro BytesNeeded della struttura NDIS_OID_REQUEST. |
|
Per un'operazione set, i dati forniti nel membro InformationBuffer della struttura NDIS_OID_REQUEST non sono validi per l'OID specificato. |
|
FilterOidRequest ha tentato di raccogliere le informazioni richieste ma non è riuscito. |
|
FilterOidRequest non è riuscito a causa di risorse insufficienti. |
|
FilterOidRequest restituisce NDIS_STATUS_FAILURE se non si applica nessuno dei valori precedenti. Il driver di filtro deve chiamare la funzione NdisWriteErrorLogEntry con parametri che specificano il motivo dell'errore. |
Commenti
FilterOidRequest è una funzione facoltativa. Se un driver di filtro non usa richieste OID, può impostare il punto di ingresso per questa funzione su NULL quando chiama la funzione NdisFRegisterFilterDriver . Se un driver di filtro definisce una funzione FilterOidRequestComplete , deve fornire la funzione FilterOidRequest .
NDIS chiama la funzione FilterOidRequest del driver di filtro per elaborare le richieste OID originate da driver eccessivamente. I driver di filtro possono inoltrare tali richieste ai driver sottostanti chiamando la funzione NdisFOidRequest .
Prima che il driver chiami NdisFOidRequest, il driver deve allocare una struttura di NDIS_OID_REQUEST e trasferire le informazioni sulla richiesta alla nuova struttura chiamando NdisAllocateCloneOidRequest. Come opzione, un driver di filtro può completare immediatamente una richiesta senza inoltrare la richiesta.
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 la funzione NdisFOidRequestComplete per informare NDIS che la richiesta è stata completata.
Per un'operazione di query , FilterOidRequest restituisce le informazioni richieste nel membro InformationBuffer e imposta la variabile nel membro BytesWritten della struttura NDIS_OID_REQUEST sulla quantità di informazioni restituite. I driver sottostanti eseguono questa operazione se il driver di filtro ha passato la richiesta a con NdisFOidRequest.
Per un'operazione set, FilterOidRequest può usare i dati nel membro InformationBuffer della struttura NDIS_OID_REQUEST per impostare le informazioni richieste dall'OID specificato. In questo caso , FilterOidRequest imposta la variabile in BytesRead sulla quantità dei dati forniti usati. I driver sottostanti eseguono questa operazione se il driver di filtro ha passato la richiesta a con NdisFOidRequest.
Come i driver miniport, i driver di filtro possono ricevere una sola richiesta alla volta. NDIS serializza le richieste inviate a un driver di filtro. NDIS non può chiamare FilterOidRequest prima che un driver di filtro completi la richiesta corrente.
NDIS chiama FilterOidRequest in IRQL <= DISPATCH_LEVEL.
Esempi
Per definire una funzione FilterOidRequest , è innanzitutto 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 con i tipi di funzione consente di eseguire l'analisi del codice per i driver, l'SDV ( Static Driver Verifier ) e altri strumenti di verifica rilevano gli errori ed è un requisito per la scrittura dei driver per il sistema operativo Windows.Ad esempio, per definire una funzione FilterOidRequest denominata "MyOidRequest", usare il tipo FILTER_OID_REQUEST come illustrato nell'esempio di codice seguente:
FILTER_OID_REQUEST MyOidRequest;
Implementare quindi la funzione come segue:
_Use_decl_annotations_
NDIS_STATUS
MyOidRequest(
NDIS_HANDLE FilterModuleContext,
PNDIS_OID_REQUEST OidRequest
)
{...}
Il tipo di funzione FILTER_OID_REQUEST è definito nel file di intestazione Ndis.h. Per identificare in modo più accurato gli errori quando si eseguono gli strumenti di analisi del codice, assicurarsi di aggiungere l'annotazione Use_decl_annotations alla definizione della funzione. L'annotazione Use_decl_annotations assicura che vengano utilizzate le annotazioni applicate al tipo di funzione FILTER_OID_REQUEST nel file di intestazione. Per altre informazioni sui requisiti per le dichiarazioni di funzione, vedere Dichiarazione di funzioni tramite tipi di ruolo di funzione per i driver NDIS.
Per informazioni sulle Use_decl_annotations, vedere Annotazione del comportamento della funzione.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Supportato in NDIS 6.0 e versioni successive. |
| Piattaforma di destinazione | Windows |
| Intestazione | ndis.h (include Ndis.h) |
| IRQL | <= DISPATCH_LEVEL |