IMAPISupport::CopyFolder

The IMAPISupport::CopyFolder method copies or moves a folder from its current parent folder to another parent folder.

Quick Info

See IMAPISupport : IUnknown.

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

Parameters

lpSrcInterface

[in] Pointer to the interface identifier (IID) representing the interface to be used to access the parent folder of the folder to be copied or moved.

lpSrcFolder

[in] Pointer to the parent folder of the folder to be copied or moved.

cbEntryID

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

lpEntryID

[in] Pointer to the entry identifier of the folder to be copied or moved.

lpInterface

Reserved; must be NULL.

lpDestFolder

[in] Pointer to the folder that is to receive the folder to be copied or moved.

lpszNewFolderName

[in] Pointer to the name of the copied or moved folder or NULL, indicating that the copied or moved folder should have the same name as the source folder, the folder pointed to by lpEntryID.

ulUIParam

[in] Handle of the window for the progress indicator dialog box and related windows. 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 copy or move operation is accomplished. The following flags can be set:

COPY_SUBFOLDERS

All of the folder's subfolders should be copied or moved. When COPY_SUBFOLDERS is not set for a copy operation, only the folder 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 folder should be moved rather than copied. If FOLDER_MOVE is not set, the folder is copied.

MAPI_UNICODE

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

Return Values

S_OK

The folder has been successfully copied or moved.

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. The operation stops without completing.

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 IMAPISupport::CopyFolder method is implemented for message store provider support objects. Message store providers can call CopyFolder in their implementation of IMAPIFolder::CopyFolder to copy or move a single folder from one parent folder to another.

CopyFolder adds the copied or moved folder as a subfolder of the destination folder.

Notes to Callers

CopyFolder allows simultaneous renaming and moving of folders and the copying or moving of subfolders of the affected folder. To copy or move all subfolders nested within the copied or moved folder, pass the COPY_SUBFOLDERS flag in ulFlags.

Expect these return values under the following conditions:

If CopyFolder returns an error value, do not proceed on the assumption that no work was done. One or more folders could have been copied or moved before CopyFolder experienced the failure.