Given a connection string, instantiates and returns a 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.
pwszInitializationString [in]
A pointer to a connection string containing the information to be used for creating, and setting properties on a data source object. If this 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, then 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 provider is specified in pwszInitializationString, then the data source specified by *ppDataSource will be used.
If *ppDataSource is non-null on entry, and a provider is specified in pwszInitializationString, GetDataSource checks to see if 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 generated from IDataInitialize or IDBPromptInitialize.
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.
pwszInitializationString specified a provider, pUnkOuter was not a null pointer, and dwClsCtx was CLSCTX_LOCAL_SERVER or CLSCTX_REMOTE_SERVER.
E_INVALIDARG
pwszInitializationString specified a provider and dwClsCtx was not a valid value.
ppDatasource was a null pointer.
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.
*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 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<IUnknown **>(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<void **>(pIDBInitialize));