MDAC 2.5 SDK - OLE DB Programmer's Reference
Chapter 2: Data Source and Session Objects

Data Source Object States

When a data source object is created, it is in an uninitialized state. For example, if the underlying data store is a file, the data source object has not yet opened the file; if the data store is an SQL database, the data source object has not yet connected to the database.

In the uninitialized state, the consumer can do only the following with the data source object:

• Call QueryInterface for IUnknown, IConnectionPointContainer, IDBAsynchStatus, IDBDataSourceAdmin, IDBInitialize, IDBProperties, IPersist, IPersistFile, or ISupportErrorInfo.
  
  
• Call AddRef or Release on any interface obtained from QueryInterface.
  
  
• Call methods on IConnectionPointContainer, IDBDataSourceAdmin, IDBInitialize, IDBAsynchStatus, IPersist, IPersistFile, or ISupportErrorInfo.
  
  
• Call methods on IDBProperties for properties in the Initialization property group.

If the consumer calls any other OLE DB method, the provider returns E_UNEXPECTED. The provider may also return E_NOINTERFACE if the consumer calls QueryInterface for an interface other than those listed.

To initialize the data source object, usually the consumer first calls IDBProperties::SetProperties to set the value of properties in the Initialization property group. For example, if the data store is a text file, the consumer might specify the name and location of the file. If the data store is a database in a DBMS, the consumer might specify the name of the server on which the database resides, along with the user ID and password to use.

Certain properties in the Initialization property group are required by the data source object for initialization. To determine which properties these are, the consumer calls IDBProperties::GetPropertyInfo for properties in the Initialization property group. For required properties, the DBPROPFLAGS_REQUIRED bit is set in the dwFlags element of the returned DBPROPINFO structure.

After the consumer has finished setting properties, it calls IDBInitialize::Initialize. Initialize can prompt for additional information, especially if the consumer has not set values for all required properties. The consumer can set properties to control how much Initialize prompts, including suppressing prompting altogether. After Initialize returns successfully, the data source object is in an initialized state. The consumer can also create and initialize a new data source object by calling IDBDataSourceAdmin::CreateDataSource.