IABLogon::OpenTemplateID

The IABLogon::OpenTemplateID method opens a recipient entry that has data residing in a host 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 the lpTemplateID parameter.

lpTemplateID

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

ulTemplateFlags

[in] Bitmask of flags used to indicate how to open the entry represented by the template identifier. The following flag can be set:

FILL_ENTRY: The host provider is creating a new entry in its container based on the entry represented by the template identifier. OpenTemplateID should either perform specific initialization of the host provider's entry, using the IMAPIProp implementation in the lpMAPIPropData parameter, or return a custom IMAPIProp implementation in the lppMAPIPropNew parameter.

lpMAPIPropData

[in] Pointer to the host provider's property object— an implementation of an interface derived from IMAPIProp.

lpInterface

[in] Pointer to the interface identifier (IID) representing the type of interface pointer to be returned in the lppMAPIPropNew parameter. Passing NULL results in the return of the standard messaging user interface, IMailUser.

lppMAPIPropNew

[out] Pointer to the bound property object —an implementation of an interface derived from IMAPIProp.

lpMAPIPropSibling

Reserved; must be NULL.

Return Values

S_OK: The appropriate code was successfully bound to related data in the host provider.
MAPI_E_UNKNOWN_ENTRYID: The template identifier passed in the lpTemplateID parameter is not recognized by the address book provider.

Remarks

The IABLogon::OpenTemplateID method is implemented only by address book providers that need to maintain control over copies of their entries that exist in the containers of host providers. Providers that implement OpenTemplateID are known as foreign address book providers. Host providers call IMAPISupport::OpenTemplateID to create a copied entry or open the copied entry, and MAPI passes on the call to IABLogon::OpenTemplateID. IABLogon::OpenTemplateID opens the entry and binds the code that controls it to data in the host provider.

Rather than use an entry identifier, OpenTemplateID uses another property, the entry's template identifier — PR_TEMPLATEID. Template identifiers should be supported for entries whose code will need to be bound to data in a host provider.

Some examples of when an address book provider should implement IABLogon::OpenTemplateID are:

To periodically update the data for a copied entry so that it stays synchronized with the original.
To implement functionality that the host provider cannot implement, such as dynamically populating a list box that appears in the entry's details table from data on a server.
To control the interaction between properties in the host provider's entry and the original entry, such as computing PR_EMAIL_ADDRESS from edit controls in the details display that hold various components of the address.

Notes to Implementers

When a host provider copies or creates an entry from your provider and you supply a property object implementation through IABLogon::OpenTemplateID, you handle most of the calls to maintain the entry. However, because it is up to the host provider to forward these calls to you, the host provider can intercept any call and perform custom processing before forwarding the call.

You should adhere to the following guidelines in your property object implementations:

When IMAPIProp::GetProps is called, determine if the request is for a computed property and if it is, handle it. Transfer all requests for noncomputed properties to the host provider.
When IMAPIProp::OpenProperty is called to open any table except the details display table, handle the request. Most tables cannot be copied accurately to the host provider. You must generate the IMAPITable implementation for these requested tables. The details table — PR_DETAILS_TABLE property — must be copied to the host provider, thereby allowing this provider to generate the table locally. You might want to wrap the display table implementation to generate display table notifications.
When IMAPIProp::SetProps is called, the host provider can validate the data before allowing you to set the properties. You can verify that all of the necessary properties were set or computed. If an error is detected, return the appropriate error value and, if possible, a further explanation through IMAPIProp::GetLastError.
When IMAPIProp::SaveChanges is called, the host provider might want to perform processing before you save the entry. You should save any data that is affected by the changed properties, such as a new address, in the host provider's entry.

In general, make your implementation of the entry that you pass back to the host provider intercept all of the methods to perform context-specific manipulation of the relevant properties. If the FILL_ENTRY flag is passed in the ulFlags parameter, set all properties for the entry.

If you return a new property object in the lppMAPIPropNew parameter, call the IUnknown::AddRef method of the host provider's property object to maintain a reference. All calls through the bound object — the IMAPIProp implementation returned in lppMAPIPropNew — should be routed to their corresponding method in the host property object after they are dealt with by the bound object.

The property identifiers of any named properties that are passed through your bound property object are in your provider's identifier name space. Your implementation of the IMAPIProp::GetNamesFromIDs method should determine the names of the properties so that it can perform any template-specific tasks. Similarly, properties that your provider passes on to the host provider must also be in your name space. For example, if you set a named property in OpenTemplateID, you should use one of your identifiers for the name, creating it if necessary by calling GetIDsFromNames.

If you do not recognize the entry identifier passed in lpTemplateID, return MAPI_E_UNKNOWN_ENTRYID.

For more information on working with address book template identifiers, see Acting as a Foreign Address Book Provider.