IMAPIForm::DoVerb

The IMAPIForm::DoVerb method requests that the form perform whatever tasks it associates with a specific verb.

Quick Info

HRESULT DoVerb(
  LONG iVerb,                        
  LPMAPIVIEWCONTEXT lpViewContext,   
  ULONG hwndParent,                  
  LPCRECT lprcPosRect                
);

Parameters

iVerb: [in] Number associated with one of the form's verbs.
lpViewContext: [in] Pointer to a view context object. The lpViewContext parameter can be NULL.
hwndParent: [in] Handle of the parent window for any dialog boxes or windows this method displays. The hwndParent parameter should be NULL if the dialog box or window is not modal.
lprcPosRect: [in] Pointer to a Win32 RECT structure containing the form's window size and position.

Return Values

S_OK: The verb was successfully invoked.
OLEOBJ_S_CANNOT_DOVERB_NOW: The verb represented by the iVerb parameter is valid, but the form cannot perform the operations associated with it at the present time.

Remarks

Form viewers call the IMAPIForm::DoVerb method to request that the form perform the tasks that it associates with each of the verbs that the form supports.

Each of the supported verbs is identified by a numeric value, passed to DoVerb in the iVerb parameter. Typical implementations of DoVerb contain a switch statement that tests the values that are valid for the iVerb parameter for the form.

Notes to Implementers

If the form viewer specifies a view context in the lpViewContext parameter, use it in your DoVerb implementation rather than the view context passed in an earlier call to the IMAPIForm::SetViewContext method. Make whatever changes that are necessary to your internal data structures and do not save the view context.

Perform the following tasks in your DoVerb implementation:

Execute whatever code is necessary for the particular verb associated with the iVerb parameter.
If necessary, restore the original view context.
If an unknown verb number was passed in, return MAPI_E_NO_SUPPORT. Otherwise, return a result based on the success or failure of whatever verb was executed.
Shut the form down. It is always your responsibility to shut down after completing a DoVerb call.

Some verbs, such as Print, should be modal with respect to the DoVerb call — that is, the indicated operation must be finished before the DoVerb call returns.

To obtain the RECT structure used by a form's window, call the Win32 function GetWindowRect.

Do not save the handle in the hwndParent parameter because although it usually remains valid until the completion of DoVerb, it can be destroyed immediately upon the call's return.

Notes to Callers

You can make nonmodal verbs act as modal verbs by pointing lpViewContext to a view context implementation that returns the VCSTATUS_MODAL flag from its GetViewStatus method.

For more information about verbs in MAPI, see Form Verbs. For more information about how verbs are handled in OLE, see the OLE Programmer's Reference.