IMAPIFolder::EmptyFolder

The IMAPIFolder::EmptyFolder method deletes all messages and subfolders from a folder without deleting the folder itself.

Quick Info

See IMAPIFolder : IMAPIContainer.

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

Parameters

ulUIParam

[in] Handle of the parent window for the progress indicator. The ulUIParam parameter is ignored unless the FOLDER_DIALOG flag is set in the ulFlags parameter.

lpProgress

[in] Pointer to a progress object for displaying a progress indicator. If NULL is passed in lpProgress, the message store provider displays a progress indicator using the MAPI progress object implementation. The lpProgress parameter is ignored unless the FOLDER_DIALOG flag is set in ulFlags.

ulFlags

[in] Bitmask of flags that controls how the folder is emptied. The following flags can be set:

DEL_ASSOCIATED

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

FOLDER_DIALOG

Displays a progress indicator while the operation proceeds.

Return Values

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. 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 information includes messages that are used to describe views and form definitions.

Notes to Implementers

Do not call IMsgStore::AbortSubmit 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:

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.