IDBInitialize::Initialize
Initializes a data source object or enumerator.
Syntax
HRESULT Initialize();
Parameters
None.
Return Code
S_OK
The method succeeded.DB_S_ASYNCHRONOUS
The method has initiated asynchronous initialization of the data source object. The consumer can call IDBAsynchStatus::GetStatus to poll for status or can register for notifications of asynchronous processing. Until asynchronous processing completes, the data source object remains in an uninitialized state.DB_S_ASYNCHRONOUS should be returned before DB_S_ERRORSOCCURRED.
DB_S_ERRORSOCCURRED
The data source object or enumerator was initialized, but one or more properties ? for which the dwOptions element of the DBPROP structure was DBPROPOPTIONS_OPTIONAL ? were not set. To return properties in error, the provider uses DBPROPSET_PROPERTIESINERROR. The method can fail to set properties for a number of reasons, including the following:It was not possible to set the property.
The value in vValue in the DBPROP structure was invalid.
The property's value conflicted with an existing property.
DB_S_ASYNCHRONOUS should be returned before DB_S_ERRORSOCCURRED. Once data source object initialization is complete, the consumer can see DB_S_ERRORSOCCURRED either by calling IDBAsynchStatus::GetStatus or by receiving IDBAsynchNotify::OnStop.
E_FAIL
A provider-specific error occurred.E_OUTOFMEMORY
The provider was unable to allocate sufficient memory to initialize the data source object or enumerator.E_UNEXPECTED
The data source object is in the process of being initialized asynchronously. To cancel asynchronous execution, call IDBAsynchStatus::Abort.DB_E_ALREADYINITIALIZED
IDBInitialize::Initialize had already been called for the data source object or enumerator, and an intervening call to IDBInitialize::Uninitialize had not been made.DB_E_CANCELED
The provider prompted for additional information and the user selected Cancel.The value passed for DBPROP_INIT_HWND was not a valid HWND.
DB_E_ERRORSOCCURRED
The data source object was not initialized due to conflicting properties. DB_E_ERRORSOCCURED can be returned if two optional properties conflict or if two required properties conflict. To return properties in error, the provider uses DBPROPSET_PROPERTIESINERROR. The method can fail to set properties for a number of reasons, including the following:It was not possible to set the property.
The value in vValue in the DBPROP structure was invalid.
The property's value conflicted with an existing property.
DB_SEC_E_AUTH_FAILED
Authentication of the consumer to the data source object or enumerator failed. The data source object or enumerator remains in the uninitialized state.
Comments
IDBInitialize::Initialize initializes the data source object or enumerator. It uses the values of properties in the Initialization property group that have been set with IDBProperties::SetProperties. If the consumer has not set values for all required properties, IDBInitialize::Initialize can prompt for values.
If IDBInitialize::Initialize returns DB_S_ERRORSOCCURRED or DB_E_ERRORSOCCURRED, the consumer can immediately call IDBProperties::GetProperties with the DBPPROPSET_PROPERTIESINERROR property set to return the properties that could not be set. For more information, see Property Sets in Appendix C: OLE DB Properties.
For information about what the consumer can and cannot do with a data source object or enumerator before it is initialized, see Data Source Object States and Enumerator States.
Initializing a Data Source Object Through a Network Connection
The following shows how to instantiate a data source object as an in-process object using CoCreateInstance.
// IDBInitialize_Initialize.cpp
// compile with: /c
#include <oledb.h>
extern CLSID CLSID_DSO;
int main() {
HRESULT hr;
IDBInitialize * pIDBInitialize;
// Create the data source object.
hr = CoCreateInstance(CLSID_DSO, NULL, CLSCTX_INPROC_SERVER, IID_IDBInitialize, (void**) &pIDBInitialize);
// Set the initialization properties.
DBPROP rgProps[8];
for (ULONG i = 0 ; i <= 7 ; i++) {
VariantInit(&rgProps[i].vValue);
rgProps[i].dwOptions = DBPROPOPTIONS_REQUIRED;
};
rgProps[0].dwPropertyID = DBPROP_INIT_LOCATION;
V_VT(&(rgProps[0].vValue)) = VT_BSTR;
V_BSTR(&(rgProps[0].vValue)) = SysAllocStringLen(OLESTR("server"), wcslen(OLESTR("server")));
rgProps[1].dwPropertyID = DBPROP_INIT_DATASOURCE;
V_VT(&(rgProps[1].vValue)) = VT_BSTR;
V_BSTR(&(rgProps[1].vValue)) = SysAllocStringLen(OLESTR("database"), wcslen(OLESTR("database")));
rgProps[2].dwPropertyID = DBPROP_AUTH_PASSWORD;
V_VT(&(rgProps[2].vValue)) = VT_BSTR;
V_BSTR(&(rgProps[2].vValue)) = SysAllocStringLen(OLESTR("password"), wcslen(OLESTR("password")));
rgProps[3].dwPropertyID = DBPROP_AUTH_USERID;
V_VT(&(rgProps[3].vValue)) = VT_BSTR;
V_BSTR(&(rgProps[3].vValue)) = SysAllocStringLen(OLESTR("username"), wcslen(OLESTR("username")));
rgProps[4].dwPropertyID = DBPROP_AUTH_ENCRYPT_PASSWORD;
V_VT(&(rgProps[4].vValue)) = VT_BOOL;
V_BOOL(&(rgProps[4].vValue)) = VARIANT_TRUE;
rgProps[5].dwPropertyID = DBPROP_AUTH_CACHE_AUTHINFO;
V_VT(&(rgProps[5].vValue)) = VT_BOOL;
V_BOOL(&(rgProps[5].vValue)) = VARIANT_TRUE;
rgProps[6].dwPropertyID = DBPROP_AUTH_PERSIST_SENSITIVE_AUTHINFO;
V_VT(&(rgProps[6].vValue)) = VT_BOOL;
V_BOOL(&(rgProps[6].vValue)) = VARIANT_TRUE;
rgProps[7].dwPropertyID = DBPROP_AUTH_PERSIST_ENCRYPTED;
V_VT(&(rgProps[7].vValue)) = VT_BOOL;
V_BOOL(&(rgProps[7].vValue)) = VARIANT_TRUE;
// Create the structure containing the properties.
DBPROPSET PropSet;
PropSet.rgProperties = rgProps;
PropSet.cProperties = 8;
PropSet.guidPropertySet = DBPROPSET_DBINIT;
// Get an IDBProperties pointer and set the
// initialization properties.
IDBProperties *pIDBProperties;
pIDBInitialize->QueryInterface(IID_IDBProperties, (void**)&pIDBProperties);
pIDBProperties->SetProperties(1, &PropSet);
pIDBProperties->Release();
// Initialize the data source object.
hr = pIDBInitialize->Initialize();
pIDBInitialize->Release();
return hr;
};