Funzione FindFirstFileExW (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 FindFirstFileExW(
[in] LPCWSTR 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.
In questa funzione il nome è limitato a MAX_PATH caratteri. Per estendere questo limite a circa 32.000 caratteri wide, chiamare la versione Unicode della funzione (FindFirstFileExW) e prependare "\\?\" al percorso. Per altre informazioni, vedere Denominazione di un file.
[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.
| Tecnologia | Supportato |
|---|---|
| Protocollo SMB (Server Message Block) 3.0 | Sì |
| Failover trasparente SMB 3.0 (TFO) | Sì |
| SMB 3.0 con condivisioni file con scalabilità orizzontale (SO) | Sì |
| File system del volume condiviso del cluster (CsvFS) | Sì |
| File system resiliente (ReFS) | Sì |
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);
}
}
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 preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.
Requisiti
| 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 (includere Windows.h) |
| Libreria | Kernel32.lib |
| DLL | Kernel32.dll |