Enumerator States

  • Article

If an enumerator does not require initialization, it is created in an initialized state and remains in that state. For example, an enumerator that searches the registry does not require initialization.

If an enumerator requires initialization, it is created in an uninitialized state. For example, if it enumerates directories, the enumerator does not yet know the starting directory. If it enumerates databases in an SQL DBMS, the enumerator has not yet connected to the DBMS.

To determine whether an enumerator requires initialization, the consumer calls QueryInterface for IDBInitialize. If this interface is exposed, the enumerator requires initialization and must also expose IDBProperties. If it is not exposed, the enumerator does not require initialization. The remainder of this section discusses enumerators that require initialization.

In the uninitialized state, the consumer can do only the following with the enumerator:

  • Call IUnknown::QueryInterface for IUnknown, IDBInitialize, IDBProperties, or ISupportErrorInfo.

  • Call AddRef or Release on any interface obtained from QueryInterface.

  • Call methods on IDBProperties for properties in the Initialization property group.

  • Call methods on IDBInitialize or ISupportErrorInfo.

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 enumerator, the consumer first calls IDBProperties::SetProperties to set the value of properties in the Initialization property group. For example, if the enumerator enumerates directories, the consumer might specify the server and directory the enumerator should start with. If the enumerator enumerates databases in an SQL DBMS, the consumer might specify the name of the server on which the DBMS resides, along with the user ID and password to use.

Certain properties in the Initialization property group are required by the enumerator 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 enumerator is in an initialized state.

If the consumer needs to reinitialize the enumerator after it has been initialized, it must first uninitialize it. For example, if the enumerator enumerates directories and the consumer needs to enumerate directories on a different server, the consumer must disconnect from the first server before connecting to the second. If the enumerator enumerates databases in an SQL DBMS and the consumer needs to enumerate databases in a different installation of that DBMS, the consumer must disconnect from the first DBMS before connecting to the second. To uninitialize the enumerator, the consumer calls IDBInitialize::Uninitialize.