Important: |
---|
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist. |
This method requests an object to perform an action in response to an end-user's action. The possible actions are enumerated for the object in IOleObject::EnumVerbs.
HRESULT DoVerb( LONG iVerb , LPMSG lpmsg , IOleClientSite * pActiveSite, LONG lindex , HWND hwndParent , LPCRECT lprcPosRect );
Parameters
Return Values
One of the values described in the following table is returned.
Value | Description |
---|---|
S_OK | Object successfully invoked specified verb. |
OLE_E_NOT_INPLACEACTIVE | The iVerbparameter is set to OLEIVERB_UIACTIVATE or OLEIVERB_INPLACEACTIVATE and object is not already visible. |
OLE_E_CANT_BINDTOSOURCE | The object handler or link object cannot connect to the link source. |
DV_E_LINDEX | Invalid lindex. |
OLEOBJ_S_CANNOT_DOVERB_NOW | The verb is valid, but in the object's current state it cannot carry out the corresponding action. |
OLEOBJ_S_INVALIDHWND | DoVerbwas successful but hwndParentis invalid. |
OLEOBJ_E_NOVERBS | The object does not support any verbs. |
OLEOBJ_S_INVALIDVERB | Object does not recognize a positive verb number. Verb is treated as OLEIVERB_PRIMARY. |
MK_E_CONNECT | Link source is across a network that is not connected to a drive on this machine. |
OLE_E_CLASSDIFF | Class for source of link has undergone a conversion. |
E_NOTIMPL | Object does not support in-place activation or does not recognize a negative verb number. |
Remarks
A "verb" is an action that an OLE object takes in response to a message from its container. An object's container, or a client linked to the object, normally calls IOleObject::DoVerbin response to some end-user action, such as double-clicking on the object. The various actions that are available for a given object are enumerated in an OLEVERBstructure, which the container obtains by calling IOleObject::EnumVerbs. IOleObject::DoVerbmatches the value of iVerbagainst the iVerbmember of the structure to determine which verb to invoke.
Through IOleObject::EnumVerbs, an object, rather than its container, determines which verbs (actions) it supports. OLE 2 defines seven verbs that are available, but not necessarily useful, to all objects. In addition, each object can define additional verbs that are unique to it. The following list describes the verbs defined by OLE:
Note to Callers
Containers call IOleObject::DoVerbas part of initializing a newly created object. Before making the call, containers should first call IOleObject::SetClientSiteto inform the object of its display location and IOleObject::SetHostNamesto alert the object that it is an embedded object and to trigger appropriate changes to the user interface of the object application in preparation for opening an editing window.
Like the OleActivatefunction in OLE 1, IOleObject::DoVerbautomatically runs the OLE server application. If an error occurs during verb execution, the object application is shut down.
If an end user invokes a verb by some means other than selecting a command from a menu (say, by double-clicking or, more rarely, single-clicking an object), the object's container should pass a pointer ( lpmsg) to a Windows MSGstructure that contains the appropriate message. For example, if the end user invokes a verb by double-clicking the object, the container should pass a MSGstructure that contains WM_LBUTTONDBLCLK, WM_MBUTTONDBLCLK, or WM_RBUTTONDBLCLK. If the container passes no message, lpmsgshould be set to NULL. The object should ignore the hwndmember of the passed MSGstructure, but can use all the other MSGmembers.
If the object's embedding container calls IOleObject::DoVerb, the client-site pointer ( pClientSite) passed to DoVerbis the same as that of the embedding site. If the embedded object is a link source, the pointer passed to DoVerbis that of the linking client's client site.
When IOleObject::DoVerbis invoked on an OLE link, it may return OLE_E_CLASSDIFF or MK_CONNECTMANUALLY. The link object returns the former error when the link source has been subjected to some sort of conversion while the link was passive. The link object returns the latter error when the link source is located on a network drive that is not currently connected to the caller's computer.
Container applications that do not support general in-place activation can still use the hwndParentand lprcPosRectparameters to support in-place playback of multimedia files. Containers must pass valid hwndParentand lprcPosRectparameters to IOleObject::DoVerb.
Some code samples pass a lindexvalue of –1 instead of zero. The value –1 works but should be avoided in favor of zero. The lindexparameter is a reserved parameter, and for reasons of consistency Microsoft recommends assigning a zero value to all reserved parameters.
Notes to Implementers
In addition to the above verbs, an object can define in its OLEVERBstructure additional verbs that are specific to itself. Positive numbers designate these object-specific verbs. An object should treat any unknown positiveverb number as if it were the primary verb and return OLE_S_INVALIDVERB to the calling function. The object should ignore verbs with negative numbers that it does not recognize and return E_NOTIMPL.
If the verb being executed places the object in the running state, you should register the object in the Running Object Table (ROT) even if its server application doesn't support linking. Registration is important because the object at some point may serve as the source of a link in a container that supports links to embeddings. Registering the object with the ROT enables the link client to get a pointer to the object directly, instead of having to go through the object's container. To perform the registration, call IOleClientSite::GetMonikerto get the full moniker of the object, call the GetRunningObjectTablefunction to get a pointer to the ROT, and then call IRunningObjectTable::Register.
Note When the object leaves the running state, remember to revoke the object's registration with the ROT by calling IOleObject::Close. If the object's container document is renamed while the object is running, you should revoke the object's registration and re-register it with the ROT, using its new name. The container should inform the object of its new moniker either by calling IOleObject::SetMonikeror by responding to the object's calling IOleClientSite::GetMoniker.
When showing a window as a result of DoVerb, it is very important for the object to explicitly call SetForegroundWindowon its editing window. This ensures that the object's window will be visible to the user even if another process originally obscured it. For more information about SetForegroundWindowand SetActiveWindow, see the Platform SDK.
Requirements
Runs on | Versions | Defined in | Include | Link to |
---|---|---|---|---|
Windows CE OS | 2.0 and later | Oleidl.h |
Note This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.