IOleCommandTarget::Exec-Methode (docobj.h)

  • Artikel

Führt den angegebenen Befehl aus oder zeigt Hilfe für den Befehl an.

Syntax

HRESULT Exec(
  [in]      const GUID *pguidCmdGroup,
  [in]      DWORD      nCmdID,
  [in]      DWORD      nCmdexecopt,
  [in]      VARIANT    *pvaIn,
  [in, out] VARIANT    *pvaOut
);

Parameter

[in] pguidCmdGroup

Der eindeutige Bezeichner der Befehlsgruppe; kann NULL sein, um die Standardgruppe anzugeben.

[in] nCmdID

Der Befehl, der ausgeführt werden soll. Dieser Befehl muss zu der Gruppe gehören, die mit pguidCmdGroup angegeben ist.

[in] nCmdexecopt

Gibt an, wie das Objekt den Befehl ausführen soll. Mögliche Werte stammen aus den OLECMDEXECOPT - und OLECMDID_WINDOWSTATE_FLAG-Enumerationen .

[in] pvaIn

Ein Zeiger auf eine VARIANTARG-Struktur , die Eingabeargumente enthält. Dieser Parameter kann NULL sein.

[in, out] pvaOut

Zeiger auf eine VARIANTARG-Struktur zum Empfangen der Befehlsausgabe. Dieser Parameter kann NULL sein.

Rückgabewert

Diese Methode gibt S_OK bei Erfolg zurück. Weitere mögliche Rückgabewerte:

Rückgabecode Beschreibung
OLECMDERR_E_UNKNOWNGROUP
 Der pguidCmdGroup-Parameter ist nicht NULL , gibt aber keine erkannte Befehlsgruppe an.
OLECMDERR_E_NOTSUPPORTED
 Der nCmdID-Parameter ist kein gültiger Befehl in der gruppe, die von pguidCmdGroup identifiziert wird.
OLECMDERR_E_DISABLED
 Der durch nCmdID identifizierte Befehl ist derzeit deaktiviert und kann nicht ausgeführt werden.
OLECMDERR_E_NOHELP
 Der Aufrufer hat um Hilfe zu dem von nCmdID identifizierten Befehl gebeten, aber es ist keine Hilfe verfügbar.
OLECMDERR_E_CANCELED
 Der Benutzer hat die Ausführung des Befehls abgebrochen.

Hinweise

Die Liste der Eingabe- und Ausgabeargumente eines Befehls und deren Paket ist für jeden Befehl eindeutig. Diese Informationen sollten mit der Spezifikation der Befehlsgruppe dokumentiert werden. (Siehe beschreibung der OLECMDID_ZOOM in der OLECMDID-Enumeration .) Wenn keine spezifischen Informationen vorliegen, wird davon ausgegangen, dass der Befehl keine Argumente akzeptiert und keinen Rückgabewert aufweist.

Hinweise für Anrufer

Die Parameter pguidCmdGroup und nCmdID identifizieren den aufzurufenden Befehl eindeutig. Der Parameter nCmdExecOpt gibt die genaue Aktion an, die ausgeführt werden soll. (Weitere Informationen finden Sie in der OLECMDEXECOPT-Enumeration .)

Die meisten Befehle nehmen weder Argumente an noch geben Werte zurück. Bei solchen Befehlen kann der Aufrufer NULL in pvaIn und pvaOut übergeben. Bei Befehlen, die einen oder mehrere Eingabewerte erwarten, kann der Aufrufer eine VARIANTARG-Variable deklarieren und initialisieren und einen Zeiger auf diese Variable in pvaIn übergeben. Wenn die Eingabe für den Befehl ein einzelner Wert ist, kann das Argument direkt in der VARIANTARG-Struktur gespeichert und an die Funktion übergeben werden. Wenn der Befehl mehrere Argumente erwartet, müssen diese Argumente unter Verwendung eines der unterstützten Typen (z. B. IDispatch oder SAFEARRAY) ordnungsgemäß innerhalb des VARIANTARG-Pakets verpackt werden.

Wenn ein Befehl ein oder mehrere Argumente zurückgibt, wird erwartet, dass der Aufrufer ein VARIANTARG deklariert, für VT_EMPTY initialisiert und seine Adresse in pvaOut übergibt. Wenn der Befehl einen einzelnen Wert zurückgibt, kann das Objekt diesen Wert direkt in pvaOut speichern. Wenn der Befehl über mehrere Ausgabewerte verfügt, werden diese in irgendeiner Weise verpackt, die für VARIANTARG geeignet sind.

Da pvaIn und pvOut aufruferseitig zugeordnet sind, sind Stapelvariablen sowohl für den Aufrufer als auch für das Objekt zulässig, das den Aufruf empfängt. Für Befehle, die null oder ein Argument bei der Eingabe verwenden und null oder einen Wert zurückgeben, ist keine zusätzliche Speicherbelegung erforderlich. Die meisten von VARIANTARG unterstützten Typen erfordern keine Speicherbelegung. Ausnahmen sind SAFEARRAY und BSTR.

Hinweise für Implementierer

Ein Befehlsziel muss diese Funktion implementieren. E_NOTIMPL ist kein gültiger Rückgabewert.

Anforderungen

   
Unterstützte Mindestversion (Client) Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows 2000 Server [nur Desktop-Apps]
Zielplattform Windows
Kopfzeile docobj.h

Weitere Informationen

IOleCommandTarget

OLECMDEXECOPT