IMSLogon::Advise
Gilt für: Outlook 2013 | Outlook 2016
Registriert ein -Objekt bei einem Nachrichtenspeicheranbieter für Benachrichtigungen zu Änderungen im Nachrichtenspeicher. Der Nachrichtenspeicher sendet dann Benachrichtigungen zu Änderungen an das registrierte Objekt.
HRESULT Advise(
ULONG cbEntryID,
LPENTRYID lpEntryID,
ULONG ulEventMask,
LPMAPIADVISESINK lpAdviseSink,
ULONG FAR * lpulConnection
);
Parameter
cbEntryID
[in] Die Größe des Eintragsbezeichners in Bytes, auf die der lpEntryID-Parameter verweist.
lpEntryID
[in] Ein Zeiger auf den Eintragsbezeichner des Objekts, über das Benachrichtigungen generiert werden sollen. Bei diesem Objekt kann es sich um einen Ordner, eine Nachricht oder ein beliebiges anderes Objekt im Nachrichtenspeicher handeln. Wenn MAPI den cbEntryID-Parameter auf 0 festlegt und null für lpEntryID übergibt, stellt die Empfehlungssenke alternativ Benachrichtigungen über Änderungen am gesamten Nachrichtenspeicher bereit.
ulEventMask
[in] Eine Ereignismaske der Typen von Benachrichtigungsereignissen, die für das Objekt auftreten, über das MAPI Benachrichtigungen generiert. Die Maske filtert bestimmte Fälle. Jedem Ereignistyp ist eine Struktur zugeordnet, die zusätzliche Informationen zum Ereignis enthält. In der folgenden Tabelle sind die möglichen Ereignistypen zusammen mit den entsprechenden Strukturen aufgeführt.
| Benachrichtigungsereignistyp | Entsprechende Struktur |
|---|---|
| fnevCriticalError |
ERROR_NOTIFICATION |
| fnevNewMail |
NEWMAIL_NOTIFICATION |
| fnevObjectCreated |
OBJECT_NOTIFICATION |
| fnevObjectDeleted |
OBJECT_NOTIFICATION |
| fnevObjectModified |
OBJECT_NOTIFICATION |
| fnevObjectCopied |
OBJECT_NOTIFICATION |
| fnevObjectMoved |
OBJECT_NOTIFICATION |
| fnevSearchComplete |
OBJECT_NOTIFICATION |
| fnevStatusObjectModified |
STATUS_OBJECT_NOTIFICATION |
lpAdviseSink
[in] Ein Zeiger auf ein Empfehlungssenkenobjekt, das aufgerufen werden soll, wenn ein Ereignis für das Sitzungsobjekt auftritt, über das eine Benachrichtigung angefordert wurde. Dieses Empfehlungssenkenobjekt muss bereits vorhanden sein.
lpulConnection
[out] Ein Zeiger auf eine Variable, die bei erfolgreicher Rückgabe die Verbindungsnummer für die Benachrichtigungsregistrierung enthält. Die Verbindungsnummer muss ungleich null sein.
Rückgabewert
S_OK
Der Aufruf erfolgreich ausgef�hrt und der erwartete Wert oder Werte zur�ckgegeben hat.
MAPI_E_NO_SUPPORT
Der Vorgang wird von MAPI oder von mindestens einem Dienstanbieter nicht unterstützt.
Hinweise
Nachrichtenspeicheranbieter implementieren die IMSLogon::Advise-Methode , um ein Objekt für Benachrichtigungsrückrufe zu registrieren. Wenn eine Änderung am angegebenen Objekt erfolgt, überprüft der Anbieter, welches Ereignismaskenbit im ulEventMask-Parameter festgelegt wurde und welche Art von Änderung daher aufgetreten ist. Wenn ein Bit festgelegt ist, ruft der Anbieter die IMAPIAdviseSink::OnNotify-Methode für das vom lpAdviseSink-Parameter angegebene Advise-Senkenobjekt auf, um das Ereignis zu melden. Daten, die in der Benachrichtigungsstruktur an die OnNotify-Routine übergeben werden, beschreiben das Ereignis.
Der Aufruf von OnNotify kann während des Aufrufs, der das Objekt ändert, oder zu einem späteren Zeitpunkt erfolgen. Auf Systemen, die mehrere Ausführungsthreads unterstützen, kann der Aufruf von OnNotify für jeden Thread erfolgen. Um einen Aufruf von OnNotify , der möglicherweise zu einem ungünstigen Zeitpunkt erfolgt, sicher zu verarbeiten, sollte eine Clientanwendung die Funktion HrThisThreadAdviseSink verwenden.
Um Benachrichtigungen bereitzustellen, muss der Nachrichtenspeicheranbieter, der Advise implementiert, eine Kopie des Zeigers auf das lpAdviseSink-Beratungssenkenobjekt aufbewahren. Dazu ruft der Anbieter die IUnknown::AddRef-Methode für die Empfehlungssenke auf, ihren Objektzeiger beizubehalten, bis die Benachrichtigungsregistrierung mit einem Aufruf der IMSLogon::Unadvise-Methode abgebrochen wird. Die Advise-Implementierung sollte der Benachrichtigungsregistrierung eine Verbindungsnummer zuweisen und AddRef für diese Verbindungsnummer aufrufen, bevor sie im lpulConnection-Parameter zurückgegeben wird. Dienstanbieter können das Objekt der Empfehlungssenke freigeben, bevor die Registrierung abgebrochen wird, aber sie dürfen die Verbindungsnummer erst freigeben, wenn Unadvise aufgerufen wurde.
Nachdem ein Aufruf von Advise erfolgreich war und bevor Unadvise aufgerufen wurde, müssen anbieter darauf vorbereitet sein, dass das Beratungssenke-Objekt freigegeben wird. Daher sollte ein Anbieter sein Beratungssenkenobjekt nach der Rückgabe von Advise freigeben, es sei denn, er verfügt über eine bestimmte langfristige Verwendung.
Weitere Informationen zum Benachrichtigungsprozess finden Sie unter Ereignisbenachrichtigung in MAPI.