IMsgStore::Advise
Applies to: Outlook 2013 | Outlook 2016
Registers to receive notification of specified events that affect the message store.
HRESULT Advise(
ULONG cbEntryID,
LPENTRYID lpEntryID,
ULONG ulEventMask,
LPMAPIADVISESINK lpAdviseSink,
ULONG_PTR lpulConnection
);
Parameters
cbEntryID
[in] The byte count in the entry identifier pointed to by the lpEntryID parameter.
lpEntryID
[in] A pointer to the entry identifier of the folder or message about which notifications should be generated, or null. If lpEntryID is set to NULL, Advise registers for notifications on the entire message store.
ulEventMask
[in] A mask of values that indicate the types of notification events that the caller is interested in and should be included in the registration. There is a corresponding NOTIFICATION structure associated with each type of event that holds information about the event. The following are valid values for the ulEventMask parameter:
fnevCriticalError
Registers for notifications about severe errors, such as insufficient memory.
fnevExtended
Registers for notifications about events specific to the particular message store provider.
fnevNewMail
Registers for notifications about the arrival of new messages.
fnevObjectCreated
Registers for notifications about the creation of a new folder or message.
fnevObjectCopied
Registers for notifications about a folder or message being copied.
fnevObjectDeleted
Registers for notifications about a folder or message being deleted.
fnevObjectModified
Registers for notifications about a folder or message being modified.
fnevObjectMoved
Registers for notifications about a folder or message being moved.
fnevSearchComplete
Registers for notifications about the completion of a search operation.
lpAdviseSink
[in] A pointer to an advise sink object to receive the subsequent notifications. This advise sink object must have already been allocated.
lpulConnection
[out] A pointer to a nonzero number that represents the connection between the caller's advise sink object and the session.
lpAdviseSink
[in] A pointer to an advise sink object to receive the subsequent notifications. This advise sink object must have already been allocated.
lpulConnection
[out] A pointer to a nonzero connection number that represents the connection between the caller's advise sink object and the message store.
Return value
S_OK
The registration was successful.
MAPI_E_NO_SUPPORT
The message store provider does not support registration for notification through the message store.
Remarks
The IMsgStore::Advise method establishes a connection between the caller's advise sink object and either the message store or an object in the message store. This connection is used to send notifications to the advise sink when one or more events, as specified in the ulEventMask parameter, occur to the advise source object. When the lpEntryID parameter points to a valid entry identifier, the advise source is the object identified by this entry identifier. When lpEntryID is NULL, the advise source is the message store.
To send a notification, either the message store provider or MAPI calls the registered advise sink's IMAPIAdviseSink::OnNotify method. One of the parameters to OnNotify, a notification structure, contains information that describes the specific event.
Notes to implementers
You can support notification with or without help from MAPI. MAPI has three support object methods for helping service providers implement notification: IMAPISupport::Subscribe, IMAPISupport::Unsubscribe, and IMAPISupport::Notify. If you elect to use the MAPI support methods, call Subscribe when your Advise method is called and release the lpAdviseSink pointer.
If you elect to support notification yourself, call the IUnknown::AddRef method of the advise sink represented by the lpAdviseSink parameter to keep a copy of this pointer. Maintain this copy until your IMsgStore::Unadvise method is called to cancel the registration.
Regardless of how you support notification, assign a nonzero connection number to the notification registration and return it in the lpulConnection parameter. Do not release this connection number until Unadvise has been called and has completed.
Notes to callers
On systems that support multiple threads of execution, the call to OnNotify can also occur on any thread at any time. If you must be assured that notifications occur only at a particular time on a particular thread, call the HrThisThreadAdviseSink function to generate the advise sink object that you pass to Advise.
After a call to Advise has succeeded and before Unadvise has been called to cancel the registration, be prepared for the advise sink object to be released. You should release your advise sink object after Advise returns unless you have a specific long-term use for it.
For more information about the notification process, see Event Notification in MAPI.
For more information about handling notifications, see Handling Notifications.
MFCMAPI reference
For MFCMAPI sample code, see the following table.
| File | Function | Comment |
|---|---|---|
| BaseDialog.cpp |
CBaseDialog::OnNotificationsOn |
MFCMAPI uses the IMsgStore::Advise method to register for notifications on the entire message store. |