IADsContainer interface (iads.h)

Article
07/22/2021

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.

Inheritance

The IADsContainer interface inherits from the IDispatch interface. IADsContainer also has these types of members:

Methods

The IADsContainer interface has these methods.


IADsContainer::CopyHere The IADsContainer::CopyHere method creates a copy of the specified directory object in this container.
IADsContainer::Create Sets up a request to create a directory object of the specified schema class and a given name in the container.
IADsContainer::Delete Deletes a specified directory object from this container.
IADsContainer::get__NewEnum Retrieves an enumerator object for the container.
IADsContainer::GetObject Retrieves an interface for a directory object in the container.
IADsContainer::MoveHere Moves a specified object to the container that implements this interface.

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

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.

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.

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

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

Examples

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

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

IADs *pADs = NULL;
IADsClass *pCls = NULL;
HRESULT hr = S_OK;
BSTR bstr;

hr = ADsGetObject(L"WinNT://myComputer,computer", IID_IADs, (void**)&pADs);
if(FAILED(hr)){return;}

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

if(FAILED(hr)){return;}

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

Requirement	Value
Minimum supported client	Windows Vista
Minimum supported server	Windows Server 2008
Target Platform	Windows
Header	iads.h