Section C.1. Objects and Interfaces

C.1. Objects and Interfaces

A method is a procedure or function that is defined on an object that interacts with the object. For instance, an interface to access Active Directory group objects would have Add and Remove methods, so that members could be added or removed from a group. Methods are normally represented as Interface::MethodName when referenced, and this is the form we adopt in this book. Objects also have properties that are retrieved using the IADs::Get (get a single-value attribute) or IADs::GetEx (get a multivalue attribute) methods and set or replaced using the IADs::Put (modify a single-value attribute) or IADs::PutEx (modify a multivalue attribute) methods.

Each ADSI object supports an IADs interface that provides six basic pieces of information about that object:

Name

Relative name for the object (relative distinguished name [RDN] in the case of Active Directory)

ADsPath

Unique identifier for object

GUID

128-bit Globally Unique Identifier of object

Class

Objectclass of the object

Schema

ADsPath to the objectclass of the object

Parent

ADsPath to the parent object

If you wanted to retrieve the GUID property of an object named objX in VBScript, you would use the following:

strGUID = objX.Get("GUID")

You can see that we are calling the IADs::Get method on the object called objX; the dot (.) indicates the invocation of a property or method. The IADs::Get method takes one parameter, the property to retrieve, which in this case is the GUID, and passes it out to a variable that we have called strGUID. To relieve you from having to use the IADs::Get method for the most common properties, certain interfaces allow you to access common properties with property methods. In these specific cases, you may use the dotted method notation to retrieve the property by using the property method of the same name. So in the previous GUID example, the GUID property has a property method of the same name (i.e., IADs::GUID). We could, therefore, retrieve the GUID with:

strGUID = objX.GUID

We won't go into the interfaces in any more depth here, we just want to give you a feel for how methods and properties can be accessed on an object via ADSI interfaces. Although an object can support more than one interface without a problem, each object supports only the interfaces that are relevant to it. For example, the user object does not support the methods that work for groups. There are approximately 40 interfaces that all begin with the prefix IADs. Interfaces can relate to many different types of objects, including objects that reside in directory services (e.g., IADsUser, IADsGroup), transient objects that don't exist in a directory service (e.g., IADsPrintJob), and security-related objects (e.g., IADsOpenDSObject, IADsAccessControlList). Note that not every object has a specific IADs interface (e.g., IADsUser) that applies to its objectclass, so in those cases, you have to use the more generic IADs or IADsContainer interfaces.

Because each directory service is slightly different, not every ADSI interface method and property works in every directory service. If you make a method call to a directory service provider that doesn't support a particular method, you'll receive an error specifying that the provider doesn't support that method. According to the ADSI specification, each service provider must reject inappropriate calls with the correct ADSI error message.