FILE_RENAME_INFORMATION struttura (ntifs.h)

La struttura FILE_RENAME_INFORMATION viene usata 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;

Members

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 deve avere esito negativo 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:

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 deve avere esito negativo se esiste già un file con il nome specificato.

RootDirectory

Handle usato da IopOpenLinkOrRenameTarget per aprire la directory di destinazione.

Se il file non viene spostato in una directory diversa o se il membro FileName contiene il nome percorso completo, questo membro è NULL. In caso contrario, è un handle per la directory radice in cui risiederà il file dopo che viene rinominato.

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. Questa operazione viene seguita in memoria dal resto della stringa. Se il membro RootDirectory è NULL e il file viene spostato in una directory diversa, questo membro specifica il nome percorso completo da assegnare al file. In caso contrario, specifica solo il nome del file o un nome percorso relativo.

Commenti

La struttura FILE_RENAME_INFORMATION viene usata 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 del chiamante formattato come struttura FILE_RENAME_INFORMATION per il valore di FileInformation. Il parametro FileHandle specifica il file da rinominare.

• Creare un'IRP con codice di funzione principale IRP_MJ_SET_INFORMATION.

I minifilter 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 della directory possa essere rimossa dalla directory padre corrente, nonché l'accesso appropriato per creare la nuova voce nel nuovo file della directory padre.

La stringa del nome file nel membro FileName deve essere specificata in uno dei moduli seguenti.

• Nome di file semplice. Il membro RootDirectory è NULL. In questo caso, il file viene semplicemente rinominato nella stessa directory. Vale a dire, l'operazione di ridenominazione modifica il nome del file, ma non il relativo percorso.

• Nome di file completo. 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 stesso deve essere un nome di file semplice.

Regole generali per le operazioni di ridenominazione:

• È possibile rinominare un file o una directory 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:

• Non è possibile rinominare un file se dispone di handle aperti, a meno che non sia aperto solo a causa di un blocco opportunistico batch (oplock) e il blocco batch può essere interrotto immediatamente.

• Non è possibile rinominare un file se esiste un file con lo stesso nome e dispone di 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, ad eccezione del 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 dello 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 a lunghezza zero.

• "Ridenominazione" del flusso di dati predefinito è consentito, ma non è una vera ridenominazione, perché lascia dietro un flusso di dati predefinito di lunghezza zero.

Le dimensioni del buffer FileInformation passate a ZwSetInformationFile o FltSetInformationFile devono essere >= sizeof(FILE_RENAME_INFORMATION) più le dimensioni in byte della stringa FileName .

Requisiti

Vedi anche

FltSetInformationFile

IRP_MJ_SET_INFORMATION

ZwSetInformationFile