MoveFileExW, fonction (winbase.h)

Article
06/27/2024

Déplace un fichier ou un répertoire existant, y compris ses enfants, avec différentes options de déplacement.

La fonction MoveFileWithProgress équivaut à la fonction MoveFileEx , sauf que MoveFileWithProgress vous permet de fournir une fonction de rappel qui reçoit des notifications de progression.

Pour effectuer cette opération en tant qu’opération transactionnelle, utilisez la fonction MoveFileTransacted.

Syntaxe

BOOL MoveFileExW(
  [in]           LPCWSTR lpExistingFileName,
  [in, optional] LPCWSTR lpNewFileName,
  [in]           DWORD   dwFlags
);

Paramètres

[in] lpExistingFileName

Nom actuel du fichier ou du répertoire sur l’ordinateur local.

Si dwFlags spécifie MOVEFILE_DELAY_UNTIL_REBOOT, le fichier ne peut pas exister sur un partage distant, car les opérations retardées sont effectuées avant que le réseau soit disponible.

Par défaut, le nom est limité à MAX_PATH caractères. Pour étendre cette limite à 32 767 caractères larges, ajoutez « \\ ?\ » au chemin d’accès. Pour plus d’informations, consultez nommage des fichiers, des chemins d’accès et des espaces de noms.

Pourboire

À compter de Windows 10, version 1607, vous pouvez choisir de supprimer la limitation MAX_PATH sans précéder « \\ ?\ ». Pour plus d’informations, consultez la section « Limite maximale de longueur de chemin » de noms, fichiers, chemin s et espaces de noms.

[in, optional] lpNewFileName

Nouveau nom du fichier ou du répertoire sur l’ordinateur local.

Lors du déplacement d’un fichier, la destination peut se trouver sur un autre système de fichiers ou un autre volume. Si la destination se trouve sur un autre lecteur, vous devez définir l’indicateur MOVEFILE_COPY_ALLOWED dans dwFlags.

Lors du déplacement d’un répertoire, la destination doit se trouver sur le même lecteur.

Si dwFlags spécifie MOVEFILE_DELAY_UNTIL_REBOOT et lpNewFileName est NULL, MoveFileEx inscrit le fichier lpExistingFileName à supprimer lorsque le système redémarre. Si lpExistingFileName fait référence à un répertoire, le système supprime le répertoire au redémarrage uniquement si le répertoire est vide.

Dans la version ANSI de cette fonction, le nom est limité à MAX_PATH caractères. Pour étendre cette limite à 32 767 caractères larges, appelez la version Unicode de la fonction et ajoutez « \ ? » au chemin d’accès. Pour plus d’informations, consultez nommage d’un fichier

Pourboire

[in] dwFlags

Ce paramètre peut être une ou plusieurs des valeurs suivantes.

Valeur	Signification
MOVEFILE_COPY_ALLOWED 2 (0x2)	Si le fichier doit être déplacé vers un autre volume, la fonction simule le déplacement à l’aide des fonctions CopyFile et DeleteFile. Si le fichier est correctement copié dans un autre volume et que le fichier d’origine ne peut pas être supprimé, la fonction réussit à laisser le fichier source intact. Cette valeur ne peut pas être utilisée avec MOVEFILE_DELAY_UNTIL_REBOOT.
MOVEFILE_CREATE_HARDLINK 16 (0x10)	Réservé pour une utilisation ultérieure.
MOVEFILE_DELAY_UNTIL_REBOOT 4 (0x4)	Le système ne déplace pas le fichier tant que le système d’exploitation n’est pas redémarré. Le système déplace le fichier immédiatement après l’exécution de AUTOCHK, mais avant de créer des fichiers de pagination. Par conséquent, ce paramètre permet à la fonction de supprimer les fichiers de pagination des start-ups précédentes. Cette valeur peut être utilisée uniquement si le processus se trouve dans le contexte d’un utilisateur qui appartient au groupe administrateurs ou au compte LocalSystem. Cette valeur ne peut pas être utilisée avec MOVEFILE_COPY_ALLOWED.
MOVEFILE_FAIL_IF_NOT_TRACKABLE 32 (0x20)	La fonction échoue si le fichier source est une source de lien, mais le fichier ne peut pas être suivi après le déplacement. Cette situation peut se produire si la destination est un volume mis en forme avec le système de fichiers FAT.
MOVEFILE_REPLACE_EXISTING 1 (0x1)	Si un fichier nommé lpNewFileName existe, la fonction remplace son contenu par le contenu du fichier lpExistingFileName, à condition que les exigences de sécurité relatives aux listes de contrôle d’accès (ACL) soient remplies. Pour plus d’informations, consultez la section Remarques de cette rubrique. Si lpNewFileName nomme un répertoire existant, une erreur est signalée.
MOVEFILE_WRITE_THROUGH 8 (0x8)	La fonction ne retourne pas tant que le fichier n’est pas réellement déplacé sur le disque. La définition de cette valeur garantit qu’un déplacement effectué en tant qu’opération de copie et de suppression est vidé sur le disque avant que la fonction ne retourne. Le vidage se produit à la fin de l’opération de copie. Cette valeur n’a aucun effet si MOVEFILE_DELAY_UNTIL_REBOOT est définie.

Valeur de retour

Si la fonction réussit, la valeur de retour est différente de zéro.

Si la fonction échoue, la valeur de retour est égale à zéro (0). Pour obtenir des informations d’erreur étendues, appelez GetLastError.

Remarques

Si le paramètre dwFlags spécifie MOVEFILE_DELAY_UNTIL_REBOOT, MoveFileEx échoue s’il ne peut pas accéder au Registre. La fonction stocke les emplacements des fichiers à renommer au redémarrage dans la valeur de Registre suivante : HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\PendingFileRenameOperations

Cette valeur de Registre est de type REG_MULTI_SZ. Chaque opération de renommage stocke l’une des chaînes terminées par NULL suivantes, selon que le renommage est une suppression ou non :

szSrcFile\0\0
szSrcFile\0szDstFile\0

La chaîne szSrcFile\0\0 indique que le fichier szSrcFile doit être supprimé lors du redémarrage. La chaîne szSrcFile\0szDstFile\0 indique que szSrcFile doit être renommé szDstFile lors du redémarrage.

Remarque Bien que \0\0 ne soit techniquement pas autorisé dans un nœud REG_MULTI_SZ, il peut, car le fichier est considéré comme renommé en nom Null.

Le système utilise ces entrées de Registre pour effectuer les opérations au redémarrage dans le même ordre qu’ils ont été émis. Par exemple, le fragment de code suivant crée des entrées de Registre qui suppriment szSrcFile et renomment szSrcFile pour être szDstFile au redémarrage :

MoveFileEx(szSrcFile, NULL, MOVEFILE_DELAY_UNTIL_REBOOT);
MoveFileEx(szSrcFile, szDstFile, MOVEFILE_DELAY_UNTIL_REBOOT);

Étant donné que les opérations réelles de déplacement et de suppression spécifiées avec l’indicateur de MOVEFILE_DELAY_UNTIL_REBOOT ont lieu une fois que l’application appelante a cessé de s’exécuter, la valeur de retour ne peut pas refléter la réussite ou l’échec du déplacement ou de la suppression du fichier. Elle reflète plutôt la réussite ou l’échec de la mise en place des entrées appropriées dans le Registre.

Le système supprime un répertoire marqué pour suppression avec l’indicateur MOVEFILE_DELAY_UNTIL_REBOOT uniquement s’il est vide. Pour garantir la suppression des répertoires, déplacez ou supprimez tous les fichiers du répertoire avant de tenter de le supprimer. Les fichiers peuvent se trouver dans le répertoire au moment du démarrage, mais ils doivent être supprimés ou déplacés avant que le système puisse supprimer le répertoire.

Les opérations de déplacement et de suppression sont effectuées au démarrage dans le même ordre qu’elles sont spécifiées dans l’application appelante. Pour supprimer un répertoire contenant des fichiers au démarrage, commencez par supprimer les fichiers.

Si un fichier est déplacé entre les volumes, MoveFileEx ne déplace pas le descripteur de sécurité avec le fichier. Le fichier est affecté au descripteur de sécurité par défaut dans le répertoire de destination.

La fonction MoveFileEx coordonne son opération avec le service de suivi des liens , afin que les sources de liens puissent être suivies à mesure qu’elles sont déplacées.

Pour supprimer ou renommer un fichier, vous devez disposer d’une autorisation de suppression sur le fichier ou supprimer l’autorisation enfant dans le répertoire parent. Si vous configurez un répertoire avec tous les accès, à l’exception de la suppression et de la suppression d’enfants et que les listes de contrôle d’accès des nouveaux fichiers sont héritées, vous devez être en mesure de créer un fichier sans pouvoir le supprimer. Toutefois, vous pouvez ensuite créer un fichier et obtenir tout l’accès que vous demandez sur le handle qui vous est retourné au moment où vous créez le fichier. Si vous demandez l’autorisation de suppression au moment où vous créez le fichier, vous pouvez supprimer ou renommer le fichier avec ce handle, mais pas avec un autre handle. Pour plus d’informations, consultez Sécurité des fichiers et droits d’accès.

Dans Windows 8 et Windows Server 2012, cette fonction est prise en charge par les technologies suivantes.

Technologie	Supporté
Protocole SMB (Server Message Block) 3.0	Oui
Basculement transparent SMB 3.0 (TFO)	Oui
SMB 3.0 avec partages de fichiers avec montée en puissance parallèle (SO)	Oui
Cluster Shared Volume File System (CsvFS)	Oui
Système de fichiers résilient (ReFS)	Oui

Exemples

Pour obtenir un exemple, consultez Création et utilisation d’un fichier temporaire.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows XP [applications de bureau \| Applications UWP]
serveur minimum pris en charge	Windows Server 2003 [applications de bureau \| Applications UWP]
plateforme cible	Windows
d’en-tête	winbase.h (inclure Windows.h)
bibliothèque	Kernel32.lib
DLL	Kernel32.dll