Platform SDK: MAPI |
The TABLE_NOTIFICATION structure describes a row in a table that has been affected by some type of event, such as a change or an error, causing a table notification to be generated.
Header file: | MAPIDEFS.H |
typedef struct _TABLE_NOTIFICATION { ULONG ulTableEvent; HRESULT hResult; SPropValue propIndex; SPropValue propPrior; SRow row; } TABLE_NOTIFICATION;
Handle this event by re-reading the entire table. Service providers that do not want to implement "rich" table notifications simply send TABLE_CHANGED events rather than more detailed events to indicate a particular type of change.
IMAPITable::SortTable
IMAPITable::SetColumns
IMAPITable::Restrict
After receiving a TABLE_ERROR event, a client cannot rely on the accuracy of the table contents. Also, pending notifications about other changes might be lost.
The IMAPITable::GetLastError method might not provide any further information about the error because it was generated at some previous point, not necessarily from the last method call.
Handle this event by assuming that nothing about the table is still valid and by re-reading the entire table. All bookmarks, instance keys, status and positioning information are invalid.
TABLE_ROW_MODIFIED events are sent after changes to the corresponding object have been committed with a call to the object's IMAPIProp::SaveChanges method. If the modified row is now the first row in the table, the value of the property tag in the propPrior member is PR_NULL.
Because this SRow structure is read-only; clients must make a copy of it if they want to make modifications. The ScDupPropSet function can be used to make the copy.
The TABLE_NOTIFICATION structure is one of the members of the union of structures included in the info member of the NOTIFICATION structure. The info member includes a TABLE_NOTIFICATION structure when the ulEventType member of the structure is set to fnevTableModified.
The order and type of columns in the row member reflect the order and type that was in effect at the time that the notification was generated, which is not necessarily the same as when the notification was delivered.
For more information about notification, see the topics described in the following table.
Topic | Description |
---|---|
Event Notification in MAPI | General overview of notification and notification events. |
Handling Notifications | Discussion of how clients should handle notifications. |
Supporting Event Notification | Discussion of how service providers can use the IMAPISupport method to generate notifications. |
Because table notifications are asynchronous, it is possible to receive notification of an added row after learning about the addition through another means. It is possible to receive a TABLE_ERROR event when there is an error in an IMAPITable::Sort, IMAPITable::Restrict, or IMAPITable::SetColumns method or when an underlying process attempts to update a table with, for example, new or modified rows.
Notification Structures, IMAPITable::Restrict, IMAPITable::SetColumns, NOTIFICATION, SPropValue, SRow