Funzione FindFirstFileExA (fileapi.h)

Cerca una directory per un file o una sottodirectory con un nome e attributi corrispondenti a quelli specificati.

Per la versione più di base di questa funzione, vedere FindFirstFile.

Per eseguire questa operazione come operazione transazionata, usare la funzione FindFirstFileTransacted .

Sintassi

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

Parametri

[in] lpFileName

Directory o percorso e il nome del file. Il nome del file può includere caratteri jolly, ad esempio un asterisco (*) o un punto interrogativo (?).

Questo parametro non deve essere NULL, una stringa non valida(ad esempio, una stringa vuota o una stringa mancante del carattere Null di terminazione) o terminare in una barra rovesciata finale (\).

Se la stringa termina con un carattere jolly, un punto o un nome di directory, l'utente deve avere accesso alla radice e a tutte le sottodirectory nel percorso.

Per impostazione predefinita, il nome è limitato a MAX_PATH caratteri. Per estendere questo limite a 32.767 caratteri wide, prependo "\\?\" al percorso. Per altre informazioni, vedere Denominazione di file, percorsi e spazi dei nomi.

[in] fInfoLevelId

Livello di informazioni dei dati restituiti.

Questo parametro è uno dei valori di enumerazione FINDEX_INFO_LEVELS .

[out] lpFindFileData

Puntatore al buffer che riceve i dati del file.

Il tipo di puntatore è determinato dal livello di informazioni specificate nel parametro fInfoLevelId .

[in] fSearchOp

Tipo di filtro da eseguire diverso dalla corrispondenza con caratteri jolly.

Questo parametro è uno dei valori di enumerazione FINDEX_SEARCH_OPS .

lpSearchFilter

Puntatore ai criteri di ricerca se l'oggetto fSearchOp specificato richiede informazioni di ricerca strutturate.

In questo momento, nessuno dei valori fSearchOp supportati richiede informazioni di ricerca estese. Pertanto, questo puntatore deve essere NULL.

[in] dwAdditionalFlags

Specifica flag aggiuntivi che controllano la ricerca.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è un handle di ricerca usato in una chiamata successiva a FindNextFile o FindClose e il parametro lpFindFileData contiene informazioni sul primo file o directory trovato.

Se la funzione ha esito negativo o non riesce a individuare i file dalla stringa di ricerca nel parametro lpFileName , il valore restituito è INVALID_HANDLE_VALUE e il contenuto di lpFindFileData è indeterminato. Per ottenere informazioni sull'errore estese, chiamare la funzione GetLastError .

Commenti

La funzione FindFirstFileEx apre un handle di ricerca e restituisce informazioni sul primo file trovato dal file system con un nome corrispondente al modello specificato. Questo può o non essere il primo file o directory visualizzato in un'applicazione di elenco di directory (ad esempio il comando dir) quando viene specificato lo stesso modello di stringa del nome file. Questo perché FindFirstFileEx non esegue alcuna ordinamento dei risultati della ricerca. Per altre informazioni, vedere FindNextFile.

L'elenco seguente identifica alcune altre caratteristiche di ricerca:

• La ricerca viene eseguita rigorosamente sul nome del file, non su alcun attributo, ad esempio una data o un tipo di file.
• La ricerca include i nomi di file lunghi e brevi.
• Un tentativo di aprire una ricerca con una barra rovesciata finale ha sempre esito negativo.
• Il passaggio di una stringa, NULL o una stringa vuota per il parametro lpFileName non è un uso valido di questa funzione. I risultati in questo caso non sono definiti.

Dopo aver stabilito l'handle di ricerca, usarlo nella funzione FindNextFile per cercare altri file che corrispondono allo stesso modello con lo stesso filtro eseguito. Quando l'handle di ricerca non è necessario, deve essere chiuso usando la funzione FindClose .

Come indicato in precedenza, non è possibile usare una barra rovesciata finale (\) nella stringa di input lpFileName per FindFirstFileEx, pertanto potrebbe non essere ovvio come eseguire ricerche nelle directory radice. Se si desidera visualizzare i file o ottenere gli attributi di una directory radice, verranno applicate le opzioni seguenti:

• Per esaminare i file in una directory radice, è possibile usare "C:\*" e passare la directory usando FindNextFile.
• Per ottenere gli attributi di una directory radice, usare la funzione GetFileAttributes .

Nelle condivisioni di rete è possibile usare un lpFileName sotto forma di "\\server\service\*". Tuttavia, non è possibile usare un lpFileName che punta alla condivisione stessa; ad esempio, "\\server\service" non è valido.

Per esaminare una directory che non è una directory radice, usare il percorso di tale directory, senza una barra rovesciata finale. Ad esempio, un argomento di "C:\Windows" restituisce informazioni sulla directory "C:\Windows", non su una directory o un file in "C:\Windows". Per esaminare i file e le directory in "C:\Windows", usare un lpFileName di "C:\Windows\*".

Chiamata seguente:

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

Equivale alla chiamata seguente:

FindFirstFile( lpFileName, lpFindData );

Tenere presente che alcuni altri thread o processi possono creare o eliminare un file con questo nome tra il momento in cui si esegue la query per il risultato e il tempo in cui si agisce sulle informazioni. Se si tratta di un potenziale problema per l'applicazione, una possibile soluzione consiste nell'usare la funzione CreateFile con CREATE_NEW (che ha esito negativo se il file esiste) o OPEN_EXISTING (che ha esito negativo se il file non esiste).

Se si scrive un'applicazione a 32 bit per elencare tutti i file in una directory e l'applicazione può essere eseguita in un computer a 64 bit, è necessario chiamare Wow64DisableWow64FsRedirection prima di chiamare FindFirstFileEx e chiamare Wow64RevertWow64FsRedirection dopo l'ultima chiamata a FindNextFile. Per altre informazioni, vedere Reindirizzamento file system.

Se il percorso punta a un collegamento simbolico, il buffer WIN32_FIND_DATA contiene informazioni sul collegamento simbolico, non sulla destinazione.

In Windows 8 e Windows Server 2012 questa funzione è supportata dalle tecnologie seguenti.

Esempi

Il codice seguente mostra un uso minimo di FindFirstFileEx. Questo programma equivale all'esempio nell'argomento 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);
   }
}

Requisiti

Vedere anche

FINDEX_INFO_LEVELS

FINDEX_SEARCH_OPS

Funzioni di gestione file

FindClose

Findfirstfile

FindFirstFileTransacted

Findnextfile

GetFileAttributes

Denominazione di un file

Collegamenti simbolici

Uso delle intestazioni di Windows

WIN32_FIND_DATA