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 pFrom ou pTo membres ne sont pas 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 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, hNameMapping s pointe vers un int suivi d’un tableau de structures SHNAMEMAPPING Unicode. Toutefois, sur Microsoft Windows NT 4.0 et versions ultérieures, SHFileOperationtoujours retourne un handle à un ensemble Unicode de structures SHNAMEMAPPING. Si vous souhaitez que les applications fonctionnent 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 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 SHNAMEMAPPING structure contient l’ancien et le nouveau chemin d’accès pour l’un des fichiers renommés.

Exigences