ShellExecuteA-Funktion (shellapi.h)

Artikel
11/20/2024

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 fehlermeldung verwendet wird. Dieser Wert kann NULL- werden, wenn der Vorgang keinem Fenster zugeordnet ist.

[in, optional] lpOperation

Typ: LPCTSTR-

Ein Zeiger auf eine null-terminated string, die in diesem Fall als Verbbezeichnet wird, das die auszuführende Aktion angibt. Die Gruppe der verfügbaren Verben hängt von der jeweiligen Datei oder dem jeweiligen Ordner ab. Im Allgemeinen sind die im Kontextmenü eines Objekts verfügbaren Aktionen verfügbar. Die folgenden Verben werden häufig verwendet:

redigieren

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

erforschen

Untersucht einen ordner, der durch lpFile-angegeben wird.

finden

Initiiert eine Suche, die mit dem durch lpDirectoryangegebenen Verzeichnis beginnt.

offen

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

drucken

Druckt die durch lpFileangegebene Datei. 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 auf, der Anwendung mit erhöhten Rechten zuzustimmen oder die Anmeldeinformationen eines Administratorkontos einzugeben, mit dem die Anwendung ausgeführt wird.

NULL

Das Standardverb wird verwendet, falls verfügbar. Andernfalls wird das Verb "open" 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--terminated string, 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 "print". Wenn ein relativer Pfad für den parameter lpDirectory 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--terminated-Zeichenfolge, die die Parameter an die Anwendung angibt. Das Format dieser Zeichenfolge wird durch das Verb bestimmt, das aufgerufen werden soll. Wenn lpFile- eine Dokumentdatei angibt, sollte lpParameters-NULL-sein.

[in, optional] lpDirectory

Typ: LPCTSTR-

Ein Zeiger auf eine NULL--terminated-Zeichenfolge, die das Standardverzeichnis (Arbeitsverzeichnis) für die Aktion angibt. Wenn dieser Wert NULL-ist, wird das aktuelle Arbeitsverzeichnis verwendet. Wenn bei lpFileein relativer Pfad bereitgestellt wird, verwenden Sie keinen relativen Pfad für lpDirectory.

[in] nShowCmd

Typ: INT-

Die Flags, die angeben, wie eine Anwendung angezeigt werden soll, wenn sie geöffnet wird. Wenn lpFile- eine Dokumentdatei angibt, wird das Flag einfach an die zugeordnete Anwendung übergeben. Es liegt an der Anwendung, zu entscheiden, wie sie behandelt werden soll. Dabei kann es sich um einen beliebigen Wert handeln, der im nCmdShow Parameter für die ShowWindow--Funktion angegeben werden kann.

Rückgabewert

Typ: HINSTANCE-

Wenn die Funktion erfolgreich ist, wird ein Wert zurückgegeben, der größer als 32 ist. Wenn die Funktion fehlschlägt, wird ein Fehlerwert zurückgegeben, der die Ursache des Fehlers angibt. Der Rückgabewert wird als HINSTANCE für die Abwärtskompatibilität mit 16-Bit-Windows-Anwendungen umgedreht. Es ist jedoch keine wahre HINSTANCE. Sie kann nur in eine INT_PTR und im Vergleich zu entweder 32 oder den folgenden Fehlercodes unten in einen INT_PTR umwandeln.

Rückgabecode	Beschreibung
0	Das Betriebssystem ist nicht genügend 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 hat den Zugriff auf die angegebene Datei verweigert.
SE_ERR_ASSOCINCOMPLETE	Die Zuordnung des Dateinamens 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 die Anforderung ein Timeout hat.
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 Nicht druckbare Datei zu drucken.
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 ein Freigabeverstoß aufgetreten.

Rufen Sie GetLastError- für erweiterte Fehlerinformationen auf.

Bemerkungen

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

CoInitializeEx(NULL, COINIT_APARTMENTTHREADED | COINIT_DISABLE_OLE1DDE)

Es gibt sicherlich Fälle, in denen ShellExecute keinen dieser Arten von Shell-Erweiterung verwendet, und diese Instanzen würden überhaupt keine COM initialisiert werden müssen. Dennoch empfiehlt es sich, vor der Verwendung dieser Funktion immer COM zu initialisieren.

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

Verwenden Sie zum Öffnen eines Ordners eine der folgenden Aufrufe:

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

Verwenden Sie ShellExecuteEx-, um Informationen über die Anwendung zu erhalten, die durch aufrufen ShellExecutegestartet wird.

Hinweis Die Ordnerfenster starten in einem separaten Prozess Einstellung in Ordneroptionen wirken sich auf ShellExecuteaus. Wenn diese Option deaktiviert ist (standardeinstellung), verwendet ShellExecute ein geöffnetes Explorer-Fenster anstelle eines neuen Fensters zu starten. Wenn kein Explorer-Fenster geöffnet ist, startet ShellExecute ein neues Fenster.

Anmerkung

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
mindestens unterstützte Client-	Windows XP [nur Desktop-Apps]
mindestens unterstützte Server-	Windows 2000 Server [nur Desktop-Apps]
Zielplattform-	Fenster
Header-	shellapi.h
Library	Shell32.lib
DLL-	Shell32.dll (Version 3.51 oder höher)