ShellExecuteA, fonction (shellapi.h)

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.

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);

ou

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.

Configuration requise

Voir aussi

CoInitializeEx

CreateProcessA

IShellExecuteHook

Lancement d’applications (ShellExecute, ShellExecuteEx, SHELLEXECUTEINFO)

ShellExecuteEx