OLE DB 提供者樣板的巨集

OLE DB 範本提供者巨集提供下列類別的功能：

屬性集對應巨集

名稱	描述
BEGIN_PROPERTY_SET	標記屬性集的開頭。
BEGIN_PROPERTY_SET_EX	標記屬性集的開頭。
BEGIN_PROPSET_MAP	標記可以隱藏或定義在提供者範圍外的屬性集開頭。
CHAIN_PROPERTY_SET	將屬性群組鏈結在一起。
END_PROPERTY_SET	標記屬性集的結尾。
END_PROPSET_MAP	標記屬性集對應的結尾。
PROPERTY_INFO_ENTRY	將屬性中的特定屬性設定為預設值。
PROPERTY_INFO_ENTRY_EX	將屬性中的特定屬性設定為您提供的值。 也可讓您設定旗標和選項。
PROPERTY_INFO_ENTRY_VALUE	將屬性中的特定屬性設定為您提供的值。

數據行對應巨集

名稱	描述
BEGIN_PROVIDER_COLUMN_MAP	標記提供者數據行對應專案的開頭。
END_PROVIDER_COLUMN_MAP	標記提供者數據行對應項目的結尾。
PROVIDER_COLUMN_ENTRY	表示提供者所支援的特定數據行。
PROVIDER_COLUMN_ENTRY_FIXED	表示提供者所支援的特定數據行。 您可以指定資料列資料類型。
PROVIDER_COLUMN_ENTRY_GN	表示提供者所支援的特定數據行。 您可以指定資料列的大小、資料類型、精確度、小數位數和架構資料列集 GUID。
PROVIDER_COLUMN_ENTRY_LENGTH	表示提供者所支援的特定數據行。 您可以指定資料列大小。
PROVIDER_COLUMN_ENTRY_STR	表示提供者所支援的特定數據行。 它會假設數據行類型為字串。
PROVIDER_COLUMN_ENTRY_TYPE_LENGTH	表示提供者所支援的特定數據行。 如同PROVIDER_COLUMN_ENTRY_LENGTH，也可讓您指定數據行的數據類型以及大小。
PROVIDER_COLUMN_ENTRY_WSTR	表示提供者所支援的特定數據行。 它會假設數據行類型為 Unicode 字元字串。

架構數據列集巨集

名稱	描述
BEGIN_SCHEMA_MAP	標記架構對應的開頭。
END_SCHEMA_MAP	標記架構對應的結尾。
SCHEMA_ENTRY	將 GUID 與類別產生關聯。

需求

Header: atldb.h

BEGIN_PROPERTY_SET

標記屬性集對應中屬性集的開頭。

語法

BEGIN_PROPERTY_SET(guid)

參數

guid
[in]屬性 GUID。

範例

請參閱 BEGIN_PROPSET_MAP。

BEGIN_PROPERTY_SET_EX

標記屬性集對應中屬性集的開頭。

語法

BEGIN_PROPERTY_SET_EX(guid, flags)

參數

guid
[in]屬性 GUID。

flags
[in]您不想公開的任何屬性集UPROPSET_HIDDEN，或UPROPSET_PASSTHROUGH提供者公開提供者範圍外定義的屬性。

範例

請參閱 BEGIN_PROPSET_MAP。

BEGIN_PROPSET_MAP

標記屬性集對應項目的開頭。

語法

BEGIN_PROPSET_MAP(Class)

參數

類別
[in]指定這個屬性集的類別。 您可以在下列 OLE DB 物件中指定屬性集：

• 數據源物件

• 會話物件

• 命令

範例

以下是範例屬性集對應：

BEGIN_PROPSET_MAP(CCustomSource)
    BEGIN_PROPERTY_SET(DBPROPSET_DATASOURCEINFO)
        PROPERTY_INFO_ENTRY(ACTIVESESSIONS)
        PROPERTY_INFO_ENTRY(DATASOURCEREADONLY)
        PROPERTY_INFO_ENTRY(BYREFACCESSORS)
        PROPERTY_INFO_ENTRY(OUTPUTPARAMETERAVAILABILITY)
        PROPERTY_INFO_ENTRY(PROVIDEROLEDBVER)
        PROPERTY_INFO_ENTRY(DSOTHREADMODEL)
        PROPERTY_INFO_ENTRY(SUPPORTEDTXNISOLEVELS)
        PROPERTY_INFO_ENTRY(USERNAME)
    END_PROPERTY_SET(DBPROPSET_DATASOURCEINFO)
    BEGIN_PROPERTY_SET(DBPROPSET_DBINIT)
        PROPERTY_INFO_ENTRY(AUTH_PASSWORD)
        PROPERTY_INFO_ENTRY(AUTH_PERSIST_SENSITIVE_AUTHINFO)
        PROPERTY_INFO_ENTRY(AUTH_USERID)
        PROPERTY_INFO_ENTRY(INIT_DATASOURCE)
        PROPERTY_INFO_ENTRY(INIT_HWND)
        PROPERTY_INFO_ENTRY(INIT_LCID)
        PROPERTY_INFO_ENTRY(INIT_LOCATION)
        PROPERTY_INFO_ENTRY(INIT_MODE)
        PROPERTY_INFO_ENTRY(INIT_PROMPT)
        PROPERTY_INFO_ENTRY(INIT_PROVIDERSTRING)
        PROPERTY_INFO_ENTRY(INIT_TIMEOUT)
    END_PROPERTY_SET(DBPROPSET_DBINIT)
    CHAIN_PROPERTY_SET(CCustomSession)
    CHAIN_PROPERTY_SET(CCustomCommand)
END_PROPSET_MAP()

CHAIN_PROPERTY_SET

這個巨集鏈結屬性會群組在一起。

語法

CHAIN_PROPERTY_SET(ChainClass)

參數

ChainClass
[in]要鏈結屬性的類別名稱。 這是 ATL 專案精靈所產生的類別，其中包含對應（例如會話、命令或數據源物件類別）。

備註

您可以將屬性集從另一個類別鏈結至您自己的類別，然後直接從類別存取屬性。

警告

請謹慎使用此巨集。 不當使用可能會導致取用者無法通過 OLE DB 一致性測試。

END_PROPERTY_SET

標記屬性集的結尾。

語法

END_PROPERTY_SET(guid)

參數

guid
[in]屬性 GUID。

範例

請參閱 BEGIN_PROPSET_MAP。

END_PROPSET_MAP

標記屬性集對應項目的結尾。

語法

END_PROPSET_MAP()

範例

請參閱 BEGIN_PROPSET_MAP。

PROPERTY_INFO_ENTRY

代表屬性集中的特定屬性。

語法

PROPERTY_INFO_ENTRY(dwPropID)

參數

dwPropID
[in] DBPROPID 值，可搭配屬性集 GUID 用來識別屬性。

備註

此巨集會將 DWORD 類型的屬性值設定為 ATLDB 中定義的預設值。 若要將屬性設定為您選擇的值，請使用 PROPERTY_INFO_ENTRY_VALUE。 若要同時設定 屬性的 VARTYPE 和 DBPROPFLAGS ，請使用 PROPERTY_INFO_ENTRY_EX。

範例

請參閱 BEGIN_PROPSET_MAP。

PROPERTY_INFO_ENTRY_EX

代表屬性集中的特定屬性。

語法

PROPERTY_INFO_ENTRY_EX(dwPropID, vt, dwFlags, value, options)

參數

dwPropID
[in] DBPROPID 值，可搭配屬性集 GUID 用來識別屬性。

vt
[in] 此屬性項目的 VARTYPE。 （定義於 wtypes.h）

dwFlags
[in] 描述此屬性項目的 DBPROPFLAGS 值。

value
[in] DWORD類型的屬性值。

options
DBPROPOPTIONS_REQUIRED 或 DBPROPOPTIONS_SETIFCHEAP。 一般而言，提供者不需要設定 選項 ，因為它是由取用者所設定。

備註

透過這個巨集，您可以直接指定 DWORD 類型的屬性值，以及選項和旗標。 若只要將屬性設定為 ATLDB.H 中定義的預設值，請使用 PROPERTY_INFO_ENTRY。 若要將屬性設定為您選擇的值，請使用 PROPERTY_INFO_ENTRY_VALUE，而不需要設定屬性的選項或旗標。

範例

請參閱 BEGIN_PROPSET_MAP。

PROPERTY_INFO_ENTRY_VALUE

代表屬性集中的特定屬性。

語法

PROPERTY_INFO_ENTRY_VALUE(dwPropID, value)

參數

dwPropID
[in] DBPROPID 值，可搭配屬性集 GUID 用來識別屬性。

value
[in] DWORD類型的屬性值。

備註

透過這個巨集，您可以直接指定 類型的 DWORD屬性值。 若要將 屬性設定為 ATLDB 中定義的預設值。H，使用 PROPERTY_INFO_ENTRY。 若要設定 屬性的值、旗標和選項，請使用 PROPERTY_INFO_ENTRY_EX。

範例

請參閱 BEGIN_PROPSET_MAP。

BEGIN_PROVIDER_COLUMN_MAP

標記提供者數據行對應專案的開頭。

語法

BEGIN_PROVIDER_COLUMN_MAP(theClass)

參數

theClass
[in]這個對應所屬的類別名稱。

範例

以下是範例提供者資料行對應：

BEGIN_PROVIDER_COLUMN_MAP(CCustomWindowsFile)
    PROVIDER_COLUMN_ENTRY("FileAttributes", 1, dwFileAttributes)
    PROVIDER_COLUMN_ENTRY("FileSizeHigh", 2, nFileSizeHigh)
    PROVIDER_COLUMN_ENTRY("FileSizeLow", 3, nFileSizeLow)
    PROVIDER_COLUMN_ENTRY_STR("FileName", 4, cFileName)
    PROVIDER_COLUMN_ENTRY_STR("AltFileName", 5, cAlternateFileName)
END_PROVIDER_COLUMN_MAP()

END_PROVIDER_COLUMN_MAP

標記提供者數據行對應項目的結尾。

語法

END_PROVIDER_COLUMN_MAP()

範例

請參閱 BEGIN_PROVIDER_COLUMN_MAP。

PROVIDER_COLUMN_ENTRY

表示提供者所支援的特定數據行。

語法

PROVIDER_COLUMN_ENTRY (name, ordinal, member)

參數

name
[in]數據行名稱。

序數
[in] 資料行編號。 除非數據行是 Bookmark 數據行，否則數據行編號不得為 0。

成員
[in]中 dataClass 對應至數據行的成員變數。

PROVIDER_COLUMN_ENTRY_FIXED

表示提供者所支援的特定數據行。

語法

PROVIDER_COLUMN_ENTRY_FIXED(name, ordinal, dbtype, member)

參數

name
[in]數據行名稱。

序數
[in] 資料行編號。 除非數據行是 Bookmark 數據行，否則數據行編號不得為 0。

dbtype
[in]DBTYPE 中的數據類型。

成員
[in]中 dataClass 儲存數據的成員變數。

備註

可讓您指定資料列資料類型。

範例

請參閱 BEGIN_PROVIDER_COLUMN_MAP。

PROVIDER_COLUMN_ENTRY_GN

表示提供者所支援的特定數據行。

語法

PROVIDER_COLUMN_ENTRY_GN (name, ordinal, flags, colSize, dbtype, precision, scale, guid)

參數

name
[in]數據行名稱。

序數
[in] 資料行編號。 除非數據行是 Bookmark 數據行，否則數據行編號不得為 0。

flags
[in]指定如何傳回數據。 dwFlags請參閱 DBBINDING 結構中的描述。

colSize
[in]數據行大小。

dbtype
[in]指出值的數據類型。 wType請參閱 DBBINDING 結構中的描述。

有效位數
[in]指出當 dbType 為DBTYPE_NUMERIC或DBTYPE_DECIMAL時，所要使用的有效位數。 bPrecision請參閱 DBBINDING 結構中的描述。

scale
[in]指出當 dbType 為DBTYPE_NUMERIC或DBTYPE_DECIMAL時，所要使用的縮放比例。 bScale請參閱 DBBINDING 結構中的描述。

guid
架構數據列集 GUID。 如需架構數據列集及其 GUID 的清單，請參閱 OLE DB 程式設計人員參考中的 IDBSchemaRowset。

備註

可讓您指定資料行的大小、數據類型、有效位數、小數位數和架構數據列集 GUID。

PROVIDER_COLUMN_ENTRY_LENGTH

表示提供者所支援的特定數據行。

語法

PROVIDER_COLUMN_ENTRY_LENGTH(name, ordinal, size, member)

參數

name
[in]數據行名稱。

序數
[in] 資料行編號。 除非數據行是 Bookmark 數據行，否則數據行編號不得為 0。

size
[in]以位元組為單位的數據行大小。

成員
[in]中 dataClass 儲存數據行數據的成員變數。

備註

可讓您指定資料行大小。

範例

請參閱 BEGIN_PROVIDER_COLUMN_MAP。

PROVIDER_COLUMN_ENTRY_STR

表示提供者所支援的特定數據行。

語法

PROVIDER_COLUMN_ENTRY_STR(name, ordinal, member)

參數

name
[in]數據行名稱。

序數
[in] 資料行編號。 除非數據行是 Bookmark 數據行，否則數據行編號不得為 0。

成員
[in]儲存數據之數據類別中的成員變數。

備註

假設數據行數據DBTYPE_STR時，請使用這個巨集。

範例

請參閱 BEGIN_PROVIDER_COLUMN_MAP。

PROVIDER_COLUMN_ENTRY_TYPE_LENGTH

表示提供者所支援的特定數據行。

語法

PROVIDER_COLUMN_ENTRY_TYPE_LENGTH(name, ordinal, dbtype, size, member)

參數

name
[in]數據行名稱。

序數
[in] 資料行編號。 除非數據行是 Bookmark 數據行，否則數據行編號不得為 0。

dbtype
[in]DBTYPE 中的數據類型。

size
[in]以位元組為單位的數據行大小。

成員
[in]儲存數據之數據類別中的成員變數。

備註

類似於 PROVIDER_COLUMN_ENTRY_LENGTH ，但也可讓您指定數據行的數據類型以及大小。

PROVIDER_COLUMN_ENTRY_WSTR

表示提供者所支援的特定數據行。

語法

PROVIDER_COLUMN_ENTRY_WSTR(name, ordinal, member)

參數

name
[in]數據行名稱。

序數
[in] 資料行編號。 除非數據行是 Bookmark 數據行，否則數據行編號不得為 0。

成員
[in]儲存數據之數據類別中的成員變數。

備註

當數據行數據是 null 終止的 Unicode 字元字串時，請使用這個巨集， DBTYPE_WSTR。

BEGIN_SCHEMA_MAP

表示架構對應的開頭。

語法

BEGIN_SCHEMA_MAP(SchemaClass);

參數

SchemaClass
包含 MAP 的類別。 這通常是會話類別。

備註

如需架構數據列集的詳細資訊，請參閱 Windows SDK 中的 IDBSchemaRowset 。

END_SCHEMA_MAP

表示架構對應的結尾。

語法

END_SCHEMA_MAP()

備註

如需詳細資訊，請參閱 IDBSchemaRowsetImpl類別。

SCHEMA_ENTRY

將 GUID 與類別產生關聯。

語法

SCHEMA_ENTRY(guid,
   rowsetClass);

參數

guid
架構數據列集 GUID。 如需架構數據列集及其 GUID 的清單，請參閱 OLE DB 程式設計人員參考中的 IDBSchemaRowset。

rowsetClass
將建立來表示架構數據列集的類別。

備註

IDBSchemaRowsetImpl 接著可以查詢 GUID 清單的對應，或者如果指定 GUID，則可以建立數據列集。 架構數據列集 IDBSchemaRowsetImpl 建立類似於標準 CRowsetImpl衍生類別，但必須提供 Execute 具有下列簽章的方法：

HRESULT Execute (LONG* pcRowsAffected,
    ULONG cRestrictions,
    const VARIANT* rgRestrictions);

此 Execute 函式會填入數據列集的數據。 ATL 專案精靈會建立，如 OLE DB 程式設計人員參考中的 IDBSchemaRowset 中所述，專案中每個必要 OLE DB 架構各有三個初始架構數據列集：

• DBSCHEMA_TABLES

• DBSCHEMA_COLUMNS

• DBSCHEMA_PROVIDER_TYPES

精靈也會在架構對應中新增三個對應的專案。 如需使用精靈建立提供者的詳細資訊，請參閱 建立 OLE DB 範本提供者 。

另請參閱

OLE DB 提供者範本
OLE DB 提供者範本架構
建立 OLE DB 提供者
OLE DB 提供者範本參考
OLE DB 提供者範本的巨集