IMAPIAdviseSink::OnNotify

The IMAPIAdviseSink::OnNotify method responds to a notification by performing one or more tasks. The tasks performed depend on the object generating the notification and type of event.

Quick Info

See IMAPIAdviseSink : IUnknown.

ULONG OnNotify(
  ULONG cNotif,                   
  LPNOTIFICATION lpNotifications  
);

Parameters

cNotif: [in] Count of NOTIFICATION structures pointed to by the lpNotifications parameter.
lpNotifications: [in] 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 begins 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 — an object that implements IMAPIAdviseSink. 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 insure 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 — 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 setting up and stopping 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 deem 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 of the affected 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 of the new messages.

For more information about how and when to generate notifications, see the topics:

Event Notification in MAPI

Supporting Event Notification