FltGetFileNameInformationUnsafe, fonction (fltkernel.h)

Article
02/06/2025

La routine FltGetFileNameInformationUnsafe retourne les informations de nom d’un fichier ou d’un répertoire ouvert.

Syntaxe

NTSTATUS FLTAPI FltGetFileNameInformationUnsafe(
  [in]           PFILE_OBJECT               FileObject,
  [in, optional] PFLT_INSTANCE              Instance,
  [in]           FLT_FILE_NAME_OPTIONS      NameOptions,
  [out]          PFLT_FILE_NAME_INFORMATION *FileNameInformation
);

Paramètres

[in] FileObject

Pointeur vers un objet de fichier pour le fichier ou le répertoire. L’objet fichier doit être actuellement ouvert. Ce paramètre est obligatoire et ne peut pas être défini sur NULL.

[in, optional] Instance

Pointeur d’instance pour l’appelant. Ce paramètre peut être défini sur NULL .

[in] NameOptions

Valeur FLT_FILE_NAME_OPTIONS contenant des indicateurs qui spécifient le format des informations de nom à renvoyer, ainsi que la méthode de requête à utiliser par le Gestionnaire de filtres. Ce paramètre est obligatoire et ne peut pas être défini sur NULL.

Le tableau suivant décrit les valeurs d’indicateur de format de nom. Un seul des indicateurs peut être spécifié. Pour plus d’informations sur ces formats, consultez FLT_FILE_NAME_INFORMATION.

Valeur	Signification
FLT_FILE_NAME_NORMALIZED	Le paramètre FileNameInformation reçoit l’adresse d’une structure contenant le nom normalisé du fichier.
FLT_FILE_NAME_OPENED	Le paramètre FileNameInformation reçoit l’adresse d’une structure contenant le nom utilisé lors de l’ouverture du fichier.
FLT_FILE_NAME_SHORT	Le paramètre FileNameInformation reçoit l’adresse d’une structure contenant le nom court (8.3) du fichier. Le nom court se compose de jusqu’à 8 caractères, suivi immédiatement d’un point et jusqu’à 3 caractères supplémentaires. Le nom court d’un fichier n’inclut pas le nom du volume, le chemin d’accès au répertoire ou le nom du flux.

Le tableau suivant décrit les valeurs de l’indicateur de méthode de requête. Un seul des indicateurs peut être spécifié.

Valeur	Signification
FLT_FILE_NAME_QUERY_DEFAULT	FltGetFileNameInformationUnsafe interroge le cache de noms du Gestionnaire de filtres pour obtenir les informations de nom de fichier. Si le nom est introuvable dans le cache, FltGetFileNameInformationUnsafe interroge le système de fichiers et met en cache le résultat.
FLT_FILE_NAME_QUERY_CACHE_ONLY	FltGetFileNameInformationUnsafe interroge le cache de noms du Gestionnaire de filtres pour obtenir les informations de nom de fichier. FltGetFileNameInformationUnsafe n’interroge pas le système de fichiers.
FLT_FILE_NAME_QUERY_FILESYSTEM_ONLY	FltGetFileNameInformationUnsafe interroge le système de fichiers pour obtenir les informations de nom de fichier. FltGetFileNameInformationUnsafe n’interroge pas le cache de noms du Gestionnaire de filtres et ne met pas en cache le résultat de la requête du système de fichiers.
FLT_FILE_NAME_QUERY_ALWAYS_ALLOW_CACHE_LOOKUP	FltGetFileNameInformationUnsafe interroge le cache de noms du Gestionnaire de filtres pour obtenir les informations de nom de fichier. Si le nom est introuvable dans le cache et qu’il est actuellement sûr de le faire, FltGetFileNameInformationUnsafe interroge le système de fichiers pour obtenir les informations de nom de fichier et met en cache le résultat.

[out] FileNameInformation

Pointeur vers une variable allouée par l’appelant qui reçoit l’adresse d’une structure FLT_FILE_NAME_INFORMATION allouée par le système. FltGetFileNameInformationUnsafe alloue cette structure à partir du pool paginé. Lorsque ces informations ne sont plus nécessaires, l’appelant doit libérer la structure en appelant FltReleaseFileNameInformation. Ce paramètre est obligatoire et ne peut pas être défini sur NULL.

Valeur de retour

FltGetFileNameInformationUnsafe retourne STATUS_SUCCESS ou une valeur NTSTATUS appropriée, comme l’une des valeurs suivantes :

Retourner le code	Description
STATUS_FLT_INVALID_NAME_REQUEST	L’objet de fichier vers lequel le paramètre FileObject pointe n’est pas ouvert actuellement. Il s’agit d’un code d’erreur.
STATUS_INVALID_PARAMETER	Une valeur non valide a été passée pour le paramètre FileNameInformation. Il s’agit d’un code d’erreur.

Remarques

La routine FltGetFileNameInformationUnsafe est fournie afin de pouvoir interroger le nom d’un objet de fichier en dehors du contexte d’une opération d’E/S sur cet objet de fichier ; sinon, vous devez appeler FltGetFileNameInformation.

Contrairement à la routine FltGetFileNameInformation, FltGetFileNameInformationUnsafe ne protège pas l’appelant contre les types de circonstances suivants, où l’interrogation du système de fichiers pour obtenir des informations de nom peut entraîner des blocages pour les méthodes de requête autres que FLT_FILE_NAME_QUERY_CACHE_ONLY :

Dans le chemin d’E/S de pagination.
Lorsque le champ TopLevelIrp du thread actuel n’est pas NULL. Pour plus d’informations, consultez IoGetTopLevelIrp.
Une fois qu’une opération de IRP_MJ_CLEANUP est terminée ; autrement dit, dans le chemin post-nettoyage, pré-fermeture ou post-fermeture (l’objet de fichier cible a le jeu d’indicateurs de FO_CLEANUP_COMPLETE).
Dans une routine de rappel de préopération (PFLT_PRE_OPERATION_CALLBACK) ou de postopération (PFLT_POST_OPERATION_CALLBACK) pour l’une des opérations suivantes :
- IRP_MJ_ACQUIRE_FOR_CC_FLUSH
- IRP_MJ_ACQUIRE_FOR_MOD_WRITE
- IRP_MJ_RELEASE_FOR_CC_FLUSH
- IRP_MJ_RELEASE_FOR_MOD_WRITE
- IRP_MJ_RELEASE_FOR_SECTION_SYNCHRONIZATION
Dans une routine de rappel postopératoire pour IRP_MJ_ACQUIRE_FOR_SECTION_SYNCHRONIZATION.
Lorsque toutes les API sont désactivées ; autrement dit, lorsque KeAreAllApcsDisabled retourne TRUE.

Pour Windows Vista / Server 2008 et versions ultérieures, si un minifilter n’a pas encore d’instance de filtre, par exemple dans sa routine DriverEntry, il peut utiliser NULL pour le paramètre instance de. Cela permet routines de DriverEntry d’accéder aux informations de nom de fichier. À l’exception de ce cas, une valeur NULL pour le paramètre d’instance est réservée à l’utilisation du système.

Dans les opérations de création, de liaison en dur et de renommage, le tunneling de noms de fichier peut invalider le composant final dans les informations de nom de fichier normalisées qu’un pilote minifilter récupère dans une routine de rappel de préopération. Si un pilote minifilter récupère les informations de nom de fichier normalisées dans une routine de rappel de préopération (PFLT_PRE_OPERATION_CALLBACK) en appelant une routine telle que FltGetFileNameInformationUnsafe, elle doit appeler FltGetTunneledName de son rappel de postopération (PFLT_POST_OPERATION_CALLBACK) pour récupérer les informations de nom de fichier correctes pour le fichier.

Pour plus d’informations sur les informations sur le nom de fichier normalisé, consultez FLT_FILE_NAME_INFORMATION.

Exigences

Exigence	Valeur
plateforme cible	Universel
d’en-tête	fltkernel.h (include Fltkernel.h)
bibliothèque	FltMgr.lib
DLL	Fltmgr.sys
IRQL	<= APC_LEVEL (voir Remarques)