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.
- Créez un fichier nommé Test.htm dans le répertoire C :\Files (C:\Files\Test.htm).
- Créez un dossier nommé Test.files dans le répertoire C :\Files (C :\Files\Test.files).
- Renseignez le dossier avec quelques fichiers. Tout fichier placé dans ce dossier est connecté à Test.htm.
- Déplacez ou copiez le fichier Test.htm dans le répertoire C :\Files2.
- 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) |