IMAPIForm::DoVerb
Applies to: Outlook 2013 | Outlook 2016
Requests that the form perform whatever tasks it associates with a specific verb.
HRESULT DoVerb(
LONG iVerb,
LPMAPIVIEWCONTEXT lpViewContext,
ULONG_PTR hwndParent,
LPCRECT lprcPosRect
);
Parameters
iVerb
[in] The number associated with one of the form's verbs.
lpViewContext
[in] A pointer to a view context object. The lpViewContext parameter can be null.
hwndParent
[in] A handle to the parent window of 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] A pointer to a Win32 RECT structure that contains the size and position of the form's window.
Return value
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 currently associated with it.
Remarks
Form viewers call the IMAPIForm::DoVerb method to request that the form perform the tasks that it associates with each verb 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 instead of the view context passed in an earlier call to the IMAPIForm::SetViewContext method. Make whatever changes 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 that is 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.
Close the form. It is always your responsibility to close the form after a DoVerb call completes.
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 GetWindowRect function.
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 non-modal verbs act as modal verbs by pointing lpViewContext to a view context implementation that returns the VCSTATUS_MODAL flag from its IMAPIViewContext::GetViewStatus method.
For more information about verbs in MAPI, see Form Verbs. For more information about how verbs are handled in OLE, see OLE and Data Transfer.
MFCMAPI reference
For MFCMAPI sample code, see the following table.
| File | Function | Comment |
|---|---|---|
| MyMAPIFormViewer.cpp |
CMyMAPIFormViewer::CallDoVerb |
MFCMAPI uses the IMAPIForm::DoVerb method to invoke a verb on a form. |