IMAPIFolder::EmptyFolder
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.
- 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.
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.
Do not call the IMsgStore::AbortSubmit method for messages in the folder that have been submitted. Submitted messages are not deleted.
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.
