IABContainer::CopyEntries

Article
03/03/2022

Applies to: Outlook 2013 | Outlook 2016

Copies one or more entries, typically messaging users or distribution lists.

HRESULT CopyEntries(
  LPENTRYLIST lpEntries,
  ULONG_PTR ulUIParam,
  LPMAPIPROGRESS lpProgress,
  ULONG ulFlags
);

Parameters

lpEntries

[in] A pointer to an array of ENTRYLIST structures that contains the entry identifiers of the entries to copy.

ulUIParam

[in] The handle to the parent window of any dialog boxes or windows that this method displays. The ulUIParam parameter must be zero if the AB_NO_DIALOG flag is set in the ulFlags parameter.

lpProgress

[in] A pointer to a progress object that displays a progress indicator, or NULL. If lpProgress is NULL, a progress indicator should be displayed by using the progress object supplied by MAPI through the IMAPISupport::DoProgressDialog method. The lpProgress parameter is ignored if the AB_NO_DIALOG flag is set in ulFlags.

ulFlags

[in] A bitmask of flags that controls how the copy operation is performed. The following flags can be set:

AB_NO_DIALOG

Suppresses display of a progress indicator. If this flag is not set, a progress indicator is displayed.

CREATE_CHECK_DUP_LOOSE

Indicates that a loose level of duplicate entry checking should be performed. The implementation of loose duplicate entry checking is provider specific. For example, a provider can define a loose match as any two entries that have the same display name.

CREATE_CHECK_DUP_STRICT

Indicates that a strict level of duplicate entry checking should be performed. The implementation of strict duplicate entry checking is provider specific. For example, a provider can define a strict match as any two entries that have both the same display name and messaging address.

CREATE_REPLACE

Indicates that a new entry should replace an existing one if it is determined that the two are duplicates.

Return value

S_OK

The copy operation succeeded.

MAPI_W_PARTIAL_COMPLETION

The copy operation succeeded overall, but one or more of the entries could not be copied. When this value is returned, the call should be handled as successful. To test for this value, use the HR_FAILED macro. For more information, see Using Macros for Error Handling.

Remarks

The IABContainer::CopyEntries method copies entries from the same container or a different container. A call to CopyEntries is functionally equivalent to making the following calls for each entry to be copied:

The IABContainer::CreateEntry method to create the new entry.
The IMAPIProp::GetProps method to read properties from the entry to be copied.
The IMAPIProp::SetProps method to write properties to the new entry.
The new entry's IMAPIProp::SaveChanges method to perform a save.
The new entry's IUnknown::Release method to release the container's reference.

Notes to implementers

All containers that support the IABContainer::CopyEntries method must be modifiable. Set your container's AB_MODIFIABLE flag in its PR_CONTAINER_FLAGS (PidTagContainerFlags) property to indicate that it is modifiable.

You must support all of the flags; however, the interpretation and use of these flags is implementation specific—that is, you can determine what the semantics of the CREATE_CHECK_DUP_LOOSE and CREATE_CHECK_DUP_STRICT flags mean in the context of your implementation. If you cannot or do not determine whether an entry is a duplicate, always allow the entry to be copied.

If the CREATE_REPLACE flag is set, always copy the entry regardless of whether CREATE_CHECK_DUP_LOOSE or CREATE_CHECK_DUP_STRICT is set and whether the entry is a duplicate.

If CREATE_REPLACE is not set and CREATE_CHECK_DUP_STRICT is set, check for duplicates. If an entry is determined to be a duplicate, do not copy the entry.

You do not need to support CREATE_REPLACE; not supporting CREATE_REPLACE means that you can safely ignore it and always perform a copy.

Return the warning MAPI_W_PARTIAL_COMPLETION only if a nonduplicate entry cannot be copied.

Notes to callers

Use the CREATE_CHECK_DUP_LOOSE and CREATE_CHECK_DUP_STRICT flags to indicate to the provider how you want the container to perform duplicate-entry checking. If you need to have an entry added regardless of whether it is a duplicate, either do not set either of these flags or set the CREATE_REPLACE flag. CREATE_REPLACE indicates that you do not care if an entry is a duplicate; you always want it to replace the original entry.