Share via


SHELLEXECUTEINFOW-Struktur (shellapi.h)

Enthält informationen, die von ShellExecuteEx verwendet werden.

Syntax

typedef struct _SHELLEXECUTEINFOW {
  DWORD     cbSize;
  ULONG     fMask;
  HWND      hwnd;
  LPCWSTR   lpVerb;
  LPCWSTR   lpFile;
  LPCWSTR   lpParameters;
  LPCWSTR   lpDirectory;
  int       nShow;
  HINSTANCE hInstApp;
  void      *lpIDList;
  LPCWSTR   lpClass;
  HKEY      hkeyClass;
  DWORD     dwHotKey;
  union {
    HANDLE hIcon;
    HANDLE hMonitor;
  } DUMMYUNIONNAME;
  HANDLE    hProcess;
} SHELLEXECUTEINFOW, *LPSHELLEXECUTEINFOW;

Member

cbSize

Art: DWORD

Erforderlich. Die Größe dieser Struktur in Bytes.

fMask

Typ: ULONG

Eine Kombination aus mindestens einem der folgenden Werte, die den Inhalt und die Gültigkeit der anderen Strukturmember angeben:

SEE_MASK_DEFAULT (0x00000000) Verwenden Sie Standardwerte.
SEE_MASK_CLASSNAME (0x00000001) Verwenden Sie den Vom lpClass-Member angegebenen Klassennamen. Wenn sowohl SEE_MASK_CLASSKEY als auch SEE_MASK_CLASSNAME festgelegt sind, wird der Klassenschlüssel verwendet.
SEE_MASK_CLASSKEY (0x00000003) Verwenden Sie den Vom hkeyClass-Member angegebenen Klassenschlüssel. Wenn sowohl SEE_MASK_CLASSKEY als auch SEE_MASK_CLASSNAME festgelegt sind, wird der Klassenschlüssel verwendet.
SEE_MASK_IDLIST (0x00000004) Verwenden Sie die Elementbezeichnerliste, die vom lpIDList-Element angegeben wird. Das lpIDList-Element muss auf eine ITEMIDLIST-Struktur verweisen.
SEE_MASK_INVOKEIDLIST (0x0000000C) Verwenden Sie die IContextMenu-Schnittstelle des Kontextmenühandlers des ausgewählten Elements. Verwenden Sie entweder lpFile , um das Element anhand des Dateisystempfads zu identifizieren, oder lpIDList , um das Element anhand seiner PIDL zu identifizieren. Mit diesem Flag können Anwendungen ShellExecuteEx verwenden, um Verben aus Kontextmenüerweiterungen anstelle der in der Registrierung aufgeführten statischen Verben aufzurufen.
Hinweis: SEE_MASK_INVOKEIDLIST überschreibt und impliziert SEE_MASK_IDLIST.
SEE_MASK_ICON (0x00000010) Verwenden Sie das Symbol, das vom hIcon-Element angegeben wird. Dieses Flag kann nicht mit SEE_MASK_HMONITOR kombiniert werden.
Hinweis: Dieses Flag wird nur in Windows XP und früher verwendet. Ab Windows Vista wird dies ignoriert.
SEE_MASK_HOTKEY (0x00000020) Verwenden Sie die Tastenkombination, die vom dwHotKey-Element angegeben wird.
SEE_MASK_NOCLOSEPROCESS (0x00000040) Verwenden Sie, um anzugeben, dass das hProcess-Element das Prozesshandle empfängt. Dieses Handle wird in der Regel verwendet, damit eine Anwendung herausfinden kann, wann ein mit ShellExecuteEx erstellter Prozess beendet wird. In einigen Fällen, z. B. wenn die Ausführung über eine DDE-Unterhaltung erfüllt wird, wird kein Handle zurückgegeben. Die aufrufende Anwendung ist dafür verantwortlich, das Handle zu schließen, wenn es nicht mehr benötigt wird.
SEE_MASK_CONNECTNETDRV (0x00000080) Überprüfen Sie die Freigabe, und stellen Sie eine Verbindung mit einem Laufwerkbuchstaben her. Dies ermöglicht die erneute Verbindung von getrennten Netzlaufwerken. Das lpFile-Element ist ein UNC-Pfad einer Datei in einem Netzwerk.
SEE_MASK_NOASYNC (0x00000100) Nur beim Starten von Dateien berücksichtigt, gilt nicht für Uris oder Shell-Namespaceelemente (z. B. "Dieser PC"). Warten Sie, bis der asynchrone Teil des Ausführungsvorgangs (z. B. DDE) abgeschlossen ist, bevor sie zurückgegeben wird. Wenn dies gilt, wird sichergestellt, dass der Startvorgang abgeschlossen ist, bevor er zurückgegeben wird. Anwendungen, die unmittelbar nach dem Aufruf von ShellExecuteEx beendet werden, sollten dieses Flag angeben. Beachten Sie, dass ShellExecuteEx seine Arbeit in einen Hintergrundthread verschiebt, wenn das Threadingmodell des Aufrufers nicht Apartment ist. Durch erzwingen, dass der Aufruf synchron ist, deaktiviert dieses Verhalten und verwendet das COM-Apartment der Anrufer. Das Angeben SEE_MASK_FLAG_HINST_IS_SITE erzwingt immer synchrones Verhalten.

Wenn der Ausführungsvorgang für einen Hintergrundthread ausgeführt wird und der Aufrufer das flag SEE_MASK_ASYNCOK nicht angegeben hat, wartet der aufrufende Thread, bis der neue Prozess gestartet wurde, bevor er zurückgibt. Dies bedeutet in der Regel, dass entweder CreateProcess aufgerufen wurde, die DDE-Kommunikation abgeschlossen wurde oder dass der benutzerdefinierte Ausführungsdelegat ShellExecuteEx darüber benachrichtigt hat, dass dies geschehen ist. Wenn das SEE_MASK_WAITFORINPUTIDLE-Flag angegeben ist, ruft ShellExecuteExWaitForInputIdle auf und wartet, bis der neue Prozess im Leerlauf liegt, bevor es zurückgegeben wird, mit einem maximalen Timeout von 1 Minute.

Weitere Informationen dazu, wann dieses Flag erforderlich ist, finden Sie im Abschnitt Hinweise.

SEE_MASK_FLAG_DDEWAIT (0x00000100) Die gleiche wie SEE_MASK_NOASYNC, die Verwendung dieser Option wird bevorzugt.
SEE_MASK_DOENVSUBST (0x00000200) Erweitern Sie alle Umgebungsvariablen, die in der vom element lpDirectory oder lpFile angegebenen Zeichenfolge angegeben sind.
SEE_MASK_FLAG_NO_UI (0x00000400) Zeigen Sie keine Benutzeroberfläche an, einschließlich Fehlerdialogfeldern, Sicherheitswarnungen oder anderer Benutzeroberfläche, die normalerweise ohne diese Option angezeigt würde.
SEE_MASK_UNICODE (0x00004000) Verwenden Sie dieses Flag, um eine Unicode-Anwendung anzugeben.
SEE_MASK_NO_CONSOLE (0x00008000) Verwenden Sie zum Erben der übergeordneten Konsole für den neuen Prozess, anstatt eine neue Konsole erstellen zu lassen. Es ist das Gegenteil von der Verwendung eines CREATE_NEW_CONSOLE-Flags mit CreateProcess.
SEE_MASK_ASYNCOK (0x00100000) Die Ausführung kann in einem Hintergrundthread ausgeführt werden, und der Aufruf sollte sofort zurückgegeben werden, ohne auf den Abschluss des Hintergrundthreads zu warten. Beachten Sie, dass ShellExecuteEx in bestimmten Fällen dieses Flag ignoriert und wartet, bis der Prozess abgeschlossen ist, bevor es zurückgegeben wird.
SEE_MASK_NOQUERYCLASSSTORE (0x01000000) Wird nicht verwendet.
SEE_MASK_HMONITOR (0x00200000) Verwenden Sie dieses Flag, wenn Sie einen Monitor auf Systemen mit mehreren Monitoren angeben. Der Monitor wird im hMonitor-Element angegeben. Dieses Flag kann nicht mit SEE_MASK_ICON kombiniert werden.
SEE_MASK_NOZONECHECKS (0x00800000) Führen Sie keine Zonenüberprüfung durch. Mit diesem Flag kann ShellExecuteEx die zonenüberprüfung umgehen, die von IAttachmentExecute eingerichtet wurde.
SEE_MASK_WAITFORINPUTIDLE (0x02000000) Warten Sie nach dem Erstellen des neuen Prozesses, bis sich der Prozess im Leerlauf befindet, bevor sie mit einem Timeout von einer Minute zurückgegeben wird. Weitere Informationen finden Sie unter WaitForInputIdle .
SEE_MASK_FLAG_LOG_USAGE (0x04000000) Gibt einen vom Benutzer initiierten Start an, der die Nachverfolgung häufig verwendeter Programme und anderer Verhaltensweisen ermöglicht.
SEE_MASK_FLAG_HINST_IS_SITE" (0x08000000) Das hInstApp-Element wird verwendet, um die IUnknown eines Objekts anzugeben, das IServiceProvider implementiert. Dieses Objekt wird als Standortzeiger verwendet. Der Standortzeiger wird verwendet, um Dienste für die ShellExecuteEx-Funktion , den Handlerbindungsprozess und aufgerufene Verbhandler bereitzustellen. ICreatingProcess kann bereitgestellt werden, damit der Aufrufer einige Parameter des zu erstellenden Prozesses ändern kann.

Dieses Flag wird in Windows 8 und höher unterstützt.

Wenn diese Option angegeben ist, wird der Aufruf synchron für den aufrufenden Thread ausgeführt.

hwnd

Typ: HWND

Optional. Ein Handle für das Besitzerfenster, das verwendet wird, um eine beliebige Benutzeroberfläche anzuzeigen und zu positionieren, die das System beim Ausführen dieser Funktion möglicherweise erstellt.

lpVerb

Typ: LPCTSTR

Eine als Verb bezeichnete Zeichenfolge, die 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. Dieser Parameter kann NULL sein. In diesem Fall wird das Standardverb verwendet, sofern verfügbar. Andernfalls wird das Verb "open" verwendet. Wenn keines der Verben verfügbar ist, verwendet das System das erste Verb, das in der Registrierung aufgeführt ist. Die folgenden Verben werden häufig verwendet:

  • edit: Startet einen Editor und öffnet das Dokument zur Bearbeitung. Wenn lpFile keine Dokumentdatei ist, schlägt die Funktion fehl.
  • explore: Untersucht den von lpFile angegebenen Ordner.
  • find: Initiiert eine Suche beginnend mit dem angegebenen Verzeichnis.
  • open: Öffnet die durch den lpFile-Parameter angegebene Datei. Bei der Datei kann es sich um eine ausführbare Datei, eine Dokumentdatei oder einen Ordner handeln.
  • print: Gibt die von lpFile angegebene Dokumentdatei aus. Wenn lpFile keine Dokumentdatei ist, schlägt die Funktion fehl.
  • properties: Zeigt die Eigenschaften der Datei oder des Ordners an.
  • runas: Startet eine Anwendung als Administrator. Die Benutzerkontensteuerung (User Account Control, UAC) fordert den Benutzer zur Zustimmung zur Ausführung der Anwendung mit erhöhten Rechten auf oder gibt die Anmeldeinformationen eines Administratorkontos ein, das zum Ausführen der Anwendung verwendet wird.

lpFile

Typ: LPCTSTR

Die Adresse einer Zeichenfolge mit NULL-Beendigung, die den Namen der Datei oder des Objekts angibt, für die ShellExecuteEx die vom lpVerb-Parameter angegebene Aktion ausführt. Zu den Systemregistrierungsverben, die von der ShellExecuteEx-Funktion unterstützt werden, gehören "open" für ausführbare Dateien und Dokumentdateien und "drucken" für Dokumentdateien, für die ein Druckhandler registriert wurde. Andere Anwendungen haben möglicherweise Shellverben über die Systemregistrierung hinzugefügt, z. B. "play" für .avi- und .wav-Dateien. Um ein Shell-Namespaceobjekt anzugeben, übergeben Sie den vollqualifizierten Analysenamen, und legen Sie das flag SEE_MASK_INVOKEIDLIST im fMask-Parameter fest.

Hinweis: Wenn das flag SEE_MASK_INVOKEIDLIST festgelegt ist, können Sie entweder lpFile oder lpIDList verwenden, um das Element anhand seines Dateisystempfads bzw. seiner PIDL zu identifizieren. Einer der beiden Werte – lpFile oder lpIDList – muss festgelegt werden.
Hinweis: Wenn der Pfad nicht im Namen enthalten ist, wird das aktuelle Verzeichnis angenommen.

lpParameters

Typ: LPCTSTR

Optional. Die Adresse einer Zeichenfolge mit NULL-Beendigung, die die Anwendungsparameter enthält. Die Parameter müssen durch Leerzeichen getrennt werden. Wenn der lpFile-Member eine Dokumentdatei angibt, sollte lpParametersNULL sein.

lpDirectory

Typ: LPCTSTR

Optional. Die Adresse einer NULL-beendeten Zeichenfolge, die den Namen des Arbeitsverzeichnisses angibt. Wenn dieser Member NULL ist, wird das aktuelle Verzeichnis als Arbeitsverzeichnis verwendet.

nShow

Typ: int

Erforderlich. Flags, die angeben, wie eine Anwendung angezeigt werden soll, wenn sie geöffnet wird; einer der SW_ Werte, die für die ShellExecute-Funktion aufgeführt sind. Wenn lpFile eine Dokumentdatei angibt, wird das Flag einfach an die zugeordnete Anwendung übergeben. Es liegt an der Anwendung, zu entscheiden, wie sie damit umgeht.

hInstApp

Typ: HINSTANCE

[out] Wenn SEE_MASK_NOCLOSEPROCESS festgelegt ist und der ShellExecuteEx-Aufruf erfolgreich ist, wird dieser Member auf einen Wert größer als 32 festgelegt. Wenn die Funktion fehlschlägt, wird sie auf einen SE_ERR_XXX Fehlerwert festgelegt, der die Ursache des Fehlers angibt. Obwohl hInstApp als HINSTANCE für die Kompatibilität mit 16-Bit-Windows-Anwendungen deklariert wird, handelt es sich nicht um eine echte HINSTANCE. Es kann nur in ein int umgewandelt werden und mit entweder 32 oder den folgenden SE_ERR_XXX Fehlercodes verglichen werden.


Fehlercode `Reason`
SE_ERR_FNF (2) Die Datei wurde nicht gefunden.
SE_ERR_PNF (3) Pfad nicht gefunden.
SE_ERR_ACCESSDENIED (5) Zugriff verweigert.
SE_ERR_OOM (8) Nicht genügend Arbeitsspeicher.
SE_ERR_DLLNOTFOUND (32) Die Dynamic-Link-Bibliothek wurde nicht gefunden.
SE_ERR_SHARE (26) Eine geöffnete Datei kann nicht freigegeben werden.
SE_ERR_ASSOCINCOMPLETE (27) Dateizuordnungsinformationen sind nicht vollständig.
SE_ERR_DDETIMEOUT (28) Timeout für DDE-Vorgang.
SE_ERR_DDEFAIL (29) Fehler beim DDE-Vorgang.
SE_ERR_DDEBUSY (30) Der DDE-Vorgang ist ausgelastet.
SE_ERR_NOASSOC (31) Dateizuordnung nicht verfügbar.

lpIDList

Typ: LPVOID

Die Adresse einer absoluten ITEMIDLIST-Struktur (PCIDLIST_ABSOLUTE), die eine Elementbezeichnerliste enthält, die die auszuführende Datei eindeutig identifiziert. Dieser Member wird ignoriert, wenn das fMask-Element keine SEE_MASK_IDLIST oder SEE_MASK_INVOKEIDLIST enthält.

lpClass

Typ: LPCTSTR

Die Adresse einer Zeichenfolge mit NULL-Beendigung, die eine der folgenden Werte angibt:

  • Eine ProgId. Beispiel: "Paint.Picture".
  • Ein URI-Protokollschema. Beispiel: "http".
  • Eine Dateierweiterung. Beispiel: ".txt".
  • Ein Registrierungspfad unter HKEY_CLASSES_ROOT, der einen Unterschlüssel benennt, der mindestens ein Shell-Verb enthält. Dieser Schlüssel verfügt über einen Unterschlüssel, der dem Registrierungsschema des Shell-Verbs entspricht, z. B.Shellverbname\.

Dieser Member wird ignoriert, wenn fMask keine SEE_MASK_CLASSNAME enthält.

hkeyClass

Typ: HKEY

Ein Handle für den Registrierungsschlüssel für den Dateityp. Die Zugriffsrechte für diesen Registrierungsschlüssel sollten auf KEY_READ festgelegt werden. Dieser Member wird ignoriert, wenn fMask keine SEE_MASK_CLASSKEY enthält.

dwHotKey

Art: DWORD

Eine Tastenkombination, die der Anwendung zugeordnet werden soll. Das Wort mit niedriger Ordnung ist der virtuelle Schlüsselcode, und das Wort mit hoher Ordnung ist ein Modifiziererflag (HOTKEYF_). Eine Liste der Modifiziererflags finden Sie in der Beschreibung der WM_SETHOTKEY Meldung. Dieser Member wird ignoriert, wenn fMask keine SEE_MASK_HOTKEY enthält.

DUMMYUNIONNAME

DUMMYUNIONNAME.hIcon

Typ: HANDLE

Ein Handle für das Symbol für den Dateityp. Dieser Member wird ignoriert, wenn fMask keine SEE_MASK_ICON enthält. Dieser Wert wird nur in Windows XP und früheren Versionen verwendet. Ab Windows Vista wird dies ignoriert.

DUMMYUNIONNAME.hMonitor

Typ: HANDLE

Ein Handle für den Monitor, auf dem das Dokument angezeigt werden soll. Dieser Member wird ignoriert, wenn fMask keine SEE_MASK_HMONITOR enthält.

hProcess

Typ: HANDLE

Ein Handle für die neu gestartete Anwendung. Dieser Member wird bei der Rückgabe festgelegt und ist immer NULL , es sei denn , fMask ist auf SEE_MASK_NOCLOSEPROCESS festgelegt. Selbst wenn fMask auf SEE_MASK_NOCLOSEPROCESS festgelegt ist, ist hProcessNULL , wenn kein Prozess gestartet wurde. Wenn beispielsweise ein zu startende Dokument eine URL ist und ein instance von Internet Explorer bereits ausgeführt wird, wird das Dokument angezeigt. Es wird kein neuer Prozess gestartet, und hProcess ist NULL.

Hinweis:ShellExecuteEx gibt nicht immer einen hProcess zurück, auch wenn ein Prozess als Ergebnis des Aufrufs gestartet wird. Ein hProcess gibt beispielsweise nicht zurück, wenn Sie SEE_MASK_INVOKEIDLIST zum Aufrufen von IContextMenu verwenden.

Hinweise

Das flag SEE_MASK_NOASYNC muss angegeben werden, wenn der Thread, der ShellExecuteEx aufruft, keine Meldungsschleife hat oder wenn der Thread oder Prozess kurz nach der Rückgabe von ShellExecuteEx beendet wird. Unter solchen Bedingungen ist der aufrufende Thread nicht verfügbar, um die DDE-Konversation abzuschließen. Daher ist es wichtig, dass ShellExecuteEx die Konversation abschließen muss, bevor die Steuerung an die aufrufende Anwendung zurückgegeben wird. Wenn die Unterhaltung nicht abgeschlossen wird, kann dies zu einem nicht erfolgreichen Start des Dokuments führen.

Wenn der aufrufende Thread über eine Nachrichtenschleife verfügt und nach dem Aufruf von ShellExecuteEx für einige Zeit vorhanden ist, ist das flag SEE_MASK_NOASYNC optional. Wenn das Flag weggelassen wird, wird die Nachrichtenpumpe des aufrufenden Threads verwendet, um die DDE-Konversation abzuschließen. Die aufrufende Anwendung erhält die Kontrolle früher wieder, da die DDE-Konversation im Hintergrund abgeschlossen werden kann.

Geben Sie für Aufrufe dieser API, die aus Benutzerinteraktionen resultieren, SEE_MASK_FLAG_LOG_USAGE an.

Um doppelte Anführungszeichen in lpParameters einzuschließen, schließen Sie jede Markierung wie im folgenden Beispiel in ein Anführungszeichenpaar ein.

sei.lpParameters = "An example: \"\"\"quoted text\"\"\"";

In diesem Fall empfängt die Anwendung drei Parameter: An, example:, und "quoted text".

Hinweis

Der Shellapi.h-Header definiert SHELLEXECUTEINFO 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]
Kopfzeile shellapi.h