struttura FILE_RENAME_INFORMATION (ntifs.h)
La struttura FILE_RENAME_INFORMATION viene utilizzata per rinominare un file.
Sintassi
typedef struct _FILE_RENAME_INFORMATION {
#if (_WIN32_WINNT >= _WIN32_WINNT_WIN10_RS1)
union {
BOOLEAN ReplaceIfExists; // FileRenameInformation
ULONG Flags; // FileRenameInformationEx
} DUMMYUNIONNAME;
#else
BOOLEAN ReplaceIfExists;
#endif
HANDLE RootDirectory;
ULONG FileNameLength;
WCHAR FileName[1];
} FILE_RENAME_INFORMATION, *PFILE_RENAME_INFORMATION;
Membri
DUMMYUNIONNAME
DUMMYUNIONNAME.ReplaceIfExists
Impostare su TRUE per specificare che se esiste già un file con il nome specificato, deve essere sostituito con il file specificato. Impostare su FALSE se l'operazione di ridenominazione non riesce se esiste già un file con il nome specificato.
DUMMYUNIONNAME.Flags
Flag per l'operazione di ridenominazione. Questo campo è applicabile solo se usato con la classe di informazioni FileRenameInformationEx.
Ecco i valori possibili:
| Valore | Significato |
|---|---|
| FILE_RENAME_REPLACE_IF_EXISTS (0x00000001) | Se esiste già un file con il nome specificato, deve essere sostituito con il file specificato. Equivalente al campo ReplaceIfExists usato con la classe di informazioni FileRenameInformation. |
| FILE_RENAME_POSIX_SEMANTICS (0x00000002) | Se viene specificato anche FILE_RENAME_REPLACE_IF_EXISTS, consentire la sostituzione di un file anche se sono presenti handle esistenti. Gli handle esistenti nel file sostituito continuano a essere validi per operazioni quali lettura e scrittura. Qualsiasi apertura successiva del nome di destinazione aprirà il file rinominato, non il file sostituito. |
| FILE_RENAME_SUPPRESS_PIN_STATE_INHERITANCE (0x00000004) | Quando si rinomina un file in una nuova directory, eliminare eventuali regole di ereditarietà correlate agli attributi FILE_ATTRIBUTE_PINNED e FILE_ATTRIBUTE_UNPINNED del file. |
| FILE_RENAME_SUPPRESS_STORAGE_RESERVE_INHERITANCE (0x00000008) | Quando si rinomina un file in una nuova directory, eliminare eventuali regole di ereditarietà correlate alla proprietà ID di riserva di archiviazione del file. |
| FILE_RENAME_NO_INCREASE_AVAILABLE_SPACE (0x00000010) | Se non viene specificato FILE_RENAME_SUPPRESS_STORAGE_RESERVE_INHERITANCE, quando si rinomina un file in una nuova directory, ridimensionare automaticamente le aree di riserva di archiviazione interessate in base alle esigenze per impedire all'utente di aumentare lo spazio disponibile visibile nel volume. Richiede la gestione dell'accesso al volume. |
| FILE_RENAME_NO_DECREASE_AVAILABLE_SPACE (0x00000020) | Se non viene specificato FILE_RENAME_SUPPRESS_STORAGE_RESERVE_INHERITANCE, quando si rinomina un file in una nuova directory, ridimensionare automaticamente le aree di riserva di archiviazione interessate in base alle esigenze per impedire all'utente di ridurre lo spazio disponibile visibile sul volume. Richiede la gestione dell'accesso al volume. |
| FILE_RENAME_PRESERVE_AVAILABLE_SPACE (0x00000030) | Equivale a specificare sia FILE_RENAME_NO_INCREASE_AVAILABLE_SPACE che FILE_RENAME_NO_DECREASE_AVAILABLE_SPACE. |
| FILE_RENAME_IGNORE_READONLY_ATTRIBUTE (0x00000040) | Se viene specificato anche FILE_RENAME_REPLACE_IF_EXISTS, consentire la sostituzione di un file anche se è di sola lettura. Richiede WRITE_ATTRIBUTES l'accesso al file sostituito. |
| FILE_RENAME_FORCE_RESIZE_TARGET_SR (0x00000080) | Se non viene specificato FILE_RENAME_SUPPRESS_STORAGE_RESERVE_INHERITANCE, quando si rinomina un file in una nuova directory che fa parte di un'area di riserva di archiviazione diversa, aumentare sempre l'area di riserva di archiviazione della directory di destinazione in base alle dimensioni complete del file rinominato. Richiede la gestione dell'accesso al volume. |
| FILE_RENAME_FORCE_RESIZE_SOURCE_SR (0x00000100) | Se non viene specificato FILE_RENAME_SUPPRESS_STORAGE_RESERVE_INHERITANCE, quando si rinomina un file in una nuova directory che fa parte di un'area di riserva di archiviazione diversa, ridurre sempre l'area di riserva di archiviazione della directory di origine in base alle dimensioni complete del file rinominato. Richiede la gestione dell'accesso al volume. |
| FILE_RENAME_FORCE_RESIZE_SR (0x00000180) | Equivale a specificare sia FILE_RENAME_FORCE_RESIZE_TARGET_SR che FILE_RENAME_FORCE_RESIZE_SOURCE_SR. |
ReplaceIfExists
Impostare su TRUE per specificare che se esiste già un file con il nome specificato, deve essere sostituito con il file specificato. Impostare su FALSE se l'operazione di ridenominazione non riesce se esiste già un file con il nome specificato.
RootDirectory
Handle usato IopOpenLinkOrRenameTarget per aprire la directory di destinazione.
Se il file non viene spostato in una directory diversa o se il membro NomeFile contiene il percorso completo, questo membro è NULL. In caso contrario, è un handle per la directory radice in cui risiederà il file dopo la ridenominazione.
Per eseguire due operazioni aperte che non causano un conflitto di condivisione, è possibile aprire RootDirectory richiedendo l'attraversamento | read-attribute. IopOpenLinkOrRenameTarget può quindi eseguire un'apertura relativa richiedendo FILE_WRITE_DATA | SINCRONIZZARE. Queste due aperture non causano conflitti di condivisione.
FileNameLength
Lunghezza, in byte, del nuovo nome per il file.
FileName[1]
Primo carattere di una stringa di caratteri wide contenente il nuovo nome per il file. Questo è seguito in memoria dal resto della stringa. Se il membro RootDirectory è NULL e il file viene spostato in una directory diversa, questo membro specifica il percorso completo da assegnare al file. In caso contrario, specifica solo il nome del file o un percorso relativo.
Osservazioni
La struttura FILE_RENAME_INFORMATION viene utilizzata per rinominare un file. Questa operazione può essere eseguita in uno dei modi seguenti:
Chiamare FltSetInformationFile o ZwSetInformationFile, passando FileRenameInformation come valore di FileInformationClass e passando un buffer allocato dal chiamante formattato come struttura FILE_RENAME_INFORMATION per il valore di FileInformation. Il parametro FileHandle specifica il file da rinominare.
Creare un IRP con il codice della funzione principale IRP_MJ_SET_INFORMATION.
I minifiltri del file system devono usare FltSetInformationFile, non ZwSetInformationFile, per rinominare un file.
La ridenominazione di un file richiede l'accesso DELETE al file in modo che la voce di directory possa essere rimossa dalla directory padre corrente, nonché l'accesso appropriato per creare la nuova voce nel nuovo file di directory padre.
La stringa del nome file nel membro FileName deve essere specificata in uno dei formati seguenti.
Nome file semplice. Il membro rootdirectory è NULL. In questo caso, il file viene semplicemente rinominato all'interno della stessa directory. Ovvero, l'operazione di ridenominazione modifica il nome del file, ma non il relativo percorso.
Nome completo del file. Il membro rootdirectory è NULL. In questo caso, l'operazione di ridenominazione modifica il nome e il percorso del file.
Nome file relativo. In questo caso, il membro RootDirectory contiene un handle per la directory di destinazione per l'operazione di ridenominazione. Il nome del file deve essere un nome file semplice.
Regole generali per le operazioni di ridenominazione:
Un file o una directory può essere rinominato solo all'interno di un volume. In altre parole, un'operazione di ridenominazione non può causare lo spostamento di un file o di una directory in un volume diverso.
Impossibile rinominare la directory radice di un volume.
Se ReplaceIfExists è impostato su FALSE e la destinazione esiste, l'operazione di ridenominazione avrà esito negativo.
Anche se ReplaceIfExists è impostato su TRUE, l'operazione di ridenominazione avrà comunque esito negativo se esiste già un file con lo stesso nome ed è una directory, un file di sola lettura o un file attualmente in esecuzione.
I file e le directory di un volume non possono essere rinominati se il volume è un volume di sola lettura, ad esempio un volume CDFS o un volume NTFS di sola lettura.
Regole speciali per la ridenominazione dei file aperti:
Un file non può essere rinominato se dispone di handle aperti, a meno che non sia aperto solo a causa di un blocco opportunistico batch (oplock) e il blocco di operazioni batch può essere interrotto immediatamente.
Non è possibile rinominare un file se esiste un file con lo stesso nome e ha handle aperti (tranne nel caso batch-oplock descritto in precedenza).
Non è possibile rinominare una directory se o una delle relative sottodirectory contiene un file con handle aperti (tranne nel caso batch-oplock descritto in precedenza).
Regole speciali per la ridenominazione dei flussi di dati NTFS:
Impossibile rinominare il flusso di directory predefinito.
Il nuovo nome per il flusso deve iniziare con due punti (:).
Un flusso di dati può essere rinominato solo all'interno di stesso file. In altre parole, un'operazione di ridenominazione non può causare lo spostamento di un flusso di dati in un file diverso.
Non è possibile rinominare un flusso di dati in una directory nel flusso di dati predefinito.
Se ReplaceIfExists è impostato su TRUE, l'operazione di ridenominazione avrà esito positivo solo se un flusso con lo stesso nome non esiste o è un flusso di dati di lunghezza zero.
"Ridenominazione" del flusso di dati predefinito è consentito, ma non si tratta di una vera ridenominazione, perché lascia dietro un flusso di dati predefinito di lunghezza zero.
Le dimensioni del buffer FileInformation passato a ZwSetInformationFile o FltSetInformationFile devono essere >= sizeof(FILE_RENAME_INFORMATION) più le dimensioni in byte della stringa FileName.
Fabbisogno
| Requisito | Valore |
|---|---|
| intestazione | ntifs.h (include Ntifs.h, Fltkernel.h) |