IMSLogon::Advise
Applies to: Outlook 2013 | Outlook 2016
Registers an object with a message store provider for notifications about changes in the message store. The message store will then send notifications about changes to the registered object.
HRESULT Advise(
ULONG cbEntryID,
LPENTRYID lpEntryID,
ULONG ulEventMask,
LPMAPIADVISESINK lpAdviseSink,
ULONG FAR * lpulConnection
);
Parameters
cbEntryID
[in] The size, in bytes, of the entry identifier pointed to by the lpEntryID parameter.
lpEntryID
[in] A pointer to the entry identifier of the object about which notifications should be generated. This object can be a folder, a message, or any other object in the message store. Alternatively, if MAPI sets the cbEntryID parameter to 0 and passes null for lpEntryID, the advise sink provides notifications about changes to the entire message store.
ulEventMask
[in] An event mask of the types of notification events occurring for the object about which MAPI will generate notifications. The mask filters specific cases. Each event type has a structure associated with it that contains additional information about the event. The following table lists the possible event types along with their corresponding structures.
| Notification event type | Corresponding structure |
|---|---|
| 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] A pointer to an advise sink object to be called when an event occurs for the session object about which notification has been requested. This advise sink object must already exist.
lpulConnection
[out] A pointer to a variable that upon a successful return holds the connection number for the notification registration. The connection number must be nonzero.
Return value
S_OK
The call succeeded and has returned the expected value or values.
MAPI_E_NO_SUPPORT
The operation is not supported by MAPI or by one or more service providers.
Remarks
Message store providers implement the IMSLogon::Advise method to register an object for notification callbacks. Whenever a change occurs to the indicated object, the provider checks to see what event mask bit was set in the ulEventMask parameter and, therefore, what type of change occurred. If a bit is set, the provider calls the IMAPIAdviseSink::OnNotify method for the advise sink object indicated by the lpAdviseSink parameter to report the event. Data passed in the notification structure to the OnNotify routine describes the event.
The call to OnNotify can occur during the call that changes the object, or at any later time. On systems that support multiple threads of execution, the call to OnNotify can occur on any thread. To safely handle a call to OnNotify that might happen at an inopportune time, a client application should use the HrThisThreadAdviseSink function.
To provide notifications, the message store provider that implements Advise needs to keep a copy of the pointer to the lpAdviseSink advise sink object; to do so, the provider calls the IUnknown::AddRef method for the advise sink to maintain its object pointer until notification registration is canceled with a call to the IMSLogon::Unadvise method. The Advise implementation should assign a connection number to the notification registration and call AddRef on this connection number before returning it in the lpulConnection parameter. Service providers can release the advise sink object before the registration is canceled, but they must not release the connection number until Unadvise has been called.
After a call to Advise has succeeded and before Unadvise has been called, providers must be prepared for the advise sink object to be released. Therefore, a provider should release its advise sink object after Advise returns, unless it has a specific long-term use for it.
For more information about the notification process, see Event Notification in MAPI.