FindFirstFileTransactedA, fonction (winbase.h)

Article
11/20/2024

[Microsoft recommande vivement aux développeurs d’utiliser d’autres moyens pour répondre aux besoins de votre application. De nombreux scénarios développés par TxF peuvent être réalisés par le biais de techniques plus simples et plus facilement disponibles. En outre, TxF peut ne pas être disponible dans les futures versions de Microsoft Windows. Pour plus d’informations et d’alternatives à TxF, consultez Alternatives à l’utilisation de NTFS transactionnel.]

Recherche un répertoire pour un fichier ou un sous-répertoire avec un nom qui correspond à un nom spécifique en tant qu’opération transactionnelle.

Cette fonction est la forme transactionnée de la fonction FindFirstFileEx.

Pour obtenir la version la plus simple de cette fonction, consultez FindFirstFile.

Syntaxe

HANDLE FindFirstFileTransactedA(
  [in]  LPCSTR             lpFileName,
  [in]  FINDEX_INFO_LEVELS fInfoLevelId,
  [out] LPVOID             lpFindFileData,
  [in]  FINDEX_SEARCH_OPS  fSearchOp,
        LPVOID             lpSearchFilter,
  [in]  DWORD              dwAdditionalFlags,
  [in]  HANDLE             hTransaction
);

Paramètres

[in] lpFileName

Répertoire ou chemin d’accès et nom de fichier. Le nom de fichier peut inclure des caractères génériques, par exemple un astérisque (*) ou un point d’interrogation ( ?).

Ce paramètre ne doit pas être null, une chaîne non valide (par exemple, une chaîne vide ou une chaîne qui manque le caractère null de fin), ou se terminer dans une barre oblique inverse de fin (\).

Si la chaîne se termine par un caractère générique, un point (.) ou un nom de répertoire, l’utilisateur doit avoir accès à la racine et à tous les sous-répertoires sur le chemin d’accès.

Par défaut, le nom est limité à MAX_PATH caractères. Pour étendre cette limite à 32 767 caractères larges, ajoutez « \\ ?\ » au chemin d’accès. Pour plus d’informations, consultez nommage des fichiers, des chemins d’accès et des espaces de noms.

Pourboire

À compter de Windows 10, version 1607, vous pouvez choisir de supprimer la limitation MAX_PATH sans précéder « \\ ?\ ». Pour plus d’informations, consultez la section « Limite maximale de longueur de chemin » de noms, fichiers, chemin s et espaces de noms.

Le fichier doit résider sur l’ordinateur local ; sinon, la fonction échoue et le dernier code d’erreur est défini sur ERROR_TRANSACTIONS_UNSUPPORTED_REMOTE.

[in] fInfoLevelId

Niveau d’informations des données retournées.

Ce paramètre est l’une des valeurs d’énumération FINDEX_INFO_LEVELS.

[out] lpFindFileData

Pointeur vers la structure WIN32_FIND_DATA qui reçoit des informations sur un fichier ou un sous-répertoire trouvé.

[in] fSearchOp

Type de filtrage à effectuer qui diffère de la mise en correspondance de caractères génériques.

Ce paramètre est l’une des valeurs d’énumération FINDEX_SEARCH_OPS.

lpSearchFilter

Pointeur vers les critères de recherche si le fSearchOp spécifié a besoin d’informations de recherche structurées.

À ce stade, aucune des valeurs fSearchOp prises en charge ne nécessite d’informations de recherche étendues. Par conséquent, ce pointeur doit être NULL.

[in] dwAdditionalFlags

Spécifie des indicateurs supplémentaires qui contrôlent la recherche.

Valeur	Signification
FIND_FIRST_EX_CASE_SENSITIVE 1	Les recherches respectent la casse.

[in] hTransaction

Handle de la transaction. Ce handle est retourné par la fonction CreateTransaction.

Valeur de retour

Si la fonction réussit, la valeur de retour est un handle de recherche utilisé dans un appel ultérieur à FindNextFile ou FindClose, et le paramètre lpFindFileData contient des informations sur le premier fichier ou répertoire trouvé.

Si la fonction échoue ou ne parvient pas à localiser des fichiers à partir de la chaîne de recherche dans le paramètre lpFileName, la valeur de retour est INVALID_HANDLE_VALUE et le contenu de lpFindFileData sont indéterminés. Pour obtenir des informations d’erreur étendues, appelez la fonction GetLastError.

Remarques

La fonction FindFirstFileTransacted ouvre un handle de recherche et retourne des informations sur le premier fichier trouvé par le système de fichiers avec un nom qui correspond au modèle spécifié. Il peut s’agir ou non du premier fichier ou répertoire qui s’affiche dans une application de liste de répertoires (par exemple, la commande dir) lorsqu’il s’agit du même modèle de chaîne de nom de fichier. Cela est dû au fait que FindFirstFileTransacted ne trie pas les résultats de la recherche. Pour plus d’informations, consultez FindNextFile.

La liste suivante identifie d’autres caractéristiques de recherche :

La recherche est effectuée strictement sur le nom du fichier, et non sur des attributs tels qu’une date ou un type de fichier.
La recherche inclut les noms de fichiers longs et courts.
Une tentative d’ouverture d’une recherche avec une barre oblique inverse de fin échoue toujours.
Le passage d’une chaîne non valide, NULL ou une chaîne vide pour le paramètre lpFileName n’est pas une utilisation valide de cette fonction. Les résultats dans ce cas ne sont pas définis.

Remarque Dans de rares cas, les informations de fichier sur les systèmes de fichiers NTFS peuvent ne pas être actuelles au moment où vous appelez cette fonction. Pour être sûr d’obtenir les informations de fichier actuelles, appelez la fonction GetFileInformationByHandle.

Si le système de fichiers sous-jacent ne prend pas en charge le type de filtrage spécifié, autre que le filtrage de répertoires, FindFirstFileTransacted échoue avec l’erreur ERROR_NOT_SUPPORTED. L’application doit utiliser FINDEX_SEARCH_OPS type FileExSearchNameMatch et effectuer son propre filtrage.

Une fois le handle de recherche établi, utilisez-le dans la fonction FindNextFile pour rechercher d’autres fichiers qui correspondent au même modèle avec le même filtrage en cours d’exécution. Lorsque le handle de recherche n’est pas nécessaire, il doit être fermé à l’aide de la fonction FindClose.

Comme indiqué précédemment, vous ne pouvez pas utiliser une barre oblique inverse de fin (\) dans la chaîne d’entrée lpFileName pour FindFirstFileTransacted, il peut donc ne pas être évident comment rechercher des répertoires racines. Si vous souhaitez afficher des fichiers ou obtenir les attributs d’un répertoire racine, les options suivantes s’appliquent :

Pour examiner les fichiers dans un répertoire racine, vous pouvez utiliser « C :\* » et parcourir le répertoire à l’aide de FindNextFile.
Pour obtenir les attributs d’un répertoire racine, utilisez la fonction GetFileAttributes.

Remarque Prepending the string « \ ?\\ » n’autorise pas l’accès au répertoire racine.

Sur les partages réseau, vous pouvez utiliser un lpFileName sous la forme suivante : « \\server\service* ». Toutefois, vous ne pouvez pas utiliser un lpFileName qui pointe vers le partage lui-même ; par exemple, « \\server\service » n’est pas valide.

Pour examiner un répertoire qui n’est pas un répertoire racine, utilisez le chemin d’accès à ce répertoire, sans barre oblique inverse. Par exemple, un argument de « C :\Windows » retourne des informations sur le répertoire « C :\Windows », et non sur un répertoire ou un fichier dans « C :\Windows ». Pour examiner les fichiers et les répertoires dans « C :\Windows », utilisez un lpFileName de « C :\Windows\* ».

N’oubliez pas que d’autres threads ou processus peuvent créer ou supprimer un fichier portant ce nom entre le moment où vous interrogez le résultat et l’heure à laquelle vous agissez sur les informations. S’il s’agit d’une préoccupation potentielle pour votre application, une solution possible consiste à utiliser la fonction CreateFile avec CREATE_NEW (qui échoue si le fichier existe) ou OPEN_EXISTING (qui échoue si le fichier n’existe pas).

Si vous écrivez une application 32 bits pour répertorier tous les fichiers d’un répertoire et que l’application peut être exécutée sur un ordinateur 64 bits, vous devez appeler Wow64DisableWow64FsRedirection avant d’appeler FindFirstFileTransacted et appeler Wow64RevertWow64FsRedirection après le dernier appel à FindNextFile. Pour plus d’informations, consultez redirecteur de système de fichiers.

Si le chemin pointe vers un lien symbolique, la mémoire tampon WIN32_FIND_DATA contient des informations sur le lien symbolique, et non sur la cible.

Dans Windows 8 et Windows Server 2012, cette fonction est prise en charge par les technologies suivantes.

Technologie	Supporté
Protocole SMB (Server Message Block) 3.0	Non
Basculement transparent SMB 3.0 (TFO)	Non
SMB 3.0 avec partages de fichiers avec montée en puissance parallèle (SO)	Non
Cluster Shared Volume File System (CsvFS)	Non
Système de fichiers résilient (ReFS)	Non

SMB 3.0 ne prend pas en charge TxF.

Note

L’en-tête winbase.h définit FindFirstFileTransacted comme alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows Vista [applications de bureau uniquement]
serveur minimum pris en charge	Windows Server 2008 [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	winbase.h (inclure Windows.h)
bibliothèque	Kernel32.lib
DLL	Kernel32.dll