IMAPIFolder::CopyMessages

The IMAPIFolder::CopyMessages method copies or moves one or more messages.

Quick Info

See IMAPIFolder : IMAPIContainer.

HRESULT CopyMessages(
  LPENTRYLIST lpMsgList,   
  LPCIID lpInterface,      
  LPVOID lpDestFolder,     
  ULONG ulUIParam,         
  LPMAPIPROGRESS lpProgress,   
  ULONG ulFlags            
);
 

Parameters

lpMsgList

[in] Pointer to an array of ENTRYLIST structures that identify the message or messages to copy or move.

lpInterface

[in] Pointer to the interface identifier (IID) representing the interface to be used to access the destination folder pointed to by the lpDestFolder parameter. Passing NULL results in the service provider returning the standard folder interface, IMAPIFolder. Clients must pass NULL. Other callers can set the lpInterface parameter to IID_IUnknown, IID_IMAPIProp, IID_IMAPIContainer, or IID_IMAPIFolder.

lpDestFolder

[in] Pointer to the open folder to receive the copied or moved messages.

ulUIParam

[in] Handle of the parent window for any dialog boxes or windows this method displays. The ulUIParam parameter is ignored unless the client sets the MESSAGE_DIALOG flag in the ulFlags parameter and passes NULL in the lpProgress 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 copy or move operation is accomplished. The following flags can be set:

MAPI_DECLINE_OK

Informs the message store provider to immediately return MAPI_E_DECLINE_COPY if it implements CopyMessage by calling the support object's IMAPISupport::DoCopyTo or IMAPISupport::DoCopyProps method.

MESSAGE_DIALOG

Displays a progress indicator as the operation proceeds.

MESSAGE_MOVE

The message or messages are to be moved rather than copied. If MESSAGE_MOVE is not set, the messages are copied.

Return Values

S_OK

The message or messages have been successfully copied or moved.

MAPI_E_DECLINE_COPY

The provider implements this method by calling a support object method and the caller has passed the MAPI_DECLINE_OK flag.

MAPI_W_PARTIAL_COMPLETION

The call succeeded, but not all entries were successfully copied or moved. 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::CopyMessages method copies or moves messages to another folder.

Messages that are open with read/write access can be moved or copied.

Notes to Implementers

If you are copying messages to another message store without using the IMAPISupport::CopyMessages method, you must first call IMAPIFolder::SetReadFlags with the GENERATE_RECEIPT_ONLY flag set. The receiving message store is not responsible for generating read reports for the copied or moved messages. If you are calling IMAPISupport::CopyMessages to implement IMAPIFolder::CopyMessages, do not make the SetReadFlags call. MAPI will take care of it.

Move or copy the messages in any order and generate read status reports in any order. That is, you can finish copying messages before generating any of the read status reports or send the reports before beginning the copy. However, read reports should be sent for all messages to be copied, regardless of whether or not the copy is successful.

When the copy or move operation involves more than one message, perform the operation as completely as possible. 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.

Try to maintain entry identifiers across move or copy operations.

Send notifications when moving or copying messages so that clients are forewarned that their calls to the messages' IMAPIProp::SaveChanges methods may fail.

Do not include a message's status in the copy or move operation. Moving or copying a message status greatly affects performance.

Notes to Callers

Use CopyMessages for populating search-results folders, where messages are often grouped by parent folder.

Expect these return values under the following conditions:

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