Funzione FltLockUserBuffer (fltkernel.h)

Articolo
10/05/2023

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 ha 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 oppure il IRP_MJ_READ o IRP_MJ_WRITE operazioni di I/O ha un codice secondario di IRP_MN_MDL. Si tratta di un codice di errore.

Commenti

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 penalità delle prestazioni sostenuta dalla chiamata successiva a MmGetSystemAddressForMdlSafe; per altre informazioni, vedere la sezione 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 di callback (FLT_PARAMETERS) in modo che punti al MDL per le pagine bloccate. Se non è presente alcun linguaggio MDL, FltLockUserBuffer ne alloca uno. Si noti che FltMgr non può generare un MDL prima che il file system esequisi, 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 ne alloca uno.

Se la struttura dei parametri dei dati di callback contiene un buffer utente, i probe FltLockUserBuffere bloccano il buffer utente.

Il chiamante può essere in esecuzione in qualsiasi contesto del processo. FltLockUserBuffer blocca automaticamente il buffer nel contesto del 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 liberi il MDL al termine dell'operazione di I/O.

Per conservare le voci della tabella delle pagine di sistema (PTEs), FltLockUserBuffer non esegue il mapping delle pagine bloccate. Dopo aver chiamato FltLockUserBuffer, il chiamante deve chiamare MmGetSystemAddressForMdlSafe, passando il membro 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 linguaggio MDL viene liberato. Il chiamante non dovrebbe mai liberare il MDL; il sistema di I/O esegue questa operazione automaticamente.

FltLockUserBuffer può essere chiamato per operazioni di I/O veloci e basate su IRP.