Funzione FindFirstFileW (fileapi.h)
Cerca in una directory un file o una sottodirectory con un nome corrispondente a un nome specifico (o un nome parziale se vengono utilizzati 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 FindFirstFileW(
[in] LPCWSTR lpFileName,
[out] LPWIN32_FIND_DATAW lpFindFileData
);
Parametri
[in] lpFileName
La directory o il percorso e il nome del file. Il nome 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 nel carattere Null di terminazione) o terminare con 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.
Suggerimento
A partire da Windows 10, versione 1607, è possibile acconsentire esplicitamente a rimuovere la limitazione MAX_PATH senza anteporre "\?\". Per informazioni dettagliate, vedere la sezione "Limitazione massima della lunghezza del percorso" di Denominazione di file, 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 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 .
Se la funzione ha esito negativo perché non è possibile trovare file corrispondenti, la funzione GetLastError restituisce ERROR_FILE_NOT_FOUND.
Commenti
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 visualizzato in un'applicazione di elenco di directory ,ad esempio il comando dir, quando viene specificato lo stesso modello di stringa del nome file. Il motivo è 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 alcun attributo, ad esempio 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, NULL o una stringa vuota non valida per il parametro lpFileName non è un uso valido di questa funzione. I risultati in questo caso non sono definiti.
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 (\) nella stringa di input lpFileName per FindFirstFile, pertanto potrebbe non essere ovvio come eseguire la ricerca nelle directory radice. Se si desidera visualizzare i file o ottenere gli attributi di una directory radice, si applicano 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 .
Nelle condivisioni di rete è possibile usare un lpFileName nel formato seguente: "\\Server\Share\*". Tuttavia, non è possibile utilizzare 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 lpFileName "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, è necessario chiamare la funzione Wow64DisableWow64FsRedirection prima di chiamare FindFirstFile e chiamare Wow64RevertWow64FsRedirection dopo l'ultima chiamata a FindNextFile. Per altre informazioni, vedere Reindirizzamento del 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 | Supportato |
|---|---|
| Protocollo SMB (Server Message Block) 3.0 | Sì |
| Failover trasparente SMB 3.0 (TFO) | Sì |
| SMB 3.0 con condivisioni file di scalabilità orizzontale (SO) | Sì |
| File system del volume condiviso cluster (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 Elenco dei 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 che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows XP [app desktop | App UWP] |
| Server minimo supportato | Windows Server 2003 [app desktop | App UWP] |
| Piattaforma di destinazione | Windows |
| Intestazione | fileapi.h (include Windows.h) |
| Libreria | Kernel32.lib |
| DLL | Kernel32.dll |