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 与类相关联。

要求

标头: 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.H 中定义的默认值。 若要将属性设置为所选的值，请使用 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。 通常情况下，提供程序不需要设置 options，因为它是由使用者设置的。

备注

使用此宏，你可以直接指定 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] 列号。 除非该列是书签列，否则列号不得为 0。

member
[in] dataClass 中对应于列的成员变量。

PROVIDER_COLUMN_ENTRY_FIXED

表示提供程序支持的特定列。

语法

PROVIDER_COLUMN_ENTRY_FIXED(name, ordinal, dbtype, member)

参数设置

name
[in] 列名称。

序号
[in] 列号。 除非该列是书签列，否则列号不得为 0。

dbtype
[in] DBTYPE 中的数据类型。

member
[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] 列号。 除非该列是书签列，否则列号不得为 0。

flags
[in] 指定如何返回数据。 请参阅 DBBINDING 结构中的 dwFlags 说明。

colSize
[in] 列大小。

dbtype
[in] 指示值的数据类型。 请参阅 DBBINDING 结构中的 wType 说明。

精度
[in] 如果 dbType 是 DBTYPE_NUMERIC 或 DBTYPE_DECIMAL，则指示获取数据时要使用的精度。 请参阅 DBBINDING 结构中的 bPrecision 说明。

scale
[in] 如果 dbType 是 DBTYPE_NUMERIC 或 DBTYPE_DECIMAL，则指示获取数据时要使用的标度。 请参阅 DBBINDING 结构中的 bScale 说明。

guid
架构行集 GUID。 有关架构行集及其 GUID 的列表，请参阅“OLE DB 程序员参考”中的 IDBSchemaRowset。

注解

允许指定列的大小、数据类型、精度、标度和架构行集 GUID。

PROVIDER_COLUMN_ENTRY_LENGTH

表示提供程序支持的特定列。

语法

PROVIDER_COLUMN_ENTRY_LENGTH(name, ordinal, size, member)

参数设置

name
[in] 列名称。

序号
[in] 列号。 除非该列是书签列，否则列号不得为 0。

size
[in] 列大小（以字节为单位）。

member
[in] dataClass 中存储列数据的成员变量。

备注

允许指定列大小。

示例

请参阅 BEGIN_PROVIDER_COLUMN_MAP。

PROVIDER_COLUMN_ENTRY_STR

表示提供程序支持的特定列。

语法

PROVIDER_COLUMN_ENTRY_STR(name, ordinal, member)

参数设置

name
[in] 列名称。

序号
[in] 列号。 除非该列是书签列，否则列号不得为 0。

member
[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] 列号。 除非该列是书签列，否则列号不得为 0。

dbtype
[in] DBTYPE 中的数据类型。

size
[in] 列大小（以字节为单位）。

member
[in] 数据类中存储数据的成员变量。

注解

与 PROVIDER_COLUMN_ENTRY_LENGTH 类似，但还允许你指定列的数据类型和大小。

PROVIDER_COLUMN_ENTRY_WSTR

表示提供程序支持的特定列。

语法

PROVIDER_COLUMN_ENTRY_WSTR(name, ordinal, member)

参数设置

name
[in] 列名称。

序号
[in] 列号。 除非该列是书签列，否则列号不得为 0。

member
[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 函数填充行集的数据。 如“OLE DB 程序员参考”中的 IDBSchemaRowset 中所述，ATL 项目向导将在项目中为三个必需的 OLE DB 架构中的每一个创建三个初始架构行集：

• DBSCHEMA_TABLES

• DBSCHEMA_COLUMNS

• DBSCHEMA_PROVIDER_TYPES

该向导还在架构映射中添加三个对应的条目。 有关使用该向导创建提供程序的详细信息，请参阅创建 OLE DB 模板提供程序。

另请参阅

OLE DB 提供程序模板
OLE DB 提供程序模板体系结构
创建 OLE DB 提供程序
OLE DB 提供程序模板参考
OLE DB 提供程序模板宏