IRowsetLocateImpl 類別

發行項
08/03/2024

實作 OLE DB IRowsetLocate 介面，從數據列集擷取任意數據列。

語法

template <
   class T,
   class RowsetInterface,
   class RowClass = CSimpleRow,
   class MapClass = CAtlMap < RowClass::KeyType, RowClass* >,
   class BookmarkKeyType = LONG,
   class BookmarkType = LONG,
   class BookmarkMapClass = CAtlMap < RowClass::KeyType, RowClass* >>
class ATL_NO_VTABLE IRowsetLocateImpl : public IRowsetImpl<
       T,
       RowsetInterface,
       RowClass,
       MapClass>

參數

T
衍生自 IRowsetLocateImpl的類別。

RowsetInterface
衍生自 IRowsetImpl的類別。

RowClass
的 HROW儲存單位。

MapClass
提供者所持有之所有數據列句柄的儲存單位。

BookmarkKeyType
書籤的類型，例如 LONG 或字串。一般書籤的長度必須至少為兩個字節。（單一位元組長度保留給 OLE DB 標準書籤DBBMK_FIRST， DBBMK_LAST和 DBBMK_INVALID。

BookmarkType
維護書籤對數據關聯性的對應機制。

BookmarkMapClass
書籤保留之所有數據列句柄的儲存單位。

需求

Header: atldb.h

成員

介面方法

名稱	描述
比較	比較兩個書籤。
GetRowsAt	從書籤位移指定的數據列開始擷取數據列。
GetRowsByBookmark	擷取符合指定書籤的數據列。
雜湊	傳回指定書籤的哈希值。

資料成員

名稱	描述
m_rgBookmarks	書籤陣列。

備註

IRowsetLocateImpl是 IRowsetLocate 介面的 OLE DB 範本實作。 IRowsetLocate 用來從數據列集擷取任意數據列。未實作這個介面的數據列集是數據 sequential 列集。當數據列集上出現時 IRowsetLocate ，數據行 0 是數據列的書籤;讀取此數據行會取得書籤值，可用來重新置放至相同的數據列。

IRowsetLocateImpl 用於在提供者中實作書籤支援。書籤是佔位元（數據列集上的索引），可讓取用者快速返回數據列，允許高速存取數據。提供者會決定哪些書籤可以唯一識別數據列。使用 IRowsetLocateImpl 方法，您可以比較書籤、依位移擷取數據列、依書籤擷取數據列，以及傳回書籤的哈希值。

若要支持數據列集中的 OLE DB 書籤，請讓數據列集繼承自這個類別。

如需實作書籤支援的詳細資訊，請參閱平臺 SDK 中 OLE DB 程式設計人員參考中的 Visual C++ 程式設計人員指南和書籤中的書籤提供者支援。

IRowsetLocateImpl::Compare

比較兩個書籤。

語法

STDMETHOD (Compare )(HCHAPTER /* hReserved */,
   DBBKMARK cbBookmark1,
   const BYTE* pBookmark1,
   DBBKMARK cbBookmark2,
   const BYTE* pBookmark2,
   DBCOMPARE* pComparison);

參數

請參閱 OLE DB 程式設計人員參考中的 IRowsetLocate：：Compare。

備註

其中一個書籤可以是標準 OLE DB 定義的標準書籤（DBBMK_FIRST、 DBBMK_LAST或 DBBMK_INVALID）。中 pComparison 傳回的值表示兩個書籤之間的關聯性：

DBCOMPARE_LT （cbBookmark1 在之前 cbBookmark2）。
DBCOMPARE_EQ （cbBookmark1 等於 cbBookmark2。）
DBCOMPARE_GT （cbBookmark1 之後 cbBookmark2）。
DBCOMPARE_NE （書籤相等且未排序。
DBCOMPARE_NOTCOMPARABLE （無法比較書籤。

IRowsetLocateImpl::GetRowsAt

從書籤位移指定的數據列開始擷取數據列。

語法

STDMETHOD (GetRowsAt )(HWATCHREGION /* hReserved1 */,
   HCHAPTER hReserved2,
   DBBKMARK cbBookmark,
   const BYTE* pBookmark,
   DBROWOFFSET lRowsOffset,
   DBROWCOUNT cRows,
   DBCOUNTITEM* pcRowsObtained,
   HROW** prghRows);

參數

請參閱 OLE DB 程式設計人員參考中的 IRowsetLocate：：GetRowsAt。

備註

若要改為從游標位置擷取，請使用 IRowset：：GetRowsAt。

IRowsetLocateImpl::GetRowsAt 不會變更游標位置。

IRowsetLocateImpl::GetRowsByBookmark

擷取一或多個符合指定書籤的數據列。

語法

STDMETHOD (GetRowsByBookmark )(HCHAPTER /* hReserved */,
   DBCOUNTITEM cRows,
   const DBBKMARK rgcbBookmarks[],
   const BYTE* rgpBookmarks,
   HROW rghRows[],
   DBROWSTATUS* rgRowStatus[]);

參數

hReserved
[in]對應至 iRowsetLocate：：GetRowsByBookmark 的 hChapter 參數。

如需其他參數，請參閱 OLE DB 程式設計人員參考中的 IRowsetLocate：：GetRowsByBookmark。

備註

書籤可以是您定義的值或 OLE DB 標準書籤（DBBMK_FIRST 或 DBBMK_LAST）。不會變更游標位置。

IRowsetLocateImpl::Hash

傳回指定書籤的哈希值。

語法

STDMETHOD (Hash )(HCHAPTER /* hReserved */,
   DBBKMARK cbBookmarks,
   const DBBKMARK* rgcbBookmarks[],
   const BYTE* rgpBookmarks[],
   DBHASHVALUE rgHashValues[],
   DBROWSTATUS rgBookmarkStatus[]);

參數

hReserved
[in]對應至 IRowsetLocate：：Hash 的 hChapter 參數。

如需其他參數，請參閱 OLE DB 程式設計人員參考中的 IRowsetLocate：：Hash。

IRowsetLocateImpl::m_rgBookmarks

書籤陣列。

語法

CAtlArray<DBROWCOUNT> m_rgBookmarks;

另請參閱

OLE DB 提供者範本
 OLE DB 提供者範本架構
 IRowsetLocate：IRowset Provider Support for Bookmarks
書籤

共用方式為