FltLockUserBuffer-Funktion (fltkernel.h)

Artikel
07/16/2024

Die FltLockUserBuffer Routine sperrt den Benutzerpuffer für einen bestimmten E/A-Vorgang.

Syntax

NTSTATUS FLTAPI FltLockUserBuffer(
  [in] PFLT_CALLBACK_DATA CallbackData
);

Parameter

[in] CallbackData

Zeigen Sie auf die FLT_CALLBACK_DATA Rückrufdatenstruktur für den E/A-Vorgang.

Rückgabewert

FltLockUserBuffer gibt STATUS_SUCCESS zurück, wenn der Benutzerpuffer erfolgreich gesperrt wurde (oder wenn der Puffer bereits durch einen vorherigen Aufruf von FltLockUserBuffergesperrt wurde). Andernfalls wird ein entsprechender NTSTATUS-Wert zurückgegeben, z. B. einer der folgenden:

Rückgabecode	Beschreibung
STATUS_INSUFFICIENT_RESOURCES	FltLockUserBuffer ein Poolzuordnungsfehler aufgetreten ist. Dies ist ein Fehlercode.
STATUS_INVALID_PARAMETER	Es wurde ein ungültiger Parameter gefunden. Beispielsweise verfügt der E/A-Vorgang nicht über einen MDL-Parameter, oder die IRP_MJ_READ- oder IRP_MJ_WRITE-E/A-Vorgänge weisen einen Nebencode von IRP_MN_MDL auf. Dies ist ein Fehlercode.

Bemerkungen

Um eine optimale Leistung zu erzielen, sollten Filtertreiber FltLockUserBuffer- nur dann aufrufen, wenn dies unbedingt erforderlich ist. Die Leistungsverlangsamung liegt nicht an FltLockUserBuffer selbst, sondern aufgrund der Leistungseinbußen, die durch den nachfolgenden Aufruf von MmGetSystemAddressForMdlSafeentstehen; weitere Informationen finden Sie weiter unten in den Anmerkungen.

Ein Minifiltertreiber kann FltLockUserBuffer- aufrufen, um den Benutzerpuffer für einen der folgenden E/A-Vorgänge zu sperren:

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 (mit Ausnahme von IRP_MN_MDL)
IRP_MJ_SET_EA
IRP_MJ_SET_QUOTA
IRP_MJ_WRITE (mit Ausnahme von IRP_MN_MDL)

FltLockUserBuffer bestimmt die entsprechende Zugriffsmethode (IoReadAccess, IoWriteAccess oder IoModifyAccess), die auf den gesperrten Puffer basierend auf dem Typ des E/A-Vorgangs angewendet werden soll.

FltLockUserBuffer legt den MdlAddress (oder OutputMdlAddress) in der Struktur des Rückrufdatenparameters (FLT_PARAMETERS) so fest, dass er auf die MDL für die gesperrten Seiten verweist. Wenn keine MDL vorhanden ist, weist FltLockUserBuffer einen zu. (Beachten Sie, dass FltMgr vor dem Dateisystem keine MDL generieren kann, weshalb FltLockUserBuffer STATUS_INVALID_PARAMETER für IRP_MJ_READ oder IRP_MJ_WRITE mit IRP_MN_MDL zurückgibt).

Wenn die Parameterstruktur des Rückrufdatens einen Systempuffer (Irp->AssociatedIrp.SystemBuffer) enthält und keinen Benutzerpuffer enthält (Irp->UserBuffer), FltLockUserBuffer sperrt den Systempuffer. Wenn keine MDL für den Systempuffer vorhanden ist, weist FltLockUserBuffer eine zu.

Wenn die Struktur des Rückrufdatenparameters einen Benutzerpuffer enthält, FltLockUserBufferProbes und Sperrungen den Benutzerpuffer.

Der Aufrufer kann in jedem Prozesskontext ausgeführt werden. FltLockUserBuffer den Puffer automatisch im richtigen Prozesskontext sperrt.

Wenn FltLockUserBuffer aus einer Rückrufroutine (PFLT_PRE_OPERATION_CALLBACK) aufgerufen wird und eine MDL zugeordnet wird, legt FltLockUserBuffer das FLTFL_CALLBACK_DATA_DIRTY Flag in der Rückrufdatenstruktur (FLT_CALLBACK_DATA) fest, sodass das E/A-System die MDL freigibt, wenn der E/A-Vorgang abgeschlossen ist.

Zum Sparen von Systemseitentabelleneinträgen (PTEs) FltLockUserBuffer die gesperrten Seiten nicht zugeordnet. Nach dem Aufrufen FltLockUserBuffermuss der Aufrufer MmGetSystemAddressForMdlSafeaufrufen, wobei der MdlAddress (oder OutputMdlAddress) in der Struktur der Rückrufdatenparameter als Wert des Mdl Parameters übergeben wird, um einen Systempuffer abzurufen, der diesen Speicher darstellt.

Wenn die Rückrufdatenstruktur freigegeben wird, wird der gesperrte Puffer automatisch entsperrt, und die MDL wird freigegeben. Der Anrufer sollte niemals die MDL freigeben; Dies erfolgt automatisch vom E/A-System.

FltLockUserBuffer- kann für schnelle E/A- und IRP-basierte Vorgänge aufgerufen werden.