Partager via


Fonction FindFirstFileExA (fileapi.h)

Recherche dans un répertoire un fichier ou un sous-répertoire avec un nom et des attributs qui correspondent à ceux spécifiés.

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

Pour effectuer cette opération en tant qu’opération transactionnelle, utilisez la fonction FindFirstFileTransacted .

Syntaxe

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

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 ne contient pas le caractère null de fin) ou se terminer par 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 de large, ajoutez « \\?\ » au chemin d’accès. Pour plus d’informations, consultez Nommage de fichiers, de chemins et d’espaces de noms.

Conseil

À compter de Windows 10, version 1607, vous pouvez choisir de supprimer la limitation de MAX_PATH sans précédencer « \?\ ». Pour plus d’informations, consultez la section « Limitation de longueur maximale du chemin d’accès » dans Naming Files, Paths et Namespaces .

[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 mémoire tampon qui reçoit les données du fichier.

Le type de pointeur est déterminé par le niveau d’informations spécifié dans le paramètre fInfoLevelId .

[in] fSearchOp

Type de filtrage à effectuer qui est différent de la 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 étendue. Par conséquent, ce pointeur doit avoir la valeur 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.
FIND_FIRST_EX_LARGE_FETCH
2
Utilise une mémoire tampon plus grande pour les requêtes d’annuaire, ce qui peut augmenter les performances de l’opération de recherche.

Windows Server 2008, Windows Vista, Windows Server 2003 et Windows XP : Cette valeur n’est pas prise en charge tant que Windows Server 2008 R2 et Windows 7.

FIND_FIRST_EX_ON_DISK_ENTRIES_ONLY
4
Limite les résultats aux fichiers physiquement sur disque. Cet indicateur n’est pertinent que lorsqu’un filtre de virtualisation de fichiers est présent.

Valeur retournée

Si la fonction réussit, la valeur de retour est un handle de recherche utilisé dans un appel suivant à 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 les fichiers de la chaîne de recherche dans le paramètre lpFileName , la valeur de retour est INVALID_HANDLE_VALUE et le contenu de lpFindFileData est indéterminé. Pour obtenir des informations d’erreur étendues, appelez la fonction GetLastError .

Notes

La fonction FindFirstFileEx ouvre un handle de recherche et retourne des informations sur le premier fichier que le système de fichiers trouve avec un nom qui correspond au modèle spécifié. Il peut s’agir ou non du premier fichier ou répertoire qui apparaît dans une application de liste de répertoires (telle que la commande dir) lorsque le même modèle de chaîne de nom de fichier est donné. Cela est dû au fait que FindFirstFileEx 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 uniquement 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.
  • La transmission d’une chaîne, d’une valeur NULL ou d’une chaîne vide non valide pour le paramètre lpFileName n’est pas une utilisation valide de cette fonction. Dans ce cas, les résultats ne sont pas définis.
Note Dans de rares cas ou sur un système fortement chargé, les informations d’attribut de fichier sur les systèmes de fichiers NTFS peuvent ne pas être à jour au moment où cette fonction est appelée. Pour obtenir les attributs de fichier du système de fichiers NTFS actuels, 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, FindFirstFileEx é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 effectué. 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 FindFirstFileEx. Par conséquent, il peut ne pas être évident de 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 d’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 .
Note L’interruption de la chaîne « \\?\\ » 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 de fin. Par exemple, un argument « 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\* ».

L’appel suivant :

FindFirstFileEx( lpFileName, 
                 FindExInfoStandard, 
                 lpFindData, 
                 FindExSearchNameMatch, 
                 NULL, 
                 0 );

Équivaut à l’appel suivant :

FindFirstFile( lpFileName, lpFindData );

N’oubliez pas qu’un autre thread ou processus peut créer ou supprimer un fichier portant ce nom entre le moment où vous interrogez le résultat et le moment où vous agissez sur les informations. S’il s’agit d’un problème potentiel 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 FindFirstFileEx 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 Prise en charge
Protocole SMB (Server Message Block) 3.0 Oui
Basculement transparent SMB 3.0 (TFO) Oui
SMB 3.0 avec partages de fichiers avec montée en puissance sortante (SO) Oui
Cluster Shared Volume File System (CsvFS) Oui
Système de fichiers résilient (ReFS) Oui
 

Exemples

Le code suivant montre une utilisation minimale de FindFirstFileEx. Ce programme est équivalent à l’exemple de la rubrique FindFirstFile .

#include <windows.h>
#include <tchar.h>
#include <stdio.h>

void _tmain(int argc, TCHAR *argv[])
{
   WIN32_FIND_DATA FindFileData;
   HANDLE hFind;

   if( argc != 2 )
   {
      _tprintf(TEXT("Usage: %s [target_file]\n"), argv[0]);
      return;
   }

   _tprintf (TEXT("Target file is %s\n"), argv[1]);
   hFind = FindFirstFileEx(argv[1], FindExInfoStandard, &FindFileData,
             FindExSearchNameMatch, NULL, 0);
   if (hFind == INVALID_HANDLE_VALUE) 
   {
      printf ("FindFirstFileEx failed (%d)\n", GetLastError());
      return;
   } 
   else 
   {
      _tprintf (TEXT("The first file found is %s\n"), 
                FindFileData.cFileName);
      FindClose(hFind);
   }
}

Notes

L’en-tête fileapi.h définit FindFirstFileEx en tant qu’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. La combinaison 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.

Configuration requise

   
Client minimal pris en charge Windows XP [applications de bureau | Applications UWP]
Serveur minimal pris en charge Windows Server 2003 [applications de bureau | Applications UWP]
Plateforme cible Windows
En-tête fileapi.h (inclure Windows.h)
Bibliothèque Kernel32.lib
DLL Kernel32.dll

Voir aussi

FINDEX_INFO_LEVELS

FINDEX_SEARCH_OPS

Fonctions de gestion de fichiers

FindClose

FindFirstFile

FindFirstFileTransacted

FindNextFile

GetFileAttributes

Nommage d’un fichier

Liens symboliques

Utilisation des en-têtes Windows

WIN32_FIND_DATA