IChapteredRowset

IChapteredRowset is the interface that allows consumers to manage chapters.

When to Implement

IChapteredRowset is required for all providers that support chapters.

When to Call

When a chapter handle is retrieved, either by calling GetData on a column containing chapter values, or from a method that returns a chapter handle, a reference count is taken against that chapter handle. When the chapter is subsequently used, no additional reference counts are taken; however, the reference count on a chapter can be explicitly incremented by calling AddRefChapter. Both reference counts must be decremented by calling ReleaseChapter.

If any HROWs in the chapter have pending changes when ReleaseChapter is called, the reference count of the chapter is decremented but the chapter remains valid, even if its reference count drops to zero. In such a situation, the chapter value might remain valid, but consumers should not count on such behavior. The chapter and its resources are freed when the pending change status on the rows is cleared, either by a call to IRowsetUpdate::Update or IRowsetUpdate::Undo. In particular, a single-chaptered provider will not be able to open another chapter until the rows are updated or undone and the chapter's resources are freed. For more information, see IRowset::ReleaseRows.