Funzione FindFirstFileTransactedW (winbase.h)
[Microsoft consiglia vivamente agli sviluppatori di usare mezzi alternativi per raggiungere le esigenze dell'applicazione. Molti scenari sviluppati da TxF possono essere ottenuti tramite tecniche più semplici e più leggibili. Inoltre, TxF potrebbe non essere disponibile nelle versioni future di Microsoft Windows. Per altre informazioni e alternative a TxF, vedere Alternative all'uso di NTFS transazionale.
Cerca una directory per un file o una sottodirectory con un nome corrispondente a un nome specifico come operazione transazionata.
Questa funzione è la forma transazionata della funzione FindFirstFileEx .
Per la versione più di base di questa funzione, vedere FindFirstFile.
Sintassi
HANDLE FindFirstFileTransactedW(
[in] LPCWSTR lpFileName,
[in] FINDEX_INFO_LEVELS fInfoLevelId,
[out] LPVOID lpFindFileData,
[in] FINDEX_SEARCH_OPS fSearchOp,
LPVOID lpSearchFilter,
[in] DWORD dwAdditionalFlags,
[in] HANDLE hTransaction
);
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.
Il file deve risiedere nel computer locale; in caso contrario, la funzione ha esito negativo e l'ultimo codice di errore è impostato su ERROR_TRANSACTIONS_UNSUPPORTED_REMOTE.
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.
Suggerimento
A partire da Windows 10, versione 1607, è possibile scegliere di rimuovere la limitazione MAX_PATH senza pre sospeso "\\?\". Per informazioni dettagliate, vedere la sezione "Limitazione massima lunghezza percorso" di nomi, 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 alla struttura WIN32_FIND_DATA che riceve informazioni su un file trovato o una sottodirectory.
[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 | Significato |
|---|---|
|
Le ricerche sono distinzione tra maiuscole e minuscole. |
[in] hTransaction
Handle per la transazione. Questo handle viene restituito dalla funzione CreateTransaction .
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 FindFirstFileTransacted 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é FindFirstFileTransacted 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 FindFirstFileTransacted, 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\*".
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 FindFirstFileTransacted 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 | No |
| Failover trasparente SMB 3.0 (TFO) | No |
| SMB 3.0 con condivisioni file con scalabilità orizzontale (SO) | No |
| File system del volume condiviso del cluster (CsvFS) | No |
| File system resiliente (ReFS) | No |
SMB 3.0 non supporta TxF.
Nota
L'intestazione winbase.h definisce FindFirstFileTransacted 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 Vista [solo app desktop] |
| Server minimo supportato | Windows Server 2008 [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | winbase.h (include Windows.h) |
| Libreria | Kernel32.lib |
| DLL | Kernel32.dll |