Structure SHELLEXECUTEINFOA (shellapi.h)

  • Article

Contient les informations utilisées par ShellExecuteEx.

Syntaxe

typedef struct _SHELLEXECUTEINFOA {
  DWORD     cbSize;
  ULONG     fMask;
  HWND      hwnd;
  LPCSTR    lpVerb;
  LPCSTR    lpFile;
  LPCSTR    lpParameters;
  LPCSTR    lpDirectory;
  int       nShow;
  HINSTANCE hInstApp;
  void      *lpIDList;
  LPCSTR    lpClass;
  HKEY      hkeyClass;
  DWORD     dwHotKey;
  union {
    HANDLE hIcon;
    HANDLE hMonitor;
  } DUMMYUNIONNAME;
  HANDLE    hProcess;
} SHELLEXECUTEINFOA, *LPSHELLEXECUTEINFOA;

Membres

cbSize

Type : DWORD

Obligatoire. Taille de cette structure, en octets.

fMask

Type : ULONG

Combinaison d’une ou plusieurs des valeurs suivantes qui indiquent le contenu et la validité des autres membres de la structure :

SEE_MASK_DEFAULT (0x00000000) Utilisez les valeurs par défaut.
SEE_MASK_CLASSNAME (0x00000001) Utilisez le nom de classe donné par le membre lpClass . Si SEE_MASK_CLASSKEY et SEE_MASK_CLASSNAME sont définis, la clé de classe est utilisée.
SEE_MASK_CLASSKEY (0x00000003) Utilisez la clé de classe fournie par le membre hkeyClass . Si SEE_MASK_CLASSKEY et SEE_MASK_CLASSNAME sont définis, la clé de classe est utilisée.
SEE_MASK_IDLIST (0x00000004) Utilisez la liste d’identificateurs d’élément donnée par le membre lpIDList . Le membre lpIDList doit pointer vers une structure ITEMIDLIST .
SEE_MASK_INVOKEIDLIST (0x0000000C) Utilisez l’interface IContextMenu du gestionnaire de menu contextuel de l’élément sélectionné. Utilisez lpFile pour identifier l’élément par son chemin de système de fichiers ou lpIDList pour identifier l’élément par son PIDL. Cet indicateur permet aux applications d’utiliser ShellExecuteEx pour appeler des verbes à partir d’extensions de menu contextuel au lieu des verbes statiques répertoriés dans le Registre.
Note: SEE_MASK_INVOKEIDLIST remplace et implique SEE_MASK_IDLIST.
SEE_MASK_ICON (0x00000010) Utilisez l’icône donnée par le membre hIcon . Cet indicateur ne peut pas être combiné avec SEE_MASK_HMONITOR.
Note: Cet indicateur est utilisé uniquement dans Windows XP et versions antérieures. Elle est ignorée à partir de Windows Vista.
SEE_MASK_HOTKEY (0x00000020) Utilisez le raccourci clavier fourni par le membre dwHotKey .
SEE_MASK_NOCLOSEPROCESS (0x00000040) Utilisez pour indiquer que le membre hProcess reçoit le handle de processus. Ce handle est généralement utilisé pour permettre à une application de savoir quand un processus créé avec ShellExecuteEx se termine. Dans certains cas, par exemple lorsque l’exécution est satisfaite par le biais d’une conversation DDE, aucun handle n’est retourné. L’application appelante est responsable de la fermeture du handle quand il n’est plus nécessaire.
SEE_MASK_CONNECTNETDRV (0x00000080) Validez le partage et connectez-vous à une lettre de lecteur. Cela permet la reconnexion des lecteurs réseau déconnectés. Le membre lpFile est un chemin d’accès UNC d’un fichier sur un réseau.
SEE_MASK_NOASYNC (0x00000100) Attendez que l’opération d’exécution se termine avant de retourner. Cet indicateur doit être utilisé par les appelants qui utilisent des formulaires ShellExecute qui peuvent entraîner une activation asynchrone, par exemple DDE, et créer un processus qui peut être exécuté sur un thread d’arrière-plan. (Remarque : ShellExecuteEx s’exécute sur un thread d’arrière-plan par défaut si le modèle de thread de l’appelant n’est pas Apartment.) Les appels à ShellExecuteEx à partir de processus en cours d’exécution sur des threads d’arrière-plan doivent toujours passer cet indicateur. En outre, les applications qui se terminent immédiatement après l’appel de ShellExecuteEx doivent spécifier cet indicateur.

Si l’opération d’exécution est effectuée sur un thread d’arrière-plan et que l’appelant n’a pas spécifié l’indicateur SEE_MASK_ASYNCOK, le thread appelant attend que le nouveau processus ait démarré avant de revenir. Cela signifie généralement que CreateProcess a été appelé, que la communication DDE est terminée ou que le délégué d’exécution personnalisé a averti ShellExecuteEx que c’est terminé. Si l’indicateur SEE_MASK_WAITFORINPUTIDLE est spécifié, ShellExecuteEx appelle WaitForInputIdle et attend que le nouveau processus soit inactif avant de revenir, avec un délai d’expiration maximal de 1 minute.

Pour plus d’informations sur les cas où cet indicateur est nécessaire, consultez la section Remarques.
SEE_MASK_FLAG_DDEWAIT (0x00000100) De la même façon que SEE_MASK_NOASYNC, l’utilisation de cette option est préférable.
SEE_MASK_DOENVSUBST (0x00000200) Développez les variables d’environnement spécifiées dans la chaîne donnée par le membre lpDirectory ou lpFile .
SEE_MASK_FLAG_NO_UI (0x00000400) N’affichez aucune interface utilisateur, y compris les boîtes de dialogue d’erreur, les avertissements de sécurité ou toute autre interface utilisateur qui serait normalement présentée sans cette option.
SEE_MASK_UNICODE (0x00004000) Utilisez cet indicateur pour indiquer une application Unicode.
SEE_MASK_NO_CONSOLE (0x00008000) Utilisez pour hériter de la console du parent pour le nouveau processus au lieu de lui faire créer une console. C’est le contraire de l’utilisation d’un indicateur CREATE_NEW_CONSOLE avec CreateProcess.
SEE_MASK_ASYNCOK (0x00100000) L’exécution peut être effectuée sur un thread d’arrière-plan et l’appel doit être retourné immédiatement sans attendre la fin du thread d’arrière-plan. Notez que dans certains cas , ShellExecuteEx ignore cet indicateur et attend que le processus se termine avant de revenir.
SEE_MASK_NOQUERYCLASSSTORE (0x01000000) Non utilisé.
SEE_MASK_HMONITOR (0x00200000) Utilisez cet indicateur lors de la spécification d’un moniteur sur des systèmes multi-moniteurs. Le moniteur est spécifié dans le membre hMonitor . Cet indicateur ne peut pas être combiné avec SEE_MASK_ICON.
SEE_MASK_NOZONECHECKS (0x00800000) N’effectuez pas de case activée de zone. Cet indicateur permet à ShellExecuteEx de contourner la vérification de zone mise en place par IAttachmentExecute.
SEE_MASK_WAITFORINPUTIDLE (0x02000000) Une fois le nouveau processus créé, attendez que le processus devienne inactif avant de revenir, avec un délai d’expiration d’une minute. Pour plus d’informations, consultez WaitForInputIdle .
SEE_MASK_FLAG_LOG_USAGE (0x04000000) Indique un lancement lancé par l’utilisateur qui permet le suivi des programmes fréquemment utilisés et d’autres comportements.
SEE_MASK_FLAG_HINST_IS_SITE (0x08000000) Le membre hInstApp est utilisé pour spécifier l’IUnknown d’un objet qui implémente IServiceProvider. Cet objet sera utilisé comme pointeur de site. Le pointeur de site est utilisé pour fournir des services à la fonction ShellExecute , au processus de liaison de gestionnaire et aux gestionnaires de verbes appelés.

ICreatingProcess peut être fourni pour permettre à l’appelant de modifier certains paramètres du processus en cours de création.

Cet indicateur est pris en charge dans Windows 8 et versions ultérieures.

Lorsque cette option est spécifiée, l’appel s’exécute de manière synchrone sur le thread appelant.

hwnd

Type : HWND

facultatif. Handle de la fenêtre propriétaire, utilisé pour afficher et positionner toute interface utilisateur que le système peut produire lors de l’exécution de cette fonction.

lpVerb

Type : LPCTSTR

Chaîne, appelée verbe, qui spécifie l’action à effectuer. L’ensemble des verbes disponibles dépend du fichier ou dossier particulier. En règle générale, les actions disponibles dans le menu contextuel d’un objet sont des verbes disponibles. Ce paramètre peut être NULL, auquel cas le verbe par défaut est utilisé s’il est disponible. Si ce n’est pas le cas, le verbe « ouvert » est utilisé. Si aucun verbe n’est disponible, le système utilise le premier verbe répertorié dans le Registre. Sauf s’il existe une raison de limiter l’action à un verbe spécifique, passez NULL pour utiliser la valeur par défaut calculée. Cela est nécessaire dans certains cas, par exemple lorsque vous spécifiez SEE_MASK_FLAG_NO_UI et que l’intention est de produire l’interface utilisateur « Ouvrir avec », si aucune application n’est installée.

Les verbes suivants sont couramment utilisés :

  • edit : lance un éditeur et ouvre le document pour modification. Si lpFile n’est pas un fichier de document, la fonction échoue.
  • explore : explore le dossier spécifié par lpFile.
  • find : lance une recherche à partir du répertoire spécifié.
  • open : ouvre le fichier spécifié par le paramètre lpFile . Le fichier peut être un fichier exécutable, un fichier de document ou un dossier.
  • print : imprime le fichier de document spécifié par lpFile. Si lpFile n’est pas un fichier de document, la fonction échoue.
  • properties : affiche les propriétés du fichier ou du dossier.
  • runas : lance une application en tant qu’administrateur. Le contrôle de compte d’utilisateur (UAC) invite l’utilisateur à donner son consentement pour exécuter l’application avec élévation de privilèges ou entre les informations d’identification d’un compte d’administrateur utilisé pour exécuter l’application.

lpFile

Type : LPCTSTR

Adresse d’une chaîne terminée par null qui spécifie le nom du fichier ou de l’objet sur lequel ShellExecuteEx effectuera l’action spécifiée par le paramètre lpVerb . Les verbes de registre système pris en charge par la fonction ShellExecuteEx incluent « open » pour les fichiers exécutables et les fichiers de document et « print » pour les fichiers document pour lesquels un gestionnaire d’impression a été inscrit. D’autres applications peuvent avoir ajouté des verbes Shell via le registre système, tels que « lire » pour les fichiers .avi et .wav. Pour spécifier un objet d’espace de noms Shell, passez le nom d’analyse complet et définissez l’indicateur SEE_MASK_INVOKEIDLIST dans le paramètre fMask .

Note: Si l’indicateur SEE_MASK_INVOKEIDLIST est défini, vous pouvez utiliser lpFile ou lpIDList pour identifier l’élément par son chemin de système de fichiers ou son PIDL respectivement. L’une des deux valeurs (lpFile ou lpIDList) doit être définie.
Note: Si le chemin d’accès n’est pas inclus avec le nom, le répertoire actif est supposé.

lpParameters

Type : LPCTSTR

facultatif. Adresse d’une chaîne terminée par null qui contient les paramètres de l’application. Les paramètres doivent être séparés par des espaces. Si le membre lpFile spécifie un fichier de document, lpParameters doit avoir la valeur NULL.

lpDirectory

Type : LPCTSTR

facultatif. Adresse d’une chaîne terminée par null qui spécifie le nom du répertoire de travail. Si ce membre a la valeur NULL, le répertoire actif est utilisé comme répertoire de travail.

nShow

Type : int

Obligatoire. Indicateurs qui spécifient la façon dont une application doit être affichée lors de son ouverture ; l’une des valeurs SW_ répertoriées pour la fonction ShellExecute . Si lpFile spécifie un fichier de document, l’indicateur est simplement passé à l’application associée. C’est à l’application de décider comment la gérer.

hInstApp

Type : HINSTANCE

[out] Si SEE_MASK_NOCLOSEPROCESS est défini et que l’appel ShellExecuteEx réussit, il définit ce membre à une valeur supérieure à 32. Si la fonction échoue, elle est définie sur une valeur d’erreur SE_ERR_XXX qui indique la cause de l’échec. Bien que hInstApp soit déclaré en tant que HINSTANCE pour la compatibilité avec les applications Windows 16 bits, il ne s’agit pas d’une véritable HINSTANCE. Il peut être casté uniquement en int et comparé à 32 ou aux codes d’erreur SE_ERR_XXX suivants.


Code d'erreur Motif
SE_ERR_FNF (2) Fichier introuvable.
SE_ERR_PNF (3) Chemin introuvable.
SE_ERR_ACCESSDENIED (5) Accès refusé.
SE_ERR_OOM (8) Mémoire insuffisante.
SE_ERR_DLLNOTFOUND (32) Bibliothèque de liens dynamiques introuvable.
SE_ERR_SHARE (26) Impossible de partager un fichier ouvert.
SE_ERR_ASSOCINCOMPLETE (27) Informations d’association de fichiers non terminées.
SE_ERR_DDETIMEOUT (28) L’opération DDE a expiré.
SE_ERR_DDEFAIL (29) Échec de l’opération DDE.
SE_ERR_DDEBUSY (30) L’opération DDE est occupée.
SE_ERR_NOASSOC (31) Association de fichiers non disponible.

lpIDList

Type : LPVOID

Adresse d’une structure ITEMIDLIST absolue (PCIDLIST_ABSOLUTE) pour contenir une liste d’identificateurs d’élément qui identifie de manière unique le fichier à exécuter. Ce membre est ignoré si le membre fMask n’inclut ni SEE_MASK_IDLIST ni SEE_MASK_INVOKEIDLIST.

lpClass

Type : LPCTSTR

Adresse d’une chaîne terminée par null qui spécifie l’un des éléments suivants :

  • Un ProgId. Par exemple, « Paint.Picture ».
  • Schéma de protocole URI. Par exemple, « http ».
  • Extension de fichier. Par exemple, « .txt ».
  • Chemin d’accès au Registre sous HKEY_CLASSES_ROOT qui nomme une sous-clé qui contient un ou plusieurs verbes Shell. Cette clé aura une sous-clé qui est conforme au schéma de registre de verbes Shell, comme lenom du verbede l’interpréteur de commandes\.

Ce membre est ignoré si fMask n’inclut pas SEE_MASK_CLASSNAME.

hkeyClass

Type : HKEY

Handle de la clé de Registre pour le type de fichier. Les droits d’accès pour cette clé de Registre doivent être définis sur KEY_READ. Ce membre est ignoré si fMask n’inclut pas SEE_MASK_CLASSKEY.

dwHotKey

Type : DWORD

Raccourci clavier à associer à l’application. Le mot de bas ordre est le code de clé virtuelle, et le mot d’ordre élevé est un indicateur de modificateur (HOTKEYF_). Pour obtenir la liste des indicateurs de modification, consultez la description du message WM_SETHOTKEY . Ce membre est ignoré si fMask n’inclut pas SEE_MASK_HOTKEY.

DUMMYUNIONNAME

DUMMYUNIONNAME.hIcon

Type : HANDLE

Handle de l’icône pour le type de fichier. Ce membre est ignoré si fMask n’inclut pas SEE_MASK_ICON. Cette valeur est utilisée uniquement dans Windows XP et les versions antérieures. Il est ignoré à partir de Windows Vista.

DUMMYUNIONNAME.hMonitor

Type : HANDLE

Handle du moniteur sur lequel le document doit être affiché. Ce membre est ignoré si fMask n’inclut pas SEE_MASK_HMONITOR.

hProcess

Type : HANDLE

Handle de l’application nouvellement démarrée. Ce membre est défini au retour et a toujours la valeur NULL , sauf si fMask est défini sur SEE_MASK_NOCLOSEPROCESS. Même si fMask est défini sur SEE_MASK_NOCLOSEPROCESS, hProcess aura la valeur NULL si aucun processus n’a été lancé. Par exemple, si un document à lancer est une URL et qu’un instance de Explorer Internet est déjà en cours d’exécution, le document s’affiche. Aucun nouveau processus n’est lancé et hProcess aura la valeur NULL.

Remarque :ShellExecuteEx ne retourne pas toujours un hProcess, même si un processus est lancé à la suite de l’appel. Par exemple, un hProcess ne retourne pas lorsque vous utilisez SEE_MASK_INVOKEIDLIST pour appeler IContextMenu.

Remarques

L’indicateur SEE_MASK_NOASYNC doit être spécifié si le thread appelant ShellExecuteEx n’a pas de boucle de message ou si le thread ou le processus se termine peu après le retour de ShellExecuteEx. Dans ces conditions, le thread appelant n’étant pas disponible pour terminer la conversation DDE, il est important que ShellExecuteEx termine la conversation avant de retourner le contrôle à l’application appelante. L’échec de la conversation peut entraîner l’échec du lancement du document.

Si le thread appelant a une boucle de message et existera pendant un certain temps après le retour de l’appel à ShellExecuteEx , l’indicateur SEE_MASK_NOASYNC est facultatif. Si l’indicateur est omis, la pompe de message du thread appelant est utilisée pour terminer la conversation DDE. L’application appelante reprend le contrôle plus tôt, car la conversation DDE peut être terminée en arrière-plan.

Pour inclure des guillemets doubles dans lpParameters, placez chaque marque dans une paire de guillemets, comme dans l’exemple suivant.

sei.lpParameters = "An example: \"\"\"quoted text\"\"\"";

Dans ce cas, l’application reçoit trois paramètres : un, exemple :, et « texte entre guillemets ».

Notes

L’en-tête shellapi.h définit SHELLEXECUTEINFO 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]
En-tête shellapi.h