IOleObject::D oVerb-Methode (oleidl.h)
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 |
|---|---|
|
iVerb ist auf OLEIVERB_UIACTIVATE oder OLEIVERB_INPLACEACTIVATE festgelegt, und das Objekt ist noch nicht sichtbar. |
|
Der Objekthandler oder das Linkobjekt kann keine Verbindung mit der Linkquelle herstellen. |
|
Ungültige Lindex. |
|
Das Verb ist gültig, aber im aktuellen Zustand des Objekts kann es die entsprechende Aktion nicht ausführen. |
|
DoVerb war erfolgreich, aber hwndParent ist ungültig. |
|
Das -Objekt unterstützt keine Verben. |
|
Die Linkquelle befindet sich in einem Netzwerk, das nicht mit einem Laufwerk auf diesem Computer verbunden ist. |
|
Die Linkquelle befindet sich in einem Netzwerk, das nicht mit einem Laufwerk auf diesem Computer verbunden ist. |
|
Die Klasse für die Linkquelle wurde konvertiert. |
|
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.
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 |