Programming Microsoft Outlook and Microsoft Exchange, Second Edition (DV-MPS Programming)

The ADSI object library is a very approachable object library. Although it does not contain many objects, you can perform many functions with them. The only potentially difficult aspect of using the ADSI object library is understanding how to access the objects in your applications using distinguished path names. At first, these path names can be a little intimidating, but after you experiment with ADSI and its objects, you will understand how to exploit the power of these paths. Creating paths is discussed later in this chapter in the section, "Creating Paths to Exchange Server Objects and Attributes."

In the ADSI architecture, every element in a directory service, such as the Exchange Server directory service, is represented by an ADSI object. The interfaces supported by the ADSI object are determined by the underlying functionality of the directory object. For example, a mailbox in Exchange Server, which does not contain directory objects under it, supports the IADs interface. In contrast, a Recipients container in the Exchange Server directory, which can hold objects such as mailboxes, distribution lists, and other Recipients Containers under it, implements the IADsContainer interface. Since the requirements for a directory object that contains other directory objects are different from those for a single directory object, ADSI provides more methods and properties through extra interfaces for them.

IADs and IADsContainer Interfaces

The primary interfaces you will use when working with ADSI objects are the IADs interface and the IADsContainer interface. The IADs interface is required for all ADSI objects. It provides properties that describe the object—in essence, the metadata of the object—and methods that allow you to manage the actual directory information the object contains. ADSI stores this directory information in a property cache, which gives you a mechanism to batch changes or additions to a specific object in a temporary location, and then burst this information to the directory service in one call. This property cache is useful because some programming languages such as Visual Basic do not provide native batching mechanisms, and without a property cache, every change you make to an ADSI object is put over the wire, decreasing performance of your application.

The property cache is useful, but only if you remember to use it! The most common mistake new ADSI developers make is not calling the specific ADSI method SetInfo to flush the cache and submit to the directory service the modifications to the object. If you do not call this method and then exit your application, the changes you make will not be persisted in the directory. The second most common mistake new ADSI developers make is not calling the GetInfo method to refresh the cache after making changes. The SetInfo method does not automatically refresh the cache for you.

In addition to supporting the GetInfo and SetInfo methods, the IADs interface supports the Get, GetEx, GetInfoEx, Put, and PutEx methods. As you would expect, Get and Put do exactly what their names imply: Get retrieves a specific property from the directory, and Put saves the value for a specific property. The versions of these methods with the Ex suffix allows you to get or put a multivalued property. A multivalued property can contain multiple values of the same type. The best example of a multivalued property in the Exchange Server directory is the Reports property. Since one person can have many direct reports, the reports property in the directory is a multivalued property—multiple direct report names can be stored in a single property for the directory object named reports. To access this property from ADSI, you must use the GetEx method. GetInfoEx is provided so that you can specify which properties to refresh in the property cache, preventing you from having to reload the entire cache from the underlying directory service.

The properties that the IADs interface implements are Name, ADsPath, Class, Schema, and Parent. (For our purposes, the Schema and Parent properties are not as important as the other three, so this discussion will focus on Name, ADsPath, and Class.) The Name property returns the relative name of the object. The ADsPath property returns the path to the object. In Exchange Server, this would be the LDAP query string that is used to access the object. The Class property is important because it returns the schema class name of the object. This property and its return value deserve a bit more attention in the next section.

Exchange Server Object Classes

In Exchange Server are some important class names you should be aware of when developing your applications, the most common of which are container, groupOfNames, organizationalPerson, person, and remote-address:

• The container class identifies the object as a container for other objects in the directory.
• The groupOfNames class corresponds to distribution lists in the Exchange Server directory.
• The organizationalPerson class is used to represent recipients in the directory.
• The person class is an abstract class. It is used to represent any object that can receive mail, so other objects such as a distribution list inherit some attributes from the person class. Because the person class is an abstract class, you can never create an explicit object from it.
• The remote-address class corresponds to a custom recipient in the directory.

IADsContainer Interface

As mentioned earlier in this chapter, if a directory object contains other objects, the directory object is considered a container. In ADSI, a container implements not only the IADs interface but also the IADsContainer interface. The IADsContainer interface provides you with more methods than those provided by the IADs interface so that you can traverse the child objects in the container as well as modify the container's properties. As you will see in the sample application in this chapter, you can use the For…Each construct in Visual Basic or VBScript to easily loop through all the child objects below a container object and retrieve individual properties from each child object. By traversing the individual objects under the container, you can easily build a hierarchical view of the information stored in the Exchange Server directory.

Other ADSI Interfaces

Covering the other ADSI interfaces is beyond the scope of this book, but you should know that ADSI does provide a powerful feature set so that you can build not only directory applications that work with Exchange Server but also applications that work with other directory services. For example, ADSI defines an IADsComputer interface that lets you store information about a computer in a directory service. ADSI also defines interfaces such as IADsPrintQueue and IADsPrintJob, which enable you to list printers available in the directory service and store specifics about the actual print jobs taking place on those print queues. For more information on the other types of ADSI interfaces that you can use, refer to the "Getting Help with ADSI" section at the end of this chapter.