Using the Rowset
Rowsets are the unifying abstraction that enables all OLE DB providers to expose base data, command results, or schema information, in tabular format. Conceptually, a rowset is a collection of rows in which each row contains columns of data.
The IOpenRowset interface exposed by the session generates a rowset object, which encapsulates the provider's data. A rowset typically has an internal buffer, or row cache, which enables shared access to the provider's data by multiple consumers. The following section describes how providers and consumers interact with the rowset.
Consumer and Provider Interactions with the Rowset
After receiving the rowset interface pointer, the consumer can request rowset metadata from the provider through IColumnsInfo, if it does not have prior knowledge of the data representation. The consumer uses the metadata to specify bindings, which describe how the consumer wants to receive the data. The consumer creates bindings by requesting IAccessor from the provider and specifying the bindings through IAccessor::CreateAccessor. The provider returns a handle to the accessor to the consumer.
The consumer then requests a number of rows from the provider using IRowset::GetNextRows. The provider retrieves the data for these rows and stores it in the data cache. The provider then returns an array of row handles to the consumer. Each row handle returned by the provider has an initial reference count of one. The consumer is then free to get the data for any rows from the provider using GetData. The consumer supplies GetData with the row handle, the handle of an accessor, and the buffer location into which to return the data; the provider copies the data to the location specified by the consumer.
Consumers using the sample provider can delete or change data in the rowset, but they cannot add new rows. To update rows, consumers call IRowsetChange::SetData, which sets the data in the data cache to the values specified by the consumer. To delete rows from the data cache, the consumer calls IRowsetChange::DeleteRows. A third method on IRowsetChange, IRowsetChange::InsertRow, is not implemented in the sample provider.
When the consumer makes any change to data in the data cache, the effects of the change are written to the data source immediately. OLE DB specifies a change-buffering model, which enables the consumer to make changes that are not realized until the consumer calls IRowsetUpdate::Update; this model is not supported by the sample provider.
When the consumer has finished working with a row, it can release the row by calling IRowset::ReleaseRows. ReleaseRows simply decrements the reference count on the row in the data cache. If the reference count for that row reaches zero, the row data is released from the data cache.