Ereignisbenachrichtigung in MAPI

Gilt für: Outlook 2013 | Outlook 2016

Ereignisbenachrichtigungen sind die Kommunikation von Informationen zwischen zwei MAPI-Objekten. Über eines der -Objekte registriert sich ein Client oder Dienstanbieter für die Benachrichtigung über eine Änderung oder einen Fehler, die als Ereignis bezeichnet wird, die im anderen Objekt stattfinden kann. Nachdem das Ereignis aufgetreten ist, wird das erste Objekt über die Änderung oder den Fehler benachrichtigt. Das Objekt, das die Benachrichtigung empfängt, wird als Beratungssenke bezeichnet. das für die Benachrichtigung verantwortliche Objekt wird als Empfehlungsquelle bezeichnet.

Es gibt drei Typen von Beratungssenkenobjekten (alle Typen sind MAPI-Standardobjekte):

• Beraten von Senkenobjekten.
• Formularberatungssenkenobjekte.
• Anzeigen von Beratungssenkenobjekten.

Beratungssenkenobjekte sind der am häufigsten verwendete Typ. Beratungssenken werden in der Regel von Clientanwendungen implementiert, um Adressbuch- und Nachrichtenspeicherbenachrichtigungen zu empfangen und die IMAPIAdviseSink: IUnknown-Schnittstelle zu unterstützen. IMAPIAdviseSink enthält eine einzelne Methode, IMAPIAdviseSink::OnNotify. Form- und Sichtberatungssenken sind seltener; sie werden implementiert, um Benachrichtigungen über Änderungen an benutzerdefinierten Formularen zu erhalten. Formularberatungssenken unterstützen die IMAPIFormAdviseSink: IUnknown-Schnittstelle und Ansichtssenken unterstützen die IMAPIViewAdviseSink : IUnknown-Schnittstelle . Da die meisten Clients standardmäßige Beratungssenkenobjekte implementieren, gehen Sie davon aus, dass Diskussionen von Benachrichtigungen sich auf Adressbuch- und Nachrichtenspeicherbenachrichtigungen beziehen und nicht formularbasierte Benachrichtigungen. Weitere Informationen zu Formularbenachrichtigungen finden Sie unter MAPI-Formularbenachrichtigungen und Schreiben von Formularservercode.

Empfehlungsquellobjekte werden von Dienstanbietern und von MAPI implementiert. Nicht alle Dienstanbieter unterstützen Ereignisbenachrichtigungen; dies ist optional, wird jedoch dringend empfohlen. Nachrichtenspeicher- und Adressbuchanbieter unterstützen in der Regel Objektbenachrichtigungen für mehrere ihrer Objekte und Tabellenbenachrichtigungen für ihre Inhalte und Hierarchietabellen. Transportanbieter unterstützen Benachrichtigungen nicht direkt; sie setzen auf alternative Kommunikationsmethoden mit Clients.

Im Gegensatz zu Beratungssenken handelt es sich bei empfehlungsquenten Objekten nicht um einen eindeutigen Typ von MAPI-Objekten. Viele MAPI-Objekte, z. B. Nachrichtenspeicher und Tabellen, können die Rolle der Empfehlungsquelle übernehmen. Eine Empfehlungsquelle ist jedes MAPI-Objekt, das folgende Aktionen ausführt:

• Implementiert eine Advise-Methode zum Empfangen von Benachrichtigungsregistrierungen.

• Implementiert eine Unadvise-Methode zum Empfangen von Benachrichtigungsabbrüchen.

• Generiert Benachrichtigungen des geeigneten Typs für die entsprechenden Beratungssenkenobjekte, die registriert wurden, indem ihre IMAPIAdviseSink::OnNotify-Methoden aufgerufen werden.

Clients, die Beratungssenkenobjekte implementieren, rufen Advise auf, wenn sie sich für eine Benachrichtigung registrieren möchten, übergeben in den meisten Fällen den Eintragsbezeichner des Objekts, mit dem die Registrierung erfolgen soll, und Heben Sie die Registrierung auf, wenn sie die Registrierung abbrechen möchten. Clients übergeben einen Parameter an Advise , der angibt, welche der verschiedenen Ereignistypen sie überwachen möchten. Advise gibt eine Zahl ungleich null zurück, die eine erfolgreiche Verbindung zwischen der Beratungssenke und der Empfehlungsquelle darstellt.

Vor dem Aufrufen von Advise können Clients ermitteln, ob ein Nachrichtenspeicheranbieter Benachrichtigungen unterstützt, indem sie überprüfen, ob das STORE_NOTIFY_OK-Flag in der eigenschaft PR_STORE_SUPPORT_MASK (PidTagStoreSupportMask) des Nachrichtenspeichers festgelegt ist. Clients können nicht im Voraus bestimmen, ob ein Adressbuchanbieter Benachrichtigungen unterstützt. Clients müssen versuchen, sich zu registrieren, und wenn der Versuch fehlschlägt, können sie davon ausgehen, dass Benachrichtigungen nicht unterstützt werden.

Wenn ein Ereignis auftritt, für das ein Client registriert ist, benachrichtigt die Empfehlungsquelle die Empfehlungssenke, indem sie ihre IMAPIAdviseSink::OnNotify-Methode mit einer Benachrichtigungsdatenstruktur aufruft, die Informationen zum Ereignis enthält. Die Implementierung von OnNotify einer Empfehlungssenke kann als Reaktion auf die Benachrichtigung Aufgaben ausführen, z. B. das Aktualisieren von Daten im Arbeitsspeicher oder das Aktualisieren einer Bildschirmanzeige.

Dienstanbieter können unterstützung für Benachrichtigungen manuell implementieren oder die Hilfe in drei IMAPISupport-Methoden nutzen: IMAPISupport::Subscribe, IMAPISupport::Unsubscribe und IMAPISupport::Notify. Die Abonnieren- und Abmeldemethoden behandeln die Registrierung und Aufhebung der Registrierung von Benachrichtigungen für Anbieter; Die Notify-Methode verarbeitet ggf. das Senden von Benachrichtigungen.

Um die Supportobjektmethoden für die Benachrichtigungsregistrierung zu verwenden, rufen Dienstanbieter INAPISupport::Subscribe in ihren Advise-Methoden auf und übergeben den Zeiger der Empfehlungssenke abonnieren, den Clients an Advise übergeben. Wenn ein Eintragsbezeichner als Eingabeparameter übergeben wird, um eine Empfehlungsquelle anzugeben, konvertieren Dienstanbieter ihn in einen binären Schlüssel. Subscribe erstellt eine eindeutige Verbindungsnummer, und es ist diese Nummer, die Dienstanbieter an Clients zurückgeben. Dienstanbieter können den Zeiger des Beratungssenkeobjekts des Kunden jederzeit freigeben, nachdem der Advise-Aufruf abgeschlossen wurde.

Wenn Clients Unadvise aufrufen, um eine Registrierung abzubrechen, verringern Dienstanbieter entweder die Referenzanzahl auf dem Zeiger der Empfehlungssenke des Clients oder rufen "Unsubscribe" auf, um dasselbe zu tun.

Wenn es an der Zeit ist, eine Benachrichtigung zu generieren, führen Dienstanbieter jede interne Verarbeitung aus, die sich auf die Benachrichtigung bezieht, und initialisiert eine NOTIFICATION-Struktur , indem sie alle nicht verwendeten Member auf Null festlegen. Diese Technik zum Initialisieren der NOTIFICATION-Struktur kann Clients helfen, kleinere, schnellere und weniger fehleranfällige OnNotify-Implementierungen zu erstellen.

Die folgende Abbildung zeigt die Kommunikation zwischen Beratungssenkenobjekten, Empfehlungsquellobjekten und MAPI. MAPI ist nur beteiligt, wenn die Empfehlungsquelle die IMAPISupport-Methoden zur Unterstützung von Benachrichtigungen aufruft.

Ereignisbenachrichtigungsaufrufe

Die MFCMAPI-Klasse CAdviseSink (mit den Dateien AdviseSink.h und AdviseSink.cpp) implementiert das Objekt der Empfehlungssenke für alle Aufrufe von Advise. Weitere Informationen zu MFCMAPI finden Sie unter MFCMAPI als Codebeispiel und MFCMAPI.