IRowsetNotify::OnRowChange

Notifies the consumer of the first change to a row, or any change that affects the entire row.

HRESULT OnRowChange (
   IRowset*            pRowset,
   ULONG            cRows,
   const HROW         rghRows[],
   DBREASON         eReason,
   DBEVENTPHASE   ePhase,
   BOOL               fCantDeny);

Parameters

pRowset

[in]
A pointer to the rowset, because the consumer may be receiving notifications from multiple rowsets and this identifies which one is calling.

cRows

[in]
The count of row handles in rghRows.

rghRows

[in]
An array of handles of rows that are changing. This array belongs to the caller (rowset) and must not be freed or used beyond the duration of the method call.

After this method returns, the reference count of these rows will be unchanged unless the consumer explicitly changes them. This is different from other methods that return rows to the consumer, in which the provider explicitly increments the reference counts. Therefore, if the consumer wants to guarantee that these row handles are valid after this method returns, it must call IRowset::AddRefRows for these rows while it is processing this method.

eReason

[in]
The reason of the event that caused this change. If this value is not recognized by the method, the method returns S_OK or DB_S_UNWANTEDREASON.

ePhase

[in]
The phase of this notification.

fCantDeny

[in]
When this flag is set to TRUE, the consumer cannot veto the event by returning S_FALSE because the provider cannot undo the event.

Return Code

S_OK
The method succeeded.

S_FALSE
The event/phase is vetoed by reason of logical objection or a failure to be able to implement, as permitted for the phase.

DB_S_UNWANTEDPHASE
The consumer is not interested in receiving this phase for this reason. The provider can optimize by making no further calls with this reason and phase. The phases for other reasons are unaffected.

DB_S_UNWANTEDREASON
The consumer is not interested in receiving any phases for this reason. The provider can optimize by making no further calls with this reason.

E_FAIL
A consumer-specific error occurred. Unless the consumer also returns S_FALSE, the provider continues the operation.

Comments

Possible reasons are any of the DBREASON_ROW_* reasons.

Phases occur as documented for the DBREASON enumeration. Prior values remain in the row up to and including the DBEVENTPHASE_ABOUTTODO phase. The new value is visible with the DBEVENTPHASE_SYNCHAFTER or later phases.

When a DBREASON_ROW_ACTIVATE notification is triggered, the array of row handles passed to OnRowChange is exactly the order in which the rows were fetched.

Unless the consumer returns S_FALSE, the provider continues the operation. This is true even if the consumer returns E_FAIL or any other error code.