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