When Notifications Are Sent

OLE DB Programmer's Reference

Providers send notifications when changes occur to provider objects, such as rowset objects, that are shared by two or more consumers. For example, when several consumers share a rowset object and one of them changes the rowset by calling an IRowsetChange method, the provider can notify the other consumers in case they need to refresh their local copies of row data. To receive these notifications, consumers must implement IRowsetNotify and register it on a connection point with the provider, which calls IRowsetNotify methods to send notifications to consumers. The consumers then take on the roll of listeners, alert to notifications of changes to the object as sent out by the provider.

Note   Providers do not send notifications when changes are attempted but fail.

Notifications also can be used to coordinate sets of changes performed by multiple consumers. Often such changes occur in phases, during which participating consumers make changes based on changes made by other consumers in previous phases.

Notifications can be nested. That is, sending one notification can cause a consumer to take actions that cause another notification to be sent.

Notifications can also be grouped. For example, providers that support notifications can be instructed to send only two notifications for an operation on multiple rowsets: one for all rows that succeeded and one for all rows that failed. If a provider supports grouping of notifications, it reports a value of DBPROPVAL_NT_MULTIPLEROWS for the property DBPROP_NOTIFICATIONGRANULARITY.

If an action by the consumer causes the provider to send multiple notifications, all of those notifications must be approved by the consumer that instigated the action before the provider performs the action. If a consumer cancels a single notification, the provider does not perform the action and returns DB_E_CANCELED. For example, if a call to IRowsetChange::SetData changes multiple columns, the consumer that made the call must approve the changes to all of the columns before the provider changes any of the columns. If the consumer does not allow a change to any single column, no columns are updated. For more information, see the entry for IRowsetChange::SetData in the reference section.

Consumers can screen out unwanted notifications of events by returning DB_S_UNWANTEDREASON or DB_S_UNWANTEDPHASE when the provider calls the consumer's IRowsetNotify methods to report the unwanted notifications. Other actions on a rowset will continue to send out notifications for all phases unless they are also specifically screened. Although providers are not required to stop notifying consumers of the unwanted notifications, they can choose, for performance reasons, not to send notifications of unwanted events.

1998-2001 Microsoft Corporation. All rights reserved.