CDataSource クラス

[アーティクル]
04/03/2023

プロバイダーからデータソースへの接続を表す OLE DB データソースオブジェクトに対応します。

構文

class CDataSource

必要条件

ヘッダー: atldbcli.h

メンバー

メソッド

Name	説明
クローズ	接続を閉じます。
GetInitializationString	現在開いているデータソースの初期化文字列を取得します。
GetProperties	接続されたデータソースに対して現在設定されている複数のプロパティの値を取得します。
GetProperty	接続されたデータソースに対して現在設定されている 1 つのプロパティの値を取得します。
未完了	呼び出し元によって提供された `CLSID`、`ProgID`、または `CEnumerator` モニカーを使って、プロバイダー (データソース) への接続を作成します。
OpenFromFileName	ユーザー指定のファイル名で指定されたファイルからデータソースを開きます。
OpenFromInitializationString	初期化文字列で指定されたデータソースを開きます。
OpenWithPromptFileName	ユーザーは、以前に作成したデータリンクファイルを選んで、対応するデータソースを開くことができます。
OpenWithServiceComponents	[データリンク] ダイアログボックスを使って、データソースオブジェクトを開きます。

解説

1 つの接続に対して 1 つ以上のデータベースセッションを作成できます。これらのセッションは、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
[出力] 初期化文字列へのポインター。

bIncludePassword
[入力] 文字列にパスワードが含まれている場合は true。そうでない場合は false。

戻り値

標準の HRESULT。

解説

結果の初期化文字列を使って、後でこのデータソース接続を再び開くことができます。

CDataSource::GetProperties

接続されているデータソースオブジェクトの要求されたプロパティ情報を返します。

構文

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

パラメーター

詳しくは、Windows SDK の "OLE DB プログラマーズリファレンス" の「IDBProperties::GetProperties」をご覧ください。

戻り値

標準の HRESULT。

解説

1 つのプロパティを取得するには、GetProperty を使います。

CDataSource::GetProperty

接続されているデータソースオブジェクトの指定されたプロパティの値を返します。

構文

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

パラメーター

guid
[入力] 取得するプロパティのプロパティセットを示す GUID。

propid
[入力] 取得するプロパティのプロパティ ID。

pVariant
[出力] 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
[入力] データプロバイダーの CLSID。

pPropSet
[入力] 設定するプロパティと値を含む DBPROPSET 構造体の配列へのポインター。 Windows SDK の "OLE DB プログラマーズリファレンス" の「プロパティセットとプロパティグループ」をご覧ください。

nPropertySets
[入力] pPropSet 引数で渡される DBPROPSET 構造体の数。

pName
[入力] 接続先のデータベース名。

pUserName
[入力] ユーザーの名前。

pPassword
[入力] ユーザーのパスワード。

nInitMode
[入力] データベースの初期化モード。有効な初期化モードの一覧については、Windows SDK の "OLE DB プログラマーズリファレンス" の初期化プロパティに関する説明をご覧ください。 nInitMode がゼロの場合、接続を開くために使われるプロパティセットに、初期化モードは含まれません。

szProgID
[入力] プログラム ID。

enumerator
[入力] 呼び出し元が CLSID を指定しないときに、接続を開くためのモニカーを取得するために使われる CEnumerator オブジェクト。

hWnd
[入力] ダイアログボックスの親であるウィンドウへのハンドル。この関数の hWnd パラメーターを使うオーバーロードを使うと、サービスコンポーネントが自動的に呼び出されます。詳しくは、「解説」をご覧ください。

dwPromptOptions
[入力] 表示するロケーターダイアログボックスのスタイルを指定します。使用できる値については、Msdasc.h を参照してください。

戻り値

標準の HRESULT。

解説

このメソッドの hWnd パラメーターを使うオーバーロードは、oledb32.dll 内のサービスコンポーネントを使ってデータソースオブジェクトを開きます。この DLL には、リソースプールや自動トランザクション登録などの、サービスコンポーネント機能の実装が含まれています。詳しくは、「OLE DB プログラマーズガイド」の OLE DB リファレンスをご覧ください。

このメソッドの hWnd パラメーターを使わないオーバーロードは、oledb32.dll 内のサービスコンポーネントを使わないでデータソースオブジェクトを開きます。この関数のこれらのオーバーロードで開かれた CDataSource オブジェクトは、サービスコンポーネントの機能を利用できません。

例

次のコードは、OLE DB テンプレートを使用して Jet 4.0 データソースを開く方法を示します。 Jet データソースは、OLE DB データソースとして扱います。ただし、Open を呼び出すときは、DBPROP_JETOLEDB_DATABASEPASSWORD を設定できるように、DBPROPSET_DBINIT と DBPROPSET_JETOLEDB_DBINIT に対する 2 つのプロパティセットが必要です。

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 の「Data Link API の概要」をご覧ください。

戻り値

標準の HRESULT。

解説

このメソッドは、oledb32.dll 内のサービスコンポーネントを使ってデータソースオブジェクトを開きます。この DLL には、リソース共有や自動トランザクション登録などのサービスコンポーネント機能の実装が含まれています。詳しくは、「OLE DB プログラマーズガイド」の OLE DB リファレンスをご覧ください。

CDataSource::OpenFromInitializationString

ユーザー指定の初期化文字列によって指定されたデータソースを開きます。

構文

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

パラメーター

szInitializationString
[入力] 初期化文字列。

fPromptForInfo
[入力] この引数を 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
[入力] ダイアログボックスの親であるウィンドウへのハンドル。

dwPromptOptions
[入力] 表示するロケーターダイアログボックスのスタイルを指定します。使用できる値については、Msdasc.h を参照してください。

szInitialDirectory
[入力] ロケーターダイアログボックスに表示される初期ディレクトリ。

戻り値

標準の 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
[入力] データプロバイダーの CLSID。

szProgID
[入力] データプロバイダーのプログラム ID。

pPropset
[入力] 設定するプロパティと値を含む DBPROPSET 構造体の配列へのポインター。 Windows SDK の "OLE DB プログラマーズリファレンス" の「プロパティセットとプロパティグループ」をご覧ください。データソースオブジェクトが初期化されている場合、プロパティはデータソースプロパティグループに属している必要があります。 pPropset で同じプロパティを複数回指定した場合、どの値が使われるかはプロバイダー固有です。 ulPropSets がゼロの場合、このパラメーターは無視されます。

ulPropSets
[入力] pPropSet 引数で渡される DBPROPSET 構造体の数。これがゼロの場合、プロバイダーは pPropset を無視します。

戻り値

標準の HRESULT。

CDataSource クラス

構文

必要条件

メンバー

メソッド

解説

CDataSource::Close

構文

CDataSource::GetInitializationString

構文

パラメーター

戻り値

解説

CDataSource::GetProperties

構文

パラメーター

戻り値

解説

CDataSource::GetProperty

構文

パラメーター

戻り値

解説

CDataSource::Open

構文

パラメーター

戻り値

解説

例

CDataSource::OpenFromFileName

構文

パラメーター

戻り値

解説

CDataSource::OpenFromInitializationString

構文

パラメーター

戻り値

解説

CDataSource::OpenWithPromptFileName

構文

パラメーター

戻り値

解説

CDataSource::OpenWithServiceComponents

構文

パラメーター

戻り値

解説

関連項目

フィードバック

フィードバック

その他のリソース