Share via

IMAPIFolder::EmptyFolder

  • Article

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

Deletes all messages and subfolders from a folder without deleting the folder itself.

HRESULT EmptyFolder(
  ULONG_PTR ulUIParam,
  LPMAPIPROGRESS lpProgress,
  ULONG ulFlags
);

Parameters

  • ulUIParam
    [in] A handle to the parent window of the progress indicator. The ulUIParam parameter is ignored unless the FOLDER_DIALOG flag is set in the ulFlags parameter.

  • lpProgress
    [in] A pointer to a progress object that displays a progress indicator. If NULL is passed in lpProgress, the message store provider displays a progress indicator by using the MAPI progress object implementation. The lpProgress parameter is ignored unless the FOLDER_DIALOG flag is set in the ulFlags parameter.

  • ulFlags
    [in] A bitmask of flags that controls how the folder is emptied. The following flags can be set:

    • DEL_ASSOCIATED
      Deletes all subfolders, including subfolders that contain messages with associated content. The DEL_ASSOCIATED flag has meaning only for the top-level folder the call acts on.

    • DELETE_HARD_DELETE
      Permanently removes all messages, including soft-deleted ones.

    • FOLDER_DIALOG
      Displays a progress indicator while the operation proceeds.

Return Value

  • S_OK
    The folder was successfully emptied.

  • MAPI_W_PARTIAL_COMPLETION
    The call succeeded, but the folder was not completely emptied. When this warning is returned, the call should be handled as successful. To test for this warning, use the HR_FAILED macro. For more information, see Using Macros for Error Handling.

Remarks

The IMAPIFolder::EmptyFolder method deletes all of a folder's contents without deleting the folder itself.

During an EmptyFolder call, submitted messages are not deleted.

A folder's associated contents include messages that are used to describe views, rules, custom forms, and custom solution storage, and can also include form definitions.

Notes to Implementers

Do not call the IMsgStore::AbortSubmit method for messages in the folder that have been submitted. Submitted messages are not deleted.

Notes to Callers

Expect these return values under the following conditions.

Condition

Return value

EmptyFolder has successfully emptied the folder.

S_OK

EmptyFolder was unable to completely empty the folder.

MAPI_W_PARTIAL_COMPLETION

EmptyFolder was unable to complete.

Any error value

When EmptyFolder is unable to complete, do not assume that no work was done. EmptyFolder might have been able to delete some of the folder's contents before encountering the error.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File

Function

Comment

MsgStoreDlg.cpp

CMsgStoreDlg::OnEmptyFolder

MFCMAPI uses the IMAPIFolder::EmptyFolder method to delete the contents of the specified folder.

See Also

Reference

IMsgStore::AbortSubmit

IMAPIFolder : IMAPIContainer

Concepts

MFCMAPI as a Code Sample

Using Macros for Error Handling