IABLogon::Advise
Gilt für: Outlook 2013 | Outlook 2016
Registriert den Aufrufer, um Benachrichtigungen über angegebene Ereignisse zu erhalten, die sich auf einen Container, einen Messagingbenutzer oder eine Verteilerliste auswirken.
HRESULT Advise(
ULONG cbEntryID,
LPENTRYID lpEntryID,
ULONG ulEventMask,
LPMAPIADVISESINK lpAdviseSink,
ULONG FAR * lpulConnection
);
Parameter
cbEntryID
[in] Die Anzahl der Bytes im Eintragsbezeichner, auf die der lpEntryID-Parameter verweist.
lpEntryID
[in] Ein Zeiger auf den Eintragsbezeichner des Objekts, über das Benachrichtigungen generiert werden sollen.
ulEventMask
[in] Eine Bitmaske von Werten, die die Typen von Benachrichtigungsereignissen angeben, an denen der Aufrufer interessiert ist, und die in die Registrierung einbezogen werden sollten. Jedem Ereignistyp, der Informationen zum Ereignis enthält, ist eine entsprechende NOTIFICATION-Struktur zugeordnet. In der folgenden Tabelle sind die gültigen Werte für den ulEventMask-Parameter und die strukturen aufgeführt, die den einzelnen Werten zugeordnet sind.
| Benachrichtigungsereignistyp | Entsprechende BENACHRICHTIGUNGsstruktur |
|---|---|
|
fnevCriticalError |
ERROR_NOTIFICATION |
|
fnevObjectCreated |
OBJECT_NOTIFICATION |
|
fnevObjectDeleted |
OBJECT_NOTIFICATION |
|
fnevObjectModified |
OBJECT_NOTIFICATION |
|
fnevObjectCopied |
OBJECT_NOTIFICATION |
|
fnevObjectMoved |
OBJECT_NOTIFICATION |
lpAdviseSink
[in] Ein Zeiger auf ein Senkeobjekt, das die nachfolgenden Benachrichtigungen empfangen soll.
lpulConnection
[out] Ein Zeiger auf einen Wert ungleich null, der die Benachrichtigungsregistrierung darstellt.
Rückgabewert
S_OK
Die Benachrichtigungsregistrierung war erfolgreich.
MAPI_E_INVALID_ENTRYID
Der im lpEntryID-Parameter übergebene Eintragsbezeichner weist nicht das entsprechende Format auf.
MAPI_E_NO_SUPPORT
Der Adressbuchanbieter unterstützt keine Benachrichtigungen, möglicherweise weil er keine Änderungen an seinen -Objekten zulässt.
MAPI_E_UNKNOWN_ENTRYID
Der Adressbuchanbieter kann den in lpEntryID übergebenen Eintragsbezeichner nicht verarbeiten.
Hinweise
Adressbuchanbieter implementieren die IABLogon::Advise-Methode , um den Aufrufer so zu registrieren, dass er benachrichtigt wird, wenn eine Änderung an einem Objekt in einem ihrer Container erfolgt. Anrufer können sich für Benachrichtigungen zu Messagingbenutzern, Verteilerlisten oder ganzen Containern registrieren.
Clients rufen in der Regel die IAddrBook::Advise-Methode auf, um sich für Adressbuchbenachrichtigungen zu registrieren. MAPI ruft dann die Advise-Methode des Adressbuchanbieters auf, der für das Objekt verantwortlich ist, das durch den Eintragsbezeichner in lpEntryID dargestellt wird.
Wenn das angegebene Objekt des in ulEventMask dargestellten Typs geändert wird, wird die OnNotify-Methode der Empfehlungssenke aufgerufen, auf die lpAdviseSink verweist. Daten, die in der NOTIFICATION-Struktur an die OnNotify-Routine übergeben werden, beschreiben das Ereignis.
Hinweise für Implementierer
Sie können Benachrichtigungen mit oder ohne Hilfe von MAPI unterstützen. MAPI verfügt über drei Unterstützungsobjektmethoden, mit denen Dienstanbieter Benachrichtigungen implementieren können:
Wenn Sie sich für die Verwendung der MAPI-Unterstützungsmethoden entscheiden, rufen Sie Subscribe auf, wenn Ihre Advise-Methode aufgerufen wird, und geben Sie den lpAdviseSink-Zeiger frei.
Wenn Sie die Benachrichtigung selbst unterstützen möchten, rufen Sie die AddRef-Methode der durch den lpAdviseSink-Parameter dargestellten Empfehlungssenke auf, um eine Kopie dieses Zeigers beizubehalten. Behalten Sie diese Kopie bei, bis Ihre IABLogon::Unadvise-Methode aufgerufen wird, um die Registrierung abzubrechen.
Unabhängig davon, wie Sie Benachrichtigungen unterstützen, weisen Sie der Benachrichtigungsregistrierung eine Verbindungsnummer ungleich 0 zu, und geben Sie sie im lpulConnection-Parameter zurück. Geben Sie diese Verbindungsnummer erst frei, wenn die Unadvise-Methode aufgerufen wurde.
Hinweise für Aufrufer
Der Zeiger der Empfehlungssenke, den Sie im lpAdviseSink-Parameter an Advise übergeben, kann auf ein Objekt verweisen, das Sie erstellt haben oder das MAPI über die Funktion HrThisThreadAdviseSink erstellt hat. Sie können HrThisThreadAdviseSink verwenden, wenn Sie mehrere Ausführungsthreads unterstützen und sicherstellen möchten, dass nachfolgende Aufrufe Ihrer OnNotify-Methode zu einem geeigneten Zeitpunkt in einem entsprechenden Thread erfolgen.
Seien Sie darauf vorbereitet, dass Ihr Beratungssenkenobjekt jederzeit nach Ihrem Anruf bei Advise und vor Ihrem Anruf bei Unadvise freigegeben wird. Daher sollten Sie Ihr Beratungssenkenobjekt nach der Rückgabe von Advise freigeben, es sei denn, Sie haben eine bestimmte langfristige Verwendung dafür.
Weitere Informationen zum Benachrichtigungsprozess finden Sie unter Ereignisbenachrichtigung in MAPI. Informationen zur Verwendung der IMAPISupport-Methoden zur Unterstützung von Benachrichtigungen finden Sie unter Unterstützen von Ereignisbenachrichtigungen. Weitere Informationen zu Multithreading und MAPI finden Sie unter Threading in MAPI.