IRowPositionChange::OnRowPositionChange

  • Article

Notifies the consumer of a row position object of a change to the current row position.

Syntax

HRESULT OnRowPositionChange (
   DBREASON       eReason,
   DBEVENTPHASE   ePhase,
   BOOL           fCantDeny);

Parameters

  • 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 or phase is vetoed because of logical objection or a failure to be able to implement.

  • 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 row position object continues the operation.

Comments

Possible reasons are DBREASON_ROWPOSITION_CLEARED, DBREASON_ROWPOSITION_CHANGED, and DBREASON_ROWPOSITION_CHAPTERCHANGED.

DBREASON_ROWPOSITION_CLEARED generates DBEVENTPHASE_OKTODO and DBEVENTPHASE_ABOUTTODO, and DBEVENTPHASE_FAILEDTODO if the notification is canceled.

DBREASON_ROWPOSITION_CHANGED and DBREASON_ROWPOSITIONCHAPTERCHANGED generate DBEVENTPHASE_SYNCHAFTER and DBEVENTPHASE_DIDEVENT, or DBEVENTPHASE_FAILEDTODO if the notification is canceled.

Consumers are required to handle reasons that are not defined in this interface by returning S_OK or DB_S_UNWANTEDREASON.