IADsContainer

The IADsContainer interface enables an ADSI container object to create, delete and manage contained ADSI objects. Container objects are used both to represent the hierarchical directory trees, such as a file system, and to organize the directory hierarchy. An example of ADSI container objects is the namespaces object that contains provider-specific top-level directory objects representing the directory trees. Other examples include a network domain object containing computer, among other things. A computer object itself can contain other objects, such as User, Group, Service, FileService and PrintQueue.

You can use the IADsContainer interface to either enumerate contained objects or manage these objects' life-cycle. An example would be to recursively navigate down 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, you typically make the request to the container object to perform the task.

The IADsContainer interface exposes the following methods and property methods.

Methods in Vtable Order

Remarks

Often you need to determine if an object is a container or not. Although you can do so by querying the IADsContainer interface on the object, a much simpler way is to invoke the IADsClass::get_Container (classObj.Container in Visual Basic) method on the object's schema class object. This method returns TRUE if the object is a container, FALSE otherwise.

When you bind to a container object using its GUID (or SID), you can only perform a limited number of operations on the container object. These operations include examination of its attributes and enumeration of its immediate children. For example, the following Visual Basic code fragment will work.

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

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

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

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

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

In case you want to call these methods of the container bound with its GUID (or SID), you need to rebind to the object using its distinguished name:

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")

More discussions of object's GUID representation can be found in IADs::get_GUID.

Example Code [Visual Basic]

The following Visual Basic code snippet determines if an ADSI object is a container.

Dim obj As IADs
Dim cls As IADsClass
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

Example Code [C++]

The following C++ code snippet determines if an ADSI object is a container. For brevity, error checking is omitted.

IADs *pADs;
ADsGetObject(L"WinNT://myComputer,computer", IID_IADs, (void**)&pADs);

BSTR bstr;
pADs->get_Schema(&bstr);
IADsClass *pCls;
ADsGetObject(bstr, IID_IADsClass, (void**)&pCls);
pADs->Release();
SysFreeString(bstr);

VARIANT_BOOL isContainer;
pCls->get_Container(&isContainer);

if(isContainer) 
    printf("Object is a container.\n");
else
    printf("Object is not a container.\n");

pCls->Release();

Requirements

  Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with DSClient).
  Windows 95/98: Requires Windows 95 or later (with DSClient).
  Header: Declared in Iads.h.

See Also

IADsClass::get_Container, IADs::get_GUID, IADsNamespaces