STRUCTURE SHELLEXECUTEINFOA (shellapi.h)
Contient des 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 |
| SEE_MASK_CLASSKEY (0x00000003) | Utilisez la clé de classe donnée par le membre hkeyClass. Si les SEE_MASK_CLASSKEY et les 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 |
| SEE_MASK_INVOKEIDLIST (0x0000000C) | Utilisez l’interface IContextMenu du gestionnaire de menus contextuels de l’élément sélectionné. Utilisez lpFile pour identifier l’élément par son chemin d’accès au système de fichiers ou lpIDList pour identifier l’élément par son code 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.
Remarque : SEE_MASK_INVOKEIDLIST remplacements et implique des 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.
Remarque : 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 donné par le membre |
| SEE_MASK_NOCLOSEPROCESS (0x00000040) | Permet d’indiquer que le membre |
| 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 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 Appartement.) Les appels à ShellExecuteEx des processus déjà en cours d’exécution sur des threads d’arrière-plan doivent toujours passer cet indicateur. En outre, les applications qui quittent immédiatement après avoir appelé 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 retourner. 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 qu’il est effectué. Si l’indicateur SEE_MASK_WAITFORINPUTIDLE est spécifié, ShellExecuteEx appelle WaitForInputIdle et attend que le nouveau processus soit inactif avant de retourner, avec un délai maximal de 1 minute. Pour plus d’informations sur le moment où cet indicateur est nécessaire, consultez la section Remarques. |
| SEE_MASK_FLAG_DDEWAIT (0x00000100) | Identique à SEE_MASK_NOASYNC, l’utilisation de cette option est préférée. |
| 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 membre. |
| SEE_MASK_FLAG_NO_UI (0x00000400) | N’affichez pas les boîtes de dialogue d’erreur de l’interface utilisateur qui seraient normalement présentées sans cette option. Les invites de sécurité sont exemptées et sont toujours affichées. |
| SEE_MASK_UNICODE (0x00004000) | Utilisez cet indicateur pour indiquer une application Unicode. |
| SEE_MASK_NO_CONSOLE (0x00008000) | Permet d’hériter de la console du parent pour le nouveau processus au lieu de le faire créer. Il est opposé à l’utilisation d’un indicateur de 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 que le thread d’arrière-plan se termine. Notez que, dans certains cas, ShellExecuteEx ignore cet indicateur et attend la fin du processus avant de retourner. |
| 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 à plusieurs moniteurs. Le moniteur est spécifié dans le membre |
| SEE_MASK_NOZONECHECKS (0x00800000) | N’effectuez pas de vérification 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 retourner, 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 le 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 pouvez ê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 façon synchrone sur le thread appelant. |
hwnd
Type : HWND
Optionnel. Handle vers 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 de verbes disponibles dépend du fichier ou du dossier particulier. En règle générale, les actions disponibles à partir du menu contextuel d’un objet sont des verbes disponibles. Ce paramètre peut être NULL, auquel cas le verbe par défaut est utilisé si 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 :
- modifier: lance un éditeur et ouvre le document pour modification. Si lpFile n’est pas un fichier de document, la fonction échoue.
- explorer: explore le dossier spécifié par lpFile.
- rechercher: lance une recherche à partir du répertoire spécifié.
ouvrir : 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. - openas: lance une interface utilisateur du sélecteur permettant à l’utilisateur de sélectionner une application avec laquelle ouvrir le fichier spécifié par le paramètre lpFile.
- d’impression : imprime le fichier de document spécifié par lpFile. Si lpFile n’est pas un fichier de document, la fonction échoue.
- propriétés: 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 entrer 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 du 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 de 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 .avi et .wav fichiers. Pour spécifier un objet d’espace de noms Shell, passez le nom d’analyse complet et définissez l’indicateur de
lpParameters
Type : LPCTSTR
Optionnel. 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
lpDirectory
Type : LPCTSTR
Optionnel. Adresse d’une chaîne terminée par null qui spécifie le nom du répertoire de travail. Si ce membre est 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 ; une des valeurs SW_ répertoriées pour la fonction ShellExecute
hInstApp
Type : HINSTANCE
[out] Si SEE_MASK_NOCLOSEPROCESS est définie et que l’appel ShellExecuteEx réussit, il définit ce membre sur 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é comme un HINSTANCE pour la compatibilité avec les applications Windows 16 bits, il n’est pas un vrai HINSTANCE. Il ne peut être casté qu’en int et comparé à 32 ou aux codes d’erreur SE_ERR_XXX suivants.
| Code d’erreur | Raison |
|---|---|
| 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) | Les informations d’association de fichiers ne sont pas 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
lpClass
Type : LPCTSTR
Adresse d’une chaîne terminée par null qui spécifie l’une des options suivantes :
- A 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é a une sous-clé qui est conforme au schéma de Registre de verbes Shell, par exemple shell\nom de verbe.
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 à 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 vers l’icône du 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 versions antérieures. Elle est ignorée à 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 sur retour et est toujours NULL, sauf si fMask est défini sur SEE_MASK_NOCLOSEPROCESS. Même si fMask est défini sur SEE_MASK_NOCLOSEPROCESS, hProcess sera NULL si aucun processus n’a été lancé. Par exemple, si un document à lancer est une URL et qu’une instance d’Internet Explorer est déjà en cours d’exécution, elle affiche le document. Aucun nouveau processus n’est lancé et hProcess sera NULL.
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 ShellExecuteEx retourné. Dans de telles conditions, le thread appelant ne sera pas disponible pour terminer la conversation DDE. Il est donc important que ShellExecuteEx terminer la conversation avant de retourner le contrôle à l’application appelante. L’échec de la fin de la conversation peut entraîner un lancement infructueuse du document.
Si le thread appelant a une boucle de message et existe pendant un certain temps après l’appel à ShellExecuteEx retourne, l’indicateur SEE_MASK_NOASYNC est facultatif. Si l’indicateur est omis, la pompe de messages du thread appelant est utilisée pour terminer la conversation DDE. L’application appelante récupère 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 entre 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 ».
Note
L’en-tête shellapi.h définit SHELLEXECUTEINFO 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 |