IDataInitialize::GetDataSource

  • Article

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

HRESULT GetDataSource(
   IUnknown *       pUnkOuter,
   DWORD            dwClsCtx,
   LPCOLESTR        pwszInitializationString,
   REFIID            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.

    When run in a 32-bit application, if pwszInitializationString is NULL, an instance of the OLE DB provider for ODBC data is returned with default properties set.

    When run in a 64-bit application, if pwszInitializationString is NULL, an instance of the SQLOLEDB provider 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.

    When run in a 32-bit application, if *ppDataSource is null and no provider is specified in pwszInitializationString, OLE DB Core Services returns a data source instance of OLE DB Provider for ODBC.

    When run in a 64-bit application, if *ppDataSource is null and no provider is specified in pwszInitializationString, OLE DB Core Services returns a data source instance of SQLOLEDB.

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