Funzione FltLockUserBuffer (fltkernel.h)

Articolo
07/16/2024

La routine FltLockUserBuffer blocca il buffer utente per una determinata operazione di I/O.

Sintassi

NTSTATUS FLTAPI FltLockUserBuffer(
  [in] PFLT_CALLBACK_DATA CallbackData
);

Parametri

[in] CallbackData

Puntatore alla struttura dei dati di callback FLT_CALLBACK_DATA per l'operazione di I/O.

Valore restituito

FltLockUserBuffer restituisce STATUS_SUCCESS se blocca correttamente il buffer utente o se il buffer è già stato bloccato da una chiamata precedente a FltLockUserBuffer. In caso contrario, restituisce un valore NTSTATUS appropriato, ad esempio uno dei seguenti:

Codice restituito	Descrizione
STATUS_INSUFFICIENT_RESOURCES	FltLockUserBuffer rilevato un errore di allocazione del pool. Si tratta di un codice di errore.
STATUS_INVALID_PARAMETER	È stato rilevato un parametro non valido. Ad esempio, l'operazione di I/O non dispone di un parametro MDL o delle operazioni di I/O IRP_MJ_READ o IRP_MJ_WRITE ha un codice secondario di IRP_MN_MDL. Si tratta di un codice di errore.

Osservazioni

Per ottenere prestazioni ottimali, i driver di filtro non devono chiamare FltLockUserBuffer a meno che non sia assolutamente necessario. Il rallentamento delle prestazioni non è dovuto a FltLockUserBuffer stesso, ma piuttosto a causa della riduzione delle prestazioni sostenuta dalla chiamata successiva a MmGetSystemAddressForMdlSafe; per altre informazioni, vedere le osservazioni successive.

Un driver minifilter può chiamare FltLockUserBuffer per bloccare il buffer utente per una delle operazioni di I/O seguenti:

IRP_MJ_DEVICE_CONTROL
IRP_MJ_DIRECTORY_CONTROL
IRP_MJ_FILE_SYSTEM_CONTROL
IRP_MJ_INTERNAL_DEVICE_CONTROL
IRP_MJ_QUERY_EA
IRP_MJ_QUERY_QUOTA
IRP_MJ_QUERY_SECURITY
IRP_MJ_READ (ad eccezione di IRP_MN_MDL)
IRP_MJ_SET_EA
IRP_MJ_SET_QUOTA
IRP_MJ_WRITE (ad eccezione di IRP_MN_MDL)

FltLockUserBuffer determina il metodo di accesso appropriato (IoReadAccess, IoWriteAccess o IoModifyAccess) da applicare per il buffer bloccato in base al tipo di operazione di I/O.

FltLockUserBuffer imposta il membro MdlAddress (o OutputMdlAddress) nella struttura dei parametri di dati del callback (FLT_PARAMETERS) in modo che punti al MDL per le pagine bloccate. Se non è presente alcun MDL, FltLockUserBuffer alloca uno. Si noti che FltMgr non può generare un MDL prima che il file system funzioni, motivo per cui FltLockUserBuffer restituisce STATUS_INVALID_PARAMETER per IRP_MJ_READ o IRP_MJ_WRITE con IRP_MN_MDL.

Se la struttura dei parametri dei dati di callback contiene un buffer di sistema (Irp->AssociatedIrp.SystemBuffer) e non contiene un buffer utente (Irp->UserBuffer), FltLockUserBuffer blocca il buffer di sistema. Se non è presente alcun MDL per il buffer di sistema, FltLockUserBuffer alloca uno.

Se la struttura dei parametri dei dati di callback contiene un buffer utente, FltLockUserBufferprobe e blocchi buffer utente.

Il chiamante può essere in esecuzione in qualsiasi contesto di processo. FltLockUserBuffer blocca automaticamente il buffer nel contesto di processo corretto.

Se FltLockUserBuffer viene chiamato da una routine di callback preoperazione (PFLT_PRE_OPERATION_CALLBACK) e alloca un MDL, FltLockUserBuffer imposta il flag FLTFL_CALLBACK_DATA_DIRTY nella struttura dei dati di callback (FLT_CALLBACK_DATA) in modo che il sistema di I/O libera il MDL al termine dell'operazione di I/O.

Per conservare le voci della tabella delle pagine di sistema ,FltLockUserBuffer non esegue il mapping delle pagine bloccate. Dopo aver chiamato FltLockUserBuffer, il chiamante deve chiamare membro MmGetSystemAddressForMdlSafe, passando il MdlAddress (o OutputMdlAddress) nella struttura dei parametri dei dati di callback come valore del parametro Mdl, per ottenere un buffer di sistema che rappresenta questa memoria.

Quando la struttura dei dati di callback viene liberata, il buffer bloccato viene sbloccato automaticamente e il file MDL viene liberato. Il chiamante non deve mai liberare il file MDL; il sistema di I/O esegue automaticamente questa operazione.

FltLockUserBuffer può essere chiamato per operazioni rapide di I/O e IRP.