IMAPISession::Advise
Gilt für: Outlook 2013 | Outlook 2016
Registriert, um Benachrichtigungen über angegebene Ereignisse zu erhalten, die sich auf die Sitzung auswirken.
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 Adressbuchs oder Nachrichtenspeicherobjekts, über das Benachrichtigungen generiert werden sollen, oder NULL, der angibt, dass der Client registriert wird, um Benachrichtigungen zu Ereignissen zu empfangen, die sich nur auf die Sitzung auswirken.
ulEventMask
[in] Eine Maske von Werten, die die Typen von Benachrichtigungsereignissen angeben, an denen der Client interessiert ist, und die in die Registrierung einbezogen werden sollten. Wenn lpEntryID NULL ist, registriert MAPI den Client automatisch für kritische Fehlerereignisse, die sich nur auf die Sitzung auswirken. Wenn lpEntryID auf einen Eintragsbezeichner verweist, sind die folgenden Werte für den ulEventMask-Parameter gültig:
fnevCriticalError
Registriert für Benachrichtigungen über schwerwiegende Fehler, z. B. unzureichender Arbeitsspeicher.
fnevExtended
Registriert sich für Benachrichtigungen zu Ereignissen, die für einen bestimmten Adressbuch- oder Nachrichtenspeicheranbieter spezifisch sind, und zum Herunterfahren der Sitzung.
fnevNewMail
Registriert sich für Benachrichtigungen über die Ankunft neuer Nachrichten.
fnevObjectCreated
Registriert sich für Benachrichtigungen über die Erstellung eines neuen Objekts.
fnevObjectCopied
Registriert sich für Benachrichtigungen zu einem Objekt, das kopiert wird.
fnevObjectDeleted
Registriert sich für Benachrichtigungen über ein Objekt, das gelöscht wird.
fnevObjectModified
Registriert sich für Benachrichtigungen zu einem Objekt, das geändert wird.
fnevObjectMoved
Registriert für Benachrichtigungen zu einem Objekt, das verschoben wird.
fnevSearchComplete
Registriert sich für Benachrichtigungen über den Abschluss eines Suchvorgangs.
lpAdviseSink
[in] Ein Zeiger auf ein Senkeobjekt, das die nachfolgenden Benachrichtigungen empfangen soll. Dieses Empfehlungssenkenobjekt muss bereits zugeordnet worden sein.
lpulConnection
[out] Ein Zeiger auf eine Nummer ungleich null, die die Verbindung zwischen dem Empfehlungssenkenobjekt des Aufrufers und der Sitzung darstellt.
Rückgabewert
S_OK
Die Registrierung war erfolgreich.
MAPI_E_INVALID_ENTRYID
Der Eintragsbezeichner, auf den lpEntryID verweist, stellt keinen gültigen Eintragsbezeichner dar.
MAPI_E_NO_SUPPORT
Der Dienstanbieter, der für den Eintragsbezeichner verantwortlich ist, auf den lpEntryID verweist, unterstützt entweder nicht den im ulEventMask-Parameter angegebenen Ereignistyp oder keine Benachrichtigung.
MAPI_E_UNKNOWN_ENTRYID
Der Eintragsbezeichner, auf den lpEntryID verweist, kann von keinem der Dienstanbieter im Profil verarbeitet werden.
Hinweise
Die IMAPISession::Advise-Methode stellt eine Verbindung zwischen dem Empfehlungssenkenobjekt des Aufrufers, der Sitzung und optional einem Dienstanbieter her. Diese Verbindung wird verwendet, um Benachrichtigungen an die Empfehlungssenke zu senden, wenn mindestens ein im ulEventMask-Parameter angegebenes Ereignis für das Objekt auftritt, auf das von lpEntryID verwiesen wird. Wenn lpEntryID NULL ist, ist das Zielobjekt die Sitzung, und Benachrichtigungen werden nur für kritische Fehler und erweiterte Ereignisse gesendet.
Wenn lpEntryID auf einen gültigen Eintragsbezeichner verweist, ruft MAPI die Advise-Methode des Anmeldeobjekts auf, das zum zuständigen Dienstanbieter gehört. Wenn lpEntryID beispielsweise auf den Eintragsbezeichner einer Verteilerliste verweist, ruft MAPI die IABLogon::Advise-Methode des entsprechenden Adressbuchanbieters auf.
Um eine Benachrichtigung zu senden, ruft entweder der Dienstanbieter oder die MAPI die IMAPIAdviseSink::OnNotify-Methode der registrierten Empfehlungssenke auf. Einer der Parameter für OnNotify, eine Benachrichtigungsstruktur, enthält Informationen, die das jeweilige Ereignis beschreiben.
Hinweise für Aufrufer
Auf Systemen, die mehrere Ausführungsthreads unterstützen, kann der Aufruf von OnNotify jederzeit auch für jeden Thread erfolgen. Wenn Sie sicherstellen müssen, dass Benachrichtigungen nur zu einem bestimmten Zeitpunkt für einen bestimmten Thread auftreten, rufen Sie die HrThisThreadAdviseSink-Funktion auf, um das Objekt der Empfehlungssenke zu generieren, das Sie an die Advise-Methode übergeben.
Um festzustellen, wann sich ein Client abgemeldet hat, registrieren Sie sich für Benachrichtigungen bei Ihrem Dienstanbieter, indem Sie Advise aufrufen, wobei lpEntryID auf NULL und cbEntryID auf 0 festgelegt ist. Wenn die Abmeldung erfolgt, erhalten Sie eine fnevExtended-Benachrichtigung.
Nachdem ein Aufruf von Advise erfolgreich war und BEVOR IMAPISession::Unadvise aufgerufen wurde, um die Registrierung abzubrechen, geben Sie Ihr Beratungssenkenobjekt frei, es sei denn, Sie haben eine bestimmte langfristige Verwendung dafür.
Eine Übersicht über den Benachrichtigungsprozess finden Sie unter Ereignisbenachrichtigung in MAPI.
Weitere Informationen zum Behandeln von Benachrichtigungen finden Sie unter Behandeln von Benachrichtigungen.
MFCMAPI-Referenz
Einen MFCMAP-Beispielcode finden Sie in der folgenden Tabelle.
| Datei | Funktion | Kommentar |
|---|---|---|
| BaseDialog.cpp |
CBaseDialog::OnNotificationsOn |
MFCMAPI verwendet die IMAPISession::Advise-Methode , um sich für Benachrichtigungen für die Sitzung zu registrieren. |