IMAPISupport::Notify

The IMAPISupport::Notify method sends a notification of a specified event to an advise source that originally registered for the notification through IMAPISupport::Subscribe.

Quick Info

See IMAPISupport : IUnknown.

HRESULT Notify(
  LPNOTIFKEY lpKey,                 
  ULONG cNotification,              
  LPNOTIFICATION lpNotifications,   
  ULONG FAR * lpulFlags             
);

Parameters

lpKey

[in] Pointer to the notification key for the advise source object. The lpKey parameter cannot be NULL.

cNotification

[in] Count of notification structures pointed to by the lpNotifications parameter.

lpNotifications

[in] Pointer to an array of NOTIFICATION structures describing pending notifications.

lpulFlags

[in, out] 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, the following flag can be set by MAPI:

NOTIFY_CANCELED: A callback function canceled a synchronous notification.

Return Values

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 IMAPISupport::Subscribe.

Notify copies the structures pointed to by the lpNotifications parameter into memory and calls the appropriate advise sink's IMAPIAdviseSink::OnNotify method. When 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.

Make 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 zero in lpulFlags, the process is still active and you should continue to send notifications as appropriate.

When using synchronous notifications, be careful to avoid deadlock situations.

For more information on the notification process, see Event Notification in MAPI.