Unterstützende Ereignisbenachrichtigung
Gilt für: Outlook 2013 | Outlook 2016
Da die Unterstützung von Ereignisbenachrichtigungen kompliziert sein kann, stellt MAPI drei Unterstützungsobjektmethoden bereit, die die schwierigsten Teile des Prozesses implementieren. Diese Methoden funktionieren als Einheit, und ein Anbieter muss alle drei oder keine davon verwenden.
Die MAPI-Unterstützungsmethoden verwenden Benachrichtigungsschlüssel, um die Verbindungen zwischen den Beratungssenken und den Objekten zu verwalten, die die Benachrichtigungen generieren. Ein Benachrichtigungsschlüssel ist eine NOTIFKEY-Struktur , die Binärdaten enthält, die ein Objekt prozessübergreifend identifizieren. Ein Benachrichtigungsschlüssel wird in der Regel aus dem Langzeiteintragsbezeichner des Quellenobjekts "Advise" kopiert. Wenn der Client im Aufruf von Advise einen Eintragsbezeichner angegeben hat, können Sie ihn für den Benachrichtigungsschlüssel verwenden. Wenn der lpEntryID-Parameter für Advise NULL ist, verwenden Sie den Eintragsbezeichner des äußerst möglichen Containerobjekts, z. B. des Nachrichtenspeichers.
Um die Supportmethoden zu verwenden, rufen Sie IMAPISupport::Subscribe auf, wenn ein Client Ihre Advise-Methode aufruft, um sich für eine Benachrichtigung zu registrieren. Ordnen Sie eine NOTIFKEY-Struktur zu, und erstellen Sie einen eindeutigen Benachrichtigungsschlüssel für Ihr Empfehlungsquellobjekt. Beispielsweise erstellt ein Nachrichtenspeicheranbieter, der aufgefordert wird, einen Client zu benachrichtigen, wenn eine Nachricht in einem bestimmten Ordner empfangen wird, einen Benachrichtigungsschlüssel für diesen Ordner. Übergeben Sie einen Zeiger auf die NOTIFKEY-Struktur im Aufruf von Subscribe zusammen mit einem Zeiger auf die Empfehlungssenke des Clients. Subscribe ruft die IUnknown::AddRef-Methode der Empfehlungssenke auf, um die Verweisanzahl zu erhöhen, und MAPI behält den Zeiger bei, bis die Registrierung abgebrochen wird.
Sie können das NOTIFY_SYNC-Flag an die Anforderung Subscribe to übergeben, dass Notify synchron verhält und erst zurückgegeben wird, wenn alle Aufrufe der IMAPIAdviseSink::OnNotify-Methoden registrierter Beratungssenken durchgeführt wurden. Legen Sie dieses Flag nur für Ihre eigene interne Verwendung fest. Legen Sie sie nicht fest, wenn Sie auf einen Client-Empfehlungsaufruf antworten. Ereignisbenachrichtigungen zwischen Clients und Anbietern sind immer asynchron. Das heißt, MAPI garantiert, dass der Aufruf, in dem ein Ereignis stattfindet, an den Client zurückgesendet wird, bevor einer der OnNotify-Aufrufe erfolgt.
Wenn Sie das NOTIFY_SYNC-Flag festlegen, nehmen Sie keine Änderungen an den Objekten der Empfehlungssenke vor, und übergeben Sie keine Wrapper-Empfehlungssenke, die von HrThisThreadAdviseSink erstellt wurde, an Subscribe. HrThisThreadAdviseSink erstellt eine threadsichere Version einer Empfehlungssenke, die nur mit asynchroner Benachrichtigung verwendet werden soll.
Wenn eine für synchrone Benachrichtigung registrierte Empfehlungssenke von OnNotify mit festgelegtem CALLBACK_DISCONTINUE-Flag zurückgibt, legt IMAPISupport::Notify das NOTIFY_CANCELED-Flag fest und gibt ohne Aufrufe an OnNotify zurück.
Sobald "Subscribe " zurückgegeben wurde, müssen Sie Ihre Kopie der Empfehlungssenke des Kunden nicht mehr beibehalten. Rufen Sie die IUnknown::Release-Methode auf, um sie freizugeben. Subscribe gibt eine Verbindungsnummer ungleich null zurück, die Sie an den Client zurückgeben sollten. Die Verbindungsnummer stellt die Verbindung zwischen der Empfehlungsquelle und der Empfehlungssenke dar. Sie bleibt solange gültig, bis der Client unadvise erfolgreich aufruft.
Wenn der Client bereit ist, eine Registrierung abzubrechen, ruft er Ihre Unadvise-Methode auf. Übergeben Sie die Verbindungsnummer aus dem Unadvise-Aufruf an IMAPISupport::Unsubscribe. Das Abmelden ruft die IUnknown::Release-Methode der Empfehlungssenke auf. Wie bei Advise und Unadvise müssen Aufrufe von Abonnieren und Abmelden gekoppelt werden. Sie müssen für jeden Anruf, der an "Subscribe" erfolgt, einen Anruf an "Abmelden" senden. Sie müssen jedoch nicht jedes Mal Abonnieren aufrufen, wenn Ihre Advise-Methode aufgerufen wird. Umgekehrt können Sie sie zum Einrichten interner Benachrichtigungen aufrufen.
Wenn ein Ereignis auftritt, weisen Sie eine oder mehrere NOTIFICATION-Strukturen des für das Ereignis geeigneten Typs zu, und rufen Sie IMAPISupport::Notify auf. Notify generiert eine Benachrichtigung für jede registrierte Empfehlungssenke. Sie sollten alle nicht verwendeten Member der NOTIFICATION-Struktur auf 0 (null) festlegen. Diese Technik zum Initialisieren der NOTIFICATION-Struktur kann Clients helfen, kleinere, schnellere und weniger fehleranfällige OnNotify-Implementierungen zu erstellen.
Beachten Sie, dass für jedes Ereignis eine separate NOTIFICATION-Struktur erforderlich ist, auch für mehrere Ereignisse desselben Typs. Wenn beispielsweise drei Clients für die Tabellenbenachrichtigung für eine bestimmte Tabelle registriert sind und der Tabelle fünf Zeilen hinzugefügt werden, müssen Sie fünf OBJECT_NOTIFICATION Strukturen für Ihren Notify-Aufruf erstellen. Eine Batchbenachrichtigung wie diese führt zu einer besseren Leistung als das fünffache Aufrufen von Notify . Für jeden Notify-Aufruf ruft MAPI die IMAPIAdviseSink::OnNotify-Methode jeder registrierten Beratungssenke auf. Wenn keine registrierten Empfehlungssenken vorhanden sind, ignoriert MAPI den Aufruf.
Dienstanbieter, die Batchbenachrichtigungen senden, müssen diese bestellen, damit sie von der ersten Benachrichtigung bis zur letzten interpretiert werden können. Diese Reihenfolge ist besonders dann erforderlich, wenn ein Benachrichtigungsbatch eine Reihe von Ereignissen enthält, z. B. TABLE_ROW_ADDED mit einem Ereignis, das auf eine vorherige Zeile verweist, die in einem anderen Ereignis im selben Batch hinzugefügt wurde.