Fonction MoveFileWithProgressA (winbase.h)

Article
06/02/2023

Déplace un fichier ou un répertoire, y compris ses enfants. Vous pouvez fournir une fonction de rappel qui reçoit les notifications de progression.

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

Syntaxe

BOOL MoveFileWithProgressA(
  [in]           LPCSTR             lpExistingFileName,
  [in, optional] LPCSTR             lpNewFileName,
  [in, optional] LPPROGRESS_ROUTINE lpProgressRoutine,
  [in, optional] LPVOID             lpData,
  [in]           DWORD              dwFlags
);

Paramètres

[in] lpExistingFileName

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

Si dwFlags spécifie MOVEFILE_DELAY_UNTIL_REBOOT, le fichier ne peut pas exister sur un partage distant, car des 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 de fichiers, de chemins et d’espaces de noms.

Conseil

À compter de Windows 10, version 1607, vous pouvez choisir de supprimer la limitation MAX_PATH sans précédencer « \\ ?\ ». Pour plus d’informations, consultez la section « Limitation maximale de la longueur du chemin d’accès » de Naming Files, Paths et Namespaces .

[in, optional] lpNewFileName

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

Lors du déplacement d’un fichier, lpNewFileName peut se trouver sur un autre système de fichiers ou volume. Si lpNewFileName 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, lpExistingFileName et lpNewFileName doivent se trouver sur le même lecteur.

Si dwFlags spécifie MOVEFILE_DELAY_UNTIL_REBOOT et que lpNewFileName a la valeur NULL, MoveFileWithProgress inscrit lpExistingFileName à supprimer au redémarrage du système. La fonction échoue si elle ne peut pas accéder au Registre pour stocker les informations relatives à l’opération de suppression. 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.

Conseil

[in, optional] lpProgressRoutine

Pointeur vers une fonction de rappel CopyProgressRoutine appelée chaque fois qu’une autre partie du fichier a été déplacée. La fonction de rappel peut être utile si vous fournissez une interface utilisateur qui affiche la progression de l’opération. Ce paramètre peut être NULL.

[in, optional] lpData

Argument à passer à la fonction de rappel CopyProgressRoutine . Ce paramètre peut être NULL.

[in] dwFlags

Options de déplacement. Ce paramètre peut prendre 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 un usage futur.
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 d’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 ne peut être utilisée que 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 que 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 . Cette valeur ne peut pas être utilisée si lpNewFileName ou lpExistingFileName nomme un répertoire.
MOVEFILE_WRITE_THROUGH 8 (0x8)	La fonction ne retourne pas tant que le fichier n’a pas été 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 le retour de la fonction. 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éfini.

Valeur retournée

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. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Lors du déplacement d’un fichier sur plusieurs volumes, si lpProgressRoutine retourne PROGRESS_CANCEL en raison de l’annulation de l’opération par l’utilisateur, MoveFileWithProgress retourne zéro et GetLastError retourne ERROR_REQUEST_ABORTED. Le fichier existant est laissé intact.

Lors du déplacement d’un fichier sur plusieurs volumes, si lpProgressRoutine retourne PROGRESS_STOP en raison de l’arrêt de l’opération par l’utilisateur, MoveFileWithProgress retourne zéro et GetLastError retourne ERROR_REQUEST_ABORTED. Le fichier existant est laissé intact.

Remarques

La fonction MoveFileWithProgress coordonne son fonctionnement 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 d’une 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 vous obtiendrez tout l’accès que vous demandez sur le handle qui vous est retourné au moment de la création du fichier. Si vous avez demandé l’autorisation de suppression au moment de la création du fichier, vous pouvez supprimer ou renommer le fichier avec ce handle, mais pas avec n’importe quel autre.

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

Technologie	Prise en charge
Protocole Server Message Block (SMB) 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
Système de fichiers du volume partagé de cluster (CsvFS)	Oui
Système de fichiers résilient (ReFS)	Oui

CsvFs effectue les E/S redirigées pour les fichiers compressés.

Notes

L’en-tête winbase.h définit MoveFileWithProgress comme un alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	winbase.h (inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll

Voir aussi

CopyFileEx

CopyProgressRoutine

Fonctions de gestion des fichiers

MoveFileEx

MoveFileTransacted