IMsgStore::Advise
Gilt für: Outlook 2013 | Outlook 2016
Registriert, um Benachrichtigungen über angegebene Ereignisse zu erhalten, die sich auf den Nachrichtenspeicher 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 Ordners oder der Nachricht, über den Benachrichtigungen generiert werden sollen, oder NULL. Wenn lpEntryID auf NULL festgelegt ist, registriert Advise für Benachrichtigungen im gesamten Nachrichtenspeicher.
ulEventMask
[in] Eine Maske von Werten, die die Typen von Benachrichtigungsereignissen angeben, an denen der Aufrufer interessiert ist und in die Registrierung einbezogen werden sollte. Jedem Ereignistyp, der Informationen zum Ereignis enthält, ist eine entsprechende NOTIFICATION-Struktur zugeordnet. Im Folgenden sind gültige Werte für den ulEventMask-Parameter aufgeführt:
fnevCriticalError
Registriert für Benachrichtigungen über schwerwiegende Fehler, z. B. unzureichender Arbeitsspeicher.
fnevExtended
Registriert sich für Benachrichtigungen zu Ereignissen, die für den jeweiligen Nachrichtenspeicheranbieter spezifisch sind.
fnevNewMail
Registriert sich für Benachrichtigungen über die Ankunft neuer Nachrichten.
fnevObjectCreated
Registriert für Benachrichtigungen über die Erstellung eines neuen Ordners oder einer neuen Nachricht.
fnevObjectCopied
Registriert sich für Benachrichtigungen zu einem Ordner oder einer Nachricht, die kopiert wird.
fnevObjectDeleted
Registriert sich für Benachrichtigungen über einen Ordner oder eine Nachricht, die gelöscht wird.
fnevObjectModified
Registriert sich für Benachrichtigungen zu einem Ordner oder einer Nachricht, die geändert wird.
fnevObjectMoved
Registriert sich für Benachrichtigungen zu einem Ordner oder einer Nachricht, die 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.
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 Verbindungsnummer ungleich null, die die Verbindung zwischen dem Objekt der Empfehlungssenke des Aufrufers und dem Nachrichtenspeicher darstellt.
Rückgabewert
S_OK
Die Registrierung war erfolgreich.
MAPI_E_NO_SUPPORT
Der Nachrichtenspeicheranbieter unterstützt keine Registrierung für Benachrichtigungen über den Nachrichtenspeicher.
Hinweise
Die IMsgStore::Advise-Methode stellt eine Verbindung zwischen dem Objekt der Empfehlungssenke des Aufrufers und dem Nachrichtenspeicher oder einem Objekt im Nachrichtenspeicher her. Diese Verbindung wird verwendet, um Benachrichtigungen an die Empfehlungssenke zu senden, wenn ein oder mehrere Ereignisse, wie im ulEventMask-Parameter angegeben, für das Advise-Quellobjekt auftreten. Wenn der lpEntryID-Parameter auf einen gültigen Eintragsbezeichner verweist, ist die Empfehlungsquelle das objekt, das durch diesen Eintragsbezeichner identifiziert wird. Wenn lpEntryID NULL ist, ist die Empfehlungsquelle der Nachrichtenspeicher.
Um eine Benachrichtigung zu senden, ruft entweder der Nachrichtenspeicheranbieter 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 Implementierer
Sie können Benachrichtigungen mit oder ohne Hilfe von MAPI unterstützen. MAPI verfügt über drei Unterstützungsobjektmethoden zur Unterstützung von Dienstanbietern bei der Implementierung von Benachrichtigungen: IMAPISupport::Subscribe, IMAPISupport::Unsubscribe und IMAPISupport::Notify. 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 IUnknown::AddRef-Methode der durch den lpAdviseSink-Parameter dargestellten Empfehlungssenke auf, um eine Kopie dieses Zeigers zu behalten. Behalten Sie diese Kopie bei, bis Ihre IMsgStore::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 Unadvise aufgerufen und abgeschlossen wurde.
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 sicher sein 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 Advise übergeben.
Nachdem ein Aufruf von Advise erfolgreich war und bevor Unadvise aufgerufen wurde, um die Registrierung abzubrechen, bereiten Sie sich darauf vor, dass das Objekt der Empfehlungssenke freigegeben wird. Sie sollten 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.
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 IMsgStore::Advise-Methode , um sich für Benachrichtigungen im gesamten Nachrichtenspeicher zu registrieren. |