SHELLEXECUTEINFOA-Struktur (shellapi.h)
Enthält Informationen, die von ShellExecuteExverwendet werden.
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;
Angehörige
cbSize
Typ: DWORD-
Erforderlich. Die Größe dieser Struktur in Byte.
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 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 Member angegeben wird. Der lpIDList Member 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 dieser Kennzeichnung können Anwendungen ShellExecuteEx- verwenden, um Verben aus Kontextmenüerweiterungen anstelle der in der Registrierung aufgeführten statischen Verben aufzurufen.
Hinweis: SEE_MASK_INVOKEIDLIST Außerkraftsetzungen und impliziert SEE_MASK_IDLIST.
|
| SEE_MASK_ICON (0x00000010) | Verwenden Sie das vom hIcon Member angegebene Symbol. Dieses Kennzeichen kann nicht mit SEE_MASK_HMONITOR kombiniert werden.
Hinweis: Dieses Kennzeichen wird nur in Windows XP und früheren Versionen verwendet. Sie wird ab Windows Vista ignoriert.
|
| SEE_MASK_HOTKEY (0x00000020) | Verwenden Sie die tastenkombination, die vom dwHotKey Member angegeben wird. |
| SEE_MASK_NOCLOSEPROCESS (0x00000040) | Wird verwendet, um anzugeben, dass das hProcess Member das Prozesshandle empfängt. Dieses Handle wird in der Regel verwendet, um es einer Anwendung zu ermöglichen, herauszufinden, wann ein mit ShellExecuteEx erstellter Prozess beendet wird. In einigen Fällen, z. B. wenn die Ausführung über eine DDE-Unterhaltung erfüllt ist, wird kein Handle zurückgegeben. Die aufrufende Anwendung ist dafür verantwortlich, das Handle zu schließen, wenn sie 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 Member ist ein UNC-Pfad einer Datei in einem Netzwerk. |
| SEE_MASK_NOASYNC (0x00000100) | Warten Sie, bis der Ausführungsvorgang abgeschlossen ist, bevor Sie zurückkehren. Dieses Flag sollte von Aufrufern verwendet werden, die ShellExecute-Formulare verwenden, die zu einer asynchronen Aktivierung führen können, 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- aus Prozessen, die bereits in Hintergrundthreads ausgeführt werden, sollten diese Kennzeichnung immer übergeben. Außerdem sollten Anwendungen, die unmittelbar nach dem Aufrufen ShellExecuteEx- beendet werden, dieses Flag angeben.
Wenn der Ausführungsvorgang in einem Hintergrundthread ausgeführt wird und der Aufrufer das SEE_MASK_ASYNCOK Flag 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 er ausgeführt wird. Wenn das SEE_MASK_WAITFORINPUTIDLE Flag angegeben ist, ruft ShellExecuteExWaitForInputIdle- auf und wartet, bis der neue Prozess leer ist, bevor er zurückgegeben wird, mit einem maximalen Timeout von 1 Minute. Weitere Erläuterungen dazu, wann diese Kennzeichnung erforderlich ist, finden Sie im Abschnitt "Anmerkungen". |
| SEE_MASK_FLAG_DDEWAIT (0x00000100) | Identisch mit SEE_MASK_NOASYNC, wird die Verwendung dieser Option bevorzugt. |
| SEE_MASK_DOENVSUBST (0x00000200) | Erweitern Sie alle Umgebungsvariablen, die in der Zeichenfolge angegeben sind, die vom lpDirectory oder lpFile Member angegeben ist. |
| SEE_MASK_FLAG_NO_UI (0x00000400) | Zeigen Sie keine Benutzeroberflächenfehlerdialoge an, die normalerweise ohne diese Option angezeigt werden. Sicherheitsaufforderungen sind ausgenommen und werden weiterhin angezeigt. |
| SEE_MASK_UNICODE (0x00004000) | Verwenden Sie dieses Flag, um eine Unicode-Anwendung anzugeben. |
| SEE_MASK_NO_CONSOLE (0x00008000) | Verwenden Sie diese Option, um die Konsole des übergeordneten Elements für den neuen Prozess zu erben, anstatt eine neue Konsole zu erstellen. Es ist das Gegenteil 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 in bestimmten Fällen ShellExecuteEx dieses Flag ignoriert und wartet, bis der Vorgang abgeschlossen ist, bevor er zurückgegeben wird. |
| SEE_MASK_NOQUERYCLASSSTORE (0x01000000) | Wird nicht verwendet. |
| SEE_MASK_HMONITOR (0x00200000) | Verwenden Sie dieses Kennzeichen, wenn Sie einen Monitor auf Systemen mit mehreren Monitoren angeben. Der Monitor wird im hMonitor Member angegeben. Dieses Kennzeichen kann nicht mit SEE_MASK_ICON kombiniert werden. |
| SEE_MASK_NOZONECHECKS (0x00800000) | Führen Sie keine Zonenüberprüfung durch. Mit dieser Kennzeichnung können ShellExecuteEx- die Zonenüberprüfung umgehen, die von IAttachmentExecuteeingefügt wird. |
| SEE_MASK_WAITFORINPUTIDLE (0x02000000) | Nachdem der neue Prozess erstellt wurde, warten Sie, bis der Prozess leer ist, bevor er zurückgegeben wird, mit einem Minutentimeout. 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 Member wird verwendet, um die IUnknown- eines Objekts anzugeben, das IServiceProvider-implementiert. Dieses Objekt wird als Websitezeiger verwendet. Der Websitezeiger 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 erstellten Prozesses ändern kann. Dieses Kennzeichen wird in Windows 8 und höher unterstützt. Wenn diese Option angegeben wird, wird der Aufruf synchron im aufrufenden Thread ausgeführt. |
hwnd
Typ: HWND-
Wahlfrei. Ein Handle für das Besitzerfenster, das verwendet wird, um alle Ui anzuzeigen und zu positionieren, die das System während der Ausführung dieser Funktion erzeugen kann.
lpVerb
Typ: LPCTSTR-
Eine Zeichenfolge, die 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. Dieser Parameter kann NULL-sein, in diesem Fall wird das Standardverb 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. Wenn 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. beim Angeben von SEE_MASK_FLAG_NO_UI und der Absicht, die Benutzeroberfläche "Öffnen mit" zu erstellen, wenn keine Apps installiert sind.
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.
- erkunden sie: Durch die lpFile-angegebenen Ordner.
- finden: Initiiert eine Suche beginnend mit dem angegebenen Verzeichnis.
- öffnen sie: Öffnet die durch den parameter lpFile angegebene Datei. Die Datei kann eine ausführbare Datei, eine Dokumentdatei oder ein Ordner sein.
- openas: Startet eine Auswahl-UI, mit der der Benutzer eine App auswählen kann, mit der die durch den parameter lpFile angegebene Datei geöffnet werden soll.
- drucken: Druckt die dokumentdatei, die durch lpFile-angegeben wird. Wenn lpFile- keine Dokumentdatei ist, schlägt die Funktion fehl.
- Eigenschaften: Zeigt die Eigenschaften der Datei oder des Ordners an.
- 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.
lpFile
Typ: LPCTSTR-
Die Adresse einer mit Null beendeten Zeichenfolge, die den Namen der Datei oder des Objekts angibt, für die ShellExecuteEx- die durch den parameter lpVerb angegebene Aktion ausführt. Die systemregistrierungsverben, die von der ShellExecuteEx-Funktion unterstützt werden, umfassen "öffnen" für ausführbare Dateien und Dokumentdateien und "drucken" für Dokumentdateien, für die ein Druckhandler registriert wurde. Andere Anwendungen haben möglicherweise Shell-Verben über die Systemregistrierung hinzugefügt, z. B. "Wiedergeben" für .avi und .wav Dateien. Um ein Shell-Namespaceobjekt anzugeben, übergeben Sie den vollqualifizierten Analysenamen, und legen Sie das SEE_MASK_INVOKEIDLIST Flag im fMask--Parameter fest.
lpParameters
Typ: LPCTSTR-
Wahlfrei. Die Adresse einer mit Null beendeten Zeichenfolge, die die Anwendungsparameter enthält. Die Parameter müssen durch Leerzeichen getrennt werden. Wenn das lpFile-Element eine Dokumentdatei angibt, sollte lpParameters-NULL-sein.
lpDirectory
Typ: LPCTSTR-
Wahlfrei. Die Adresse einer mit Null beendeten Zeichenfolge, die den Namen des Arbeitsverzeichnisses angibt. Wenn dieses Mitglied 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 behandelt werden soll.
hInstApp
Typ: HINSTANCE-
[out] Wenn SEE_MASK_NOCLOSEPROCESS festgelegt ist und der ShellExecuteEx-Aufruf erfolgreich ausgeführt wird, wird dieses Element auf einen Wert festgelegt, der größer als 32 ist. Wenn die Funktion fehlschlägt, wird sie auf einen SE_ERR_XXX Fehlerwert festgelegt, der die Ursache des Fehlers angibt. Obwohl hInstApp- zur Kompatibilität mit 16-Bit-Windows-Anwendungen als HINSTANCE deklariert wird, ist dies kein wahrer HINWEIS. Sie kann nur in eine int und im Vergleich zu 32 oder den folgenden SE_ERR_XXX Fehlercodes umgestellt werden.
| Fehlercode | Grund |
|---|---|
| SE_ERR_FNF (2) | Die Datei wurde nicht gefunden. |
| SE_ERR_PNF (3) | Pfad nicht gefunden. |
| SE_ERR_ACCESSDENIED (5) | Zugriff abgelehnt. |
| SE_ERR_OOM (8) | Nicht genügend Arbeitsspeicher. |
| SE_ERR_DLLNOTFOUND (32) | Die Bibliothek für dynamische Verknüpfungen wurde nicht gefunden. |
| SE_ERR_SHARE (26) | Eine geöffnete Datei kann nicht freigegeben werden. |
| SE_ERR_ASSOCINCOMPLETE (27) | Dateizuordnungsinformationen sind nicht abgeschlossen. |
| SE_ERR_DDETIMEOUT (28) | Timeout des DDE-Vorgangs. |
| 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. Dieses Element wird ignoriert, wenn das fMask Member nicht SEE_MASK_IDLIST oder SEE_MASK_INVOKEIDLISTenthält.
lpClass
Typ: LPCTSTR-
Die Adresse einer mit Null beendeten Zeichenfolge, 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 ein oder mehrere Shellverben enthält. Dieser Schlüssel verfügt über einen Unterschlüssel, der dem Shell-Verbregistrierungsschema entspricht, z. B. Shell-\Verbname.
Dieses Element wird ignoriert, wenn fMask- nicht SEE_MASK_CLASSNAMEenthä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. Dieses Element wird ignoriert, wenn fMask- nicht SEE_MASK_CLASSKEYenthält.
dwHotKey
Typ: DWORD-
Eine Tastenkombination, die der Anwendung zugeordnet werden soll. Das Wort mit niedriger Reihenfolge ist der virtuelle Schlüsselcode, und das Hochreihenfolgenwort ist ein Modifizierer-Flag (HOTKEYF_). Eine Liste der Modifiziererkennzeichnungen finden Sie in der Beschreibung der WM_SETHOTKEY Nachricht. Dieses Element wird ignoriert, wenn fMask- nicht SEE_MASK_HOTKEYenthält.
DUMMYUNIONNAME
DUMMYUNIONNAME.hIcon
Typ: HANDLE
Ein Handle zum Symbol für den Dateityp. Dieses Element wird ignoriert, wenn fMask- nicht SEE_MASK_ICONenthält. Dieser Wert wird nur in Windows XP und früheren Versionen verwendet. Sie wird ab Windows Vista ignoriert.
DUMMYUNIONNAME.hMonitor
Typ: HANDLE
Ein Handle auf dem Monitor, auf dem das Dokument angezeigt werden soll. Dieses Element wird ignoriert, wenn fMask- nicht SEE_MASK_HMONITORenthält.
hProcess
Typ: HANDLE
Ein Handle für die neu gestartete Anwendung. Dieses Element wird beim Zurückgeben festgelegt und ist immer NULL-, es sei denn, fMask- auf SEE_MASK_NOCLOSEPROCESSfestgelegt ist. Selbst wenn fMask- auf SEE_MASK_NOCLOSEPROCESSfestgelegt ist, wird hProcess-NULL-, wenn kein Prozess gestartet wurde. Wenn beispielsweise ein dokument, das gestartet werden soll, eine URL ist und eine Instanz von Internet Explorer bereits ausgeführt wird, wird das Dokument angezeigt. Es wird kein neuer Prozess gestartet, und hProcess- wird NULL-.
Bemerkungen
Das flag SEE_MASK_NOASYNC muss angegeben werden, wenn der Threadaufruf ShellExecuteEx keine Meldungsschleife enthält oder der Thread oder Prozess bald nach ShellExecuteEx- beendet wird. Unter diesen Bedingungen steht der aufrufende Thread nicht zur Verfügung, um die DDE-Unterhaltung abzuschließen. Daher ist es wichtig, dass ShellExecuteEx die Unterhaltung abschließen, bevor die Steuerung an die aufrufende Anwendung zurückgegeben wird. Fehler beim Abschließen der Unterhaltung kann zu einem erfolglosen Start des Dokuments führen.
Wenn der aufrufende Thread über eine Meldungsschleife verfügt und nach dem Aufruf von ShellExecuteEx- einige Zeit vorhanden ist, ist das SEE_MASK_NOASYNC-Flag optional. Wenn das Flag ausgelassen wird, wird die Nachrichtenpumpe des aufrufenden Threads verwendet, um die DDE-Unterhaltung abzuschließen. Die aufrufende Anwendung erhält die Kontrolle früher wieder, da die DDE-Unterhaltung im Hintergrund abgeschlossen werden kann.
Um doppelte Anführungszeichen in lpParameterseinzuschließen, schließen Sie die einzelnen Markierungen 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, Beispiel:und "an zitierten Text".
Anmerkung
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 |
|---|---|
| mindestens unterstützte Client- | Windows XP [nur Desktop-Apps] |
| mindestens unterstützte Server- | Windows 2000 Server [nur Desktop-Apps] |
| Header- | shellapi.h |