MoveFileTransactedA, fonction (winbase.h)

Article
03/03/2024

[Microsoft recommande vivement aux développeurs d’utiliser d’autres moyens pour répondre aux besoins de votre application. De nombreux scénarios utilisant TxF peuvent être réalisés à l’aide de techniques plus simples et plus facilement disponibles. En outre, TxF peut ne pas être disponible dans les versions à venir de Microsoft Windows. Pour plus d’informations et les alternatives à TxF, consultez Alternatives à l’utilisation de Transactionnel NTFS.]

Déplace un fichier existant ou un répertoire, y compris ses enfants, en tant qu’opération transactionnelle.

Syntaxe

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

Paramètres

[in] lpExistingFileName

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

Par défaut, le nom est limité à MAX_PATH caractères. Pour étendre cette limite à 32 767 caractères de large, 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 de MAX_PATH sans précédencer « \ ?\ ». Pour plus d’informations, consultez la section « Limitation de longueur maximale du chemin d’accès » dans Naming Files, Paths et Namespaces .

[in, optional] lpNewFileName

Nouveau nom du fichier ou du répertoire. Le nouveau nom ne doit pas déjà exister. Un nouveau fichier peut se trouver sur un autre système de fichiers ou lecteur. Un nouveau répertoire doit se trouver sur le même lecteur.

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. L’opération d’écriture dans la valeur de Registre, comme indiqué dans la section Remarques, est celle qui est traitée. Le déplacement de fichiers est terminé lorsque l’ordinateur redémarre, une fois la transaction terminée.
MOVEFILE_REPLACE_EXISTING 1 (0x1)	S’il existe un fichier nommé lpNewFileName , 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)	Un appel à MoveFileTransacted signifie que l’opération de déplacement de fichier est terminée lorsque l’opération de validation est terminée. Cet indicateur n’est pas nécessaire ; il n’y a aucun effet négatif si cet indicateur est spécifié, autre qu’un ralentissement de l’opération. 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.

[in] hTransaction

Handle de la transaction. Ce handle est retourné par la fonction CreateTransaction .

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, MoveFileTransacted 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, MoveFileTransacted retourne zéro et GetLastError retourne ERROR_REQUEST_ABORTED. Le fichier existant est laissé intact.

Remarques

Si le paramètre dwFlags spécifie MOVEFILE_DELAY_UNTIL_REBOOT, MoveFileTransacted échoue s’il ne peut pas accéder au Registre. La fonction stocke transactionnellement 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 qu’il s’agit d’une suppression ou non :

szDstFile\0\0

szSrcFile\0szDstFile\0

La chaîne szDstFile\0\0 indique que le fichier szDstFile doit être supprimé au redémarrage.

La chaîne szSrcFile\0szDstFile\0 indique que szSrcFile doit être renommé szDstFile au redémarrage.

Note Bien que \0\0 ne soit techniquement pas autorisé dans un nœud REG_MULTI_SZ , cela peut être dû au fait que 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’elles ont été émises. Pour plus d’informations sur l’utilisation de l’indicateur MOVEFILE_DELAY_UNTIL_REBOOT , consultez MoveFileWithProgress.

Si un fichier est déplacé sur plusieurs volumes, MoveFileTransacted ne déplace pas le descripteur de sécurité avec le fichier. Le fichier se voit attribuer le descripteur de sécurité par défaut dans le répertoire de destination.

Cette fonction échoue toujours si vous spécifiez l’indicateur MOVEFILE_FAIL_IF_NOT_TRACKABLE ; le suivi n’est pas pris en charge par TxF.

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	No
Basculement transparent SMB 3.0 (TFO)	No
SMB 3.0 avec partages de fichiers avec montée en puissance parallèle (SO)	No
Système de fichiers du volume partagé de cluster (CsvFS)	No
Système de fichiers résilient (ReFS)	No

SMB 3.0 ne prend pas en charge TxF.

Configuration requise

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

Voir aussi

CopyFileTransacted

Fonctions de gestion des fichiers

MoveFileWithProgress

NTFS transactionnel

Share via