MDAC 2.5 SDK - OLE DB Programmer's Reference
OLE DB Core Components Interfaces

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.

A property or value specified in pwszInitializationString was invalid or 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.

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_IDBInitialize,
   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));