IMAPIAdviseSink::OnNotify

Article
05/31/2022

Applies to: Outlook 2013 | Outlook 2016

Responds to a notification by performing one or more tasks. The tasks performed depend on the type of event and the object that generates the notification.

ULONG OnNotify(
  ULONG cNotif,
  LPNOTIFICATION lpNotifications
);

Parameters

cNotif

[in] The count of NOTIFICATION structures pointed to by the lpNotifications parameter.

lpNotifications

[in] A pointer to one or more NOTIFICATION structures that provide information about the events that have occurred.

Return value

S_OK

The notification was processed successfully.

Remarks

The notification process starts when a client or MAPI makes a call to a service provider's Advise method to register to receive a notification of a particular type for a particular object. One of the parameters to the Advise method is a pointer to an advise sink object that implements the IMAPIAdviseSink interface. When an event occurs to the target object that corresponds to the registered notification, the service provider, either directly or indirectly through MAPI, calls the advise sink's OnNotify method.

The call to OnNotify can occur either during the MAPI call that is causing the event or at some later time. On systems that support multiple threads of execution, OnNotify can be called either on the same thread that was used for registration or on a different thread. Clients can make sure that the OnNotify call is made on the same thread used to call Advise by creating the advise sink that they pass to Advise with the HrThisThreadAdviseSink function.

The lpNotifications parameter points to one or more NOTIFICATION structures that describe what has changed during the event. There is a different type of NOTIFICATION structure for each type of event.

The following table lists the values that are used to represent the possible types of events and the structures associated with each value:

Notification event type	Corresponding structure
fnevCriticalError	ERROR_NOTIFICATION
fnevNewMail	NEWMAIL_NOTIFICATION
fnevObjectCreated	OBJECT_NOTIFICATION
fnevObjectDeleted	OBJECT_NOTIFICATION
fnevObjectModified	OBJECT_NOTIFICATION
fnevObjectCopied	OBJECT_NOTIFICATION
fnevSearchComplete	OBJECT_NOTIFICATION
fnevTableModified	TABLE_NOTIFICATION
fnevStatusObjectModified	STATUS_OBJECT_NOTIFICATION
fnevExtended	EXTENDED_NOTIFICATION

For more information about how to set up and stop notifications, see the reference entries for the Advise and Unadvise methods for any of the following interfaces: IABLogon, IAddrBook, IMAPIForm, IMAPISession, IMAPITable, IMsgStore, and IMSLogon.

For general information about the notification process, see Event Notification in MAPI.

Notes to implementers

Your OnNotify implementation will typically consist of one or more blocks of code for each type of notification you expect to receive. Within these blocks of code, perform any tasks that you consider necessary as a response to the notification. For example, suppose you register to receive fnevObjectModified notifications on a folder that is included in a dialog box display. In the block of code that you include in your OnNotify method to handle fnevObjectModified notifications, you might send a Windows message to the dialog box to request an updated display.

Do not modify or free the NOTIFICATION structure passed to OnNotify. The data in the structure is valid only until OnNotify returns.

Notes to callers

When changes occur to multiple objects, you can notify a registered advise sink in a single call to OnNotify or in multiple calls depending on memory constraints. This is true regardless of whether the changes are the result of one method call or several. For example, a call to IMAPIFolder::CopyMessages can affect multiple messages and folders. As a message store provider, you can make one call to OnNotify with an fnevObjectModified event type for the target folder or many calls, one for each affect messages. Similarly, if a client makes repeated calls to IMAPIFolder::CreateMessage, these calls can be combined into one fnevObjectModified event for the folder or separated into individual fnevObjectCreated events for each new message.

For more information about how and when to generate notifications, see Event Notification in MAPI and Supporting Event Notification.

MFCMAPI reference

For MFCMAPI sample code, see the following table.

File	Function	Comment
AdviseSink.h and AdviseSink.cpp	CAdviseSink::OnNotifyDesc	The CAdviseSink class is implemented to handle all notifications in MFCMAPI.