Freigeben über


ShellExecuteA-Funktion (shellapi.h)

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

Syntax

HINSTANCE ShellExecuteA(
  [in, optional] HWND   hwnd,
  [in, optional] LPCSTR lpOperation,
  [in]           LPCSTR lpFile,
  [in, optional] LPCSTR lpParameters,
  [in, optional] LPCSTR 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 Arten von Shellerweiterungen verwendet und für diese Instanzen überhaupt keine COM-Initialisierung erforderlich wäre. 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 ausführen oder in der Registrierung gespeichert sein.

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 durchsuchen:

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 durch lpFile angegebene Datei. Wenn lpOperation auf "open" oder "explore" festgelegt ist, versucht die Funktion, den Ordner zu öffnen oder zu durchsuchen.

Verwenden Sie ShellExecuteEx, um Informationen zu der Anwendung abzurufen, die als Ergebnis des Aufrufs von ShellExecute gestartet wird.

Hinweis Die Einstellung Ordnerfenster in einem separaten Prozess starten unter 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 die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, 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)

Weitere Informationen

CoInitializeEx

CreateProcessA

IShellExecuteHook

Starten von Anwendungen (ShellExecute, ShellExecuteEx, SHELLEXECUTEINFO)

ShellExecuteEx