Edit

Copying Address Book Entries

  • Article

Applies to: Outlook 2013 | Outlook 2016

Your container's IABContainer::CopyEntries method is called when one or more recipients from the same or another container are to be copied into this container. CopyEntries has four input parameters: an array of entry identifiers representing the recipients to be copied, a window handle for the progress indicator, a progress object pointer, and a flags value. Your provider should display progress if the AB_NO_DIALOG flag is not set and use the progress object from the lpProgress parameter if it is not NULL. If lpProgress is NULL, call IMAPISupport::DoProgressDialog to use the MAPI progress object. For more information about displaying progress, see Displaying a Progress Indicator.

In addition to AB_NO_DIALOG to suppress a progress indicator, one of two other flags can be set to request a type of duplicate entry checking: CREATE_CHECK_DUP_LOOSE or CREATE_CHECK_DUP_STRICT. The CREATE_CHECK_DUP_LOOSE and CREATE_CHECK_DUP_STRICT flags are only suggestions as to how your provider determines duplicate entries and can be ignored. MAPI suggests that your provider implement support for these flags as follows.

Duplicate entry flag Suggested implementation
CREATE_CHECK_DUP_LOOSE
Check if the display name in the entry to be created matches the display name of an entry already in the container.
CREATE_CHECK_DUP_STRICT
Check if both the display name and the search key in the entry to be created match the display name and search key of a container entry.

The last flag, CREATE_REPLACE, indicates that the new entry should replace the existing one if your provider has determined that an entry to be created is a duplicate of an entry already in your container.

If your provider is a personal address book, include the PR_DETAILS_TABLE (PidTagDetailsTable) property in every copy operation. Including the details display table of a copied recipient enables your container to display the details of the recipient rather than having to call the original container to create the display.

To implement IABContainer::CopyEntries

  1. Determine if each entry identifier in the lpEntries parameter is in a format that your provider handles and if it is not, fail and return MAPI_E_INVALID_ENTRYID.

  2. If an entry identifier represents a messaging user, distribution list, or container that your provider handles:

  3. Call your IMAPISupport::OpenEntry method to open the corresponding recipient.

  4. Copy the recipient to your container.

  5. If the entry identifier represents a foreign recipient:

  6. Call your container's IABContainer::CreateEntry method to create a new recipient.

  7. Set initial properties on the new recipient.

  8. Call the new object's IMAPIProp::SaveChanges method to save it.

  9. Update the container's contents table to reflect the new recipient.

  10. Call IMAPISupport::Notify to send a table notification to registered clients.