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
| LONG iVerb,
||//Value representing verb to be performed
| LPMSG lpmsg,
||//Ptr to Windows message
| IOleClientSite *pActiveSite,
||//Ptr to active client site
| LONG lindex,
||//Reserved for future use
| HWND hwndParent,
||//Handle of window containing the object
| LPCRECT lprcPosRect
||//Ptr to object's display rectangle
[in] The number assigned to the verb in the OLEVERB
structure returned by IOleObject::EnumVerbs
[in] Points to the MSG structure describing the event (such as a double-click)
that invoked the verb.
[in] Points to the object's active client site, where the event occurred that
invoked the verb.
[in] Reserved for future use; should be zero.
[in] Handle of the document window containing the object. This and lprcPosRect
together make it possible to open a temporary window for an object, where hwndParent
is the parent window in which the object's window is to be displayed, and lprcPosRect
defines the area available for displaying the object window within that
parent. A temporary window is useful, for example, to a multimedia object that opens
itself for playback but not for editing.
[in] Points to the RECT structure containing the coordinates, in pixels, that
define an object's bounding rectangle in hwndParent
. This and hwndParent
together enable opening multimedia objects for playback but not for editing.
Object successfully invoked specified verb.
set to OLEIVERB_UIACTIVATE or OLEIVERB_INPLACEACTIVATE and object is not
The object handler or link object cannot connect to the link source.
The verb is valid, but in the object's current state it cannot carry out the
was successful but hwndParent
The object does not support any verbs.
Object does not recognize a positive verb number. Verb is treated as
Link source is across a network that is not connected to a drive on this
Class for source of link has undergone a conversion.
Object does not support in-place activation or does not recognize a negative
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
in 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 OLEVERB
structure, which the container obtains by calling IOleObject::EnumVerbs
matches the value of iVerb
against the iVerb
member of the structure to determine which verb to invoke.
, an object, rather than its container, determines which verbs (i.e., 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 table describes the verbs defined by OLE:
Note to Callers
||Specifies the action that occurs when an end-user double-clicks the object in
its container. The object, not the container, determines this action. If the
object supports in-place activation, the primary verb usually activates the
object in place.
||Instructs an object to show itself for editing or viewing. Called to display
newly inserted objects for initial editing and to show link sources. Usually an
alias for some other object-defined verb.
||Instructs an object, including one that otherwise supports in-place
activation, to open itself for editing in a window separate from that of its container.
If the object does not support in-place activation, this verb has the same
semantics as OLEIVERB_SHOW.
||Causes an object to remove its user interface from the view. Applies only to
objects that are activated in-place.
||Activates an object in place, along with its full set of user-interface tools,
including menus, toolbars, and its name in the title bar of the container
window. If the object does not support in-place activation, it should return
||Activates an object in place without displaying tools, such as menus and
toolbars, that end-users need to change the behavior or appearance of the object.
Single-clicking such an object causes it to negotiate the display of its
user-interface tools with its container. If the container refuses, the object remains
active but without its tools displayed.
||Used to tell objects to discard any undo state that they may be maintaining
without deactivating the object.
Containers call IOleObject::DoVerb
as part of initializing a newly created object. Before making the call,
containers should first call IOleObject::SetClientSite
to inform the object of its display location and IOleObject::SetHostNames
to 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 OleActivate
function in OLE 1, IOleObject::DoVerb
automatically 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 MSG
structure containing the appropriate message. For example, if the end-user
invokes a verb by double-clicking the object, the container should pass a MSG
structure containing WM_LBUTTONDBLCLK, WM_MBUTTONDBLCLK, or WM_RBUTTONDBLCLK.
If the container passes no message, lpmsg
should be set to NULL. The object should ignore the hwnd
member of the passed MSG
structure, but can use all the other MSG
If the object's embedding container calls IOleObject::DoVerb
, the client-site pointer (pClientSite
) passed to DoVerb
is the same as that of the embedding site. If the embedded object is a link
source, the pointer passed to DoVerb
is that of the linking client's client site.
is 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. The only way to connect a
link under these conditions is to first call QueryInterface
, ask for IOleLink
, allocate a bind context, and run the link source by calling IOleLink::BindToSource
Container applications that do not support general in-place activation can
still use the hwndParent
parameters to support in-place playback of multimedia files. Containers must
pass valid hwndParent
parameters to IOleObject::DoVerb
Some code samples pass a lindex
value of -1 instead of zero. The value -1 works but should be avoided in
favor of zero. The lindex
parameter is a reserved parameter, and for reasons of consistency Microsoft
recommends assigning a zero value to all reserved parameters.
Notes to Implementors
In addition to the above verbs, an object can define in its OLEVERB
structure additional verbs that are specific to itself. Positive numbers
designate these object-specific verbs. An object should treat any unknown positive
verb 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::GetMoniker
to get the full moniker of the object, call the GetRunningObjectTable
API function to get a pointer to the ROT, and then call IRunningObjectTable::Register
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::SetMoniker
or 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 SetForegroundWindow
on 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 SetForegroundWindow
, see the Win32 SDK
SetForegroundWindow, SetActiveWindow in Win32
- Software for developers
Software for Android Developers
- More information resources
Unix Manual Pages