Fonction FltGetFileNameInformationUnsafe (fltkernel.h)

Article
08/07/2023

La routine FltGetFileNameInformationUnsafe retourne des informations de nom pour un fichier ou 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 fichier pour le fichier ou le répertoire. L’objet file 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 à retourner, 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 comprend jusqu’à 8 caractères, suivis 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 d’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 de FLT_FILE_NAME_INFORMATION allouée par le système. FltGetFileNameInformationUnsafe alloue cette structure à partir d’un 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 retournée

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

Code de retour	Description
STATUS_FLT_INVALID_NAME_REQUEST	L’objet file vers lequel pointe le paramètre FileObject 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 vous permet d’interroger le nom d’un objet 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 d’informations de nom dans le système de fichiers peut entraîner des interblocages pour des 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 l’opération de IRP_MJ_CLEANUP terminée ; autrement dit, dans le chemin d’accès post-propre, pré-fermeture ou post-fermeture (l’objet fichier cible a l’indicateur FO_CLEANUP_COMPLETE défini).
Dans une routine de rappel de préopération (PFLT_PRE_OPERATION_CALLBACK) ou de post-opé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 tous les API sont désactivés ; autrement dit, lorsque KeAreAllApcsDisabled retourne TRUE.

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

Dans les opérations de création, de liaison matérielle et de renommage, le tunneling de nom 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 des 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, il doit appeler FltGetTunneledName à partir de sa routine de rappel 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 de nom de fichier normalisé, consultez FLT_FILE_NAME_INFORMATION.

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
En-tête	fltkernel.h (inclure Fltkernel.h)
Bibliothèque	FltMgr.lib
DLL	Fltmgr.sys
IRQL	<= APC_LEVEL (voir remarques)