Fonction FltLockUserBuffer (fltkernel.h)

Article
10/05/2023

La routine FltLockUserBuffer verrouille la mémoire tampon utilisateur pour une opération d’E/S donnée.

Syntaxe

NTSTATUS FLTAPI FltLockUserBuffer(
  [in] PFLT_CALLBACK_DATA CallbackData
);

Paramètres

[in] CallbackData

Pointeur vers la structure de données de rappel FLT_CALLBACK_DATA pour l’opération d’E/S.

Valeur retournée

FltLockUserBuffer retourne STATUS_SUCCESS s’il verrouille correctement la mémoire tampon utilisateur (ou si la mémoire tampon a déjà été verrouillée par un appel précédent à FltLockUserBuffer.) Sinon, il retourne une valeur NTSTATUS appropriée, telle que l’une des valeurs suivantes :

Code de retour	Description
STATUS_INSUFFICIENT_RESOURCES	FltLockUserBuffer a rencontré un échec d’allocation de pool. Il s’agit d’un code d’erreur.
STATUS_INVALID_PARAMETER	Un paramètre non valide a été rencontré. Par exemple, l’opération d’E/S n’a pas de paramètre MDL, ou les opérations d’E/S IRP_MJ_READ ou IRP_MJ_WRITE ont un code mineur de IRP_MN_MDL. Il s’agit d’un code d’erreur.

Remarques

Pour de meilleures performances, les pilotes de filtre ne doivent pas appeler FltLockUserBuffer , sauf si cela est absolument nécessaire. Le ralentissement des performances n’est pas dû à FltLockUserBuffer lui-même, mais plutôt à la pénalité de performances encourue par l’appel suivant à MmGetSystemAddressForMdlSafe ; pour plus d’informations, consultez remarques ultérieures.

Un pilote de minifiltre peut appeler FltLockUserBuffer pour verrouiller la mémoire tampon utilisateur pour l’une des opérations d’E/S suivantes :

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 (sauf avec IRP_MN_MDL)
IRP_MJ_SET_EA
IRP_MJ_SET_QUOTA
IRP_MJ_WRITE (sauf avec IRP_MN_MDL)

FltLockUserBuffer détermine la méthode d’accès appropriée (IoReadAccess, IoWriteAccess ou IoModifyAccess) à appliquer pour la mémoire tampon verrouillée en fonction du type d’opération d’E/S.

FltLockUserBuffer définit le membre MdlAddress (ou OutputMdlAddress) dans la structure de paramètres de données de rappel (FLT_PARAMETERS) pour qu’il pointe vers la MDL pour les pages verrouillées. S’il n’y a pas de MDL, FltLockUserBuffer en alloue un. (Notez que FltMgr ne peut pas générer de MDL avant le système de fichiers, c’est pourquoi FltLockUserBuffer retourne STATUS_INVALID_PARAMETER pour IRP_MJ_READ ou IRP_MJ_WRITE avec IRP_MN_MDL).

Si la structure des paramètres de données de rappel contient une mémoire tampon système (Irp-AssociatedIrp.SystemBuffer>) et ne contient pas de mémoire tampon utilisateur (Irp-UserBuffer>), FltLockUserBuffer verrouille la mémoire tampon système. S’il n’existe pas de MDL pour la mémoire tampon système, FltLockUserBuffer en alloue un.

Si la structure des paramètres de données de rappel contient une mémoire tampon utilisateur, FltLockUserBuffersonde et verrouille la mémoire tampon utilisateur.

L’appelant peut s’exécuter dans n’importe quel contexte de processus. FltLockUserBuffer verrouille automatiquement la mémoire tampon dans le contexte de processus approprié.

Si FltLockUserBuffer est appelé à partir d’une routine de rappel de pré-opération (PFLT_PRE_OPERATION_CALLBACK) et qu’il alloue un MDL, FltLockUserBuffer définit l’indicateur de FLTFL_CALLBACK_DATA_DIRTY dans la structure de données de rappel (FLT_CALLBACK_DATA) afin que le système d’E/S libère la MDL une fois l’opération d’E/S terminée.

Pour conserver les entrées de table de pages système (PTE), FltLockUserBuffer ne mappe pas les pages verrouillées. Après avoir appelé FltLockUserBuffer, l’appelant doit appeler MmGetSystemAddressForMdlSafe, en passant le membre MdlAddress (ou OutputMdlAddress) dans la structure de paramètres de données de rappel comme valeur du paramètre Mdl , pour obtenir une mémoire tampon système qui représente cette mémoire.

Lorsque la structure de données de rappel est libérée, la mémoire tampon verrouillée est automatiquement déverrouillée et le MDL est libéré. L’appelant ne doit jamais libérer le MDL ; le système d’E/S effectue automatiquement cette opération.

FltLockUserBuffer peut être appelé pour des opérations rapides basées sur les E/S et les IRP.