IABContainer::CreateEntry

Artikel
04/04/2023

Gilt für: Outlook 2013 | Outlook 2016

Erstellt einen neuen Eintrag, bei dem es sich um einen Messagingbenutzer, eine Verteilerliste oder einen anderen Container sein kann.

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

Parameter

cbEntryID

[in] Die Anzahl der Bytes im Eintragsbezeichner, auf die der lpEntryID-Parameter verweist.

lpEntryID

[in] Ein Zeiger auf den Eintragsbezeichner einer Vorlage zum Erstellen neuer Einträge eines bestimmten Typs.

ulCreateFlags

[in] Eine Bitmaske von Flags, die steuert, wie die Eingabeerstellung ausgeführt wird. Die folgenden Flags können festgelegt werden:

CREATE_CHECK_DUP_LOOSE

Es sollte eine lose Überprüfung von Doppelten einträgen durchgeführt werden. Die Implementierung der Überprüfung von losen Doppelten Einträgen ist anbieterspezifisch. Beispielsweise kann ein Anbieter eine lose Übereinstimmung als zwei beliebige Einträge definieren, die denselben Anzeigenamen haben.

CREATE_CHECK_DUP_STRICT

Es sollte eine strenge Überprüfung der Doppelten Einträge durchgeführt werden. Die Implementierung der strengen Überprüfung von Doppelten Einträgen ist anbieterspezifisch. Beispielsweise kann ein Anbieter eine strikte Übereinstimmung als zwei beliebige Einträge definieren, die sowohl den gleichen Anzeigenamen als auch die gleiche Messagingadresse haben.

CREATE_REPLACE

Ein neuer Eintrag sollte einen vorhandenen Eintrag ersetzen, wenn festgestellt wird, dass die beiden Duplikate sind.

lppMAPIPropEntry

[out] Ein Zeiger auf einen Zeiger auf den neu erstellten Eintrag.

Rückgabewert

S_OK

Der neue Eintrag wurde erfolgreich erstellt.

Hinweise

Die IABContainer::CreateEntry-Methode erstellt einen neuen Eintrag eines bestimmten Typs im angegebenen Container und gibt einen Zeiger auf eine Schnittstellenimplementierung für weiteren Zugriff auf den Eintrag zurück. Der neue Eintrag wird mithilfe einer Vorlage erstellt, die aus der Liste der verfügbaren Vorlagen des Containers ausgewählt wurde, die in seiner einmaligen Tabelle veröffentlicht wurden. Aufrufer greifen auf die einmalige Tabelle eines Containers zu, indem sie ihre IMAPIProp::OpenProperty-Methode aufrufen und die eigenschaft PR_CREATE_TEMPLATES (PidTagCreateTemplates) anfordern.

Hinweise für Implementierer

Alle Container, die die IABContainer::CreateEntry-Methode unterstützen, müssen änderbar sein. Legen Sie das AB_MODIFIABLE-Flag Ihres Containers in seiner PR_CONTAINER_FLAGS-Eigenschaft (PidTagContainerFlags) fest, um anzugeben, dass er änderbar ist.

Sie sollten alle ulCreateFlags-Flags unterstützen. Die Interpretation und Verwendung dieser Flags ist jedoch implementierungsspezifisch, d. h. Sie können bestimmen, was die Semantik von CREATE_CHECK_DUP_LOOSE und CREATE_CHECK_DUP_STRICT im Kontext Ihrer Implementierung bedeuten. Wenn Sie nicht feststellen können oder nicht, ob es sich bei einem Eintrag um ein Duplikat handelt, lassen Sie das Erstellen des Eintrags immer zu.

Einige Anbieter implementieren eine strenge Eingabeüberprüfung, indem sie den Anzeigenamen, die Messagingadresse und den Suchschlüssel in einem Eintrag abgleichen. Andere Anbieter beschränken die Übereinstimmung auf den Anzeigenamen und die Adresse. Die Überprüfung des losen Eintrags wird häufig implementiert, indem nur der Anzeigename überprüft wird.

Hinweise zu Hostadressbuchanbieterimplementierern

Wenn Ihr Container Einträge aus den Vorlagen anderer Anbieter erstellen kann, sollte Ihre Implementierung von CreateEntry Speicher für einige oder alle Eigenschaften bereitstellen, die den erstellten Einträgen zugeordnet sind. Wenn Sie z. B. Speicher für die eigenschaft PR_DETAILS_TABLE (PidTagDetailsTable) eines Eintrags bereitstellen, können Sie dessen Detaildialogfeld generieren, ohne sich auf den ausländischen Anbieter verlassen zu müssen.

Wenn Ihr Container Einträge erstellen kann, die die eigenschaft PR_TEMPLATEID (PidTagTemplateid) unterstützen, muss Ihre Implementierung von CreateEntry die folgenden Schritte ausführen:

Rufen Sie die IMAPISupport::OpenTemplateID-Methode auf. OpenTemplateID ermöglicht es dem Code des ausländischen Anbieters für den Eintrag, an den neuen Eintrag zu binden, der erstellt wird. Ausländische Anbieter unterstützen diesen Bindungsprozess, um die Kontrolle über Einträge zu behalten, die aus ihren Vorlagen in den Containern von Hostadressbuchanbietern erstellt wurden.
Führen Sie alle erforderlichen Initialisierungen durch, und füllen Sie das neue Objekt mit allen Eigenschaften aus dem Eintrag im Fremdanbieter auf, die das Objekt im lppMAPIPropNew-Parameter von OpenTemplateID zurückgegeben hat.

Wenn OpenTemplateID erfolgreich ist, kopieren Sie die Eigenschaften in die Implementierung, auf die der lppMAPIPropNew-Parameter verweist, und nicht direkt in die Implementierung, auf die der lpMAPIPropData-Parameter verweist. Initialisieren Sie den neuen Eintrag für die Offlineverwendung wie jeder andere Eintrag eines ausländischen Anbieters.

Wenn OpenTemplateID einen Fehler zurückgibt, sollte CreateEntry fehlschlagen. Lassen Sie das Erstellen des Eintrags nicht zu. Da der ausländische Anbieter Annahmen über die Daten in Ihrem Anbieter treffen kann, erstellen Sie keinen Eintrag mit einem Vorlagenbezeichner, der nicht erfolgreich an den ausländischen Anbieter gebunden wurde.

Hinweise für Aufrufer

Wenn CreateEntry zurückgibt, können Sie möglicherweise sofort auf den Eintragsbezeichner für den neuen Eintrag zugreifen. Einige Adressbuchanbieter stellen es erst zur Verfügung, nachdem Sie die IMAPIProp::SaveChanges-Methode des neuen Eintrags aufgerufen haben.

Obwohl doppelte Überprüfungsflags als Parameter an CreateEntry übergeben werden, erfolgt der Vorgang zur Duplikatüberprüfung erst, wenn SaveChanges aufgerufen wird. Daher werden verwandte Fehler wie MAPI_E_COLLISION, die darauf hindeuten, dass versucht wurde, einen bereits vorhandenen Eintrag zu erstellen, von SaveChanges und nicht von CreateEntry zurückgegeben.