Funzione FindFirstFileTransactedA (winbase.h)
[Microsoft consiglia vivamente agli sviluppatori di usare mezzi alternativi per soddisfare le esigenze dell'applicazione. Molti scenari per cui è stato sviluppato TxF possono essere ottenuti tramite tecniche più semplici e più facilmente disponibili. 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 in una directory 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ù semplice di questa funzione, vedere FindFirstFile.
Sintassi
HANDLE FindFirstFileTransactedA(
[in] LPCSTR 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
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 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.
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 .
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.
[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 da quello dei caratteri jolly.
Questo parametro è uno dei valori di enumerazione FINDEX_SEARCH_OPS .
lpSearchFilter
Puntatore ai criteri di ricerca se l'oggetto fSearchOp specificato necessita di informazioni di ricerca strutturate.
Al 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 fanno 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. 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 FindFirstFileTransacted 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, 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.
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 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\service*". Tuttavia, non è possibile utilizzare 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 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 Wow64Disow64FsRedirection prima di chiamare FindFirstFileTransacted 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 | No |
| Failover trasparente SMB 3.0 (TFO) | No |
| SMB 3.0 con condivisioni file di scalabilità orizzontale (SO) | No |
| File system del volume condiviso cluster (CsvFS) | No |
| Resilient File System (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 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 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 |