IMAPIFolder::CopyFolder

The IMAPIFolder::CopyFolder method copies or moves a subfolder.

Quick Info

See IMAPIFolder : IMAPIContainer.

HRESULT CopyFolder(
  ULONG cbEntryID,            
  LPENTRYID lpEntryID,        
  LPCIID lpInterface,         
  LPVOID lpDestFolder,        
  LPTSTR lpszNewFolderName,   
  ULONG ulUIParam,            
  LPMAPIPROGRESS lpProgress,   
  ULONG ulFlags               
);
 

Parameters

cbEntryID

[in] Count of bytes in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] Pointer to the entry identifier of the subfolder to copy or move.

lpInterface

[in] Pointer to the interface identifier (IID) representing the interface to be used to access the folder pointed to by the lpDestFolder parameter. Passing NULL results in the service provider returning the standard folder interface, IMAPIFolder. Valid values for lpInterface include IID_IUnknown, IID_IMAPIProp, IID_IMAPIContainer, or IID_IMAPIFolder.

lpDestFolder

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

lpszNewFolderName

[in] Pointer to the name of the copied or moved folder in its new destination. If lpszNewFolderName is set to NULL, the name of the source subfolder is used for the name of the destination folder.

ulUIParam

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

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 the copy or move operation. The following flags can be set:

COPY_SUBFOLDERS

All of the subfolders in the subfolder to be copied should also be copied. When COPY_SUBFOLDERS is not set for a copy operation, only the subfolder identified by lpEntryID is copied. With a move operation, the COPY_SUBFOLDERS behavior is the default regardless of whether the flag is set.

FOLDER_DIALOG

Requests the display of a progress indicator.

FOLDER_MOVE

The subfolder is to be moved rather than copied. If FOLDER_MOVE is not set, the subfolder is copied.

MAPI_DECLINE_OK

Informs the message store provider that if it implements CopyFolder by calling its support object's IMAPISupport::DoCopyTo or IMAPISupport::DoCopyProps method, it should instead immediately return MAPI_E_DECLINE_COPY from CopyFolder.

MAPI_UNICODE

The name of the destination folder is in Unicode format. If the MAPI_UNICODE flag is not set, the folder name is in ANSI format.

Return Values

S_OK

The specified folder has been successfully copied or moved.

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and the message store provider does not support Unicode, or MAPI_UNICODE was not set and the message store provider only supports Unicode.

MAPI_E_COLLISION

The name of the folder being moved or copied is the same as that of a subfolder in the destination folder. The message store provider requires that folder names be unique.

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_E_FOLDER_CYCLE

The source folder directly or indirectly contains the destination folder. Significant work might have been performed before this condition was discovered so the source and destination folder might be partially modified.

MAPI_W_PARTIAL_COMPLETION

The call succeeded, but not all entries were successfully copied. 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::CopyFolder method copies or moves a subfolder from one location to another. The subfolder being copied or moved is added to the destination folder as a subfolder.

Notes to Implementers

When the copy or move operation involves more than one folder, as indicated by the COPY_SUBFOLDERS flag being set, perform the operation as completely as possible for each folder. Sometimes one of the folders to be moved or copied does not exist or has already been moved or copied elsewhere. 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 retain all message entry identifiers in the copied messages. Preserving entry identifiers is not required, but it is recommended.

Notes to Callers

Expect these return values under the following conditions:

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

If an entry identifier for a folder that doesn't exist is passed in lpEntryID, CopyFolder returns MAPI_W_PARTIAL_COMPLETION or MAPI_E_NOT_FOUND, depending on the message store's implementation.

Depending on the message store provider, the entry identifier of the original message may or may not be preserved in the copied message. MAPI recommends that entry identifiers be preserved whenever possible, but it is not a requirement. You can generally depend on the following:

• When moving a folder between two different types of message stores, the entry identifier is guaranteed to change.
• When moving a folder between two message stores of the same type, the entry identifier almost always changes.
• When moving a folder to another location within the same message store, the entry identifier might or might not change, depending on the message store provider.