IMAPISupport::DoCopyTo

The IMAPISupport::DoCopyTo method copies or moves all properties of one object, except for specifically excluded properties, to another object.

Quick Info

See IMAPISupport : IUnknownA6YDUA.

HRESULT DoCopyTo(

Parameters

lpSrcInterface

[in] Pointer to the interface identifier (IID) representing the interface to be used to access the object with the properties to be copied or moved.

lpSrcObj

[in] Pointer to the object with the properties to be copied or moved.

ciidExclude

[in] Count of interfaces to exclude when copying or moving properties.

rgiidExclude

[in] Array of interface identifiers indicating interfaces that should not be used when copying or moving supplemental information to the destination object.

lpExcludeProps

[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.

ulUIParam

[in] Handle of the parent window for the progress indicator.

lpProgress

[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.

lpDestInterface

[in] Pointer to the interface identifier representing the interface to be used to access the object to receive the copied or moved properties.

lpDestObj

[in] Pointer to the object to receive the copied or moved properties.

ulFlags

[in] Bitmask of flags that controls the copy or move operation. The following flags can be set:

MAPI_DIALOG

Allows the display of a progress indicator.

MAPI_MOVE

DoCopyTo should perform a move operation rather than a copy operation. When this flag is not set, DoCopyTo performs a copy operation.

MAPI_NOREPLACE

Existing properties in the destination object should not be overwritten. When this flag is not set, DoCopyTo overwrites existing properties.

lppProblems

[out] On input, can be NULL, indicating no need for error information, or a pointer to a pointer to an SPropProblemArray.R6Y64 structure. If lppProblems is a valid pointer on input, DoCopyTo returns detailed information about errors in copying one or more properties.

Return Values

S_OK

The properties have been successfully copied or moved.

MAPI_E_COLLISION

A property to be copied or moved already exists in the destination object and the MAPI_NOREPLACE flag is set.

MAPI_E_FOLDER_CYCLE

The source object directly or indirectly contains the destination object. Significant work might have been performed before this condition was discovered, so the source and destination objects might be partially modified.

MAPI_E_INTERFACE_NOT_SUPPORTED

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.

MAPI_E_NO_ACCESS

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.

MAPI_E_INVALID_PARAMETER

The lpSrcInterface parameter is NULL.

The following values can be returned in the SPropProblemArray.R6Y64 structure, but not as return values for DoCopyTo. These errors apply to a single property:

MAPI_E_BAD_CHARWIDTH

Either the MAPI_UNICODE flag was set and DoCopyTo does not support Unicode, or MAPI_UNICODE was not set and DoCopyTo only supports Unicode.

MAPI_E_COMPUTED

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.

MAPI_E_INVALID_TYPE

The property type is invalid.

MAPI_E_UNEXPECTED_TYPE

The property type is not the type expected by the caller.

Remarks

The IMAPISupport::DoCopyTo method is implemented for message store provider support objects. Message store providers can call IMAPISupport::DoCopyTo to implement IMAPIProp::CopyTo1_YJNNR for their folders and messages.

DoCopyTo by default 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.

Notes to Callers

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_TIMEKARQ1N in the property tag exclude array. To exclude a message s recipient list, add the PR_MESSAGE_RECIPIENTS11I0I35 property to the exclude array. To exclude a message s attachments, add the PR_MESSAGE_ATTACHMENTS4HE.45 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_S8XM0 or PR_CONTAINER_CONTENTSKJXKKY 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.R6Y64 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::GetLastErrorHW29U0 to retrieve detailed error information.

If CopyTo returns S_OK, free the returned SPropProblemArray structure by calling the MAPIFreeBuffer16U06F 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.

For more information about calling IMAPISupport::DoCopyTo, see Using a Support Object for Copying2_KSUGH.

See Also