ShellExecuteW-Funktion (shellapi.h)

Artikel
03/04/2024

Führt einen Vorgang für eine angegebene Datei aus.

Syntax

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

Parameter

[in, optional] hwnd

Typ: HWND

Ein Handle für das übergeordnete Fenster, das zum Anzeigen einer Benutzeroberfläche oder Fehlermeldungen verwendet wird. Dieser Wert kann NULL sein, wenn der Vorgang keinem Fenster zugeordnet ist.

[in, optional] lpOperation

Typ: LPCTSTR

Ein Zeiger auf eine NULL-Zeichenfolge, die in diesem Fall als Verb bezeichnet wird, der die auszuführende Aktion angibt. Der Satz verfügbarer Verben hängt von der jeweiligen Datei oder dem jeweiligen Ordner ab. Im Allgemeinen sind die im Kontextmenü eines Objekts verfügbaren Aktionen verfügbare Verben. Die folgenden Verben werden häufig verwendet:

Bearbeiten

Startet einen Editor und öffnet das Dokument zur Bearbeitung. Wenn lpFile keine Dokumentdatei ist, schlägt die Funktion fehl.

explore

Untersucht einen ordner, der von lpFile angegeben wurde.

Suchen

Initiiert eine Suche, die in dem von lpDirectory angegebenen Verzeichnis beginnt.

open

Öffnet das durch den lpFile-Parameter angegebene Element. Das Element kann eine Datei oder ein Ordner sein.

print

Gibt die von lpFile angegebene Datei aus. Wenn lpFile keine Dokumentdatei ist, schlägt die Funktion fehl.

RunAs

Startet eine Anwendung als Administrator. Die Benutzerkontensteuerung (User Account Control, UAC) fordert den Benutzer zur Zustimmung auf, die Anwendung mit erhöhten Rechten auszuführen oder die Anmeldeinformationen eines Administratorkontos einzugeben, das zum Ausführen der Anwendung verwendet wird.

NULL

Das Standardverb wird verwendet, sofern verfügbar. Andernfalls wird das Verb "offen" verwendet. Wenn kein Verb verfügbar ist, verwendet das System das erste Verb, das in der Registrierung aufgeführt ist.

[in] lpFile

Typ: LPCTSTR

Ein Zeiger auf eine NULL-Zeichenfolge, die die Datei oder das Objekt angibt, für die das angegebene Verb ausgeführt werden soll. Um ein Shell-Namespaceobjekt anzugeben, übergeben Sie den vollqualifizierten Analysenamen. Beachten Sie, dass nicht alle Verben für alle Objekte unterstützt werden. Beispielsweise unterstützen nicht alle Dokumenttypen das Verb "drucken". Wenn ein relativer Pfad für den lpDirectory-Parameter verwendet wird, verwenden Sie keinen relativen Pfad für lpFile.

[in, optional] lpParameters

Typ: LPCTSTR

Wenn lpFile eine ausführbare Datei angibt, ist dieser Parameter ein Zeiger auf eine null-beendete Zeichenfolge, die die Parameter angibt, die an die Anwendung übergeben werden sollen. Das Format dieser Zeichenfolge wird durch das Verb bestimmt, das aufgerufen werden soll. Wenn lpFile eine Dokumentdatei angibt, sollte lpParametersNULL sein.

[in, optional] lpDirectory

Typ: LPCTSTR

Ein Zeiger auf eine null-beendete Zeichenfolge, die das Standardverzeichnis (Arbeits-)Verzeichnis für die Aktion angibt. Wenn dieser Wert NULL ist, wird das aktuelle Arbeitsverzeichnis verwendet. Wenn bei lpFile ein relativer Pfad angegeben wird, verwenden Sie keinen relativen Pfad für lpDirectory.

[in] nShowCmd

Typ: INT

Die Flags, die angeben, wie eine Anwendung beim Öffnen angezeigt werden soll. Wenn lpFile eine Dokumentdatei angibt, wird das Flag einfach an die zugehörige Anwendung übergeben. Die Anwendung entscheidet, wie sie behandelt werden soll. Dies kann jeder der Werte sein, die im Parameter nCmdShow für die Funktion ShowWindow angegeben werden können.

Rückgabewert

Typ: HINSTANCE

Wenn die Funktion erfolgreich ist, gibt sie einen Wert größer als 32 zurück. Wenn die Funktion fehlschlägt, gibt sie einen Fehlerwert zurück, der die Ursache des Fehlers angibt. Der Rückgabewert wird für die Abwärtskompatibilität mit 16-Bit-Windows-Anwendungen als HINSTANCE umgewandelt. Es ist jedoch kein wahrer HINWEIS. Sie kann nur in eine INT_PTR umgewandelt und mit 32 oder den folgenden Fehlercodes verglichen werden.

Rückgabecode	Beschreibung
0	Das Betriebssystem verfügt nicht über Arbeitsspeicher oder Ressourcen.
ERROR_FILE_NOT_FOUND	Die angegebene Datei wurde nicht gefunden.
ERROR_PATH_NOT_FOUND	Der angegebene Pfad wurde nicht gefunden.
ERROR_BAD_FORMAT	Die .exe-Datei ist ungültig (nicht win32-.exe oder Fehler in .exe Bild).
SE_ERR_ACCESSDENIED	Das Betriebssystem verweigerte den Zugriff auf die angegebene Datei.
SE_ERR_ASSOCINCOMPLETE	Die Dateinamenzuordnung ist unvollständig oder ungültig.
SE_ERR_DDEBUSY	Die DDE-Transaktion konnte nicht abgeschlossen werden, da andere DDE-Transaktionen verarbeitet wurden.
SE_ERR_DDEFAIL	Fehler bei der DDE-Transaktion.
SE_ERR_DDETIMEOUT	Die DDE-Transaktion konnte nicht abgeschlossen werden, da für die Anforderung ein Timeout war.
SE_ERR_DLLNOTFOUND	Die angegebene DLL wurde nicht gefunden.
SE_ERR_FNF	Die angegebene Datei wurde nicht gefunden.
SE_ERR_NOASSOC	Der angegebenen Dateinamenerweiterung ist keine Anwendung zugeordnet. Dieser Fehler wird auch zurückgegeben, wenn Sie versuchen, eine Datei zu drucken, die nicht druckbar ist.
SE_ERR_OOM	Es war nicht genügend Arbeitsspeicher vorhanden, um den Vorgang abzuschließen.
SE_ERR_PNF	Der angegebene Pfad wurde nicht gefunden.
SE_ERR_SHARE	Es ist eine Freigabeverletzung aufgetreten.

Rufen Sie GetLastError für erweiterte Fehlerinformationen auf.

Hinweise

Da ShellExecute die Ausführung an Shellerweiterungen (Datenquellen, Kontextmenühandler, Verbimplementierungen) delegieren kann, die mithilfe von COM (Component Object Model) aktiviert werden, sollte COM initialisiert werden, bevor ShellExecute aufgerufen wird. Für einige Shell-Erweiterungen ist der COM-Typ "Single-Threaded Apartment" (STA) erforderlich. In diesem Fall sollte COM wie hier gezeigt initialisiert werden:

CoInitializeEx(NULL, COINIT_APARTMENTTHREADED | COINIT_DISABLE_OLE1DDE)

Es gibt sicherlich Instanzen, in denen ShellExecute keinen dieser Shellerweiterungstypen verwendet, und für diese Instanzen muss COM überhaupt nicht initialisiert werden. Dennoch empfiehlt es sich, com immer zu initialisieren, bevor Sie diese Funktion verwenden.

Mit dieser Methode können Sie alle Befehle im Kontextmenü eines Ordners oder in der Registrierung ausführen.

Verwenden Sie einen der folgenden Aufrufe, um einen Ordner zu öffnen:

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

oder

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

Verwenden Sie den folgenden Aufruf, um einen Ordner zu erkunden:

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

Verwenden Sie den folgenden Aufruf, um das Find-Hilfsprogramm der Shell für ein Verzeichnis zu starten.

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

Wenn lpOperationNULL ist, öffnet die Funktion die von lpFile angegebene Datei. Wenn lpOperation "open" oder "explore" ist, versucht die Funktion, den Ordner zu öffnen oder zu durchsuchen.

Verwenden Sie ShellExecuteEx, um Informationen zu der Anwendung abzurufen, die durch den Aufruf von ShellExecute gestartet wird.

Hinweis Die Einstellung Ordner starten in einer separaten Prozesseinstellung in Ordneroptionen wirkt sich auf ShellExecute aus. Wenn diese Option deaktiviert ist (die Standardeinstellung), verwendet ShellExecute ein geöffnetes Explorer Fenster, anstatt ein neues zu starten. Wenn kein Explorer Fenster geöffnet ist, startet ShellExecute ein neues Fenster.

Hinweis

Der shellapi.h-Header definiert ShellExecute als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit nicht codierungsneutralem Code kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	shellapi.h
Bibliothek	Shell32.lib
DLL	Shell32.dll (Version 3.51 oder höher)