Partager via


Fonction SHFileOperationW (shellapi.h)

Copie, déplace, renomme ou supprime un objet de système de fichiers. Cette fonction a été remplacée dans Windows Vista par IFileOperation.

Syntaxe

int SHFileOperationW(
  [in, out] LPSHFILEOPSTRUCTW lpFileOp
);

Paramètres

[in, out] lpFileOp

Type : LPSHFILEOPSTRUCT

Pointeur vers une structure SHFILEOPSTRUCT qui contient les informations dont cette fonction a besoin pour effectuer l’opération spécifiée. Ce paramètre doit contenir une valeur valide qui n’est pas NULL. Vous êtes responsable de la validation de la valeur. Si vous ne le validez pas, vous rencontrerez des résultats inattendus.

Valeur retournée

Type : int

Retourne zéro en cas de réussite ; dans le cas contraire. Les applications doivent normalement simplement case activée pour zéro ou zéro.

Il est recommandé d’examiner la valeur du membre fAnyOperationsAborted du SHFILEOPSTRUCT. SHFileOperation peut retourner 0 pour réussir si l’utilisateur annule l’opération. Si vous ne case activée pas fAnyOperationsAborted ainsi que la valeur de retour, vous ne pouvez pas savoir que la fonction a accompli la tâche complète que vous lui avez demandée et vous pouvez procéder selon des hypothèses incorrectes.

N’utilisez pas GetLastError avec les valeurs renvoyées de cette fonction.

Pour examiner les valeurs non nulles à des fins de résolution des problèmes, elles correspondent en grande partie à celles définies dans Winerror.h. Toutefois, plusieurs de ses valeurs de retour possibles sont basées sur des codes d’erreur antérieurs à Win32, qui, dans certains cas, chevauchent les valeurs Winerror.h ultérieures sans correspondre à leur signification. Ces valeurs particulières sont détaillées ici, et pour ces valeurs spécifiques, seules ces significations doivent être acceptées sur les codes Winerror.h. Toutefois, ces valeurs sont fournies avec les avertissements suivants :

  • Il s’agit de codes d’erreur antérieurs à Win32 et ne sont plus pris en charge ou définis dans un fichier d’en-tête public. Pour les utiliser, vous devez les définir vous-même ou les comparer à la valeur numérique.
  • Ces codes d’erreur sont susceptibles d’être modifiés et ont toujours été modifiés.
  • Ces valeurs sont fournies uniquement comme aide au débogage. Elles ne doivent pas être considérées comme définitives.
Code d'erreur Valeur Signification
DE_SAMEFILE 0x71 Les fichiers source et de destination sont le même fichier.
DE_MANYSRC1DEST 0x72 Plusieurs chemins de fichiers ont été spécifiés dans la mémoire tampon source, mais un seul chemin d’accès de fichier de destination.
DE_DIFFDIR 0x73 L’opération de renommage a été spécifiée, mais le chemin d’accès de destination est un autre répertoire. Utilisez plutôt l’opération de déplacement.
DE_ROOTDIR 0x74 La source est un répertoire racine, qui ne peut pas être déplacé ou renommé.
DE_OPCANCELLED 0x75 L’opération a été annulée par l’utilisateur ou annulée en mode silencieux si les indicateurs appropriés ont été fournis à SHFileOperation.
DE_DESTSUBTREE 0x76 La destination est une sous-arborescence de la source.
DE_ACCESSDENIEDSRC 0x78 Les paramètres de sécurité ont refusé l’accès à la source.
DE_PATHTOODEEP 0x79 Le chemin d’accès source ou de destination a dépassé ou dépasserait MAX_PATH.
DE_MANYDEST 0x7A L’opération a impliqué plusieurs chemins de destination, ce qui peut échouer dans le cas d’une opération de déplacement.
DE_INVALIDFILES 0x7C Le chemin d’accès dans la source ou la destination ou les deux n’était pas valide.
DE_DESTSAMETREE 0x7D La source et la destination ont le même dossier parent.
DE_FLDDESTISFILE 0x7E Le chemin d’accès de destination est un fichier existant.
DE_FILEDESTISFLD 0x80 Le chemin d’accès de destination est un dossier existant.
DE_FILENAMETOOLONG 0x81 Le nom du fichier dépasse MAX_PATH.
DE_DEST_IS_CDROM 0x82 La destination est un CD-ROM en lecture seule, éventuellement non mis en forme.
DE_DEST_IS_DVD 0x83 La destination est un DVD en lecture seule, éventuellement non mis en forme.
DE_DEST_IS_CDRECORD 0x84 La destination est un CD-ROM accessible en écriture, éventuellement non mis en forme.
DE_FILE_TOO_LARGE 0x85 Le fichier impliqué dans l’opération est trop volumineux pour le média de destination ou le système de fichiers.
DE_SRC_IS_CDROM 0x86 La source est un CD-ROM en lecture seule, éventuellement non mis en forme.
DE_SRC_IS_DVD 0x87 La source est un DVD en lecture seule, éventuellement non mis en forme.
DE_SRC_IS_CDRECORD 0x88 La source est un CD-ROM accessible en écriture, éventuellement non mis en forme.
DE_ERROR_MAX 0xB7 MAX_PATH a été dépassé pendant l’opération.
0x402 Une erreur inconnue s'est produite. Cela est généralement dû à un chemin d’accès non valide dans la source ou la destination. Cette erreur ne se produit pas sur Windows Vista et versions ultérieures.
ERRORONDEST 0x10000 Une erreur non spécifiée s’est produite sur la destination.
DE_ROOTDIR | ERRORONDEST 0x10074 Destination est un répertoire racine qui ne peut pas être renommé.

Remarques

Vous devez utiliser des noms de chemins complets avec cette fonction. Son utilisation avec des noms de chemin d’accès relatifs n’est pas thread safe.

À deux exceptions près, vous ne pouvez pas utiliser SHFileOperation pour déplacer des dossiers spéciaux d’un lecteur local vers un ordinateur distant en spécifiant un chemin d’accès réseau. Les exceptions sont les dossiers Mes documents (CSIDL_PERSONAL, CSIDL_DOCUMENTS) et Mes images (CSIDL_MYPICTURES).

Lorsqu’il est utilisé pour supprimer un fichier, SHFileOperation supprime définitivement le fichier, sauf si vous définissez l’indicateur FOF_ALLOWUNDO dans le membre fFlags de la structure SHFILEOPSTRUCT pointée vers lpFileOp. La définition de cet indicateur envoie le fichier à la Corbeille. Si vous souhaitez simplement supprimer un fichier et garantir qu’il n’est pas placé dans la Corbeille, utilisez DeleteFile.

Si un gestionnaire de rappel de copie est exposé et inscrit, SHFileOperation l’appelle , sauf si vous définissez un indicateur tel que FOF_NOCONFIRMATION dans le membre fFlags de la structure pointée vers lpFileOp. Pour plus d’informations sur l’implémentation de gestionnaires de rappel de copie, consultez ICopyHook ::CopyCallback .

La suppression de fichier est récursive, sauf si vous définissez l’indicateur FOF_NORECURSION dans lpFileOp.

Connexion de fichiers

Avec Windows 2000 ou version ultérieure, il est possible de connecter un fichier HTML à un dossier qui contient des fichiers associés, tels que des images ou des feuilles de style gif (Graphics Interchange Format). Si la connexion de fichier est activée, lorsque vous déplacez ou copiez le fichier HTML, le dossier connecté et tous ses fichiers sont également déplacés ou copiés. À l’inverse, si vous déplacez le dossier avec les fichiers associés, le fichier HTML est également déplacé.

Le fichier HTML doit avoir une extension .htm ou .html. Vous créez la connexion aux fichiers associés en plaçant le dossier qui les contient dans le même dossier que le fichier HTML. Le nom du dossier qui contient les fichiers connectés doit être identique au nom du fichier HTML suivi de « _files » ou « .files » (ceci respecte la casse ; par exemple, ). Files » ne fonctionne pas). Un exemple est donné ici.

  1. Créez un fichier nommé Test.htm dans le répertoire C :\Files (C:\Files\Test.htm).
  2. Créez un dossier nommé Test.files dans le répertoire C :\Files (C :\Files\Test.files).
  3. Renseignez le dossier avec quelques fichiers. Tout fichier placé dans ce dossier est connecté à Test.htm.
  4. Déplacez ou copiez le fichier Test.htm dans le répertoire C :\Files2.
  5. Notez que le répertoire Test.files se trouve désormais également dans le répertoire C :\Files2.

La connexion de fichier est activée par défaut. Il peut être désactivé en ajoutant une entrée REG_DWORD , NoFileFolderConnection, comme illustré ici :

HKEY_CURRENT_USER
   Software
      Microsoft
         Windows
            CurrentVersion
               Explorer
                  NoFileFolderConnection

La définition de NoFileFolderConnection sur 1 désactive la connexion de fichier. Si la valeur est définie sur zéro ou est manquante, la connexion de fichier est activée.

Pour déplacer uniquement les fichiers spécifiés et aucun des fichiers connectés, définissez l’indicateur FOF_NO_CONNECTED_ELEMENTS dans le membre fFlags de la structure pointée vers lpFileOp.

Notez que l’utilisation d’un dossier portant un nom tel que « MyFile_files » pour définir une connexion peut ne pas être valide pour les versions localisées de Windows. Le terme « files » doit peut-être être remplacé par le mot équivalent dans la langue locale.

Notes

L’en-tête shellapi.h définit SHFileOperation 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 2000 Server [applications de bureau uniquement]
Plateforme cible Windows
En-tête shellapi.h
Bibliothèque Shell32.lib
DLL Shell32.dll (version 4.0 ou ultérieure)
Ensemble d’API ext-ms-win-shell-shell32-l1-2-1 (introduit dans Windows 10, version 10.0.10240)