Directory Services

IADsContainer

The IADsContainer interface enables an ADSI container object to create, delete, and manage contained ADSI objects. Container objects represent hierarchical directory trees, such as in a file system, and to organize the directory hierarchy.

You can use the IADsContainer interface to either enumerate contained objects or manage their lifecycle. An example would be to recursively navigate a directory tree. By querying the IADsContainer interface on an ADSI object, you can determine if the object has any children. If the interface is not supported, the object is a leaf. Otherwise, it is a container. You can continue this process for the newly found container objects. To create, copy, or delete an object, send the request to the container object to perform the task.

Methods in Vtable Order

The IADsContainer interface inherits the methods of the standard COM interfaces:

IUnknown
IDispatch

In addition, IADsContainer defines the following methods.

Method	Description
get_Count	Retrieves the number of directory objects in the container.
get__NewEnum	Retrieves an enumerator object for the container.
get_Filter	Retrieves the filter on the schema classes to use for an enumeration.
put_Filter	Sets the filter on the schema classes to use for an enumeration.
get_Hints	Retrieves the properties to retrieve for each object that is enumerated by the container.
put_Hints	Sets the properties to retrieve for each object that is enumerated by the container.
GetObject	Retrieves an interface for a directory object in the container.
Create	Creates an object in the container.
Delete	Deletes an object in the container.
CopyHere	Copies an object to the container.
MoveHere	Moves an object to the container.

Properties

The IADsContainer interface defines the following properties. The preceding table includes access methods for these properties.

Property	Description
Count	Contains the number of directory objects in the container.
Filter	Contains the filter on the schema classes to use for an enumeration.
Hints	Contains the properties to retrieve for each object that is enumerated by the container.

Remarks

To determine if an object is a container, use the IADsClass.Container property of the object.

When you bind to a container object using its GUID (or SID), you can only perform specific operations on the container object. These operations include examination of the object attributes and enumeration of the object's immediate children. These operations are shown in the following code example.

Dim con As IADsContainer
Dim obj As IADs
Set con = GetObject("LDAP://svr01/<GUID=xxxx>")
con.Filter = Array("user")
For Each item In con
	debug.print item.Name " &  " of " & item.Class
Next

Windows 2000: If you attempt to retrieve the ADsPath attribute of a child object thus obtained, you will get a value that has the child RDN and the parent GUID combined. For example, "LDAP://serverName//CN=Jeff Smith,<GUID=xxxx>"

All other operations, that is, GetObject, Create, Delete, CopyHere, and MoveHere are not supported in the container's GUID representation. For example, the last line of the following code example will result in an error.

[Visual Basic]
Dim con As IADsContainer
Dim obj As IADs
Set con = GetObject("LDAP://svr01/<GUID=xxxx>")
Set obj = con.GetObject("user", "CN=Jeff Smith")

Binding, using GUID (or SID), is intended for low overhead and, thus, fast binds, which are often used for object introspection.

To call these methods of the container bound with its GUID (or SID), rebind to the object using its distinguished name.

[Visual Basic]
Dim conGUID, conDN As IADsContainer
Dim obj As IADs
Set conGUID = GetObject("LDAP://svr/<GUID=xxxx>")
Set conDN=GetObject("LDAP://svr/" & conGUID.Get("distinguishedName"))
Set obj = conDN.GetObject("user", "CN=Jeff Smith")

Windows XP: Binding to a container object with a GUID using the LDAP provider no longer returns a 'GUID ADsPath' for the child objects of the container, and rebinding is not required when attempting to access child objects with the GetObject, Create, Delete, CopyHere, and MoveHere methods.

For more information about object GUID representation, see IADs.GUID.

Example Code [Visual Basic]

The following code example determines if an ADSI object is a container.

Dim obj As IADs
Dim cls As IADsClass
On Error GoTo Cleanup

Set obj = GetObject("WinNT://myComputer,computer")
Set cls = GetObject(obj.Schema)
If (cls.Container = TRUE) Then
	MsgBox "The object is a container."
Else
	MsgBox "The object is a leaf."
End If

Cleanup:
	If (Err.Number<>0) Then
		MsgBox("An error has occurred. " & Err.Number)
	End If
	Set obj = Nothing
	Set cls = Nothing

Example Code [C++]