SHELLEXECUTEINFOA-Struktur (shellapi.h)
Enthält von ShellExecuteEx verwendete Informationen.
Syntax
typedef struct _SHELLEXECUTEINFOA {
DWORD cbSize;
ULONG fMask;
HWND hwnd;
LPCSTR lpVerb;
LPCSTR lpFile;
LPCSTR lpParameters;
LPCSTR lpDirectory;
int nShow;
HINSTANCE hInstApp;
void *lpIDList;
LPCSTR lpClass;
HKEY hkeyClass;
DWORD dwHotKey;
union {
HANDLE hIcon;
HANDLE hMonitor;
} DUMMYUNIONNAME;
HANDLE hProcess;
} SHELLEXECUTEINFOA, *LPSHELLEXECUTEINFOA;
Member
cbSize
Art: DWORD
Erforderlich. Die Größe dieser Struktur in Bytes.
fMask
Typ: ULONG
Eine Kombination aus einem oder mehreren 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 Klassennamen, der vom lpClass-Member angegeben wird. Wenn sowohl SEE_MASK_CLASSKEY als auch SEE_MASK_CLASSNAME festgelegt sind, wird der Klassenschlüssel verwendet. |
| SEE_MASK_CLASSKEY (0x00000003) | Verwenden Sie den Klassenschlüssel, der vom hkeyClass-Member angegeben wird. 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 seines 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üheren Versionen 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 der hProcess-Member 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-Konversation 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-Mitglied ist ein UNC-Pfad einer Datei in einem Netzwerk. |
| SEE_MASK_NOASYNC (0x00000100) | Warten Sie, bis der Ausführungsvorgang abgeschlossen ist, bevor sie zurückgegeben wird. Dieses Flag sollte von Aufrufenden verwendet werden, die ShellExecute-Formulare verwenden, die möglicherweise zu einer asynchronen Aktivierung führen, z. B. DDE, und einen Prozess erstellen, der in einem Hintergrundthread ausgeführt werden kann. (Hinweis: ShellExecuteEx wird standardmäßig in einem Hintergrundthread ausgeführt, wenn das Threadingmodell des Aufrufers nicht Apartment ist.) Aufrufe von ShellExecuteEx von Prozessen, die bereits in Hintergrundthreads ausgeführt werden, sollten dieses Flag immer übergeben. Außerdem sollten Anwendungen, die unmittelbar nach dem Aufrufen von ShellExecuteEx beendet werden, dieses Flag angeben.
Wenn der Ausführungsvorgang in einem 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ückgegeben wird. Dies bedeutet in der Regel, dass entweder CreateProcess aufgerufen wurde, die DDE-Kommunikation abgeschlossen wurde oder dass der benutzerdefinierte Ausführungsdelegat ShellExecuteEx benachrichtigt hat, dass dies erfolgt ist. Wenn das flag SEE_MASK_WAITFORINPUTIDLE 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) | Wie SEE_MASK_NOASYNC wird die Verwendung dieser Option bevorzugt. |
| SEE_MASK_DOENVSUBST (0x00000200) | Erweitern Sie alle Umgebungsvariablen, die in der vom lpDirectory - oder lpFile-Member angegebenen Zeichenfolge angegeben sind. |
| SEE_MASK_FLAG_NO_UI (0x00000400) | Zeigen Sie keine Benutzeroberfläche (UI) an, einschließlich Fehlerdialogen, Sicherheitswarnungen oder einer anderen Benutzeroberfläche, die normalerweise ohne diese Option angezeigt wird. |
| SEE_MASK_UNICODE (0x00004000) | Verwenden Sie dieses Flag, um eine Unicode-Anwendung anzugeben. |
| SEE_MASK_NO_CONSOLE (0x00008000) | Verwenden Sie , um die Konsole des übergeordneten Elements für den neuen Prozess zu erben, anstatt eine neue Konsole erstellen zu lassen. Dies 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 auf den Abschluss des Prozesses wartet, 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 aus. Dieses Flag ermöglicht ShellExecuteEx die Umgehung der Zonenüberprüfung, die von IAttachmentExecute eingerichtet wurde. |
| SEE_MASK_WAITFORINPUTIDLE (0x02000000) | Nachdem der neue Prozess erstellt wurde, warten Sie, bis der Prozess im Leerlauf ist, bevor sie zurückgegeben wird, mit einem Timeout von einer Minute. 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) | Der hInstApp-Member wird verwendet, um die IUnknown eines Objekts anzugeben, das IServiceProvider implementiert. Dieses Objekt wird als Websitezeiger verwendet. Der Standortzeiger wird verwendet, um Dienste für die ShellExecute-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 im 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 erzeugt.
lpVerb
Typ: LPCTSTR
Eine als Verb bezeichnete Zeichenfolge, die die auszuführende Aktion angibt. Der Satz der verfügbaren Verben hängt von der jeweiligen Datei oder dem jeweiligen Ordner ab. Im Allgemeinen sind die über das 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. Sofern es keinen Grund gibt, die Aktion auf ein bestimmtes Verb zu beschränken, übergeben Sie NULL, um den berechneten Standardwert zu verwenden. Dies ist in einigen Fällen erforderlich, z. B. wenn SEE_MASK_FLAG_NO_UI angegeben wird und die Benutzeroberfläche "Öffnen mit" erstellt werden soll, wenn keine Apps installiert sind.
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.
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
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 unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für