IRowsetNotify::OnRowChange

OLE DB Programmer's Reference

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

HRESULT OnRowChange (    IRowset       *pRowset,    DBCOUNTITEM    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 for the change as indicated by the value of DBREASON. 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 notification, expressed by the value of DBREASON or DBEVENTPHASE or both, 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. 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 IRowsetNotify::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.

When calling IRowsetNotify::OnRowChange with DBREASON_ROW_INSERT, providers should assign and send the same valid row handle for all phases because consumers can use row handles to match notifications. This assumption was unstated prior to OLE DB 2.6, and for maximum interoperability, consumers should make allowances for DBEVENTPHASE_OKTODO and DBEVENTPHASE_ABOUTTODO phases for NULL row handles.

See Also