Last modified: January 16, 2009
Applies to: Office 2010 | Outlook 2010 | Visual Studio
Sends a notification of a specified event to an advise source that originally registered for the notification through the IMAPISupport::Subscribe method.
The IMAPISupport::Notify method is implemented for all service provider support objects. Service providers call Notify to request that MAPI generate a notification for an advise sink that has previously registered for the notification through the IMAPISupport::Subscribe method.
Notify copies the structures pointed to by the lpNotifications parameter into memory and calls the appropriate advise sink's IMAPIAdviseSink::OnNotify method. When OnNotify is finished with the notification, it releases the memory involved. The caller does not need to allocate memory; MAPI performs all necessary memory allocation.
The notification key passed in the lpKey parameter should be identical to the key passed in lpKey to the IMAPISupport::Subscribe method. Many providers use the entry identifier of the advise source as the key, but other data, such as a file path, can be used. MAPI uses this key to find all the registrations for notifications on the identified advise source.
Be sure that you set the lpEntryID member of the notification structure to a long-term entry identifier.
If you set the NOTIFY_SYNC flag on the Subscribe call for any of the pending notifications, Notify calls the IMAPIAdviseSink::OnNotify method callback functions before returning. An advise sink can be created manually or by calling HrAllocAdviseSink. The HrAllocAdviseSink function allows its caller to specify a callback function that Notify calls as part of the notification. The callback function conforms to the NOTIFCALLBACK prototype. Callback functions implemented by clients always return S_OK; callback functions implemented by service providers can return CALLBACK_DISCONTINUE.
If a callback function returns CALLBACK_DISCONTINUE, MAPI stops sending notifications and returns NOTIFY_CANCELED in the Notify method's lpulFlags parameter. You can assume that the process is inactive and stop generating notifications for that process. If Notify returns 0 in lpulFlags, the process is still active and you should continue to send notifications, as appropriate.
When you use synchronous notifications, be careful to avoid deadlock situations.
For more information about the notification process, see Event Notification in MAPI.