IMAPIFolder::DeleteMessages

The IMAPIFolder::DeleteMessages method deletes one or more messages.

Quick Info

See IMAPIFolder : IMAPIContainer.

HRESULT DeleteMessages(
  LPENTRYLIST lpMsgList,   
  ULONG ulUIParam,         
  LPMAPIPROGRESS lpProgress,   
  ULONG ulFlags            
);
 

Parameters

lpMsgList

[in] Pointer to an ENTRYLIST structure that contains the number of messages to delete and an array of ENTRYID structures identifying the messages.

ulUIParam

[in] Handle of the parent window for the progress indicator. The ulUIParam parameter is ignored unless the MESSAGE_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 MESSAGE_DIALOG flag is set in ulFlags.

ulFlags

[in] Bitmask of flags that controls how the messages are deleted. The following flag can be set:

MESSAGE_DIALOG

Displays a progress indicator as the operation proceeds.

Return Values

S_OK

The specified message or messages were successfully deleted.

MAPI_W_PARTIAL_COMPLETION

The call succeeded, but not all of the messages were successfully deleted. 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::DeleteMessages method deletes messages from a folder. Messages that do not exist, that have been moved elsewhere, that are open with read/write access, or that are currently submitted cannot be deleted.

Notes to Implementers

When the delete operation involves more than one message, perform the operation as completely as possible for each folder, even if one or more of the messages cannot be deleted. Do not stop the operation prematurely unless a failure occurs that is beyond your control, such as running out of memory, running out of disk space, or corruption in the message store.

During a DeleteMessages call, messages being processed by the MAPI spooler are not deleted; they are left in their parent folders. Do not call the IMsgStore::AbortSubmit method for these messages.

Notes to Callers

Expect these return values under the following conditions:

When DeleteMessages is unable to complete, do not assume that no work was done. DeleteMessages might have been able to delete one or more of the messages before encountering the error.

DeleteMessages returns MAPI_W_PARTIAL_COMPLETION or MAPI_E_NOT_FOUND, depending on the message store's implementation.