CUtlProps 类

项目
04/03/2023

实现各种 OLE DB 属性接口的属性（例如 IDBProperties、IDBProperties 和 IRowsetInfo）。

语法

template < class T >
class ATL_NO_VTABLE CUtlProps : public CUtlPropsBase

参数

T
包含 BEGIN_PROPSET_MAP 的类。

要求

标头: atldb.h

成员

方法

名称	描述
GetPropValue	从属性集获取属性。
IsValidValue	用于在设置属性之前验证值。
OnInterfaceRequested	当使用者在对象创建接口上调用方法时，处理对可选接口的请求。
OnPropertyChanged	在设置属性以处理链接属性后调用。
SetPropValue	设置属性集中的属性。

备注

此类中的大多数是实现详细信息。

CUtlProps 包含两个成员用于在内部设置属性：GetPropValue 和 SetPropValue。

有关属性集映射中使用的宏的详细信息，请参阅 BEGIN_PROPSET_MAP 和 END_PROPSET_MAP。

CUtlProps::GetPropValue

从属性集获取属性。

语法

OUT_OF_LINE HRESULT GetPropValue(const GUID* pguidPropSet,
   DBPROPID dwPropId,
   VARIANT* pvValue);

参数

pguidPropSet
[in] PropSet 的 GUID。

dwPropId
[in] 属性索引。

pvValue
[out] 指向包含新属性值的变体的指针。

返回值

失败时为 Failure，如果成功，则为 S_OK。

CUtlProps::IsValidValue

用于在设置属性之前验证值。

语法

virtual HRESULT CUtlPropsBase::IsValidValue(ULONG /* iCurSet */,
   DBPROP* pDBProp);

参数

iCurSet
属性集数组中的索引；如果只有一个属性集，则为零。

pDBProp
DBPROP 结构中的属性 ID 和新值。

返回值

标准 HRESULT。默认返回值为 S_OK。

注解

如果想要在要用于设置属性的值上运行任何验证例程，则应重写此函数。例如，可以针对密码表验证 DBPROP_AUTH_PASSWORD 以确定有效值。

CUtlProps::OnInterfaceRequested

当使用者在其中一个对象创建接口上调用方法时，处理对可选接口的请求。

语法

virtual HRESULT CUtlPropsBase::OnInterfaceRequested(REFIID riid);

参数

riid
[in] 请求的接口的 IID。有关详细信息，请参阅 OLE DB 程序员参考中 ICommand::Execute 的 riid 参数的说明（MDAC SDK 中）。

注解

当使用者在其中一个对象创建接口上（例如，IDBCreateSession、IDBCreateCommand、IOpenRowset 或 ICommand）调用方法时，OnInterfaceRequested 处理使用者对可选接口的请求。它为请求的接口设置相应的 OLE DB 属性。例如，如果使用者请求 IID_IRowsetLocate，则 OnInterfaceRequested 设置 DBPROP_IRowsetLocate 接口。这样做会在创建行集期间保持正确的状态。

在使用者调用 IOpenRowset::OpenRowset 或 ICommand::Execute 时调用此方法。

如果使用者打开对象并请求可选接口，则提供程序应将与该接口关联的属性设置为VARIANT_TRUE。若要允许特定于属性的处理，OnInterfaceRequested 在调用提供程序的 Execute 方法之前调用。默认情况下，OnInterfaceRequested 处理以下接口：

IRowsetLocate
IRowsetChange
IRowsetUpdate
IConnectionPointContainer
IRowsetScroll

如果要处理其他接口，请在数据源、会话、命令或行集类中重写此函数以处理函数。重写应通过常规集/获取属性接口，以确保设置属性还会设置其他链接属性（查看 OnPropertyChanged）。

CUtlProps::OnPropertyChanged

在设置属性以处理链接属性后调用。

语法

virtual HRESULT OnPropertyChanged(ULONG /* iCurSet */,
   DBPROP* pDBProp);

参数

iCurSet
属性集数组中的索引；如果只有一个属性集，则为零。

pDBProp
DBPROP 结构中的属性 ID 和新值。

返回值

标准 HRESULT。默认返回值为 S_OK。

注解

如果要处理链接的属性（例如书签或更新，其值依赖于其他属性值），则应重写此函数。

示例

在此函数中，用户从 DBPROP* 参数中获取属性 ID。现在，可以将 ID 与属性进行比较，以便链接。找到该属性时，将使用现在将与其他属性一起设置的属性来调用 SetProperties。在这种情况下，如果用户获取 DBPROP_IRowsetLocate、DBPROP_LITERALBOOKMARKS 或 DBPROP_ORDEREDBOOKMARKS 属性，则可以设置 DBPROP_BOOKMARKS 属性。

HRESULT OnPropertyChanged(ULONG /*iCurSet*/, DBPROP* pDBProp)
{
   ATLASSERT(pDBProp != NULL);

   DWORD dwPropertyID = pDBProp->dwPropertyID;

   if (dwPropertyID == DBPROP_IRowsetLocate || 
      dwPropertyID == DBPROP_LITERALBOOKMARKS ||
      dwPropertyID == DBPROP_ORDEREDBOOKMARKS)
   {
      CComVariant var = pDBProp->vValue;

      if (var.boolVal == VARIANT_TRUE)
      {
         // Set the bookmarks property as these are chained
         CComVariant bookVar(true);
         CDBPropSet set(DBPROPSET_ROWSET);
         set.AddProperty(DBPROP_BOOKMARKS, bookVar);

         return SetProperties(1, &set);
      }
   }

   return S_OK;
}

CUtlProps::SetPropValue

设置属性集中的属性。

语法

HRESULT SetPropValue(const GUID* pguidPropSet,
   DBPROPID dwPropId,
   VARIANT* pvValue);

参数