ShellExecuteA, fonction (shellapi.h)

Article
08/26/2023

Effectue une opération sur un fichier spécifié.

Syntaxe

HINSTANCE ShellExecuteA(
  [in, optional] HWND   hwnd,
  [in, optional] LPCSTR lpOperation,
  [in]           LPCSTR lpFile,
  [in, optional] LPCSTR lpParameters,
  [in, optional] LPCSTR lpDirectory,
  [in]           INT    nShowCmd
);

Paramètres

[in, optional] hwnd

Type : HWND

Handle de la fenêtre parente utilisée pour afficher une interface utilisateur ou des messages d’erreur. Cette valeur peut être NULL si l’opération n’est pas associée à une fenêtre.

[in, optional] lpOperation

Type : LPCTSTR

Pointeur vers une chaîne terminée par null, appelé dans ce cas un verbe, qui spécifie l’action à effectuer. L’ensemble de verbes disponibles dépend du fichier ou dossier particulier. En règle générale, les actions disponibles à partir du menu contextuel d’un objet sont des verbes disponibles. 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 un dossier spécifié par lpFile.

trouver

Lance une recherche commençant dans le répertoire spécifié par lpDirectory.

ouvrir

Ouvre l’élément spécifié par le paramètre lpFile . L’élément peut être un fichier ou un dossier.

print

Imprime le fichier spécifié par lpFile. Si lpFile n’est pas un fichier de document, la fonction échoue.

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.

NULL

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.

[in] lpFile

Type : LPCTSTR

Pointeur vers une chaîne terminée par null qui spécifie le fichier ou l’objet sur lequel exécuter le verbe spécifié. Pour spécifier un objet d’espace de noms Shell, passez le nom complet de l’analyse. Notez que tous les verbes ne sont pas pris en charge sur tous les objets. Par exemple, tous les types de documents ne prennent pas en charge le verbe « print ». Si un chemin relatif est utilisé pour le paramètre lpDirectory , n’utilisez pas de chemin relatif pour lpFile.

[in, optional] lpParameters

Type : LPCTSTR

Si lpFile spécifie un fichier exécutable, ce paramètre est un pointeur vers une chaîne terminée par null qui spécifie les paramètres à passer à l’application. Le format de cette chaîne est déterminé par le verbe à appeler. Si lpFile spécifie un fichier de document, lpParameters doit avoir la valeur NULL.

[in, optional] lpDirectory

Type : LPCTSTR

Pointeur vers une chaîne terminée par null qui spécifie le répertoire par défaut (de travail) de l’action. Si cette valeur est NULL, le répertoire de travail actuel est utilisé. Si un chemin relatif est fourni dans lpFile, n’utilisez pas de chemin relatif pour lpDirectory.

[in] nShowCmd

Type : INT

Indicateurs qui spécifient la façon dont une application doit être affichée lors de son ouverture. 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. Il peut s’agir de l’une des valeurs spécifiées dans le paramètre nCmdShow de la fonction ShowWindow.

Valeur retournée

Type : HINSTANCE

Si la fonction réussit, elle retourne une valeur supérieure à 32. Si la fonction échoue, elle retourne une valeur d’erreur qui indique la cause de l’échec. La valeur de retour est castée en tant que HINSTANCE pour la compatibilité descendante avec les applications Windows 16 bits. Ce n’est pas un vrai hinstance, cependant. Il peut être casté uniquement en INT_PTR et comparé à 32 ou aux codes d’erreur suivants ci-dessous.

Code de retour	Description
0	Le système d’exploitation n’a pas de mémoire ou de ressources.
ERROR_FILE_NOT_FOUND	Le fichier spécifié est introuvable.
ERROR_PATH_NOT_FOUND	Le chemin spécifié est introuvable.
ERROR_BAD_FORMAT	Le fichier .exe n’est pas valide (.exe non Win32 ou erreur dans .exe image).
SE_ERR_ACCESSDENIED	Le système d’exploitation a refusé l’accès au fichier spécifié.
SE_ERR_ASSOCINCOMPLETE	L’association de nom de fichier est incomplète ou non valide.
SE_ERR_DDEBUSY	La transaction DDE n’a pas pu être effectuée, car d’autres transactions DDE étaient en cours de traitement.
SE_ERR_DDEFAIL	Échec de la transaction DDE.
SE_ERR_DDETIMEOUT	La transaction DDE n’a pas pu être effectuée, car la demande a expiré.
SE_ERR_DLLNOTFOUND	La DLL spécifiée est introuvable.
SE_ERR_FNF	Le fichier spécifié est introuvable.
SE_ERR_NOASSOC	Aucune application n’est associée à l’extension de nom de fichier donnée. Cette erreur sera également retournée si vous tentez d’imprimer un fichier qui n’est pas imprimable.
SE_ERR_OOM	Il n’y avait pas assez de mémoire pour terminer l’opération.
SE_ERR_PNF	Le chemin spécifié est introuvable.
SE_ERR_SHARE	Une violation de partage s’est produite.

Appelez GetLastError pour obtenir des informations d’erreur étendues.

Remarques

Étant donné que ShellExecute peut déléguer l’exécution à des extensions Shell (sources de données, gestionnaires de menus contextuels, implémentations de verbes) activées à l’aide du modèle COM (Component Object Model), COM doit être initialisé avant l’appel de ShellExecute . Certaines extensions shell nécessitent le type d’appartement monothread (STA) COM. Dans ce cas, COM doit être initialisé comme indiqué ici :

CoInitializeEx(NULL, COINIT_APARTMENTTHREADED | COINIT_DISABLE_OLE1DDE)

Il existe certainement des cas où ShellExecute n’utilise pas l’un de ces types d’extension Shell et où ces instances ne nécessitent pas du tout l’initialisation de COM. Néanmoins, il est recommandé d’initialiser com avant d’utiliser cette fonction.

Cette méthode vous permet d’exécuter toutes les commandes dans le menu contextuel d’un dossier ou stockées dans le Registre.

Pour ouvrir un dossier, utilisez l’un des appels suivants :

ShellExecute(handle, NULL, <fully_qualified_path_to_folder>, NULL, NULL, SW_SHOWNORMAL);

ShellExecute(handle, "open", <fully_qualified_path_to_folder>, NULL, NULL, SW_SHOWNORMAL);

Pour explorer un dossier, utilisez l’appel suivant :

ShellExecute(handle, "explore", <fully_qualified_path_to_folder>, NULL, NULL, SW_SHOWNORMAL);

Pour lancer l’utilitaire Find de l’interpréteur de commandes pour un répertoire, utilisez l’appel suivant.

ShellExecute(handle, "find", <fully_qualified_path_to_folder>, NULL, NULL, 0);

Si lpOperation a la valeur NULL, la fonction ouvre le fichier spécifié par lpFile. Si lpOperation est « open » ou « explore », la fonction tente d’ouvrir ou d’explorer le dossier.

Pour obtenir des informations sur l’application lancée suite à l’appel de ShellExecute, utilisez ShellExecuteEx.

Note Le paramètre Lancer le dossier dans un autre paramètre de processus dans Options de dossier affecte ShellExecute. Si cette option est désactivée (paramètre par défaut), ShellExecute utilise une fenêtre Explorer ouverte au lieu d’en lancer une nouvelle. Si aucune fenêtre Explorer n’est ouverte, ShellExecute en lance une nouvelle.

Notes

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

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]
Plateforme cible	Windows
En-tête	shellapi.h
Bibliothèque	Shell32.lib
DLL	Shell32.dll (version 3.51 ou ultérieure)