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 l’état 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 à 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 dans la position de 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é en tant que chaîne à fin null unique, il s’agit en fait d’une mémoire tampon qui peut contenir plusieurs noms de fichiers délimités par null. Chaque nom de fichier est arrêté par un seul caractère NULL. Le nom du dernier fichier est arrêté avec un double caractère NULL (« \0\0 ») pour indiquer la fin de la mémoire tampon.
pTo
Type : PCZZTSTR
Comme pFrom, le membre pTo est également une chaîne terminée double-null et est gérée de la même façon. Toutefois, pTo doit respecter les 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 répertoire. Pour supprimer cette boîte de dialogue et que les répertoires sont créés 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 fFlags membre spécifie FOF_MULTIDESTFILES.
- Packez plusieurs noms dans la chaîne pTo de la même façon que pour pFrom.
- Utilisez des chemins complets. L’utilisation de chemins 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 peuvent être annulées uniquement à partir du même processus que celui qui a effectué l’opération d’origine.
Dans les systèmes Windows Vista et 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 à tous les pour toute boîte de dialogue affichée.
FOF_NOCONFIRMMKDIR
Ne demandez pas à l’utilisateur de confirmer la création d’un répertoire si l’opération exige qu’elle soit créée.
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 fonctionnez pas de manière récursive dans des sous-répertoires, qui est le comportement par défaut.
FOF_NO_UI
windows Vista. Effectuez l’opération en mode silencieux, en présentant aucune interface utilisateur à l’utilisateur. Cela équivaut à FOF_SILENT | FOF_NOCONFIRMATION | FOF_NOERRORUI | FOF_NOCONFIRMMKDIR.
FOF_RENAMEONCOLLISION
Donnez au fichier en cours d’exploitation un nouveau nom dans une opération de déplacement, de copie ou de renommage si un fichier portant 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 à mesure qu’ils sont utilisés.
FOF_WANTMAPPINGHANDLE
Si FOF_RENAMEONCOLLISION est spécifié et que des fichiers ont été renommés, affectez un objet de mappage de noms qui contient leurs anciens noms et nouveaux aux hNameMappings membre. 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étruit définitivement pendant une opération de suppression plutôt que recyclé. Cet indicateur remplace partiellement FOF_NOCONFIRMATION.
fAnyOperationsAborted
Type : BOOL
Lorsque la fonction est retournée, ce membre contient TRUE si des opérations de fichier ont été abandonnées avant qu’elles ne soient terminées ; sinon, FALSE. Une opération peut être abandonnée manuellement par l’utilisateur via l’interface utilisateur ou elle peut être 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 est retournée, ce membre contient un handle vers un objet de mappage de noms qui contient les anciens et nouveaux noms des fichiers renommés. Ce membre n’est utilisé que si le membre fFlags inclut l’indicateur de FOF_WANTMAPPINGHANDLE. Pour plus d’informations, consultez les 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 n’est utilisé que si fFlags inclut l’indicateur de FOF_SIMPLEPROGRESS.
Remarques
// WRONG
LPTSTR pszSource = L"C:\\Windows\\*";
// RIGHT
LPTSTR pszSource = L"C:\\Windows\\*\0";
Pour tenir compte des deux caractères null de fin, veillez à créer des mémoires tampons suffisamment volumineuses pour contenir MAX_PATH (qui inclut normalement le caractère null de fin unique) plus 1.
Il ne peut pas être surévalué que vos chemins d’accès doivent toujours être des chemins complets. Si les noms
Si vous ne fournissez pas de chemin complet, les faits suivants deviennent pertinents :
- L’absence de chemin d’accès avant qu’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 en cours d’exécution. Le répertoire vu 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 complet pour supprimer le fichier dans la Corbeille.
SHFileOperation échoue sur n’importe quel chemin précédé de « \ ? ».
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 de 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 comme 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, hNameMapping s pointe vers un int suivi d’un tableau de structures SHNAMEMAPPING ANSI. Pour les applications Unicode,
x = SHFileOperation(&shop);
if (fWin9x)
HandleAnsiNameMappings(shop.hNameMappings);
else
HandleUnicodeNameMappings(shop.hNameMappings);
Traitez hNameMappings comme 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
Note
L’en-tête shellapi.h définit SHFILEOPSTRUCT comme 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.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows XP [applications de bureau uniquement] |
| serveur minimum pris en charge | Windows 2000 Server [applications de bureau uniquement] |
| d’en-tête | shellapi.h |