Structure SHFILEOPSTRUCTA (shellapi.h)
Contient des informations que la fonction SHFileOperation utilise pour effectuer des opérations de fichier.
Syntaxe
typedef struct _SHFILEOPSTRUCTA {
HWND hwnd;
UINT wFunc;
PCZZSTR pFrom;
PCZZSTR pTo;
FILEOP_FLAGS fFlags;
BOOL fAnyOperationsAborted;
LPVOID hNameMappings;
PCSTR lpszProgressTitle;
} SHFILEOPSTRUCTA, *LPSHFILEOPSTRUCTA;
Membres
hwnd
Type : HWND
Handle de fenêtre dans la boîte de dialogue pour afficher des informations sur la status de l’opération de fichier.
wFunc
Type : UINT
Valeur qui indique l’opération à effectuer. Une des valeurs suivantes :
FO_COPY
Copiez les fichiers spécifiés dans le membre pFrom vers l’emplacement spécifié dans le membre pTo .
FO_DELETE
Supprimez les fichiers spécifiés dans pFrom.
FO_MOVE
Déplacez les fichiers spécifiés dans pFrom vers l’emplacement spécifié dans pTo.
FO_RENAME
Renommez le fichier spécifié dans pFrom. Vous ne pouvez pas utiliser cet indicateur pour renommer plusieurs fichiers avec un seul appel de fonction. Utilisez FO_MOVE à la place.
pFrom
Type : PCZZTSTR
Les caractères génériques MS-DOS standard, tels que « * », sont autorisés uniquement à la position du nom de fichier. L’utilisation d’un caractère générique ailleurs dans la chaîne entraîne des résultats imprévisibles.
Bien que ce membre soit déclaré comme une seule chaîne terminée par null, il s’agit en fait d’une mémoire tampon qui peut contenir plusieurs noms de fichiers délimités par des valeurs Null. Chaque nom de fichier est terminé par un seul caractère NULL . Le nom du dernier fichier se termine par un double caractère NULL (« \0\0 ») pour indiquer la fin de la mémoire tampon.
pTo
Type : PCZZTSTR
À l’instar de pFrom, le membre pTo est également une chaîne terminée par double null et est géré de la même façon. Toutefois, pTo doit répondre aux spécifications suivantes :
- Les caractères génériques ne sont pas pris en charge.
- Les opérations de copie et de déplacement peuvent spécifier des répertoires de destination qui n’existent pas. Dans ce cas, le système tente de les créer et affiche normalement une boîte de dialogue pour demander à l’utilisateur s’il souhaite créer le nouveau répertoire. Pour supprimer cette boîte de dialogue et créer les répertoires en mode silencieux, définissez l’indicateur FOF_NOCONFIRMMKDIR dans fFlags.
- Pour les opérations de copie et de déplacement, la mémoire tampon peut contenir plusieurs noms de fichiers de destination si le membre fFlags spécifie FOF_MULTIDESTFILES.
- Empaquetez plusieurs noms dans la chaîne pTo de la même façon que pour pFrom.
- Utilisez des chemins d’accès complets. L’utilisation de chemins d’accès relatifs n’est pas interdite, mais peut avoir des résultats imprévisibles.
fFlags
Type : FILEOP_FLAGS
Indicateurs qui contrôlent l’opération de fichier. Ce membre peut prendre une combinaison des indicateurs suivants.
FOF_ALLOWUNDO
Conservez les informations d’annulation, si possible.
Avant Windows Vista, les opérations ne pouvaient être annulées qu’à partir du même processus que celui qui effectuait l’opération d’origine.
Dans Windows Vista et les systèmes ultérieurs, l’étendue de l’annulation est une session utilisateur. Tout processus en cours d’exécution dans la session utilisateur peut annuler une autre opération. L’état d’annulation est conservé dans le processus Explorer.exe, et tant que ce processus est en cours d’exécution, il peut coordonner les fonctions d’annulation.
Si le paramètre de fichier source ne contient pas de chemin d’accès complet et de noms de fichiers, cet indicateur est ignoré.
FOF_CONFIRMMOUSE
Non utilisé.
FOF_FILESONLY
Effectuez l’opération uniquement sur les fichiers (et non sur les dossiers) si un nom de fichier générique (.) est spécifié.
FOF_MULTIDESTFILES
Le membre pTo spécifie plusieurs fichiers de destination (un pour chaque fichier source dans pFrom) plutôt qu’un répertoire dans lequel tous les fichiers sources doivent être déposés.
FOF_NOCONFIRMATION
Répondez avec Oui à Tout pour toute boîte de dialogue qui s’affiche.
FOF_NOCONFIRMMKDIR
Ne demandez pas à l’utilisateur de confirmer la création d’un répertoire si l’opération en nécessite la création.
FOF_NO_CONNECTED_ELEMENTS
Version 5.0. Ne déplacez pas les fichiers connectés en tant que groupe. Déplacez uniquement les fichiers spécifiés.
FOF_NOCOPYSECURITYATTRIBS
Version 4.71. Ne copiez pas les attributs de sécurité du fichier. Le fichier de destination reçoit les attributs de sécurité de son nouveau dossier.
FOF_NOERRORUI
N’affichez pas de boîte de dialogue à l’utilisateur si une erreur se produit.
FOF_NORECURSEREPARSE
Non utilisé.
FOF_NORECURSION
Effectuez uniquement l’opération dans le répertoire local. Ne pas opérer de manière récursive dans les sous-répertoires, ce qui est le comportement par défaut.
FOF_NO_UI
Windows Vista. Effectuez l’opération en mode silencieux, en ne présentant aucune interface utilisateur à l’utilisateur. Cela équivaut à FOF_SILENT | FOF_NOCONFIRMATION | FOF_NOERRORUI | FOF_NOCONFIRMMKDIR.
FOF_RENAMEONCOLLISION
Donnez le fichier en cours d’utilisation sur un nouveau nom dans une opération de déplacement, de copie ou de renommage si un fichier avec le nom cible existe déjà à la destination.
FOF_SILENT
N’affichez pas de boîte de dialogue de progression.
FOF_SIMPLEPROGRESS
Affichez une boîte de dialogue de progression, mais n’affichez pas les noms de fichiers individuels tels qu’ils sont utilisés.
FOF_WANTMAPPINGHANDLE
Si FOF_RENAMEONCOLLISION est spécifié et que des fichiers ont été renommés, attribuez un objet de mappage de noms qui contient leurs anciens et nouveaux noms au membre hNameMappings . Cet objet doit être libéré à l’aide de SHFreeNameMappings lorsqu’il n’est plus nécessaire.
FOF_WANTNUKEWARNING
Version 5.0. Envoyez un avertissement si un fichier est définitivement détruit pendant une opération de suppression plutôt que recyclé. Cet indicateur remplace partiellement FOF_NOCONFIRMATION.
fAnyOperationsAborted
Type : BOOL
Lorsque la fonction retourne, ce membre contient TRUE si des opérations de fichier ont été abandonnées avant d’être terminées ; sinon, FALSE. Une opération peut être abandonnée manuellement par l’utilisateur via l’interface utilisateur ou abandonnée en mode silencieux par le système si les indicateurs FOF_NOERRORUI ou FOF_NOCONFIRMATION ont été définis.
hNameMappings
Type : LPVOID
Lorsque la fonction retourne, ce membre contient un handle à un objet de mappage de noms qui contient les anciens et les nouveaux noms des fichiers renommés. Ce membre est utilisé uniquement si le membre fFlags inclut l’indicateur FOF_WANTMAPPINGHANDLE . Pour plus d’informations, consultez Remarques.
lpszProgressTitle
Type : PCTSTR
Pointeur vers le titre d’une boîte de dialogue de progression. Il s’agit d’une chaîne terminée par null. Ce membre est utilisé uniquement si fFlags inclut l’indicateur FOF_SIMPLEPROGRESS .
Remarques
// WRONG
LPTSTR pszSource = L"C:\\Windows\\*";
// RIGHT
LPTSTR pszSource = L"C:\\Windows\\*\0";
Pour prendre en compte les deux caractères null de fin, veillez à créer des mémoires tampons suffisamment grandes pour contenir MAX_PATH (qui inclut normalement le caractère null de fin unique) plus 1.
Il ne peut pas être exagéré que vos chemins doivent toujours être des chemins complets. Si les membres pFrom ou pTo sont des noms non qualifiés, les répertoires actuels sont extraits des paramètres globaux du lecteur actuel et du répertoire gérés par les fonctions GetCurrentDirectory et SetCurrentDirectory .
Si vous ne fournissez pas de chemin d’accès complet, les faits suivants deviennent pertinents :
- L’absence d’un chemin d’accès avant un nom de fichier n’indique pas à SHFileOperation que ce fichier réside à la racine du répertoire actif.
- La variable d’environnement PATH n’est pas utilisée par SHFileOperation pour déterminer un chemin d’accès valide.
- ShFileOperation ne peut pas être utilisé pour utiliser le répertoire qui est le répertoire actif lorsqu’il commence à s’exécuter. Le répertoire considéré comme le répertoire actif est à l’échelle du processus et peut être modifié à partir d’un autre thread pendant l’exécution de l’opération. Si cela devait se produire, les résultats de SHFileOperation seraient imprévisibles.
Si pFrom est défini sur un nom de fichier sans chemin d’accès complet, la suppression du fichier avec FO_DELETE ne le déplace pas vers la Corbeille, même si l’indicateur FOF_ALLOWUNDO est défini. Vous devez fournir un chemin d’accès complet pour supprimer le fichier dans la Corbeille.
SHFileOperation échoue sur tout chemin préfixé par « \? ».
Il existe deux versions de cette structure, une version ANSI (SHFILEOPSTRUCTA) et une version Unicode (SHFILEOPSTRUCTW). La version Unicode est identique à la version ANSI, sauf que les chaînes de caractères larges (LPCWSTR) sont utilisées à la place des chaînes de caractères ANSI (LPCSTR). Sur Windows 98 et versions antérieures, seule la version ANSI est prise en charge. Sur Microsoft Windows NT 4.0 et versions ultérieures, les versions ANSI et Unicode de cette structure sont prises en charge. SHFILEOPSTRUCTW et SHFILEOPTSTRUCTA ne doivent jamais être utilisés directement; la structure appropriée est redéfinie en tant que SHFILEOPSTRUCT par le précompileur selon que l’application est compilée pour ANSI ou Unicode.
SHNAMEMAPPING a des versions ANSI et Unicode similaires. Pour les applications ANSI, hNameMappings pointe vers un int suivi d’un tableau de structures ANSI SHNAMEMAPPING . Pour les applications Unicode, hNameMappings pointe vers un int suivi d’un tableau de structures Unicode SHNAMEMAPPING . Toutefois, sur Microsoft Windows NT 4.0 et versions ultérieures, SHFileOperation retourne toujours un handle à un ensemble Unicode de structures SHNAMEMAPPING. Si vous souhaitez que les applications soient fonctionnelles avec toutes les versions de Windows, l’application doit utiliser du code conditionnel pour gérer les mappages de noms. Par exemple :
x = SHFileOperation(&shop);
if (fWin9x)
HandleAnsiNameMappings(shop.hNameMappings);
else
HandleUnicodeNameMappings(shop.hNameMappings);
Traitez hNameMappings comme un pointeur vers une structure dont les membres sont une valeur UINT suivie d’un pointeur vers un tableau de structures SHNAMEMAPPING , comme indiqué dans sa déclaration :
struct HANDLETOMAPPINGS
{
UINT uNumberOfMappings; // Number of mappings in the array.
LPSHNAMEMAPPING lpSHNameMapping; // Pointer to the array of mappings.
};
La valeur UINT indique le nombre de structures SHNAMEMAPPING dans le tableau. Chaque structure SHNAMEMAPPING contient l’ancien et le nouveau chemin d’accès d’un des fichiers renommés.
Notes
L’en-tête shellapi.h définit SHFILEOPSTRUCT en tant qu’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. La combinaison 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
| Client minimal pris en charge | Windows XP [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows 2000 Server [applications de bureau uniquement] |
| En-tête | shellapi.h |
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour