ADSI Enumerator Object

An ADSI Enumerator Object is a dependent COM object in Active Directory that enumerates its Active Directory host object. ADSI Container Objects, ADSI Members Objects, and ADSI Collection Objects host enumerator objects. This object supports the Automation IEnumVARIANT interface, which is retrieved by the get__NewEnum ( _NewEnum) method supported by IADsContainer, IADsMembers, and IADsCollection. By convention, all items managed by an enumerator object are of the same Automation data type. An enumeration should not retrieve some items as VARIANTs of type VT_I4 and others as VARIANTs of type VT_BSTR. Active Directory objects interfaces are represented by the VT_UNKNOWN type.

When to Implement

Implement ADSI Enumerator Object only when you are providing Active Directory enumeration functionality for your directory service implementation.

Follow one of three models for caching collections during enumeration. The caching model affects the behavior of Active Directory when an object in a collection is deleted from the underlying directory service "outside" of Active Directory.

1. Collections are cached. The collection of object instances is retrieved from the underlying directory in its entirety when get_NewEnum (_NewEnum) is called to create a new enumerator object. If the source object for an Active Directory object instance in the retrieved collection is deleted from the underlying directory, you do not become aware of the deletion until an IADs::GetInfo or IADs::SetInfo attempts to access the source instance.
2. Collections are incrementally cached. The collection is retrieved from the underlying directory one object at a time when IEnumVARIANT::Next is called. Reset returns to the beginning of the collection in the cache and Next will return cached objects until the end of the cache is reached, at which point new objects are added from the underlying store. Once an Active Directory object instance is in the cache, you do not become aware of its deletion from the underlying directory until an IADs::GetInfo or IADs::SetInfo attempts to access the source instance.
3. Collections are not cached. The collection is retrieved from the underlying directory one object at a time when IEnumVARIANT::Next is called. Reset returns to the beginning of the collection in the underlying store. Next and Reset operations cannot retrieve deleted objects, since the objects are fetched on-demand from the underlying directory. Only the "current" object is cached. If the current object is deleted, you do not become aware of its deletion from the underlying directory until an IADs::GetInfo or IADs::SetInfo attempts to access the source instance.

ADSI Container Object or ADSI Members Object enumerations yield one or more Active Directory interfaces. Cache the retrieved pointers for any Active Directory objects you intend to manipulate to avoid the overhead of obtaining a new interface pointer. For example, a Visual Basic program that enumerates a container and populates a listbox with names can cache the interface pointers associated with the names for later use. This approach provides greater performance than populating the listbox during enumeration and obtaining a new interface pointer when the user makes a selection.

QuickInfo

  Windows NT: Use version 4.0 and later.

See Also

ADsBuildEnumerator, ADsEnumerateNext, ADsFreeEnumerator