ADSI Interfaces

Microsoft® Windows® 2000 Scripting Guide

Each interface contains a set of methods you use to programmatically administer directories. Methods either perform an action or identify something about the object to which they are attached. Methods that perform an action are always referred to as methods, and methods that describe an object are often called properties.

A common convention for showing an interface and its method or property is interfacename::methodname or interfacename::propertyname. For example, the GetEx method of the IADs core interface is written as IADs::GetEx.

Whether an interface is available to administer a directory service is dependent on the provider being used. Providers do not implement all interfaces. For example, the LDAP provider does not implement the IADsADSystemInfo interface because this interface is specifically designed to retrieve information about a client computer and the currently logged-on user in an Active Directory domain. In contrast, the LDAP provider is specifically designed to interact on domain controllers with Active Directory and other LDAP-compliant directories.

Note

• To use the IADsADSystemInfo interface, the computer must be running Windows 2000 or an operating system in the Windows XP family and the interface must be created separately from the binding operation.

In addition, providers do not necessarily implement all methods within an interface. For example, the LDAP provider does not implement the CopyHere method of the IADsContainer interface. Instead, you must use other techniques to perform a copy operation.

For a list of the interfaces supported by each system provider, go to the Active Directory Programmer's Guide link on the Web Resources page at https://www.microsoft.com/windows/reskits/webresources and search for the topic "Provider Support of ADSI Interfaces."

Categorizing Interfaces

Interface categorizations make it easier to locate the appropriate interface for a particular task. Table 5.6 shows the interface categories, a general description of their purposes, and the interfaces within each category that are implemented by the LDAP provider.

Table 5.6 Interfaces Implemented by the LDAP Provider

LDAP Provider Objects and Their Interfaces

Grouping interfaces by the objects that they support simplifies the process of determining the properties and methods that are implemented for an object. For a table showing the ADSI object types generated by the LDAP provider, such as generic object (GenObject) and User, and the ADSI interfaces supported by each object, see the Active Directory Programmer's Guide link on the Web Resources page at https://www.microsoft.com/windows/reskits/webresources and search for the topic "ADSI Objects of LDAP." For tables implemented by the other system providers, search for the following topics:

• "ADSI Objects for WinNT"

• "ADSI Objects for NDS"

• "ADSI Objects of NWCOMPAT"

The core interfaces, IADs and IADsContainer, are the two interfaces you are most likely to encounter when working with COM objects instantiated by the ADSI system providers. Interfaces implemented by the LDAP or WinNT provider to perform specialized tasks, such as changing a user account password or reading an attribute stored as a large integer, appear in the ADSI task-based chapters in this book.

IADs Properties

The six read-only properties in the IADs interface let you uniquely identify every object in the directory.

• IADs::ADsPath. Returns a string containing the fully qualified path of the object in the directory. The path uniquely identifies the object in the directory and can be used to retrieve the object as long as the object is not moved.

• IADs::Class. Returns a string containing the name of the schema class of the object.

• IADs::GUID. Returns a string containing the globally unique identifier (GUID) of the object.

  You can use the GUID returned by this property to bind directly to the object. If you choose to do this, however, the ADsPath property will return a GUID ADsPath.

• IADs::Name. Returns a string containing the relative name of the object within the underlying directory service. This name distinguishes the object from its siblings.

• IADs::Parent. Returns a string containing the ADsPath of the parent object.

  Although concatenating the Parent property to the Name property in an ADSI script might sometimes return the object's ADsPath, it is not guaranteed to return valid results. Use the object's ADsPath property to retrieve the actual ADsPath.

• IADs::Schema. Returns a string containing the schema class of the object.

  You can use the string returned by this property to bind to the schema class object. After you have bound to the schema class object, you can determine the mandatory and optional attributes defined for objects based on the schema. For more information about mandatory and optional attributes, see "Classes and Attributes" earlier in this chapter.

The script in Listing 5.55 displays information about the na.fabrikam.com domain using the IADs properties collection.

Listing 5.55 Displaying Information About a Domain Using IADs Properties

1
2
3
4
5
6
7

Set objDomain = GetObject("LDAP://dc=NA,dc=fabrikam,dc=com")
Wscript.Echo "ADsPath:" & objDomain.ADsPath
Wscript.Echo "Class:" & objDomain.Class
Wscript.Echo "GUID:" & objDomain.GUID
Wscript.Echo "Name:" & objDomain.Name
Wscript.Echo "Parent:" & objDomain.Parent
Wscript.Echo "Schema:" & objDomain.Schema

When this script runs, it echoes IADs properties in the domain object, as shown in the following list:

ADsPath:LDAP://dc=NA,dc=fabrikam,dc=com
Class:domainDNS
GUID:618a1da520255a41ab778f5dc1d8da4d
Name:dc=NA
Parent:LDAP://dc=fabrikam,dc=com
Schema:LDAP://schema/domainDNS

IADsContainer Property

The one read-only property in IADsContainer lets you read the object classes specified in the Filter method.

• IADsContainer::Filter. This property returns the class of objects being filtered in a container enumeration.

  IADsContainer::Filter is also considered a method because you use it to set the Filter property on a container object to be enumerated. Therefore, to separate the property from the method, the property is referred to as get_Filter because it reads the value of the filter. The method is referred to as put_Filter because it sets or writes the value of the filter.

The other two properties of IADsContainer, IADsContainer::Count and IADsContainer::Hints, are not implemented in the LDAP provider.

The script in Listing 5.56 displays the Filter property in the container enumeration of the HR OU. Note that you must assign a value to the Filter property by using the Filter method, as shown in line 2 of the listing.

Listing 5.56 Displaying the Filtered Property

1
2
3
4
5
6

Set objOU = GetObject("LDAP://OU=HR,dc=NA,dc=fabrikam,dc=com")
ObjOU.Filter= Array("Computer", "User")
Wscript.Echo "Object Filters:"
For each strObject in objOU.Filter
 Wscript.Echo vbTab & strObject
Next

When this script runs, it echoes the IADsContainer::Filter property in the HR OU, as shown in the following list:

Object Filters:
        Computer
        User

For information about IADsContainer methods, see the following sections earlier in this chapter:

• IADsContainer::Filter (put_Filter). "Enumerating Active Directory Objects in Containers"

• IADsContainer::get__NewEnum. "Enumerating Active Directory Objects in Containers"

  This method allows a script to enumerate through a container of objects. Every script in "Enumerating Active Directory Objects in Containers" implicitly calls this method to perform enumeration tasks with the VBScript For Each statement. Therefore, no explicit call to this method appears in the scripts.

• IADsContainer::Create. "Creating Directory Service Objects"

• IADsContainer::Delete. "Deleting Directory Service Objects"

• IADsContainer::MoveHere. "Moving and Renaming Objects"

One method of IADsContainer that requires some explanation beyond referring to sections earlier in this chapter is:

• IADsContainer::GetObject. This method retrieves an IADs reference to an object in a container.

After you have used the VBScript GetObject function to bind to a container, you can then use the IADs::GetObject method to retrieve an object from the container. However, for simplicity, you will usually complete a single GetObject function call to bind directly to an object in a container instead of performing the binding operation in two steps.