FILE_RENAME_INFORMATION structure (ntifs.h)

La structure FILE_RENAME_INFORMATION est utilisée pour renommer un fichier.

Syntaxe

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;

Membres

DUMMYUNIONNAME

DUMMYUNIONNAME.ReplaceIfExists

Définissez sur TRUE pour spécifier que si un fichier portant le nom donné existe déjà, il doit être remplacé par le fichier donné. Définissez sur FALSE si l’opération de renommage doit échouer si un fichier portant le nom donné existe déjà.

DUMMYUNIONNAME.Flags

Indicateurs pour l’opération de renommage. Ce champ s’applique uniquement lorsqu’il est utilisé avec la classe d’informations FileRenameInformationEx .

Les valeurs possibles sont les suivantes :

ReplaceIfExists

Définissez sur TRUE pour spécifier que si un fichier portant le nom donné existe déjà, il doit être remplacé par le fichier donné. Définissez sur FALSE si l’opération de renommage doit échouer si un fichier portant le nom donné existe déjà.

RootDirectory

Handle que IopOpenLinkOrRenameTarget utilise pour ouvrir le répertoire cible.

Si le fichier n’est pas déplacé vers un autre répertoire, ou si le membre FileName contient le chemin d’accès complet, ce membre a la valeur NULL. Sinon, il s’agit d’un handle pour le répertoire racine sous lequel le fichier réside après son renommage.

Pour effectuer deux opérations d’ouverture qui ne provoquent pas de conflit de partage, vous pouvez ouvrir RootDirectory en demandant une traversée | read-attribute. IopOpenLinkOrRenameTarget peut ensuite effectuer une ouverture relative en demandant FILE_WRITE_DATA | SYNCHRONISER. Ces deux ouvertures ne provoquent pas de conflit de partage.

FileNameLength

Longueur, en octets, du nouveau nom du fichier.

FileName[1]

Premier caractère d’une chaîne de caractères larges contenant le nouveau nom du fichier. Ceci est suivi en mémoire par le reste de la chaîne. Si le membre RootDirectory a la valeur NULL et que le fichier est déplacé vers un autre répertoire, ce membre spécifie le nom de chemin complet à affecter au fichier. Sinon, elle spécifie uniquement le nom de fichier ou un chemin d’accès relatif.

Remarques

La structure FILE_RENAME_INFORMATION est utilisée pour renommer un fichier. Cette opération peut être effectuée de l’une des manières suivantes :

• Appelez FltSetInformationFile ou ZwSetInformationFile, en passant FileRenameInformation comme valeur de FileInformationClass et en transmettant une mémoire tampon allouée à l’appelant au format FILE_RENAME_INFORMATION structure pour la valeur de FileInformation. Le paramètre FileHandle spécifie le fichier à renommer.

• Créez un IRP avec le code de fonction principal IRP_MJ_SET_INFORMATION.

Les minifiltres du système de fichiers doivent utiliser FltSetInformationFile, et non ZwSetInformationFile, pour renommer un fichier.

Le renommage d’un fichier nécessite l’accès DELETE au fichier afin que l’entrée de répertoire puisse être supprimée du répertoire parent actuel, ainsi que l’accès approprié pour créer l’entrée dans le nouveau fichier de répertoire parent.

La chaîne de nom de fichier dans le membre FileName doit être spécifiée dans l’un des formulaires suivants.

• Nom de fichier simple. (Le membre RootDirectory est NULL.) Dans ce cas, le fichier est simplement renommé dans le même répertoire. Autrement dit, l’opération de renommage modifie le nom du fichier, mais pas son emplacement.

• Nom de fichier complet. (Le membre RootDirectory est NULL.) Dans ce cas, l’opération de renommage modifie le nom et l’emplacement du fichier.

• Nom de fichier relatif. Dans ce cas, le membre RootDirectory contient un handle dans le répertoire cible pour l’opération de renommage. Le nom de fichier lui-même doit être un nom de fichier simple.

Règles générales pour les opérations de renommage :

• Un fichier ou un répertoire ne peut être renommé qu’au sein d’un volume. En d’autres termes, une opération de renommage ne peut pas entraîner le déplacement d’un fichier ou d’un répertoire vers un autre volume.

• Impossible de renommer le répertoire racine d’un volume.

• Si ReplaceIfExists a la valeur FALSE et que la cible existe, l’opération de renommage échoue.

• Même si ReplaceIfExists a la valeur TRUE, l’opération de renommage échoue toujours si un fichier portant le même nom existe déjà et qu’il s’agit d’un répertoire, d’un fichier en lecture seule ou d’un fichier en cours d’exécution.

• Les fichiers et répertoires d’un volume ne peuvent pas être renommés s’il s’agit d’un volume en lecture seule, tel qu’un volume CDFS ou un volume NTFS en lecture seule.

Règles spéciales pour renommer les fichiers ouverts :

• Un fichier ne peut pas être renommé s’il a des descripteurs ouverts, sauf s’il est ouvert uniquement en raison d’un verrou opportuniste par lot (oplock) et que le verrouillage oplock de lot peut être cassé immédiatement.

• Un fichier ne peut pas être renommé si un fichier portant le même nom existe et a des descripteurs ouverts (sauf dans le cas de batch-oplock décrit précédemment).

• Un répertoire ne peut pas être renommé s’il ou l’un de ses sous-répertoires contient un fichier qui a des descripteurs ouverts (sauf dans le cas de batch-oplock décrit précédemment).

Règles spéciales pour renommer les flux de données NTFS :

• Le flux de répertoire par défaut ne peut pas être renommé.

• Le nouveau nom du flux doit commencer par un signe deux-points (:).

• Un flux de données ne peut être renommé que dans le même fichier. En d’autres termes, une opération de renommage ne peut pas entraîner le déplacement d’un flux de données vers un autre fichier.

• Un flux de données sur un répertoire ne peut pas être renommé en flux de données par défaut.

• Si ReplaceIfExists est défini sur TRUE, l’opération de renommage réussit uniquement si un flux portant le même nom n’existe pas ou s’il s’agit d’un flux de données de longueur nulle.

• « Renommer » le flux de données par défaut est autorisé, mais il ne s’agit pas d’un véritable renommage, car il laisse derrière lui un flux de données par défaut de longueur nulle.

La taille de la mémoire tampon FileInformation passée à ZwSetInformationFile ou FltSetInformationFile doit être >= sizeof(FILE_RENAME_INFORMATION) plus la taille en octets de la chaîne FileName .

Configuration requise

Voir aussi

FltSetInformationFile

IRP_MJ_SET_INFORMATION

ZwSetInformationFile