Export (0) Print
Expand All

IMAPIAdviseSink::OnNotify

Last modified: July 23, 2011

Applies to: Outlook

In this article
Notes to Implementers
Notes to Callers
MFCMAPI Reference

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
);

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.

S_OK

The notification was processed successfully.

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.

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.

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.

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.

Show:
© 2014 Microsoft