IABLogon::OpenTemplateID
Gilt für: Outlook 2013 | Outlook 2016
Öffnet einen Empfängereintrag mit Daten, die sich in einem Hostadressbuchanbieter befinden.
HRESULT OpenTemplateID(
ULONG cbTemplateID,
LPENTRYID lpTemplateID,
ULONG ulTemplateFlags,
LPMAPIPROP lpMAPIPropData,
LPCIID lpInterface,
LPMAPIPROP FAR * lppMAPIPropNew,
LPMAPIPROP lpMAPIPropSibling
);
Parameter
cbTemplateID
[in] Die Byteanzahl im Vorlagenbezeichner, auf die der lpTemplateID-Parameter verweist.
lpTemplateID
[in] Ein Zeiger auf den Vorlagenbezeichner oder PR_TEMPLATEID Eigenschaft (PidTagTemplateid) des zu öffnenden Empfängereintrags.
ulTemplateFlags
[in] Eine Bitmaske von Flags, mit der angegeben wird, wie der durch den Vorlagenbezeichner dargestellte Eintrag geöffnet werden soll. Das folgende Flag kann festgelegt werden:
FILL_ENTRY
Der Hostanbieter erstellt einen neuen Eintrag in seinem Container basierend auf dem Eintrag, der durch den Vorlagenbezeichner dargestellt wird. Die IABLogon::OpenTemplateID-Methode sollte entweder eine spezifische Initialisierung des Eintrags des Hostanbieters mithilfe der IMPLEMENTIERUNG IMAPIProp : IUnknown im lpMAPIPropData-Parameter durchführen oder eine benutzerdefinierte IMAPIPropPropNew-Schnittstellenimplementierung im lppMAPIPropNew-Parameter zurückgeben.
lpMAPIPropData
[in] Ein Zeiger auf das Eigenschaftsobjekt des Hostanbieters und die Implementierung einer von IMAPIProp abgeleiteten Schnittstelle.
lpInterface
[in] Ein Zeiger auf den Schnittstellenbezeichner (Interface Identifier, IID), der den Typ des Schnittstellenzeigers darstellt, der im lppMAPIPropNew-Parameter zurückgegeben werden soll. Die Übergabe von NULL gibt die Standardmäßige Messaging-Benutzeroberfläche IMailUser : IMAPIProp zurück.
lppMAPIPropNew
[out] Ein Zeiger auf das gebundene Eigenschaftsobjekt und eine Implementierung einer von IMAPIProp abgeleiteten Schnittstelle.
lpMAPIPropSibling
[out] Reserviert; muss NULL sein.
Rückgabewert
S_OK
Der entsprechende Code wurde erfolgreich an verwandte Daten im Hostanbieter gebunden.
MAPI_E_NO_SUPPORT
Das Objekt unterstützt keine Vorlagen-IDs.
MAPI_E_UNKNOWN_ENTRYID
Der im lpTemplateID-Parameter übergebene Vorlagenbezeichner wird vom Adressbuchanbieter nicht erkannt.
Hinweise
Die IABLogon::OpenTemplateID-Methode wird nur von Adressbuchanbietern implementiert, die die Kontrolle über Kopien ihrer Einträge behalten müssen, die sich in den Containern von Hostanbietern befinden. Anbieter, die OpenTemplateID implementieren, werden als Fremdadressbuchanbieter bezeichnet. Hostanbieter rufen IMAPISupport::OpenTemplateID auf, um einen kopierten Eintrag zu erstellen oder den kopierten Eintrag zu öffnen, und MAPI übergibt den Aufruf an IABLogon::OpenTemplateID. IABLogon::OpenTemplateID öffnet den Eintrag und bindet den Code, der ihn steuert, an Daten im Hostanbieter.
Anstelle eines Eintragsbezeichners verwendet IABLogon::OpenTemplateID eine andere Eigenschaft, den Vorlagenbezeichner des Eintrags PR_TEMPLATEID. Vorlagenbezeichner sollten für Einträge unterstützt werden, deren Code an Daten in einem Hostanbieter gebunden werden muss.
Beispiele für die Implementierung von IABLogon::OpenTemplateID durch einen Adressbuchanbieter sind:
Um die Daten für einen kopierten Eintrag regelmäßig zu aktualisieren, damit er mit dem Original synchronisiert bleibt.
Um Funktionen zu implementieren, die der Hostanbieter nicht implementieren kann, z. B. das dynamische Auffüllen einer Liste, die in der Detailtabelle des Eintrags aus Daten auf einem Server angezeigt wird.
Um die Interaktion zwischen Eigenschaften im Eintrag des Hostanbieters und dem ursprünglichen Eintrag zu steuern, z. B. das Berechnen des PR_EMAIL_ADDRESS (PidTagEmailAddress) aus den Werten der Bearbeitungssteuerelemente in der Detailanzeige, die verschiedene Komponenten der Adresse enthalten.
Hinweise für Implementierer
Wenn ein Hostanbieter einen Eintrag von Ihrem Anbieter kopiert oder erstellt und Sie eine Eigenschaftenobjektimplementierung über IABLogon::OpenTemplateID bereitstellen, verarbeiten Sie die meisten Aufrufe, um den Eintrag zu verwalten. Da es jedoch Aufgabe des Hostanbieters ist, diese Aufrufe an Sie weiterzuleiten, kann der Hostanbieter jeden Anruf abfangen und vor der Weiterleitung des Anrufs eine benutzerdefinierte Verarbeitung durchführen.
Sie sollten die folgenden Richtlinien in Ihren Eigenschaftenobjektimplementierungen verwenden:
Wenn IMAPIProp::GetProps aufgerufen wird, bestimmen Sie, ob die Anforderung für eine berechnete Eigenschaft gilt, und behandeln Sie sie, wenn dies der Zeitpunkt ist. Übertragen Sie alle Anforderungen für nicht berechnete Eigenschaften an den Hostanbieter.
Wenn IMAPIProp::OpenProperty aufgerufen wird, um eine beliebige Tabelle mit Ausnahme der Detailanzeigetabelle zu öffnen, verarbeiten Sie die Anforderung. Die meisten Tabellen können nicht genau auf den Hostanbieter kopiert werden. Sie müssen die IMAPITable-Implementierung für diese angeforderten Tabellen generieren. Die Detailtabelle PR_DETAILS_TABLE Eigenschaft (PidTagDetailsTable) muss in den Hostanbieter kopiert werden. Dadurch kann dieser Anbieter die Tabelle lokal generieren. Möglicherweise möchten Sie die Implementierung der Anzeigetabelle umschließen, um Anzeigetabellenbenachrichtigungen zu generieren.
Wenn IMAPIProp::SetProps aufgerufen wird, kann der Hostanbieter die Daten überprüfen, bevor Sie die Eigenschaften festlegen können. Sie können überprüfen, ob alle erforderlichen Eigenschaften festgelegt oder berechnet wurden. Wenn ein Fehler erkannt wird, geben Sie den entsprechenden Fehlerwert und, falls möglich, eine zusätzliche Erklärung über IMAPIProp::GetLastError zurück.
Wenn IMAPIProp::SaveChanges aufgerufen wird, möchte der Hostanbieter möglicherweise die Verarbeitung durchführen, bevor Sie den Eintrag speichern. Sie sollten alle Daten, die von den geänderten Eigenschaften betroffen sind, z. B. eine neue Adresse, im Eintrag des Hostanbieters speichern.
Im Allgemeinen sollte die Implementierung des Eintrags, den Sie an den Hostanbieter zurückgeben, alle Methoden abfangen, um kontextspezifische Manipulationen der relevanten Eigenschaften durchzuführen. Wenn das FILL_ENTRY-Flag im ulTemplateFlags-Parameter übergeben wird, legen Sie alle Eigenschaften für den Eintrag fest.
Wenn Sie ein neues Eigenschaftsobjekt im lppMAPIPropNew-Parameter zurückgeben, rufen Sie die IUnknown::AddRef-Methode des Eigenschaftsobjekts des Hostanbieters auf, um einen Verweis beizubehalten. Alle Aufrufe über das gebundene Objekt, das die IMAPIProp-Implementierung in lppMAPIPropNew zurückgegeben hat, sollten an die entsprechende Methode im Hosteigenschaftsobjekt weitergeleitet werden, nachdem sie vom gebundenen Objekt behandelt wurden.
Die Eigenschaftenbezeichner aller benannten Eigenschaften, die über das gebundene Eigenschaftsobjekt übergeben werden, befinden sich im Bezeichnernamespace Ihres Anbieters. Ihre Implementierung der IMAPIProp::GetNamesFromIDs-Methode sollte die Namen der Eigenschaften bestimmen, damit sie vorlagenspezifische Aufgaben ausführen kann. Ebenso müssen sich Eigenschaften, die Ihr Anbieter an den Hostanbieter übergibt, ebenfalls in Ihrem Namespace befinden. Wenn Sie beispielsweise eine benannte Eigenschaft in OpenTemplateID festlegen, sollten Sie einen Ihrer Bezeichner für den Namen verwenden und ihn ggf. durch Aufrufen der IMAPIProp::GetIDsFromNames-Methode erstellen.
Wenn Sie den in lpTemplateID übergebenen Eintragsbezeichner nicht erkennen, geben Sie MAPI_E_UNKNOWN_ENTRYID zurück.
Weitere Informationen zum Arbeiten mit Adressbuchvorlagenbezeichnern finden Sie unter Als Fremdadressbuchanbieter fungieren.