OLE DB Programmer's Reference

IDataInitialize::GetDataSource

Given a connection string, instantiates and returns an uninitialized data source object.

HRESULT GetDataSource(
   IUnknown *       pUnkOuter,
   DWORD            dwClsCtx,
   LPCOLESTR        pwszInitializationString,
   REFID            riid,
   IUnknown **      ppDataSource);

Parameters

pUnkOuter [in]
A pointer to the controlling IUnknown interface if the data source object is being created as a part of an aggregate; otherwise, it is a null pointer.
dwClsCtx [in]
CLSCTX values. CLSCTX_ALL, CLSCTX_SERVER, and CLSCTX_INPROC_SERVER are acceptable values, but the service components will always attempt to load the provider in-process. Ignored if *ppDataSource is not NULL.
pwszInitializationString [in]
A pointer to a connection string containing the information to be used for creating and setting initialization properties on a data source object. Initialization properties are those in DBPROPSET_DBINIT, as well as provider-specific properties. If pwszInitializationString is NULL, an instance of the OLE DB provider for ODBC data is returned with default properties set.
riid [in]
The requested IID for the data source object returned in *ppDataSource.
ppDataSource [in, out]
A pointer to a data source object.

If *ppDataSource is null on entry, IDataInitialize::GetDataSource generates a new data source object based on the information in pwszInitializationString and returns a pointer to that data source object in *ppDataSource.

If *ppDataSource is null and no provider is specified in pwszInitializationString, the data source object will be defaulted to the OLE DB Provider for ODBC.

If *ppDataSource is non-null and no provider is specified in pwszInitializationString, the data source specified by *ppDataSource will be used.

If *ppDataSource is non-null on entry and a provider is specified in pwszInitializationString, IDataInitialize::GetDataSource checks to see whether the specified provider matches the data source object passed in *ppDataSource. If so, GetDataSource sets the specified properties on the existing data source object. If not, GetDataSource returns an error and leaves *ppDataSource untouched.

Return Code

S_OK
The method succeeded.
E_FAIL
A provider-specific error occurred.
E_NOINTERFACE
The data source did not support the interface specified in riid.

riid was IID_NULL.

*ppDataSource was not null and did not indicate an OLE DB data source object.

E_UNEXPECTED
The data source object cannot return the requested interface because the data source object is not initialized.
DB_E_MISMATCHEDPROVIDER
The data source object specified by *ppDataSource did not match the data source object specified in pwszInitializationString.
DB_E_NOAGGREGATION
pwszInitializationString specified a provider, pUnkOuter was not a null pointer, and riid was something other than IID_IUnknown.

pwszInitializationString specified a provider, pUnkOuter was not a null pointer, and the provider does not support aggregation.

dwClsCtx required out-of-process operation, which is not supported.

The provider does not support in-process operation and cannot be aggregated.

E_INVALIDARG
pwszInitializationString specified a provider, and dwClsCtx was not a valid value.

ppDataSource was a null pointer.

*ppDataSource and pUnkOuter were both non-null. *ppDataSource cannot be aggregated in *pUnkOuter because it has already been created.

REGDB_E_CLASSNOTREG
The provider indicated in pwszInitializationString was not found.

dwClsCtx indicated a server type not supported by the provider specified in pwszInitializationString.

DB_E_ERRORSOCCURRED
A property specified in pwszInitializationString was not supported by the provider.

Properties were specified in pwszInitializationString but *ppDataSource indicated a data source that was already initialized.

A property specified in pwszInitializationString was a read-only property, and the property was not set to its default value.

It was not possible to set a property specified in pwszInitializationString.

One or more properties specified in pwszInitializationString conflicted with an existing property or with one another.

DB_E_BADINITSTRING
A property or value specified in pwszInitializationString was invalid or not supported by the provider.

Comments

None.

Code Example

The following code fragment shows how a consumer might use IDataInitialize to connect to a data source object:

HRESULT                hr               = S_OK;
IDBInitialize *        pIDBInitialize    = NULL;
IDataInitialize *      pIDataInitialize  = NULL;

hr = CoCreateInstance(
   CLSID_MSDAINITIALIZE,
   NULL,
   CLSCTX_INPROC_SERVER,
   IID_IDataInitialize,
   reinterpret_cast<LPVOID *>(&pIDataInitialize));
   if (!SUCCEEDED(hr))
      return hr;

hr = pIDataInitialize->GetDataSource(
   NULL,
   CLSCTX_INPROC_SERVER,
   L"Provider=MSDAORA;User ID=Oracle;Data Source=\\ORACLE",
   IID_IDBInitialize,
   reinterpret_cast<IUnknown **>(&pIDBInitialize));