TABLE_NOTIFICATION 

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.

Quick Info

typedef struct _TABLE_NOTIFICATION

{ 

     ULONG        ulTableEvent; 

     HRESULT      hResult; 

     SPropValue   propIndex; 

     SPropValue   propPrior; 

     SRow         row;

} TABLE_NOTIFICATION;

Members

ulTableEvent

Bitmask of flags used to represent the table event type. The following flags can be set:

TABLE_CHANGED

Indicates at a high level that something about the table has changed. The table s state is as it was before the event, meaning that all PR_INSTANCE_KEY properties, bookmarks, current positioning, and user interface selections are still valid.

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.

TABLE_ERROR

An error has occurred, usually during the processing of an asynchronous operation. Errors during the processing of the following methods can generate this event:

IMAPITable::SortTable

IMAPITable::SetColumns

IMAPITable::Restrict

The IMAPITable::GetLastError method cannot provide any further information about the error because it was generated at some previous point, not necessarily from the last method call.

TABLE_RELOAD

The data in the table should be reloaded. Service providers send TABLE_RELOAD when, for example, the underlying data is stored in a database and the database is replaced.

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_RESTRICT_DONE

A restriction operation initiated with an IMAPITable::Restrict method call has completed.

TABLE_ROW_ADDED

A new row has been added to the table and the corresponding object saved. TABLE_ROW_ADDED events are generated after a call to the object s IMAPIProp::SaveChanges method.

TABLE_ROW_DELETED

A row has been removed from the table. The propPrior member is set to NULL.

TABLE_ROW_MODIFIED

A row has been changed. The row member contains the affected properties for the row. Multiple TABLE_ROW_MODIFIED events are sent in the order that they appear in the table view.

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 the value of the property tag in the propPrior member is PR_NULL.

TABLE_SETCOL_DONE

A column setting operation initiated with an IMAPITable::SetColumns method call has competed.

TABLE_SORT_DONE

A table sorting operation initiated with an IMAPITable::SortTable method call has competed.

hResult

HRESULT value for the error that has occurred, if the ulTableEvent member is set to TABLE_ERROR.

propIndex

SPropValue81C9._8 structure for the PR_INSTANCE_KEY property of the affected row.

propPrior

SPropValue structure for the PR_INSTANCE_KEY property of the row preceding the affected one. If the affected row is the first row in the table, propPrior must be set to PR_NULL and not zero. Zero is not a valid property tag.

row

SRowB8USB6 structure containing the data for the affected row. This structure is filled for all table notification events, even if an event of the current type doesn t require it. For table notification events that do not pass row data, the cValues member of the SRow structure is set to zero and lpProps member is NULL. This SRow structure is read-only; to make modifications, a copy must be made. 

Remarks

The TABLE_NOTIFICATION structure is one of the members of the union of structures included in the info member of the NOTIFICATION1KRZ0QA structure. When the info member of a NOTIFICATION structure contains a TABLE_NOTIFICATION structure, the ulEventType member of the NOTIFICATION structure is set to fnevTableModified.

When table notifications are generated, a NOTIFICATION1KRZ0QA structure that includes a TABLE_NOTIFICATION structure in its info member is constructed. The TABLE_NOTIFICATION19A4ZN9 describes the change that has occurred to the table.

The properties that are included in the row member are ordered using the column set that was established from the previous IMAPITable::SetColumns call, if one occurred. If a SetColumns call has been made after the notification was generated, the column set described in the row member will not match the current set of columns. If no SetColumns call was made prior to the notification being sent, the columns are ordered in a default order decided by the table implementer.

For more information about notification, see the topics described in the following table.

Because table notifications are asynchronous, clients and service providers might receive a notification of an added row after they have learned of the addition. 

They might 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.

See Also