The IMAPISupport::DoCopyTo method copies or moves all properties of one object, except for specifically excluded properties, to another object.
HRESULT DoCopyTo(
LPCIID lpSrcInterface,
LPVOID lpSrcObj,
ULONG ciidExclude,
LPCIID rgiidExclude,
LPSPropTagArray lpExcludeProps,
ULONG ulUIParam,
LPMAPIPROGRESS lpProgress,
LPCIID lpDestInterface,
LPVOID lpDestObj,
ULONG ulFlags,
LPSPropProblemArray FAR * lppProblems
);
[in] Pointer to a property tag array identifying the property tags that should be excluded from the copy or move operation. Passing NULL in the lpExcludeProps parameter indicates that all of the object's properties should be copied or moved. DoCopyTo returns MAPI_E_INVALID_PARAMETER when the cValues member of the SPropTagArray structure pointed to by lpExcludeProps is set to zero.
[in] Pointer to a progress indicator implementation. If NULL is passed in the lpProgress parameter, MAPI provides the progress implementation. The lpProgress parameter is ignored unless the MAPI_DIALOG flag is set in the ulFlags parameter.
DoCopyTo should perform a move operation rather than a copy operation. When this flag is not set, DoCopyTo performs a copy operation.
[out] On input, can be NULL, indicating no need for error information, or a pointer to a pointer to an SPropProblemArray structure. If lppProblems is a valid pointer on input, DoCopyTo returns detailed information about errors in copying one or more properties.
The interface identified by the lpSrcInterface parameter is not supported by the object pointed to by lpSrcObj, or the interface identified by the lpDestInterface parameter is not supported by the object pointed to by lpDestObj.
An attempt was made to access an object for which the caller has insufficient permissions. This error is returned if the destination object is the same as the source object.
The lpSrcInterface parameter is NULL.
The following values can be returned in the SPropProblemArray structure, but not as return values for DoCopyTo. These errors apply to a single property:
The property cannot be modified by the caller because it is a read-only property, computed by the owner of the destination object. This error is not severe; the caller should allow the copy operation to continue.
The IMAPISupport::DoCopyTo method is implemented for message store provider support objects. Message store providers can call DoCopyTo to implement IMAPIProp::CopyTo 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, 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:
PROP_TAG(PT_LONG, 0x8002)
To avoid copying a message's delivery time when copying the message to a different folder, specify PR_MESSAGE_DELIVERY_TIME in the property tag exclude array. To exclude a message's recipient list, add the PR_MESSAGE_RECIPIENTS property to the exclude array. To exclude a message's attachments, add the PR_MESSAGE_ATTACHMENTS property to the array.
Similarly, prevent the copying or moving of a folder or address book container's hierarchy or contents table by including PR_CONTAINER_HIERARCHY or PR_CONTAINER_CONTENTS in the property tag exclude array.
Ignore MAPI_E_COMPUTED errors returned in the SPropProblemArray structure in the lppProblems parameter.
The interface identifier pointed to by lpSrcInterface is usually the same as the interface identifier pointed to by lpDestInterface.
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, include 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 it doesn't recognize.
When you use the rgiidExclude parameter to exclude an interface, it also excludes all interfaces derived from that interface. For example, excluding IMAPIContainer 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 — errors that apply to the operation as a whole — and individual errors — errors that apply to individual properties. These individual errors are placed in an SPropProblemArray structure. You can suppress error reporting at the property level by passing NULL for the property problem array structure parameter rather than a valid pointer.
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 IMAPISupport::GetLastError to retrieve detailed error information.
If CopyTo 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.
IMAPISupport::CopyFolder, IMAPISupport::CopyMessages, IMAPISupport::DoCopyTo, SPropProblemArray, SPropTagArray