IAddrBook::Advise
Gilt für: Outlook 2013 | Outlook 2016
Registriert einen Client oder Dienstanbieter, um Benachrichtigungen über Änderungen an einem oder mehreren Einträgen im Adressbuch zu erhalten.
HRESULT Advise(
ULONG cbEntryID,
LPENTRYID lpEntryID,
ULONG ulEventMask,
LPMAPIADVISESINK lpAdviseSink,
ULONG_PTR lpulConnection
);
Parameter
cbEntryID
[in] Die Byteanzahl im Eintragsbezeichner, auf die der lpEntryID-Parameter verweist.
lpEntryID
[in] Ein Zeiger auf den Eintragsbezeichner des Adressbuchcontainers, des Messagingbenutzers oder der Verteilerliste, der eine Benachrichtigung generiert, wenn eine Änderung des Typs oder der Typen auftritt, die im ulEventMask-Parameter beschrieben sind.
ulEventMask
[in] Ein oder mehrere Benachrichtigungsereignisse, die der Aufrufer registriert, um zu empfangen. Jedes Ereignis ist einer bestimmten Benachrichtigungsstruktur zugeordnet, die Informationen zu der aufgetretenen Änderung enthält. In der folgenden Tabelle sind die gültigen Werte für ulEventMask und die entsprechenden Strukturen aufgeführt.
| Benachrichtigungsereignis | Entsprechende Struktur |
|---|---|
|
fnevCriticalError |
ERROR_NOTIFICATION |
|
fnevObjectCreated |
OBJECT_NOTIFICATION |
|
fnevObjectDeleted |
OBJECT_NOTIFICATION |
|
fnevObjectModified |
OBJECT_NOTIFICATION |
|
fnevObjectCopied |
OBJECT_NOTIFICATION |
|
fnevObjectMoved |
OBJECT_NOTIFICATION |
|
fnevTableModified |
TABLE_NOTIFICATION |
lpAdviseSink
[in] Ein Zeiger auf das Objekt der Empfehlungssenke, das aufgerufen werden soll, wenn das Ereignis auftritt, für das eine Benachrichtigung angefordert wurde.
lpulConnection
[out] Ein Zeiger auf eine Verbindungsnummer ungleich null, die die Benachrichtigungsregistrierung darstellt.
Rückgabewert
S_OK
Die Benachrichtigungsregistrierung war erfolgreich.
MAPI_E_INVALID_ENTRYID
Der Adressbuchanbieter, der für den in lpEntryID übergebenen Eintragsbezeichner verantwortlich ist, konnte keine Benachrichtigung für den entsprechenden Eintrag registrieren.
MAPI_E_NO_SUPPORT
Benachrichtigungen werden vom Adressbuchanbieter, der für das Objekt verantwortlich ist, nicht unterstützt, das durch den eintragsbezeichner identifiziert wird, der im lpEntryID-Parameter übergeben wird.
MAPI_E_UNKNOWN_ENTRYID
Der in lpEntryID übergebene Eintragsbezeichner kann von keinem der Adressbuchanbieter im Profil verarbeitet werden.
Hinweise
Clients und Dienstanbieter rufen die Advise-Methode auf, um sich für einen oder mehrere Benachrichtigungstypen in einem Adressbucheintrag zu registrieren. Die Benachrichtigungstypen werden durch die Ereignismaske angegeben, die mit dem ulEventMask-Parameter übergeben wird.
MAPI leitet diesen Advise-Aufruf an den Adressbuchanbieter weiter, der für den Eintrag verantwortlich ist, wie durch den Eintragsbezeichner im lpEntryID-Parameter angegeben. Der Adressbuchanbieter verarbeitet entweder die Registrierung selbst oder ruft die Supportmethode IMAPISupport::Subscribe auf, um MAPI aufzufordern, den Aufrufer zu registrieren. Eine Verbindungsnummer ungleich 0 (null) wird zurückgegeben, um die erfolgreiche Registrierung darzustellen.
Wenn eine Änderung am Eintrag des durch die Benachrichtigungsregistrierung angegebenen Typs erfolgt, ruft der Adressbuchanbieter die IMAPIAdviseSink::OnNotify-Methode für das im lpAdviseSink-Parameter angegebene Beratungssenkeobjekt auf. Die OnNotify-Methode enthält eine NOTIFICATION-Struktur als Eingabeparameter, die Daten zum Beschreiben des Ereignisses enthält.
Je nach Adressbuchanbieter kann der Aufruf von OnNotify unmittelbar nach der Änderung des registrierten Objekts oder zu einem späteren Zeitpunkt erfolgen. Auf Systemen, die mehrere Ausführungsthreads unterstützen, kann der Aufruf von OnNotify für jeden Thread erfolgen. Clients können anfordern, dass diese Benachrichtigungen für einen bestimmten Thread erfolgen, indem sie die HrThisThreadAdviseSink-Funktion aufrufen, um das Objekt der Empfehlungssenke zu erstellen, das an Advise übergeben wird.
Da ein Adressbuchanbieter das von Clients übergebene Beratungssenkenobjekt jederzeit nach erfolgreichem Abschluss des Advise-Aufrufs und vor einem IAddrBook::Unadvise-Aufruf freigeben kann, um die Benachrichtigung abzubrechen, sollten Clients ihre Beratungssenkenobjekte freigeben, wenn Advise zurückgibt.
Weitere Informationen zum Benachrichtigungsprozess finden Sie unter Ereignisbenachrichtigung in MAPI.