IMAPIForm::ShutdownForm

The IMAPIForm::ShutdownForm method closes the form.

Quick Info

See IMAPIForm : IUnknown.

HRESULT Close(
  ULONG ulSaveOptions  
);

Parameters

ulSaveOptions
[in] Value that controls how or whether data in the form is saved before the form is closed. One of the following values 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 Values

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:

  1. Check that a viewer has not already called ShutdownForm and return E_UNEXPECTED if it has. Although this is unlikely, it is wise to make the check.
  2. Call your form's IUnknown::AddRef method so that storage for your form and any internal data structures remain available until processing is finished.
  3. Determine whether or not 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 SaveMessage method.
  4. Destroy your form's user interface window.
  5. Release your form's message and message site objects by calling their IUnknown::Release methods.
  6. Notify all registered viewers of the pending shutdown by calling their IMAPIViewAdviseSink::OnShutdown methods.
  7. Call IMAPIViewContext::SetAdviseSink to cancel your form's registration for notification by setting the advise sink pointer to NULL.
  8. Call the MAPIFreeBuffer function to free the memory for your form's properties.
  9. Call your form's IUnknown::Release method, matching the AddRef call made in step 2.
  10. 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.

See Also

IMAPIViewAdviseSink::OnShutdown