ShellExecuteW, fonction (shellapi.h)

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

Syntaxe

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

Paramètres

[in, optional] hwnd

Type : HWND

Handle vers 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ée dans ce cas , verbqui spécifie l’action à effectuer. L’ensemble de disponibilité verbs 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 disponibles verbs. Les éléments suivants verbs 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 un dossier spécifié par lpFile.

find

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

open

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 entrer les informations d’identification d’un compte d’administrateur utilisé pour exécuter l’application.

ZÉRO

La valeur par défaut verb est utilisée, le cas échéant. Si ce n’est pas le cas, le «open » verb est utilisé. Si aucun des deux verb n’est disponible, le système utilise le premier verb 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 fichier ou l’objet spécifié verb. Pour spécifier un objet d’espace de noms Shell, passez le nom d’analyse complet. Notez que tous verbs ne sont pas pris en charge sur tous les objets. Par exemple, tous les types de documents ne prennent pas en charge le «print ». verb Si un chemin relatif est utilisé pour le paramètre lpDirectory n’utilise pas de chemin relatif pour lpFile.

Si lpFile spécifie un fichier exécutable et «open » ou «runas » verbs sont utilisés dans lpOperation, la chaîne de ligne de commande du processus lancé inclut un caractère d’espace blanc de fin.

[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. La chaîne de ligne de commande d’un processus lancé avec «open » ou «runas » verbs dans lpOperation inclut un caractère d’espace blanc de fin et les paramètres sont ajoutés à cette chaîne de ligne de commande. Le format de cette chaîne est déterminé par celui verb à appeler. Si lpFile spécifie un fichier de document, lpParameters doit être 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 à 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 transmis à l’application associée. Il incombe à l’application de décider comment la gérer. Il peut s’agir de l’une des valeurs qui peuvent être spécifiées dans le paramètre nCmdShow pour 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 convertie en tant que HINSTANCE pour la compatibilité descendante avec les applications Windows 16 bits. Mais ce n’est pas un vrai HINSTANCE. Il ne peut être casté qu’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 aux extensions Shell (sources de données, gestionnaires de menus contextuels, verb implémentations) qui sont activées à l’aide du modèle objet de composant (COM), COM doit être initialisé avant l’appel de ShellExecute . Certaines extensions Shell nécessitent le type STA (Single-Threaded Apartment) COM. Dans ce cas, COM doit être initialisé comme indiqué ici :

CoInitializeEx(NULL, COINIT_APARTMENTTHREADED | COINIT_DISABLE_OLE1DDE)

Il existe certainement des instances où ShellExecute n’utilise pas l’un de ces types d’extension Shell et que ces instances ne nécessitent pas que COM soit initialisé du tout. Néanmoins, il est recommandé d’initialiser toujours 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 Shell 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.

Spécifications

Voir aussi

CoInitializeEx

CreateProcessW

IShellExecuteHook

Lancement d’applications (ShellExecute, ShellExecuteEx, SHELLEXECUTEINFO)

ShellExecuteEx