IMAPISupport::DoCopyProps
The IMAPISupport::DoCopyProps
method copies or moves one or more properties of an object to another object.
Quick Info
See IMAPISupport
: IUnknown.
HRESULT DoCopyProps(
|
LPCIID lpSrcInterface, |
|
|
LPVOID lpSrcObj, |
|
|
LPSPropTagArray lpIncludeProps, |
|
|
ULONG ulUIParam, |
|
|
LPMAPIPROGRESS lpProgress, |
|
|
LPCIID lpDestInterface, |
|
|
LPVOID lpDestObj, |
|
|
ULONG ulFlags, |
|
|
LPSPropProblemArray FAR * lppProblems |
|
|
) |
|
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.
lpIncludeProps
[in] Pointer
to an SPropTagArray
structure holding a counted array of property tags indicating the
properties to copy or move. The lpIncludeProps parameter cannot be NULL.
ulUIParam
[in] Handle
of the parent window for the progress indicator.
lpProgress
[in] Pointer
to an implementation of a progress indicator. If NULL is passed in the lpProgress
parameter, the progress indicator is displayed using MAPI s 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 properties that are copied or moved.
lpDestObj
[in] Pointer
to the object to receive the copied or moved properties.
ulFlags
[in] Bitmask
of flags that controls how the copy or move operation is performed. The
following flags can be set:
MAPI_DIALOG
Allows the
display of a progress indicator.
MAPI_MOVE
DoCopyProps should perform a move operation rather than a copy
operation. When this flag is not set, DoCopyProps performs a copy
operation.
MAPI_NOREPLACE
Existing
properties in the destination object should not be overwritten. When this flag
is not set, DoCopyProps overwrites existing properties.
lppProblems
[in, 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, DoCopyProps returns detailed information about errors in copying
one or more properties.
Return Values
S_OK
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
source object or the interface identified by the lpDestInterface
parameter is not supported by the destination object.
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.
The following
values can be returned in the SPropProblemArray structure, but not
as return values for DoCopyProps. These errors apply to a single
property:
MAPI_E_BAD_CHARWIDTH
Either the
MAPI_UNICODE flag was set and DoCopyProps does not support Unicode, or
MAPI_UNICODE was not set and DoCopyProps 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::DoCopyProps
method is implemented for message store provider support objects. Message store
providers can call IMAPISupport::DoCopyProps to implement IMAPIProp::CopyProps for their folders and
messages. IMAPISupport::DoCopyProps copies or moves the properties
identified in the property tag array pointed to by lpIncludeProps that
are present in the object pointed to by lpSrcObj.
Notes to Callers
When copying
properties between like objects, such as between two messages, the lpSrcInterface
and lpDestInterface parameters must contain the same interface
identifier and lpSrcObj and lpDestObj parameters must point to
objects of the same type. If lpDestInterface is set to NULL, then 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 property in the property tag
array pointed to by lpIncludeProps. To copy the message s attachments,
include the PR_MESSAGE_ATTACHMENTS property.
To copy a
folder or address book container s hierarchy or contents table, include PR_CONTAINER_HIERARCHY or PR_CONTAINER_CONTENTS in the property tag array. To
include a folder s associated contents table, include the PR_FOLDER_ASSOCIATED_CONTENTS 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 or errors that occur with the operation as a whole and individual errors, or errors that occur with one
or more of the 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 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 IMAPISupport::GetLastError to retrieve detailed error
information.
If DoCopyProps
returns S_OK, free the returned SPropProblemArray structure by calling
the MAPIFreeBuffer
function.
For more
information about calling IMAPISupport::DoCopyProps, see Using a
Support Object for Copying.
See Also