ADSI and COM

Now that we have some background on COM, let's take another look at ADSI from a COM perspective.

What Is an ADSI Object?

In most cases, when I refer to ADSI or an Active Directory object, I'm referring to a representation of a directory entry. I tend to use the term directory entry when referring to the unit of data stored in the directory—independent of how that data is accessed. The term directory object refers to the ADSI representation of a directory entry. Each directory entry is made up of one or more attributes, which are the named properties of the object and represent pieces of data stored in the directory object. In many cases an attribute may contain lists of data, with each piece of data known as a value.

You might think that there are two objects, one on the client side and the other on the server, but that isn't the case. The ADSI object always "exists" on the client, specifically in the address space of the process that requests the object. ADSI is known as a COM in-process server. The relationship between a directory entry and a directory object, shown in Figure 3-8, becomes apparent when changing the property value of an object. The properties are changed locally, but they must be committed before they are written to the directory and other clients can access the new values.

ADSI Interfaces

An ADSI object has multiple interfaces, some of which are specific to the class of directory entry being represented. For example, the IADsUser interface is available for directory objects representing a user. One interface I'll use in many of the examples in this book is the IADs interface. This interface provides the set of properties and methods applicable to all directory objects. In Chapter 6, I'll discuss the specifics of the IADs interface.

Figure 3-8 The relationship between a directory entry and a directory object.

All ADSI objects representing directory entries support the IADs, IADsContainer, IADsDeleteOps, IADsObjectOptions, IADsOpenDSObject, IADsPropertyList, IDirectoryObject, and IDirectorySearch interfaces in addition to specific interfaces. Which interfaces are available depends on the type of directory object being represented and the provider being used. Table 3-2 contains a list of ADSI interfaces available to directory objects when a program uses the LDAP provider to communicate with Active Directory.

Interface	Description
IADs	Used to identify the current object and to get and set property values. This interface is discussed in Chapter 6.
IADsClass	Used to manage the definition for a class, including identifying values, the type of class, properties for the object, inheritance settings, container settings, and help information. This interface is discussed in Chapter 9.
IADsContainer	Used to enumerate objects in a container and for creating, deleting, copying, and moving objects in a container. This interface is discussed in Chapter 6.
IADsDeleteOps	Used to delete the current object and any contained objects.
IADsGroup	Used to manage a group object, including adding and removing objects to the group and testing an object for membership in the group. This interface is discussed in Chapter 10.
IADsLocality	Used to manage a locality object. This interface contains properties related to the physical location of a network resource.
IADsMembers	Used to enumerate the members of a group. This interface is discussed in Chapter 10.
IADsO IADsOU	Interfaces used to manage organization and organizational-Unit objects. An organization object is supported but not used by default in Active Directory. An organizationalUnit is a special form of container used to group related objects.
IADsObjectOptions	Used to control various options of the LDAP provider.
IADsOpenDSObject	Used to supply a security context when binding to a directory object. This interface is discussed in Chapter 4.
IADsPrintQueue IADsPrintQueue- Operations	Interfaces used to manage printers on the network. A printQueue object exposes both interfaces used to identify and control a printer's job queue.
IADsProperty	Used to manage the definition of an attribute, including the object identifier, syntax, minimum and maximum range, and whether the attribute is multivalued. This interface is discussed in Chapter 9.
IADsPropertyEntry IADsPropertyList IADsPropertyValue IADsPropertyValue2	Family of interfaces used to examine the properties and values of a directory object. (Even though it has a similar name, the IADsProperty interface is different and is not part of the IADsProperty XXX family of interfaces.) These interfaces are discussed in Chapter 7.
IADsSyntax	Used to get and set the Automation data type that represents the data. This interface is discussed in Chapter 9.
IADsUser	Used to manage a user object, including getting and setting user information, specifying the groups that this user belongs to, and changing the user's password. This interface is discussed in Chapter 10.
IDirectoryObject	Provides non-Automation clients with a low-overhead way to access directory objects. This interface is discussed in Chapter 7.
IDirectorySearch	Provides non-Automation clients with a low-overhead way to search Active Directory. This interface is discussed in Chapter 6.

Table 3-2 ADSI interfaces for directory objects.

The other ADSI interfaces are used for utility purposes or to conveniently manage data types. ADSI includes a large number of data type interfaces, but the LDAP provider only supports a subset of them. A list of those interfaces and objects is shown in Table 3-3. I'll discuss these objects and interfaces as needed.

Interface	Category	Description
IADsDNWithBinary	Data type	Interface to a DNWithBinary object. Used to map a GUID to a distinguished name.
IADsDNWithString	Data type	Interface to a DNWithString object. Used to associate a string with a distinguished name.
IADsExtension	Extension	Interface used to extend ADSI functionality.
IADsLargeInteger	Data type	Interface to a LargeInteger object. Used to manipulate 64-bit integers.
IADsSecurityDescriptor IADsAccessControlEntry IADsAccessControlList	Security	Interfaces to manage security and access-control objects. These interfaces provide a convenient means to work with the various Windows security data types.
IADsADSystemInfo	Utility	Interface to an ADSystemInfo object. Used to get system information about the local computer. Only available on Windows 2000; it is not supported on Windows NT, Windows 98, or Windows 95. This interface is briefly mentioned in Chapter 9.
IADsNamespaces	Core	Used to manage the installed ADSI providers. Interface to a container of name-spaces available from installed providers.
IADsNameTranslate	Utility	Interface to a NameTranslate object. Used to translate object and account names into various formats.
IADsPathname	Utility	Interface to a Pathname object. Used to parse path strings into various formats.
IADsWinNTSystemInfo	Utility	Interface to a WinNTSystemInfo object. Used to retrieve Windows NT–style information on a computer running Windows 2000. Requires Windows 2000 or Windows NT 4 with the Active Directory Client. Not supported on Windows 95 or Windows 98.

Table 3-3 Other ADSI objects and interfaces.