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.
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.
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 |
Feedback
https://aka.ms/ContentUserFeedback.
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unterFeedback senden und anzeigen für