CDataSource 类

项目
04/03/2023

对应于一个 OLE DB 数据源对象，该对象表示通过提供程序建立的与数据源的连接。

语法

class CDataSource

要求

标头: atldbcli.h

成员

方法

名称	描述
Close	关闭连接。
GetInitializationString	检索当前打开的数据源的初始化字符串。
GetProperties	获取当前为连接的数据源设置的属性的值。
GetProperty	获取当前为连接的数据源设置的单个属性的值。
打开	使用调用方提供的 `CLSID`、`ProgID` 或 `CEnumerator` 名字对象创建与提供者（数据源）的连接。
OpenFromFileName	从由用户提供的文件名指定的文件打开数据源。
OpenFromInitializationString	打开由初始化字符串指定的数据源。
OpenWithPromptFileName	允许用户选择之前创建的数据链接文件来打开对应的数据源。
OpenWithServiceComponents	使用“数据链接”对话框打开数据源对象。

注解

可以为单个连接创建一个或多个数据库会话。这些会话由 CSession 表示。在使用 CSession::Open 创建会话之前，必须调用 CDataSource::Open 以打开连接。

有关如何使用 CDataSource 的示例，请参阅 CatDB 示例。

CDataSource::Close

通过释放 m_spInit 指针关闭连接。

语法

void Close() throw();

CDataSource::GetInitializationString

检索当前打开的数据源的初始化字符串。

语法

HRESULT GetInitializationString(BSTR* pInitializationString,
   bool bIncludePassword = false) throw();

参数

pInitializationString
[out] 指向初始化字符串的指针。

bIncludePassword
[in] 如果字符串包含密码，则为 true；否则为 false。

返回值

标准 HRESULT。

注解

生成的初始化字符串可用于后续重新打开此数据源连接。

CDataSource::GetProperties

返回为连接的数据源对象请求的属性信息。

语法

HRESULT GetProperties(ULONG ulPropIDSets,
   constDBPROPIDSET* pPropIDSet,
   ULONG* pulPropertySets,
   DBPROPSET** ppPropsets) const throw();

参数

请参阅 Windows SDK 中“OLE DB 程序员参考”中的 IDBProperties::GetProperties。

返回值

标准 HRESULT。

备注

若要获取单个属性，请使用 GetProperty。

CDataSource::GetProperty

返回连接的数据源对象的指定属性的值。

语法

HRESULT GetProperty(const GUID& guid,
   DBPROPID propid,
   VARIANT* pVariant) const throw();

参数

guid
[in] 标识要为其返回属性的属性集的 GUID。

propid
[in] 要返回的属性的属性 ID。

pVariant
[out] 指向变量的指针，其中 GetProperty 返回属性的值。

返回值

标准 HRESULT。

注解

若要获取多个属性，请使用 GetProperties。

CDataSource::Open

使用 CLSID、ProgID 或 CEnumerator 名字对象打开与数据源的连接，或使用定位器对话框提示用户。

语法

HRESULT Open(const CLSID& clsid,
   DBPROPSET* pPropSet = NULL,
   ULONG nPropertySets = 1) throw();

HRESULT Open(const CLSID& clsid,
   LPCTSTR pName,
   LPCTSTR pUserName = NULL,
   LPCTSTR pPassword = NULL,
   long nInitMode = 0) throw();HRESULT Open(LPCTSTR szProgID,
   DBPROPSET* pPropSet = NULL,
   ULONG nPropertySets = 1) throw();HRESULT Open(LPCTSTR szProgID,
   LPCTSTR pName,  LPCTSTR pUserName = NULL,
   LPCTSTR pPassword = NULL,
   long nInitMode = 0) throw();

HRESULT Open(const CEnumerator& enumerator,
   DBPROPSET* pPropSet = NULL,
   ULONG nPropertySets = 1) throw();

HRESULT Open(const CEnumerator& enumerator,
   LPCTSTR pName,
   LPCTSTR pUserName = NULL,
   LPCTSTR pPassword = NULL,
   long nInitMode = 0) throw();

HRESULT Open(HWND hWnd = GetActiveWindow(),
   DBPROMPTOPTIONS dwPromptOptions = DBPROMPTOPTIONS_WIZARDSHEET) throw();

HRESULT Open(LPCWSTR szProgID,
   DBPROPSET* pPropSet = NULL,
   ULONG nPropertySets = 1) throw();

HRESULT Open(LPCSTR szProgID,
   LPCTSTR pName,LPCTSTR pUserName = NULL,
   LPCTSTR pPassword = NULL,
   long nInitMode = 0) throw();

参数

clsid
[in] 数据提供程序的 CLSID。

pPropSet
[in] 指向 DBPROPSET 结构数组的指针，该结构包含要设置的属性和值。请参阅 Windows SDK 中“OLE DB 程序员参考”中的属性集和属性组。

nPropertySets
[in] 传入 pPropSet 参数的 DBPROPSET 结构的数目。

pName
[in] 要连接的数据库的名称。

pUserName
[in] 用户的名称。

pPassword
[in] 用户的密码。

nInitMode
[in] 数据库初始化模式。有关有效初始化模式的列表，请参阅 Windows SDK 中“OLE DB 程序员参考”中的初始化属性。如果 nInitMode 为零，则用于打开连接的属性集中不包含初始化模式。

szProgID
[in] 一个程序标识符。

enumerator
[in] 如果调用方未指定 CLSID，则获取用于打开连接的名字对象的 CEnumerator 对象。

hWnd
[in] 将成为对话框父级的窗口的句柄。使用 hWnd 参数的函数重载将自动调用服务组件；有关详细信息，请参阅备注。

dwPromptOptions
[in] 确定要显示的定位器对话框的样式。请参阅 Msdasc.h 了解可能的值。

返回值

标准 HRESULT。

注解

对于使用 hWnd 参数的方法重载，可使用服务组件 oledb32.dll 打开数据源对象；此 DLL 包含服务组件功能的实现，例如资源池、自动事务登记等。有关详细信息，请参阅 OLE DB 程序员指南中的 OLE DB 参考。

对于不使用 hWnd 参数的方法重载，无需使用 oledb32.dll 中的服务组件的情况下即可打开数据源对象。使用这些函数重载打开的 CDataSource 对象将无法使用服务组件的任何功能。

示例

下面的代码演示如何使用 OLE DB 模板打开 Jet 4.0 数据源。你将 Jet 数据源视为 OLE DB 数据源。但是，对 Open 的调用需要两个属性集：一个用于 DBPROPSET_DBINIT，另一个用于 DBPROPSET_JETOLEDB_DBINIT，这样你就可以设置 DBPROP_JETOLEDB_DATABASEPASSWORD。

CDBPropSet rgDBPropSet[2];  // Declare two property sets;
                            // set properties elsewhere as appropriate.

hr = m_DataSource.Open(szProgId, rgDBPropSet, 2);

CDataSource::OpenFromFileName

从由用户提供的文件名指定的文件打开数据源。

语法

HRESULT OpenFromFileName(LPCOLESTR szFileName) throw();

参数

szFileName
[in] 文件的名称，通常是数据源连接 (.UDL) 文件。

有关数据链接文件（.udl 文件）的详细信息，请参阅 Windows SDK 中的数据链接 API 概述。

返回值

标准 HRESULT。

备注

此方法使用 oledb32.dll 中的服务组件打开数据源对象；此 DLL 包含资源池、自动事务登记等服务组件功能的实现。有关详细信息，请参阅 OLE DB 程序员指南中的 OLE DB 参考。

CDataSource::OpenFromInitializationString

打开由用户提供的初始化字符串指定的数据源。

语法

HRESULT OpenFromInitializationString(LPCOLESTR szInitializationString,
   bool fPromptForInfo= false) throw();

参数

szInitializationString
[in] 初始化字符串。

fPromptForInfo
[in] 如果此参数设置为 true，则 OpenFromInitializationString 会将 DBPROP_INIT_PROMPT 属性设置为 DBPROMPT_COMPLETEREQUIRED，这表示仅在需要更多信息时才提示用户。对于初始化字符串指定需要密码但字符串不包含密码的数据库的情况，这非常有用。尝试连接到数据库时，系统将提示用户输入密码（或任何其他丢失的信息）。

默认值为 false，它指示永远不会提示用户（将 DBPROP_INIT_PROMPT 设置为 DBPROMPT_NOPROMPT）。

返回值

标准 HRESULT。

备注

此方法使用 oledb32.dll 中的服务组件打开数据源对象；此 DLL 包含资源池、自动事务登记等服务组件功能的实现。

CDataSource::OpenWithPromptFileName

此方法通过对话框提示用户，然后使用由用户指定的文件打开数据源。

语法

HRESULT OpenWithPromptFileName(HWND hWnd = GetActiveWindow(   ),
   DBPROMPTOPTIONS dwPromptOptions = DBPROMPTOPTIONS_NONE,
   LPCOLESTR szInitialDirectory = NULL) throw();

参数

hWnd
[in] 将成为对话框父级的窗口的句柄。

dwPromptOptions
[in] 确定要显示的定位器对话框的样式。请参阅 Msdasc.h 了解可能的值。

szInitialDirectory
[in] 要在定位器对话框中显示的初始目录。

返回值

标准 HRESULT。

备注

CDataSource::OpenWithServiceComponents

使用 oledb32.dll 中的服务组件打开数据源对象。

语法

HRESULT OpenWithServiceComponents (const CLSID clsid,
   DBPROPSET* pPropset = NULL,
   ULONG ulPropSets = 1);

HRESULT OpenWithServiceComponents (LPCSTR szProgID,
   DBPROPSET* pPropset = NULL,
   ULONG ulPropSets = 1);

参数

clsid
[in] 数据提供程序的 CLSID。

szProgID
[in] 数据提供程序的程序 ID。

pPropset
[in] 指向 DBPROPSET 结构数组的指针，该结构包含要设置的属性和值。请参阅 Windows SDK 中“OLE DB 程序员参考”中的属性集和属性组。如果数据源对象进行初始化，则属性必须属于数据源属性组。如果在 pPropset 中多次指定相同的属性，使用的值就特定于提供程序。如果 ulPropSets 为零，则忽略此参数。

ulPropSets
[in] 传入 pPropSet 参数的 DBPROPSET 结构的数目。如果此值为零，提供程序会忽略 pPropset。

通过

CDataSource 类

语法

要求

成员

方法

注解

CDataSource::Close

语法

CDataSource::GetInitializationString

语法

参数

返回值

注解

CDataSource::GetProperties

语法

参数

返回值

备注

CDataSource::GetProperty

语法

参数

返回值

注解

CDataSource::Open

语法

参数

返回值

注解

示例

CDataSource::OpenFromFileName

语法

参数

返回值

备注

CDataSource::OpenFromInitializationString

语法

参数

返回值

备注

CDataSource::OpenWithPromptFileName

语法

参数

返回值

备注

CDataSource::OpenWithServiceComponents

语法

参数

返回值

备注

另请参阅

反馈

反馈

其他资源