One of the values in the following table is returned.

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 DoVerbin response to some user action, such as double-clicking the object.

The various actions available for a given object are enumerated in an OLEVERBstructure, which the container obtains by calling EnumVerbs.

DoVerbmatches the value of iVerbagainst the iVerbmember of the structure to determine which verb to invoke.

Through 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 verbs are defined by OLE:

OLEIVERB_PRIMARY (0L)

Specifies the action that occurs when a 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.

OLEIVERB_SHOW (–1)

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.

OLEIVERB_OPEN (–2)

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.

OLEIVERB_HIDE (–3)

Causes an object to remove its user interface from the view. Applies only to objects that are activated in-place.

OLEIVERB_UIACTIVATE (–4)

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 E_NOTIMPL.

OLEIVERB_INPLACEACTIVATE (–5)

Activates an object in place without displaying tools, such as menus and toolbars, that 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.

OLEIVERB_DISCARDUNDOSTATE (–6)

Used to tell objects to discard any undo state that they might be maintaining without deactivating the object.

To determine whether the platform supports this interface, see Determining Supported COM APIs.

Containers call DoVerbas part of initializing a newly created object.

Before making the call, containers should do the following:

• Call IOleObject::SetClientSiteto inform the object of its display location
  
  
• Call 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, DoVerbautomatically runs the OLE server application. If an error occurs during verb execution, the object application is shut down.

If a 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 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 other MSGmembers.

If the object's embedding container calls 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 DoVerbis invoked on an OLE link, it can return OLE_E_CLASSDIFF or MK_CONNECTMANUALLY:

• The link object returns OLE_E_CLASSDIFF when the link source has been subjected to some sort of conversion while the link was passive.
  
  
• The link object returns MK_CONNECTMANUALLY when the link source is on a network drive that is not 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 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 reserved, and for reasons of consistency Microsoft recommends assigning a zero value to all reserved parameters.

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 an 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, register the object in the Running Object Table (ROT) even if its server application does not support linking. Registration is important because the object might at some point 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, do the following:

1. Call IOleClientSite::GetMonikerto get the full moniker of the object,
   
   
2. Call the GetRunningObjectTablefunction to get a pointer to the ROT, and then
   
   
3. Call IRunningObjectTable::Register.
   
   

Note:
When the object leaves the running state, remember to revoke the object's registration with the ROT by calling Close.

Note:
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.

Note:
The container should inform the object of its new moniker 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 is visible to the user even if another process originally obscured it.

For more information about SetForegroundWindowand SetActiveWindow, see the Windows SDK.