Funzione FindFirstFileExA (fileapi.h)

Articolo
11/20/2024

Cerca in una directory un file o una sottodirectory con un nome e attributi che corrispondono a quelli specificati.

Per la versione più semplice 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

La directory o il 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 che manca il 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, anteporre "\\?\" al percorso. Per altre informazioni, vedere denominazione di file, percorsi e spazi dei nomi.

Mancia

A partire da Windows 10, versione 1607, è possibile acconsentire esplicitamente alla rimozione della limitazione MAX_PATH senza anteporre "\\?\". Per informazioni dettagliate, vedere la sezione "Limitazione massima della lunghezza del percorso" di nomi, 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 specificato 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 il specificato fSearchOp necessita di informazioni di ricerca strutturate.

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

[in] dwAdditionalFlags

Specifica flag aggiuntivi che controllano la ricerca.

Valore	Significato
FIND_FIRST_EX_CASE_SENSITIVE 1	Le ricerche fanno distinzione tra maiuscole e minuscole.
FIND_FIRST_EX_LARGE_FETCH 2	Usa un buffer più grande per le query di directory, che può migliorare le prestazioni dell'operazione di ricerca. Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Questo valore non è supportato fino a Windows Server 2008 R2 e Windows 7.
FIND_FIRST_EX_ON_DISK_ENTRIES_ONLY 4	Limita i risultati ai file fisicamente su disco. Questo flag è rilevante solo quando è presente un filtro di virtualizzazione file.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è un handle di ricerca usato in una chiamata successiva a FindNextFile o FindClosee 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 del lpFindFileData è indeterminato. Per ottenere informazioni estese sull'errore, chiamare la funzione GetLastError .

Osservazioni

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. Può trattarsi o meno del primo file o della directory visualizzata 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 l'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 non valida, NULLo una stringa vuota per il parametro lpFileName non è un uso valido di questa funzione. In questo caso i risultati non sono definiti.

Nota In rari casi o in un sistema pesantemente caricato, le informazioni sull'attributo file nei file system NTFS potrebbero non essere correnti al momento della chiamata di questa funzione. Per assicurarsi di ottenere gli attributi correnti del file system NTFS, chiamare la funzione GetFileInformationByHandle.

Se il file system sottostante non supporta il tipo specificato di filtro, ad eccezione del filtro della directory, FindFirstFileEx ha esito negativo con l'errore ERROR_NOT_SUPPORTED. L'applicazione deve usare FINDEX_SEARCH_OPS tipo FileExSearchNameMatch ed eseguire il proprio filtro.

Dopo aver stabilito l'handle di ricerca, usarlo nella funzione FindNextFile per cercare altri file che corrispondono allo stesso modello con lo stesso filtro che viene 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 (\) nel lpFileName stringa di input per FindFirstFileEx, pertanto potrebbe non essere ovvio come cercare le directory radice. Per 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 scorrere la directory usando FindNextFile.
Per ottenere gli attributi di una directory radice, usare la funzione GetFileAttributes.

Nota la stringa "\\?\" non consente l'accesso alla directory radice.

Nelle condivisioni di rete è possibile usare un lpFileName nel formato seguente: "\\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\*".

La chiamata seguente:

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

Equivale alla chiamata seguente:

FindFirstFile( lpFileName, lpFindData );

Tenere presente che un altro thread o processo potrebbe creare o eliminare un file con questo nome tra il momento in cui si esegue la query per il risultato e il momento 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.

Tecnologia	Sostenuto
Protocollo SMB (Server Message Block) 3.0	Sì
SMB 3.0 Transparent Failover (TFO)	Sì
SMB 3.0 con condivisioni file con scalabilità orizzontale (SO)	Sì
Cluster Shared Volume File System (CsvFS)	Sì
Resilient File System (ReFS)	Sì

Esempi

Il codice seguente illustra 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);
   }
}

Nota

L'intestazione fileapi.h definisce FindFirstFileEx come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows XP [app desktop \| App UWP]
server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
piattaforma di destinazione	Finestre
intestazione	fileapi.h (include Windows.h)
libreria	Kernel32.lib
dll	Kernel32.dll