Класс CDataSource

Статья
10/12/2023

Соответствует объекту источника данных OLE DB, который представляет подключение через поставщика к источнику данных.

Синтаксис

class CDataSource

Требования

Заголовок: atldbcli.h

Участники

Методы

Имя	Описание
Закрыть	Закрывает подключение.
GetInitializationString	Извлекает строку инициализации источника данных, открытого в данный момент.
GetProperties	Возвращает значения свойств, заданных в настоящее время для подключенного источника данных.
Getproperty	Возвращает значение одного свойства, заданного в настоящее время для подключенного источника данных.
Открыть	Создает подключение к поставщику (источнику данных) с помощью `CLSIDProgID`моникера, `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();

Параметры

См. раздел IDBProperties::GetProperties в справочнике программиста OLE DB в пакете SDK для Windows.

Возвращаемое значение

Стандартный HRESULT.

Замечания

Чтобы получить одно свойство, используйте GetProperty.

CDataSource::GetProperty

Возвращает значение указанного свойства для подключенного объекта источника данных.

Синтаксис

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

Параметры

guid
[in] Идентификатор GUID, определяющий набор свойств, для которого необходимо вернуть свойство.

propid
[in] Идентификатор свойства для возвращаемого свойства.

pVariant
[out] Указатель на вариант, в котором GetProperty возвращается значение свойства.

Возвращаемое значение

Стандартный HRESULT.

Замечания

Чтобы получить несколько свойств, используйте GetProperties.

CDataSource::Open

Открывает подключение к источнику данных с помощью CLSIDProgIDmoniker или moniker или 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 , содержащих свойства и значения, которые необходимо задать. См . раздел "Наборы свойств" и "Группы свойств" в справочнике программиста OLE DB в пакете SDK для Windows.

nPropertySets
[in] Число структур DBPROPSET, переданных в аргументе pPropSet.

pName
[входные данные] Имя базы данных, к которой необходимо подключиться.

pUserName
[входные данные] Имя пользователя.

pPassword
[входные данные] Пароль пользователя.

nInitMode
[входные данные] Режим инициализации базы данных. Ознакомьтесь со сведениями о свойствахинициализации в справочнике программиста OLE DB в пакете SDK для Windows для списка допустимых режимов инициализации. Если nInitMode равно нулю, режим инициализации не включен в набор свойств, используемый для открытия подключения.

szProgID
[входные данные] Идентификатор программы.

enumerator
[in] Объект CEnumerator, используемый для получения моникера для открытия соединения, когда вызывающий объект не указывает.CLSID

hWnd
[входные данные] Дескриптор окна, которое является родительским объектом диалогового окна. Использование перегрузки функции, использующего параметр hWnd , автоматически вызывает компоненты службы; дополнительные сведения см. в разделе "Примечания".

dwPromptOptions
[входные данные] Определяет стиль отображаемого диалогового окна выбора. Возможные значения см. в файле Msdasc.h.

Возвращаемое значение

Стандартный HRESULT.

Замечания

Перегрузка метода, использующая параметр hWnd , открывает объект источника данных с компонентами службы в oledb32.dll; эта библиотека DLL содержит реализацию функций компонентов службы, таких как пул ресурсов, автоматическое перечисление транзакций и т. д. Дополнительные сведения см. в справочнике по OLE DB в руководстве программиста OLE DB.

Перегрузки методов, которые не используют параметр hWnd , открывают объект источника данных без использования компонентов службы в oledb32.dll. Объект CDataSource, открытый с этими перегрузками функций, не сможет использовать любую из функций компонентов службы.

Пример

В следующем коде показано, как открыть источник данных Jet 4.0 с помощью шаблонов OLE DB. Источник данных 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
[входные данные] Имя файла (обычно это файл подключения к источнику данных (UDL)).

Дополнительные сведения о файлах ссылок на данные (UDL-файлы) см. в разделе "Обзор API связи данных" в пакете SDK для Windows.

Возвращаемое значение

Стандартный 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.

Замечания

CDataSource::OpenWithPromptFileName

Этот метод отображает диалоговое окно, а затем открывает источник данных, используя указанный пользователем файл.

Синтаксис

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

Параметры

hWnd
[входные данные] Дескриптор окна, которое является родительским объектом диалогового окна.

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
[in] Поставщик CLSID данных.

szProgID
[входные данные] Идентификатор программы поставщика данных.

pPropset
[in] Указатель на массив структур DBPROPSET , содержащих свойства и значения, которые необходимо задать. См . раздел "Наборы свойств" и "Группы свойств" в справочнике программиста OLE DB в пакете SDK для Windows. При инициализации объекта источника данных свойства должны принадлежать к группе свойств источника данных. Если одно и то же свойство указано несколько раз в pPropset, то какое значение используется поставщиком. Если ulPropSets равно нулю, этот параметр игнорируется.

ulPropSets
[in] Число структур DBPROPSET, переданных в аргументе pPropSet. Если это равно нулю, поставщик игнорирует pPropset.

Возвращаемое значение

Стандартный HRESULT.

Замечания

См. также

Шаблоны объекта-получателя OLE DB
Ссылка на шаблоны объекта-получателя OLE DB

Класс CDataSource

Синтаксис

Требования

Участники

Методы

Замечания

CDataSource::Close

Синтаксис

CDataSource::GetInitializationString

Синтаксис

Параметры

Возвращаемое значение

Замечания

CDataSource::GetProperties

Синтаксис

Параметры

Возвращаемое значение

Замечания

CDataSource::GetProperty

Синтаксис

Параметры

Возвращаемое значение

Замечания

CDataSource::Open

Синтаксис

Параметры

Возвращаемое значение

Замечания

Пример

CDataSource::OpenFromFileName

Синтаксис

Параметры

Возвращаемое значение

Замечания

CDataSource::OpenFromInitializationString

Синтаксис

Параметры

Возвращаемое значение

Замечания

CDataSource::OpenWithPromptFileName

Синтаксис

Параметры

Возвращаемое значение

Замечания

CDataSource::OpenWithServiceComponents

Синтаксис

Параметры

Возвращаемое значение

Замечания

См. также

Обратная связь

Обратная связь

Дополнительные ресурсы