Handling message store notification

Applies to: Outlook 2013 | Outlook 2016

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:

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.