IMAPISupport::OpenTemplateID
Applies to: Outlook 2013 | Outlook 2016
Opens a recipient entry in a foreign address book provider.
HRESULT OpenTemplateID(
ULONG cbTemplateID,
LPENTRYID lpTemplateID,
ULONG ulTemplateFlags,
LPMAPIPROP lpMAPIPropData,
LPCIID lpInterface,
LPMAPIPROP FAR * lppMAPIPropNew,
LPMAPIPROP lpMAPIPropSibling
);
Parameters
cbTemplateID
[in] The byte count in the template identifier pointed to by lpTemplateID.
lpTemplateID
[in] A pointer to the template identifier PR_TEMPLATEID (PidTagTemplateid) property of the recipient entry to be opened.
ulTemplateFlags
[in] A 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] A 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 : IUnknown and supports the interface being requested in the lpInterface parameter.
lpInterface
[in] A pointer to the interface identifier (IID) that represents the interface to be used to access the entry. The lppMAPIPropNew parameter points to an interface of the type specified by lpInterface. Passing NULL returns the standard interface for a messaging user, IID_IMailUser.
lppMAPIPropNew
[out] A pointer to the interface implementation that the foreign provider supplies for accessing the entry.
lpMAPIPropSibling
Reserved; must be NULL.
Return value
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 that belong 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. For more information, see the descriptions of these methods and Acting as a Host Address Book Provider.
If the OpenTemplateID call returns as the bound interface the same property object implementation that 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.