IMAPISupport::Notify
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.
HRESULT Notify(
LPNOTIFKEY lpKey,
ULONG cNotification,
LPNOTIFICATION lpNotifications,
ULONG FAR * lpulFlags
);
Parameters
lpKey
[in] A pointer to the notification key for the advise source object. The lpKey parameter cannot be NULL.cNotification
[in] The count of notification structures pointed to by the lpNotifications parameter.lpNotifications
[in] A pointer to an array of NOTIFICATION structures that describe pending notifications.lpulFlags
[in, out] A bitmask of flags that controls the notification process. On input, the following flag can be set:- MAPI_UNICODE
The strings in the notification structures pointed to by lpNotifications are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.
On output, MAPI can set the following flag:
- NOTIFY_CANCELED
A callback function canceled a synchronous notification.
- MAPI_UNICODE
Return Value
- S_OK
The notifications were successfully generated.
Remarks
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.
Notes to Callers
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.