IMAPIForm::ShutdownForm

Article
03/03/2022

Applies to: Outlook 2013 | Outlook 2016

Closes the form.

HRESULT ShutdownForm(
  ULONG ulSaveOptions
);

Parameters

ulSaveOptions

[in] A value that controls how or whether data in the form is saved before the form is closed. One of the following flags can be set:

SAVEOPTS_NOSAVE

Form data should not be saved.

SAVEOPTS_PROMPTSAVE

The user should be prompted to save any changed data in the form.

SAVEOPTS_SAVEIFDIRTY

Form data should be saved if it has changed since the last save. If no user interface is being displayed, the form can optionally switch to using the functionality for the SAVEOPTS_NOSAVE option.

Return value

S_OK

The form was closed.

E_UNEXPECTED

The form was already closed by a prior call to ShutdownForm.

Remarks

Form viewers call the IMAPIForm::ShutdownForm method to close a form.

Notes to implementers

Perform the following tasks in your implementation of ShutdownForm:

Check that a viewer has not already called ShutdownForm, and return E_UNEXPECTED if it has. Although this is unlikely, you should check.
Call your form's IUnknown::AddRef method so that storage for the form and any internal data structures remain available until processing is finished.
Determine whether there are any unsaved changes to the form's data. Save unsaved data according to how the ulSaveOptions parameter is set by calling your viewer's IMAPIMessageSite::SaveMessage method.
Destroy your form's user interface window.
Release your form's message and message site objects by calling their IUnknown::Release methods.
Notify all registered viewers of the pending shutdown by calling their IMAPIViewAdviseSink::OnShutdown methods.
Call the IMAPIViewContext::SetAdviseSink method to cancel your form's registration for notification by setting the advise sink pointer to null.
Call the MAPIFreeBuffer function to free the memory for your form's properties.
Call your form's IUnknown::Release method, matching the AddRef call made in step 2.
Return S_OK.

Note

After these actions have been completed, the only valid methods on the form object that may be called are those from the IUnknown interface.

Notes to callers

When ShutdownForm returns, regardless of whether it returns an error, release the form by calling its IUnknown::Release method. You can safely ignore any errors returned by ShutdownForm.