When Notifications Are Sent

Notifications are sent when significant changes occur to row or rowset state. Many of the events have multiple phases, which occur because multiple consumers may need to cooperate to validate and safely perform the transitions. These phases correspond to initial validation, preparation, commit, and operation completion.

Providers do not send notifications when no work will be done. For example, providers would not send notifications in the following cases:

• The method returns a trivial error, such as E_INVALIDARG.
  
  
• The method accepts an array of values to operate on, and the array size is zero.
  
  
• The provider is in a state where the method will always fail.

It is possible for notifications to be nested. That is, sending one notification can cause a consumer to take actions that cause another notification to be sent.

Notifications also can be grouped. If a provider supports grouping of notifications, it will report a value of DBPROPVAL_NT_MULTIPLEROWS for the property DBPROP_NOTIFICATIONGRANULARITY. If an action causes the provider to send multiple notifications, all of those notifications must be approved by the consumer 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 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 of the columns, no columns are updated.

Consumers can screen out unwanted events or phases of an event by returning DB_S_UNWANTEDREASON or DB_S_UNWANTEDPHASE from the methods on IRowsetNotify. There is no guaranteed effect, but an optimized provider may cease sending the unwanted event or phase of an event. Screening out a phase applies only to that particular event. Other events will still send out notifications for all phases unless they are also screened.