Published: July 16, 2012
Copies or moves all properties of one object, except for specifically excluded properties, to another object.
The IMAPISupport::DoCopyTo method is implemented for message store provider support objects. Message store providers can call DoCopyTo to implement the IMAPIProp::CopyTo method for their folders and messages.
By default, DoCopyTo copies or moves all of the properties of one object to another object. Any subobjects in the source object are automatically included in the operation and copied or moved in their entirety.
If any of the copied or moved properties already exist in the destination object, the existing properties are overwritten by the new properties, unless the MAPI_NOREPLACE flag is set in the ulFlags parameter. Existing information in the destination object that is not overwritten is left untouched.
To exclude properties from the copy or move operation, include their property tags in the lpExcludeProps parameter. If you pass the results of using the PROP_TAG macro to build a property tag from a specific identifier in the property tag array, all properties with that identifier will be excluded. For example, the following entry in the property tag array causes all properties with an identifier of 0x8002 to be excluded, regardless of type:
To avoid copying a message's delivery time when you copy the message to a different folder, specify PR_MESSAGE_DELIVERY_TIME (PidTagMessageDeliveryTime) in the property tag exclude array. To exclude a message's recipient list, add the PR_MESSAGE_RECIPIENTS (PidTagMessageRecipients) property to the exclude array. To exclude a message's attachments, add the PR_MESSAGE_ATTACHMENTS (PidTagMessageAttachments) property to the array.
Similarly, to prevent the copying or moving of a folder or address book container's hierarchy or contents table, include PR_CONTAINER_HIERARCHY (PidTagContainerHierarchy) or PR_CONTAINER_CONTENTS (PidTagContainerContents) in the property tag exclude array.
Ignore MAPI_E_COMPUTED errors returned in the SPropProblemArray structure in the lppProblems parameter.
The interface identifier that lpSrcInterface points to is usually the same as the interface identifier that lpDestInterface points to.
If you pass an acceptable interface identifier in lpDestInterface but an invalid pointer in lpDestObj, the results are unpredictable. Most likely this will cause your provider to fail.
Conversely, if you are aware of supplemental information that should not be copied or moved, add the interface identifiers for the interfaces to be excluded in the array passed in the rgiidExclude parameter. For example, if you are copying messages, but not any of their message attachments, pass IID_IMessage in the rgiidExclude array. DoCopyTo ignores any interfaces listed in rgiidExclude that it does not recognize.
When you use the rgiidExclude parameter to exclude an interface, it also excludes all interfaces derived from that interface. For example, excluding the IMAPIContainer interface causes folders or address book containers to be excluded, depending on the type of provider. Do not exclude IMAPIProp or IUnknown because so many interfaces derive from them.
DoCopyTo reports global errors that apply to the operation as a whole, and individual errors that apply to individual properties. These individual errors are put in an SPropProblemArray structure. You can suppress error reporting at the property level by passing NULL, rather than a valid pointer, for the property problem array structure parameter.
If you want to receive information about errors, pass a valid SPropProblemArray structure pointer in the lppProblems parameter. When DoCopyTo returns S_OK, check for possible errors with individual properties in the structure. When DoCopyTo returns an error, no information is returned in the SPropProblemArray structure. Instead, call the IMAPISupport::GetLastError method to retrieve detailed error information.
If DoCopyTo returns S_OK, free the returned SPropProblemArray structure by calling the MAPIFreeBuffer function.
If a global error occurs on the DoCopyTo call, do not use or free the SPropProblemArray structure. Providers should ignore the ulIndex member in SPropProblemArray structures returned by DoCopyTo.