IMAPISupport::OpenTemplateID

The IMAPISupport::OpenTemplateID method opens a recipient entry in a foreign address book provider.

Quick Info

HRESULT OpenTemplateID(
  ULONG cbTemplateID,                
  LPENTRYID lpTemplateID,            
  ULONG ulTemplateFlags,             
  LPMAPIPROP lpMAPIPropData,         
  LPCIID lpInterface,                
  LPMAPIPROP FAR * lppMAPIPropNew,   
  LPMAPIPROP lpMAPIPropSibling       
);

Parameters

cbTemplateID

[in] Count of bytes in the template identifier pointed to by lpTemplateID.

lpTemplateID

[in] Pointer to the template identifier — PR_TEMPLATEID property — of the recipient entry to be opened.

ulTemplateFlags

[in] Bitmask of flags used to describe how to open the entry. The following flag can be set:

FILL_ENTRY: A new entry is being created. When the foreign provider receives the subsequent IABLogon::OpenTemplateID call from MAPI, it can control how the entry is created by modifying properties pointed to by the lpMAPIPropData parameter or by returning a specific interface implementation in lppMAPIPropNew to control how properties for the new entry are set.

lpMAPIPropData

[in] Pointer to the interface implementation that the caller uses to access the entry. This is the implementation that the foreign provider can wrap with its own implementation and return in the lppMAPIPropNew parameter. The lpMAPIPropData parameter must point to a read/write interface implementation that derives from IMAPIProp and supports the interface being requested in the lpInterface parameter.

lpInterface

[in] Pointer to the interface identifier (IID) representing the interface to be used to access the entry. The lppMAPIPropNew parameter points to an interface of the type specified by lpInterface. Passing NULL results in the return of the standard interface for a messaging user, IID_IMailUser.

lppMAPIPropNew

[out] Pointer to the interface implementation supplied by the foreign provider for accessing the entry.

lpMAPIPropSibling

Reserved; must be NULL.

Return Values

S_OK: The binding process was successful.
MAPI_E_UNKNOWN_ENTRYID: The foreign address book provider doesn't exist.

Remarks

The IMAPISupport::OpenTemplateID method is implemented only for address book provider support objects. OpenTemplateID is called only by address book providers that can act as hosts for entries belonging to other address book providers, also known as foreign providers. Host providers call OpenTemplateID to open a foreign entry, which occurs when data in the host provider is bound to code in the foreign provider.

Notes to Callers

Call OpenTemplateID only if you support the storage of entries with template identifiers from foreign address book providers. Such support places additional requirements on your IABContainer::CreateEntry and IABLogon::OpenEntry implementations. See the descriptions of these methods and Acting as a Host Address Book Provider for more information.

If the OpenTemplateID call returns as the bound interface the same property object implementation as you passed in, you can release your reference to your property object. This is because the foreign provider has called the object's AddRef method to keep its own reference. If the foreign provider does not need to keep a reference to the property object, then OpenTemplateID will return the unbound property object.

If OpenTemplateID fails with MAPI_E_UNKNOWN_ENTRYID, try to continue by treating the entry as read-only.