IOleObject::D oVerb-Methode (oleidl.h)

Artikel
08/25/2023

Fordert an, dass ein Objekt eine Aktion als Reaktion auf die Aktion eines Endbenutzers ausführt. Die möglichen Aktionen werden für das Objekt in IOleObject::EnumVerbs aufgelistet.

Syntax

HRESULT DoVerb(
  [in] LONG           iVerb,
  [in] LPMSG          lpmsg,
  [in] IOleClientSite *pActiveSite,
  [in] LONG           lindex,
  [in] HWND           hwndParent,
  [in] LPCRECT        lprcPosRect
);

Parameter

[in] iVerb

Zahl, die dem Verb in der OLEVERB-Struktur zugewiesen ist, die von IOleObject::EnumVerbs zurückgegeben wird.

[in] lpmsg

Zeiger auf die MSG-Struktur , die das Ereignis (z. B. einen Doppelklick) beschreibt, das das Verb aufgerufen hat. Der Aufrufer sollte die MSG-Struktur unverändert übergeben, ohne zu versuchen, die Werte eines der Strukturmember zu interpretieren oder zu ändern.

[in] pActiveSite

Zeiger auf die IOleClientSite-Schnittstelle am aktiven Clientstandort des Objekts, an dem das Ereignis aufgetreten ist, das das Verb aufgerufen hat.

[in] lindex

Dieser Parameter ist reserviert und muss null sein.

[in] hwndParent

Das Handle des Dokumentfensters, das das Objekt enthält. Dies und lprcPosRect zusammen ermöglichen es, ein temporäres Fenster für ein Objekt zu öffnen, wobei hwndParent das übergeordnete Fenster ist, in dem das Objektfenster angezeigt werden soll, und lprcPosRect definiert den Bereich, der zum Anzeigen des Objektfensters innerhalb dieses übergeordneten Elements verfügbar ist. Ein temporäres Fenster ist z. B. für ein Multimediaobjekt nützlich, das sich für die Wiedergabe, aber nicht für die Bearbeitung öffnet.

[in] lprcPosRect

Zeiger auf die RECT-Struktur , die die Koordinaten in Pixel enthält, die das umgebende Rechteck eines Objekts in hwndParent definieren. Dies und hwndParent ermöglichen zusammen das Öffnen von Multimediaobjekten für die Wiedergabe, aber nicht für die Bearbeitung.

Rückgabewert

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

Rückgabecode	Beschreibung
OLE_E_NOT_INPLACEACTIVE	iVerb ist auf OLEIVERB_UIACTIVATE oder OLEIVERB_INPLACEACTIVATE festgelegt, und das Objekt ist noch nicht sichtbar.
OLE_E_CANT_BINDTOSOURCE	Der Objekthandler oder das Linkobjekt kann keine Verbindung mit der Linkquelle herstellen.
DV_E_LINDEX	Ungültige Lindex.
OLEOBJ_S_CANNOT_DOVERB_NOW	Das Verb ist gültig, aber im aktuellen Zustand des Objekts kann es die entsprechende Aktion nicht ausführen.
OLEOBJ_S_INVALIDHWND	DoVerb war erfolgreich, aber hwndParent ist ungültig.
OLEOBJ_E_NOVERBS	Das -Objekt unterstützt keine Verben.
OLEOBJ_S_INVALIDVERB	Die Linkquelle befindet sich in einem Netzwerk, das nicht mit einem Laufwerk auf diesem Computer verbunden ist.
MK_E_CONNECT	Die Linkquelle befindet sich in einem Netzwerk, das nicht mit einem Laufwerk auf diesem Computer verbunden ist.
OLE_E_CLASSDIFF	Die Klasse für die Linkquelle wurde konvertiert.
E_NOTIMPL	Das Objekt unterstützt keine direkte Aktivierung oder erkennt keine negative Verbnummer.

Hinweise

Ein "Verb" ist eine Aktion, die ein OLE-Objekt als Reaktion auf eine Nachricht aus seinem Container ausführt. Der Container eines Objekts oder ein mit dem Objekt verknüpfter Client ruft normalerweise IOleObject::D oVerb als Reaktion auf eine Endbenutzeraktion auf, z. B. durch Doppelklicken auf das Objekt. Die verschiedenen Aktionen, die für ein bestimmtes Objekt verfügbar sind, werden in einer OLEVERB-Struktur aufgezählt, die der Container durch Aufrufen von IOleObject::EnumVerbs abruft. IOleObject::D oVerb gleicht den Wert von iVerb mit dem iVerb-Member der -Struktur ab, um zu bestimmen, welches Verb aufgerufen werden soll.

Über IOleObject::EnumVerbs bestimmt ein Objekt anstelle seines Containers, welche Verben (d. h. Aktionen) es unterstützt. OLE 2 definiert sieben Verben, die für alle Objekte verfügbar, aber nicht notwendigerweise nützlich sind. Darüber hinaus kann jedes Objekt zusätzliche Verben definieren, die für es eindeutig sind. In der folgenden Tabelle werden die durch OLE definierten Verben beschrieben.

Verb	BESCHREIBUNG
OLEIVERB_PRIMARY (0L)	Gibt die Aktion an, die auftritt, wenn ein Endbenutzer auf das Objekt in seinem Container doppelklicken. Das -Objekt, nicht der Container, bestimmt diese Aktion. Wenn das Objekt die direkte Aktivierung unterstützt, aktiviert das primäre Verb das Objekt in der Regel.
OLEIVERB_SHOW (-1)	Weist ein Objekt an, sich zum Bearbeiten oder Anzeigen anzuzeigen. Wird aufgerufen, um neu eingefügte Objekte für die anfängliche Bearbeitung anzuzeigen und Linkquellen anzuzeigen. In der Regel ein Alias für ein anderes objektdefiniertes Verb.
OLEIVERB_OPEN (-2)	Weist ein -Objekt, einschließlich eines Objekts, das andernfalls die direkte Aktivierung unterstützt, an, sich selbst zur Bearbeitung in einem Fenster zu öffnen, das von dem des Containers getrennt ist. Wenn das Objekt die direkte Aktivierung nicht unterstützt, verfügt dieses Verb über die gleiche Semantik wie OLEIVERB_SHOW.
OLEIVERB_HIDE (-3)	Bewirkt, dass ein Objekt seine Benutzeroberfläche aus der Ansicht entfernt. Gilt nur für Objekte, die vor Ort aktiviert werden.
OLEIVERB_UIACTIVATE (-4)	Aktiviert ein Objekt an Ort und Stelle zusammen mit seinen vollständigen Tools für die Benutzeroberfläche, einschließlich Menüs, Symbolleisten und dessen Namen in der Titelleiste des Containerfensters. Wenn das Objekt die direkte Aktivierung nicht unterstützt, sollte es E_NOTIMPL zurückgeben.
OLEIVERB_INPLACEACTIVATE (-5)	Aktiviert ein Objekt, ohne Tools wie Menüs und Symbolleisten anzuzeigen, die Endbenutzer das Verhalten oder die Darstellung des Objekts ändern müssen. Durch einen Einfachenklick auf ein solches Objekt wird die Anzeige seiner Benutzeroberflächentools mit seinem Container ausgehandelt. Wenn der Container ablehnt, bleibt das Objekt aktiv, ohne dass seine Tools angezeigt werden.
OLEIVERB_DISCARDUNDOSTATE (-6)	Wird verwendet, um -Objekte anzuweisen, jeden Rückgängig-Zustand zu verwerfen, den sie beibehalten können, ohne das Objekt zu deaktivieren.

Hinweise für Anrufer

Container rufen IOleObject::D oVerb als Teil der Initialisierung eines neu erstellten Objekts auf. Vor dem Aufruf sollten Container zunächst IOleObject::SetClientSite aufrufen, um das Objekt über seinen Anzeigespeicherort zu informieren, und IOleObject::SetHostNames , um das Objekt darauf hinzuweisen, dass es sich um ein eingebettetes Objekt handelt, und um geeignete Änderungen an der Benutzeroberfläche der Objektanwendung auszulösen, um ein Bearbeitungsfenster zu öffnen.

IOleObject::D oVerb führt die OLE-Serveranwendung automatisch aus. Wenn während der Verbausführung ein Fehler auftritt, wird die Objektanwendung heruntergefahren.

Wenn ein Endbenutzer ein Verb auf andere Weise aufruft, als einen Befehl aus einem Menü auszuwählen (z. B. durch Doppelklicken oder seltener durch Einenklick auf ein Objekt), sollte der Container des Objekts einen Zeiger auf eine Windows-MSG-Struktur übergeben, die die entsprechende Meldung enthält. Wenn der Endbenutzer beispielsweise ein Verb durch Doppelklicken auf das Objekt aufruft, sollte der Container eine MSG-Struktur übergeben, die WM_LBUTTONDBLCLK, WM_MBUTTONDBLCLK oder WM_RBUTTONDBLCLK enthält. Wenn der Container keine Nachricht übergibt, sollte lpmsg auf NULL festgelegt werden. Das -Objekt sollte den hwnd-Member der übergebenen MSG-Struktur ignorieren, kann aber alle anderen MSG-Member verwenden.

Wenn der Einbettungscontainer des Objekts IOleObject::D oVerb aufruft, entspricht der an IOleObject::D oVerb übergebene Clientstandortzeiger (pClientSite) dem des Einbettungsstandorts. Wenn das eingebettete Objekt eine Linkquelle ist, ist der an IOleObject::D oVerb übergebene Zeiger der Clientstandort des Verknüpfenden Clients.

Wenn IOleObject::D oVerb für einen OLE-Link aufgerufen wird, wird möglicherweise OLE_E_CLASSDIFF oder MK_CONNECTMANUALLY zurückgegeben. Das Linkobjekt gibt den vorherigen Fehler zurück, wenn die Linkquelle einer Konvertierung unterzogen wurde, während der Link passiv war. Das link-Objekt gibt den letzten Fehler zurück, wenn sich die Linkquelle auf einem Netzlaufwerk befindet, das derzeit nicht mit dem Computer des Aufrufers verbunden ist. Die einzige Möglichkeit, einen Link unter diesen Bedingungen zu verbinden, besteht darin, zuerst IUnknown::QueryInterface aufzurufen, nach IOleLink zu fragen, einen Bindungskontext zuzuweisen und die Linkquelle auszuführen, indem IOleLink::BindToSource aufgerufen wird.

Containeranwendungen, die keine allgemeine direkte Aktivierung unterstützen, können weiterhin die Parameter hwndParent und lprcPosRect verwenden, um die direkte Wiedergabe von Multimediadateien zu unterstützen. Container müssen gültige hwndParent - und lprcPosRect-Parameter an IOleObject::D oVerb übergeben.

Einige Codebeispiele übergeben den Lindex-Wert -1 anstelle von Null. Der Wert -1 funktioniert, sollte jedoch zugunsten von 0 (null) vermieden werden. Der Lindex-Parameter ist ein reservierter Parameter. Aus Gründen der Konsistenz empfiehlt Microsoft, allen reservierten Parametern einen Nullwert zuzuweisen.

Hinweise für Implementierer

Zusätzlich zu den oben genannten Verben kann ein Objekt in seiner OLEVERB-Struktur zusätzliche Verben definieren, die für sich selbst spezifisch sind. Positive Zahlen bezeichnen diese objektspezifischen Verben. Ein -Objekt sollte jede unbekannte positive Verbnummer so behandeln, als wäre es das primäre Verb und gibt OLEOBJ_S_INVALIDVERB an die aufrufende Funktion zurück. Das Objekt sollte Verben mit negativen Zahlen ignorieren, die es nicht erkennt, und E_NOTIMPL zurückgeben.

Wenn das ausgeführte Verb das Objekt in den Status "Wird ausgeführt" versetzt, sollten Sie das Objekt in der ausgeführten Objekttabelle (ROT) registrieren, auch wenn die Serveranwendung keine Verknüpfung unterstützt. Die Registrierung ist wichtig, da das Objekt irgendwann als Quelle eines Links in einem Container dienen kann, der Links zu Einbettungen unterstützt. Durch die Registrierung des Objekts bei rot kann der Linkclient direkt einen Zeiger auf das Objekt abrufen, anstatt den Container des Objekts durchlaufen zu müssen. Rufen Sie zum Durchführen der Registrierung IOleClientSite::GetMoniker auf, um den vollständigen Moniker des Objekts abzurufen, rufen Sie die GetRunningObjectTable-Funktion auf, um einen Zeiger auf rot zu erhalten, und rufen Sie dann IRunningObjectTable::Register auf.

Hinweis Wenn das Objekt den Ausführungsstatus verlässt, denken Sie daran, die Registrierung des Objekts bei rot durch Aufrufen von IOleObject::Close zu widerrufen. Wenn das Containerdokument des Objekts umbenannt wird, während das Objekt ausgeführt wird, sollten Sie die Registrierung des Objekts widerrufen und es mit dem neuen Namen erneut bei rot registrieren. Der Container sollte das Objekt über seinen neuen Moniker informieren, indem er entweder IOleObject::SetMoniker aufruft oder auf den Aufruf von IOleClientSite::GetMoniker des Objekts reagiert.

Wenn ein Fenster als Ergebnis von IOleObject::D oVerb angezeigt wird, ist es sehr wichtig, dass das Objekt SetForegroundWindow explizit im Bearbeitungsfenster aufruft. Dadurch wird sichergestellt, dass das Fenster des Objekts für den Benutzer sichtbar ist, auch wenn es ursprünglich von einem anderen Prozess verdeckt wurde. Weitere Informationen finden Sie unter SetForegroundWindow und SetActiveWindow.

Anforderungen

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