IABContainer::CreateEntry

Platform SDK: MAPI

IABContainer::CreateEntry

The IABContainer::CreateEntry method creates a new entry, which can be a messaging user, a distribution list, or another container.

Quick Info

See IABContainer : IMAPIContainer.

HRESULT CreateEntry(
  ULONG cbEntryID,                   
  LPENTRYID lpEntryID,               
  ULONG ulCreateFlags,               
  LPMAPIPROP FAR * lppMAPIPropEntry  
);

Parameters

cbEntryID

[in] Count of the bytes in the entry identifier pointed to by the lpEntryID parameter.

lpEntryID

[in] Pointer to the entry identifier of a template for creating new entries of a particular type.

ulCreateFlags

[in] Bitmask of flags that controls how entry creation is performed. The following flags can be set:

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.

lppMAPIPropEntry

[out] Pointer to a pointer to the newly created entry.

Return Values

S_OK: The new entry was successfully created.

Remarks

The IABContainer::CreateEntry method creates a new entry of a particular type in the container, returning a pointer to an interface implementation for further access to the entry. The new entry is created using a template that has been selected from the container's list of available templates published in its one-off table. Callers access a container's one-off table by calling its IMAPIProp::OpenProperty method and requesting the PR_CREATE_TEMPLATES property.

Notes to Implementers

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

Although the MAPI personal address book does not support the CREATE_REPLACE flag, MAPI recommends that you 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 created.

Some providers implement strict entry checking by matching the display name, messaging address, and search key in an entry; other providers limit the match to display name and address. Loose entry checking is often implemented by checking the display name only.

Notes to Host Provider Implementers

If your container can create entries from the templates of other providers, your implementation of CreateEntry should provide storage for some or all of the properties associated with the created entries. For example, if you provide storage for an entry's PR_DETAILS_TABLE property, you will be able to generate its details dialog box without having to depend on the foreign provider.

If your container can create entries that support the PR_TEMPLATEID property, your implementation of CreateEntry must:

Call IMAPISupport::OpenTemplateID. OpenTemplateID allows the foreign provider's code for the entry to bind to the new entry being created. Foreign providers support this binding process to maintain control over entries created from their templates into the containers of host providers.
Perform any necessary initialization and populate the new object with all of the properties from the entry in the foreign provider — the object returned in the lppMAPIPropNew parameter from OpenTemplateID.

If OpenTemplateID succeeds, copy the properties to the bound interface — the implementation pointed to by the lppMAPIPropNew parameter — rather than directly to the implementation pointed to by the lpMAPIPropData parameter. Initialize the new entry for offline use as you would any other entry from a foreign provider.

If OpenTemplateID returns an error, CreateEntry should fail. Do not allow the entry to be created. Because the foreign provider can make assumptions about the data in your provider, do not create an entry with a template identifier that has not been successfully bound to the foreign provider.

Notes to Callers

When CreateEntry returns, you may or may not be able to access the entry identifier for the new entry immediately. Some address book providers do not make it accessible until after you have called the new entry's IMAPIProp::SaveChanges method.

Although duplicate checking flags are passed as parameters to CreateEntry, the duplicate checking operation does not occur until SaveChanges is called. Therefore, related errors such as MAPI_E_COLLISION, indicating that an attempt was made to create an already existing entry, are returned by SaveChanges rather than CreateEntry.