Funzione FindFirstFileA (fileapi.h)

Articolo
11/20/2024

Cerca in una directory un file o una sottodirectory con un nome corrispondente a un nome specifico (o un nome parziale se vengono usati caratteri jolly).

Per specificare attributi aggiuntivi da usare in una ricerca, usare la funzione FindFirstFileEx.

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

Sintassi

HANDLE FindFirstFileA(
  [in]  LPCSTR             lpFileName,
  [out] LPWIN32_FIND_DATAA lpFindFileData
);

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 disporre delle autorizzazioni di 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.

[out] lpFindFileData

Puntatore alla struttura WIN32_FIND_DATA che riceve informazioni su un file o una directory trovata.

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 .

Se la funzione ha esito negativo perché non è possibile trovare file corrispondenti, la funzione GetLastError restituisce ERROR_FILE_NOT_FOUND.

Osservazioni

La funzione FindFirstFile 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. Ciò è dovuto al fatto che FindFirstFile 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 attributi quali una data o un tipo di file (per altre opzioni, vedere FindFirstFileEx).
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.

Dopo aver stabilito l'handle di ricerca, è possibile usarlo per cercare altri file che corrispondono allo stesso modello usando la funzione FindNextFile .

Quando l'handle di ricerca non è più necessario, chiuderlo usando la funzione FindClose , non CloseHandle.

Come indicato in precedenza, non è possibile usare una barra rovesciata finale (\) nel lpFileName stringa di input per FindFirstFile, pertanto potrebbe non essere ovvio come eseguire la ricerca nelle 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 sotto forma di "\\Server\Share\*". Tuttavia, non è possibile usare un lpFileName che punta alla condivisione stessa; Ad esempio, "\\Server\Share" 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\*".

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, È consigliabile chiamare la funzione wow64DisableWow64FsRedirection prima di chiamare FindFirstFile 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

L'esempio C++ seguente illustra un uso minimo di 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 = FindFirstFile(argv[1], &FindFileData);
   if (hFind == INVALID_HANDLE_VALUE) 
   {
      printf ("FindFirstFile failed (%d)\n", GetLastError());
      return;
   } 
   else 
   {
      _tprintf (TEXT("The first file found is %s\n"), 
                FindFileData.cFileName);
      FindClose(hFind);
   }
}

Per un altro esempio, vedere Elencare i file in una directory.

Nota

L'intestazione fileapi.h definisce FindFirstFile 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