Last modified: July 23, 2011
Applies to: Outlook
Copies or moves one or more properties of an object to another object.
The IMAPISupport::DoCopyProps method is implemented for message store provider support objects. Message store providers can call DoCopyProps to implement the IMAPIProp::CopyProps method for their folders and messages. DoCopyProps copies or moves the properties that are identified in the property tag array pointed to by lpIncludeProps and that are present in the object pointed to by lpSrcObj.
When you copy properties between objects of the same type, such as two messages, the lpSrcInterface and lpDestInterface parameters must contain the same interface identifier, and the lpSrcObj and lpDestObj parameters must point to objects of the same type. If lpDestInterface is set to NULL, DoCopyProps returns MAPI_E_INVALID_PARAMETER. If you set lpDestInterface to an acceptable interface identifier, but set lpDestObj to an invalid pointer, the results are unpredictable. Most likely your provider will fail.
Set the MAPI_NOREPLACE flag if you do not want any of the properties in the destination object to be overwritten. Properties in the destination object that exist in the source object and are not overwritten are not deleted or modified.
To copy a message's recipient list, include the PR_MESSAGE_RECIPIENTS (PidTagMessageRecipients) property in the property tag array pointed to by the lpIncludeProps parameter. To copy the message's attachments, include the PR_MESSAGE_ATTACHMENTS (PidTagMessageAttachments) property.
To copy 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 array. To include a folder's associated contents table, include the PR_FOLDER_ASSOCIATED_CONTENTS (PidTagFolderAssociatedContents) property in the array.
If subfolders are copied or moved, their contents are copied or moved in their entirety, regardless of the use of properties indicated by the SPropTagArray structure.
DoCopyProps reports global errors that occur with the operation as a whole, and individual errors that occur with one or more of the 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 DoCopyProps returns S_OK, check for possible errors with individual properties in the structure. When DoCopyProps returns an error, no information is returned in the SPropProblemArray structure. Instead, call the IMAPISupport::GetLastError method to retrieve detailed error information.
If DoCopyProps returns S_OK, free the returned SPropProblemArray structure by calling the MAPIFreeBuffer function.