Platform SDK: Active Directory, ADSI, and Directory Services

Containers and Children

In a directory structure, objects occupy different locations in a hierarchy. There are two basic ways these objects relate to each other in ADSI. One relationship is between containers and their members; the other is between objects and their children.

A container is an object that holds a collection of similar objects. All the objects in a container share the same Class attribute, but they do not necessarily have related ADsPath attributes. Examples of containers and their members include a namespace and its domains, a domain and its computers, and a user group and its users.

The children of an object are all the items one level below that object in the directory structure. Unlike members of a container, an object's children need not share the same Class, but their ADsPath attributes will be directly related. For example, the children of a domain object include users, computers, global user groups, and other objects whose position in the directory structure is directly beneath the domain.

ADSI container objects all implement the IADsContainer interface, which supports the following properties and methods.

Property Description
Filter Restricts an enumeration of the container's contents to return only objects whose class matches the classes listed in the Filter property.
Count Returns the number of objects in the container, or if the Filter property has been specified, the number of objects of classes specified in the Filter.

Method Description
GetObject Binds the directory item with the specified ADsPath to a named variable.
Create Creates a new object of a specified class in the current container.
Delete Removes an object of the specified class from the current container.
Copyhere Creates a copy of the object with a specified ADsPath in the current container. Note that the object must be in the same directory namespace. For example, you cannot copy an object from an LDAP: namespace to a WinNT: namespace.
Movehere Moves the object with a specified ADsPath from its original location to the current container. The same namespace restrictions that apply to the Copyhere method also apply to the Movehere method.

The following sections show how to find the members of a container and the children of a specific object.

Enumerating Container Members

To enumerate the members of a container, use the Members property of the container object:

For Each member In userGroup.Members
    WScript.Echo member.Name
Next

The following script will list all the members of user group Guests and their Description attributes:

Dim userGroup
Dim user

Set userGroup = GetObject("WinNT://mydomain/mymachine/guests")

For Each user In userGroup.Members
    WScript.Echo user.Class & ": " & user.Name
    WScript.Echo user.Description
    WScript.Echo
Next

This script produces output similar to the following:

User: Guest
Built-in account for guest access to the computer/domain

GlobalGroup: Domain Guests
All domain guests

Listing Object Children

To list the children of an object, simply put the object in a For Each loop:

For Each item In myDomain
    WScript.Echo item.Name
Next

The following script lists all the children of a domain and their Class attributes:

Dim myDomain
Dim item

Set myDomain = GetObject("WinNT://mydomain")

For Each item In myDomain
    WScript.Echo item.Class & ": " & item.Name
Next

Filtering

The last example is capable of producing a lot of output in a large domain, probably more than is actually useful. It is possible to limit the information returned from the enumeration of a container by applying a filter to that container.

All ADSI container objects have a Filter property, which is an array of schema class names that will be returned in a given enumeration. The following code will limit the return values to only computers and users in the domain:

Set myDomain = GetObject("WinNT://mydomain")

myDomain.Filter = Array("computer", "user")
For Each item in myDomain
    WScript.Echo item.Class & ": " & item.Name
Next

Note the use of the Array function in the example. The Filter property expects an array, and even if only one value should be applied in the filter, it must still be made into an array. Passing the schema class name by itself, without using the Array function, does not raise an error, but no filtering will be applied. This line of code will set the filter to return only services in the domain:

myDomain.Filter = Array("service")

In order to change the filter settings and reuse the filter, clear its contents by setting it to an empty string:

myDomain.Filter = ""