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.
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 |
|---|---|
|
Das Betriebssystem verfügt nicht über Arbeitsspeicher oder Ressourcen. |
|
Die angegebene Datei wurde nicht gefunden. |
|
Der angegebene Pfad wurde nicht gefunden. |
|
Die .exe-Datei ist ungültig (nicht win32-.exe oder Fehler in .exe Bild). |
|
Das Betriebssystem verweigerte den Zugriff auf die angegebene Datei. |
|
Die Dateinamenzuordnung ist unvollständig oder ungültig. |
|
Die DDE-Transaktion konnte nicht abgeschlossen werden, da andere DDE-Transaktionen verarbeitet wurden. |
|
Fehler bei der DDE-Transaktion. |
|
Die DDE-Transaktion konnte nicht abgeschlossen werden, da für die Anforderung ein Timeout war. |
|
Die angegebene DLL wurde nicht gefunden. |
|
Die angegebene Datei wurde nicht gefunden. |
|
Der angegebenen Dateinamenerweiterung ist keine Anwendung zugeordnet. Dieser Fehler wird auch zurückgegeben, wenn Sie versuchen, eine Datei zu drucken, die nicht druckbar ist. |
|
Es war nicht genügend Arbeitsspeicher vorhanden, um den Vorgang abzuschließen. |
|
Der angegebene Pfad wurde nicht gefunden. |
|
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
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
Starten von Anwendungen (ShellExecute, ShellExecuteEx, SHELLEXECUTEINFO)