Handling Message Store Notification
Applies to: Office 2010 | Outlook 2010 | Visual Studio
To register for message store notifications, call either the IMAPISession::Advise or IMsgStore::Advise method and specify a message store, folder, or message entry identifier in the contents of the lpEntryID parameter. Message store providers support both object and table notifications. Whether you register with particular message store objects, with the folder hierarchy and contents tables that describe these objects, or with both objects and tables depends on the notifications you expect to see, the calls you make to perform operations, and how the message store provider supports notification.
Because MAPI allows flexibility in how providers support notifications, be aware that you will not always receive the same type of notification in response to a particular event from all message store providers. Some message store providers do not support notifications at all. To determine if the message store you are using supports notification, look for the STORE_NOTIFY_OK bit in its PR_STORE_SUPPORT_MASK (PidTagStoreSupportMask) property.
At one end of the spectrum of message store providers that support notification are the providers that generate "rich" notifications; these providers send descriptive notifications for all registered advise sources. At the other end are the message store providers that support limited notifications; these providers send general notifications for a restricted number of advise sources.
For example, if you copy a message to a folder with which you have registered to receive both object copied and object moved notifications, you may or may not receive the object copied notification. Whether or not you receive it depends on:
The method that you called to perform the copy. This could be IMAPIFolder::CopyMessages, IMAPIProp::CopyTo, or IMAPIProp::CopyProps.
How the message store provider implements the copy method.
Whether or not the message store provider supports object copied notifications on folders.
Because there are no strict guidelines that describe how to implement event notification for message store providers, clients cannot expect consistent behavior. MAPI does make recommendations as to how message store providers implement event notification and the following table outlines these recommendations. Read the table as follows: after you perform the operation in the first column, expect to receive a notification of the type listed in the second column if you have registered for that type with the object listed in the third column. For example, after you have created a folder, you will receive an fnevObjectCreated notification only if you have registered for fnevObjectCreated notifications with the message store.
Operation |
Event type |
Advise source |
|---|---|---|
Create a folder |
fnevObjectCreated |
Message store |
Delete a folder |
fnevObjectDeleted |
Message store Deleted folder |
Move a folder from one folder to another |
fnevObjectMoved |
Message store Moved folder |
Copy a folder from one folder to another |
fnevObjectCopied |
Message store and copied folder (no fnevObjectCreated notification sent for the new copy of the folder) |
Change in a computed folder property (PR_SUBFOLDERS (PidTagSubfolders), PR_CONTENT_UNREAD (PidTagContentUnreadCount), PR_CONTENT_COUNT (PidTagContentCount) |
fnevObjectModified |
Message store Changed folder (No notification to parent folder) |
Create a message |
fnevObjectCreated |
Message store |
Delete a message, causing a change in the parent folder's PR_CONTENT_COUNT property |
fnevObjectDeleted |
Message store Deleted message |
Move a message from one folder to another |
fnevObjectMoved |
Message store Moved message |
Copy a message from one folder to another |
fnevObjectCopied |
Message store Copied message (No fnevObjectCreated notification for new copy of the message) |
Save a message, causing a change in the parent folder's PR_CONTENT_COUNT property |
fnevObjectCreated |
Message store on first save only |
Save a message |
fnevObjectModified |
Message store on saves after the first save Changed message (No notification to parent folder) |
Complete a search operation |
fnevSearchComplete |
Message store Search folder |
New message |
fnevNewMail |
Message store |
Note
When you receive an object modified notification, remember that the property tag array portion of the OBJECT_NOTIFICATION structure pointed to by the lpNotifications parameter in the OnNotify call may or may not be NULL. Message store providers are not required to insert property information in this array and most do not. Make sure your OnNotify method can handle the case where the lpPropTagArray pointer is NULL.
For most, if not all object notifications, update the view of the affected folder or folders.