funzione FILTER_SYNCHRONOUS_OID_REQUEST (ndis.h)

  • Articolo

NDIS chiama la funzione FilterSynchronousOidRequest di un driver di filtro per visualizzare in anteprima una richiesta OID sincrona prima che la richiesta venga assegnata al driver miniport sottostante.

Questa funzione è supportata in NDIS 6.81 e versioni successive.

Sintassi

NDIS_STATUS FILTER_SYNCHRONOUS_OID_REQUEST(
            NDIS_HANDLE      FilterModuleContext,
  [in, out] NDIS_OID_REQUEST *OidRequest,
  [out]     PVOID            *CallContext
);

Parametri

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, out] OidRequest

Puntatore a una struttura NDIS_OID_REQUEST che specifica l'operazione richiesta.

[out] CallContext

Uno slot di archiviazione di dimensioni PVOID per il driver di filtro per condividere lo stato tra i gestori FilterSynchronousOidRequest e FilterSynchronousOidRequestComplete . NDIS garantisce che questo punta inizialmente a un valore zero. Per altre informazioni, vedere la sezione Osservazioni.

Valore restituito

Questa funzione restituisce uno dei codici di NDIS_STATUS appropriati seguenti:

Codice restituito Descrizione
NDIS_STATUS_SUCCESS Consentire alla richiesta OID di continuare a propagarsi fino al driver miniport. I driver di filtro devono restituire questo codice di stato per qualsiasi tipo non riconosciuto di OID.
NDIS_STATUS_ALREADY_COMPLETE Arrestare la propagazione della richiesta OID verso il basso e restituirla al chiamante con lo stato NDIS_STATUS_SUCCESS.
  • NDIS_STATUS_BUFFER_TOO_SHORT
  • NDIS_STATUS_INVALID_LENGTH
  • NDIS_STATUS_INVALID_DATA
 Uguale a FilterDirectOidRequest.
NDIS_STATUS_RESOURCES Uguale a FilterDirectOidRequest, ma con cautela che le richieste OID sincrone devono essere completate rapidamente e pertanto i driver di filtro devono in genere evitare di allocare risorse.
NDIS_STATUS_NOT_SUPPORTED I driver di filtro non devono restituire questo codice semplicemente perché l'OID non è riconosciuto. I driver di filtro possono restituire questo risultato solo se il filtro riconosce l'operazione, ma non può eseguirla per qualche motivo.

Commenti

FilterSynchronousOidRequest è una funzione facoltativa. Se un driver di filtro non deve osservare o modificare le richieste OID sincrone inviate al driver miniport, il driver di filtro deve impostare il punto di ingresso per questa funzione su NULL quando chiama NdisFRegisterFilterDriver.

NDIS chiama la funzione FilterSynchronousOidRequest del driver di filtro per elaborare le richieste OID sincrone originate da driver eccessivamente. I driver di filtro possono leggere o modificare alcuni campi nella struttura NDIS_OID_REQUEST come indicato di seguito:

Campo Filtrare l'accesso
Intestazione Sola lettura
RequestType Lettura/Scrittura
PortNumber Lettura/Scrittura
Timeout Non accedere
RequestId Non accedere
Requesthandle Lettura/Scrittura
DATA Lettura/Scrittura
NdisReserved Non accedere
MiniportReserved Non accedere
SourceReserved Non accedere
SupportedRevision Lettura/Scrittura
Reserved1, Reserved2 Non accedere
SwitchId Lettura/Scrittura
VPortId Lettura/Scrittura
Flags Lettura/Scrittura

Oltre a modificare la struttura di NDIS_OID_REQUEST , i driver di filtro possono controllare la richiesta usando il codice restituito da FilterSynchronousOidRequest:

  • NDIS_STATUS_SUCCESS: l'OID continua a propagarsi fino al driver miniport.
  • NDIS_STATUS_ALREADY_COMPLETE: l'OID viene immediatamente completato ai driver overlying, senza prima propagarsi al driver miniport. La richiesta OID viene completata al driver overlying con NDIS_STATUS_SUCCESS.
  • Qualsiasi altro codice di stato: l'OID viene immediatamente completato ai driver overlying, senza prima propagarsi al driver miniport. La richiesta OID viene completata al driver overlying con il codice di stato restituito dal driver di filtro.

Se il driver del filtro registra anche un gestore FilterSynchronousOidRequestComplete , NDIS garantisce che il gestore FilterSynchronousOidRequestComplete venga chiamato se e solo se il gestore FilterSynchronousOidRequest restituisce NDIS_STATUS_SUCCESS.

Il gestore FilterSynchronousOidRequest può scrivere qualsiasi valore di dimensioni PVOID in *CallContext e lo stesso valore verrà restituito al gestore FilterSynchronousOidRequestComplete del driver di filtro al termine della richiesta OID. Il driver di filtro può usarlo per trasportare lo stato tra i due gestori. Poiché il gestore FilterSynchronousOidRequestComplete viene richiamato solo se il gestore FilterSynchronousOidRequest restituisce NDIS_STATUS_SUCCESS, non esiste alcun motivo per scrivere un valore in *CallContext quando restituisce qualsiasi altro codice. Analogamente, non esiste alcun motivo per scrivere un valore in *CallContext se il driver di filtro non fornisce un gestore FilterSynchronousOidRequestComplete .

I driver di filtro non devono restituire NDIS_STATUS_PENDING da un gestore FilterSynchronousOidRequest . Le richieste OID sincrone non possono essere sospese o annullate.

I driver di filtro devono essere restituiti rapidamente dal gestore FilterSynchronousOidRequest , senza bloccare, attendere o dormire. Le richieste OID sincrone vengono usate solo per le operazioni a bassa latenza e i driver di filtro devono cercare di continuare o completarli entro diversi millisecondi. NDIS non serializza le richieste OID sincrone tra loro, rispetto ad altre richieste OID o a FilterPause. È responsabilità del driver di filtro implementare qualsiasi sincronizzazione necessaria.

NDIS serializza le richieste OID sincrone su FilterDetach: NDIS garantisce che nessuna richiesta OID sincrona sarà attiva una volta richiamato FilterDetach .

I driver di filtro non devono chiamare NdisAllocateCloneOidRequest o NdisCancelOidRequest in una richiesta OID sincrona. I driver di filtro non devono chiamare NdisFSynchronousOidRequest su una richiesta OID ricevuta tramite un gestore FilterSynchronousOidRequest .

Se un driver di filtro genera irQL nel gestore FilterSynchronousOidRequest , deve ripristinare irQL al livello iniziale prima di restituire dal gestore FilterSynchronousOidRequest .

Requisiti

Requisito Valore
Client minimo supportato Windows 10, versione 1709
Piattaforma di destinazione Windows
Intestazione ndis.h (include Ndis.h)
IRQL <= DISPATCH_LEVEL

Vedi anche

FilterSynchronousOidRequestComplete

NdisFSynchronousOidRequest

Interfaccia richiesta OID sincrona in NDIS 6.80