IABContainer::CopyEntries

The IABContainer::CopyEntries method copies one or more entries, typically messaging users or distribution lists.

Quick Info

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

Parameters

lpEntries

[in] Pointer to an array of ENTRYLIST structures containing the entry identifiers of the entries to copy.

ulUIParam

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

lpProgress

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

ulFlags

[in] 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: Suggests 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 having the same display name.
CREATE_CHECK_DUP_STRICT: Suggests 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 having both the same display name and messaging address.
CREATE_REPLACE: A new entry should replace an existing one if it is determined that the two are duplicates.

Return Values

S_OK: The copy operation succeeded.
MAPI_W_PARTIAL_COMPLETION: The copy operation succeeded overall, but one or more of the recipients could not be copied. When this warning is returned, the call should be handled as successful. To test for this warning, use the HR_FAILED macro. See Using Macros for Error Handling.

Remarks

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

IABContainer::CreateEntry to create the new recipient.
The new recipient's IMAPIProp::SaveChanges method to perform a save.
The new recipient's IUnknown::Release method to release the container's reference.

The personal address book (PAB) supplied by MAPI does not support the CREATE_REPLACE flag. For duplicate entry checking, the PAB defines "loose" to mean that two entries are duplicates if their original display names are equal and "strict" to mean that two entries are duplicates if both their original display names and search keys are equal. In the PAB, the original display name is defined as the transmittable display name, if available. Otherwise, it is simply the display name. Combined with the PR_SEARCH_KEY property, these criteria usually eliminate duplicates in most applications whether automated or user driven.

Notes to Implementers

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

You must support all of the ulFlags flags; however, the interpretation and use of these flags is implementation-specific. That is, you can determine what the semantics of CREATE_CHECK_DUP_LOOSE and CREATE_CHECK_DUP_STRICT mean within 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 CREATE_REPLACE is set, always copy the entry regardless of whether CREATE_CHECK_DUP_LOOSE or CREATE_CHECK_DUP_STRICT is set and whether or not the entry is a duplicate.

If CREATE_REPLACE is not set and CREATE_CHECK_DUP_STRICT is set, check for duplicates. If any entries are determined to be duplicates, do not copy the entry.

You do not need to support the CREATE_REPLACE flag; not supporting CREATE_REPLACE means that you can 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 suggest to the provider how you would like the container to perform duplicate entry checking. If you need to have an entry added regardless of whether or not 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 duplication; you always want it to replace the original entry.