A client can use one of four methods to copy or move a message or a folder:
By setting the appropriate flags and parameters, CopyTo and CopyProps can by made to work just like CopyFolder or CopyMessages. Consider the following issues when deciding which method to call:
You can use the IMAPIProp methods to copy or move either a folder or a message. IMAPIFolder::CopyMessages works with messages only; IMAPIFolder::CopyFolder works with folders only.
Whereas using the IMAPIFolder methods does not require any knowledge of the properties supported by the folder or message to be copied or moved, you must have some knowledge to use the IMAPIProp methods. With IMAPIProp::CopyProps, you must be able to explicitly specify which of the folder or message properties that you want to copy or move. With IMAPIProp::CopyTo, unless you want to copy or move all of the properties, you must explicitly specify which ones should be excluded. For more information about these methods, see Copying Properties.
The number of properties to be copied or moved can affect your decision as to which method to use. If you are copying or moving multiple messages, call IMAPIFolder::CopyMessages. An alternate choice is to call IMAPIProp::CopyProps to copy only the folder's PR_CONTAINER_CONTENTS property. The following procedure shows how to use CopyMessages.
If you want to copy the complete contents of a folder to another folder, call the source folder's IMAPIFolder::CopyFolder or IMAPIProp::CopyTo method.
To copy a few of a folder's properties, call its IMAPIProp::CopyProps method. To copy most of a folder's properties, call IMAPIProp::CopyTo.
For example, if you want to copy a folder's PR_DISPLAY_NAME and PR_COMMENT properties, you have the following options:
In this case, CopyProps is the best choice because it is meant to be used to copy a small set of properties and is the easiest call to implement.
To copy or move only folder properties, without including messages, call the folder's IMAPIProp::CopyTo method and exclude the following properties:
The copy methods can return S_OK, indicating total success, MAPI_W_PARTIAL_COMPLETION, indicating partial success, or an error. If MAPI_W_PARTIAL_COMPLETION is returned, use the HR_FAILED macro to access a more specific error. See Using Macros for Error Handling.
If you copy messages from one message store to another and Unicode is not supported by both, be aware that information can be lost due to code page conversion. Usually you cannot know if the message stores support one or both formats, making it impossible to determine whether to copy text properties as ASCII strings or as Unicode strings. If you support Unicode, try to perform a Unicode copy; if it fails with the error value MAPI_E_BAD_CHARWIDTH, resort to ASCII.