Handling Message Store Notification

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

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.