Share via

IMAPISupport::CopyFolder

  • Article

Applies to: Office 2010 | Outlook 2010 | Visual Studio

Copies or moves a folder from its current parent folder to another parent folder.

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

Parameters

  • lpSrcInterface
    [in] A pointer to the interface identifier (IID) that represents the interface to be used to access the parent folder of the folder to be copied or moved.

  • lpSrcFolder
    [in] A pointer to the parent folder of the folder to be copied or moved.

  • cbEntryID
    [in] The byte count in the entry identifier pointed to by lpEntryID.

  • lpEntryID
    [in] A pointer to the entry identifier of the folder to be copied or moved.

  • lpInterface
    [in] Reserved; must be NULL.

  • lpDestFolder
    [in] A pointer to the folder that is to receive the folder to be copied or moved.

  • lpszNewFolderName
    [in] A pointer to the name of the copied or moved folder; otherwise, NULL, which indicates that the copied or moved folder should have the same name as the source folder (the folder pointed to by lpEntryID).

  • ulUIParam
    [in] A 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] 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 ulFlags.

  • ulFlags
    [in] A 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 instead of 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 Value

  • 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. For more information, see Using Macros for Error Handling.

Remarks

The IMAPISupport::CopyFolder method is implemented for message store provider support objects. Message store providers can call IMAPISupport::CopyFolder in their implementation of IMAPIFolder::CopyFolder to copy or move a single folder from one parent folder to another.

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

Notes to Callers

IMAPISupport::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 in the copied or moved folder, pass the COPY_SUBFOLDERS flag in ulFlags.

Expect the following return values under the following conditions:

Condition

Return value

CopyFolder successfully copied or moved the folder and all its subfolders, if applicable.

S_OK

CopyFolder was unable to successfully copy or move all of the folders.

MAPI_W_PARTIAL_COMPLETION

CopyFolder was unable to complete.

Any error value

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.

See Also

Reference

IMAPISupport : IUnknown