Reading and Writing Properties of Active Directory Objects

All objects have properties. All Active Directory™ Service Interface (ADSI) COM objects have one or more interfaces with methods that retrieve the properties of the directory object that the COM object represents. There are a number of ways you can read properties from an object:

• Get a specific property by name. The IADs interface has two methods IADs::Get and IADs::GetEx to read a specific property. Every ADSI COM object has an IADs interface.
• Get a specified list of properties. The IDirectoryObject interface has the method IDirectoryObject::GetObjectAttributes that allows you to specify a list containing the names of the properties to read and returns an array of structures containing the requested property values.
• Enumerate all properties on the object. The IADsPropertyList interface allows you to enumerate all the properties on an object.
• Get special properties. The Automation interfaces (IADs*) have property methods that allow you to get special properties that are not stored in an object. Or the property methods may allow you to get an object property in a data format that differs from the actual data type stored. For example, the IADs interface has property methods such as IADs::get_Name which is an object's relative path (of the form RDNAttributeName=RDN, for example, CN=Jeff Smith), IADs::get_Class which is an object's class, IADs::get_Parent which is the ADsPath to the object's parent.

ADSI allows you to cache properties locally after they have been read from the directory server. So, you also have a choice of reading the properties from the local property cache or retrieving the properties directly from the directory server. ADSI also has methods to update the cache as well as specifying whether all properties for an object are cached or just those you've specified.

After you have retrieved a property, you read its value. The data type of a property depends on the definition of the property (also known as an attribute) in the Active Directory schema. For each type of property that can exist in Active Directory, there is an attributeSchema object in the Active Directory schema. An attributeSchema object defines the characteristics of the attribute. One of these characteristics is the attribute's syntax, which determines the data type of the attribute's values. For more information, see Characteristics of Attributes and Syntaxes for Active Directory Attributes.

The Automation interfaces (IADs*) return a property value as a VARIANT or a pointer to an Automation interface on a COM object that represents the property. The IDirectoryObject and IDirectorySearch interfaces return a property as a pointer to a structure containing a typed property value or a pointer to a string of bytes. In addition, IDirectoryObject and IDirectorySearch retrieve properties directly from the directory server instead of using a local property cache.