Working with Directories: The AddressLists Collection | Programming Microsoft Outlook and Microsoft Exchange, Second Edition (DV-MPS Programming)

[Previous] [Next]

The AddressEntries collection contains all the individual AddressEntry objects for each entry in the directory. The AddressEntries collection provides a number of methods and properties. However, as a developer, you will probably use the Count property, and the Add, Item, and Sort methods the most. The Count property returns the number of entries in the current directory. The Add method adds new entries into the directory. The Add method does not support adding new entries into the Exchange Server directory, only into the Personal Address Books of Outlook users. See Chapter 14 of the book to learn how to use ADSI to add new directory objects into Exchange Server.

The Item method accesses a particular AddressEntry object. The Sort method allows you to decide how the AddressEntry objects should be arranged in the collection. The following example shows you how to use these methods and the Count property in your application. The example counts the number of entries and then displays the first entry when the list is sorted alphabetically and in ascending order. Then the example adds a new entry into the Personal Address Book and re-sorts the list alphabetically and in descending order. Finally, the code displays the first entry in the list after the sort.

     Sub CommandButton1_Click         set oNS = Application.GetNameSpace("MAPI")         set oALs = oNS.AddressLists         set oALPAB = oALs("Personal Address Book")         set oALPABEntries = oALPAB.AddressEntries         intCount = oALPABEntries.Count         msgbox "There are " & intCount & " entries in the " & oALPAB.Name         'Make sure the entries are sorted alphabetically ascending         oALPABEntries.Sort "[Name]",1         set oFirst = oALPABEntries.GetFirst         msgbox "The first entry alphabetically ascending is " & _             oFirst.Name         Set oNewEntry = oALPABEntries.Add("SMTP", "bob", _             "bob@microsoft.com")         'Need to save the item by updating         oNewEntry.Update         'Re-sort by name alphabetically descending         oALPABEntries.Sort "[Name]",2         set oFirst = oALPABEntries.GetFirst         msgbox "The first entry alphabetically descending is " & _             oFirst.Name     End Sub

AddressEntry Object

The AddressEntry object represents individual directory entries in the AddressEntries collection. This object contains information about how Outlook should send e-mail to a user, such as via the user's Internet (SMTP) address. This object also can hold much more than individual users and their information. The AddressEntry object can hold both public and private distribution lists. As you will see in the following section, the AddressEntry object contains many properties and methods that you will want to take advantage of in your applications. Please note that many of these properties and methods are the same in CDO, so you can leverage this knowledge when developing CDO applications.

AddressEntry Properties

There are a number of properties on the AddressEntry object that you will want to familiarize yourself with. These properties allow you to query the directory for specific information on a particular directory entry. The following section describes these properties in more detail.

Address, Name, and Type Properties

The Address, Name, and Type properties are lumped together in this section because they are very similar to one another. Each of these properties enable you to retrieve or set specific information about users in the directory. For example, the Address property returns or sets the mailing address of the current AddressEntry object. (The Address property is also available on the Recipient object in Outlook when you are adding recipients to e-mail messages.) The Name property represents the display name of the user. For example, at Microsoft, my display name is Thomas Rizzo (Exchange), whereas my address is thomriz@microsoft.com and my type is EX because I am on an Exchange Server. The Type property can hold many values beyond EX, such as SMTP, CCMAIL, and X400. Look in the documentation for the specific directory service that you are using to find out which types the service supports. The following example shows you how to retrieve the Address, Name, and Type properties. Note that only certain directories, such as the Personal Address Book, allow you to change these properties.

     Sub CommandButton1_Click         set oNS = Application.GetNameSpace("MAPI")         set oALs = oNS.AddressLists         set oALPAB = oALs("Personal Address Book")         set oALPABEntries = oALPAB.AddressEntries         set oFirst = oALPABEntries.GetFirst         txtMessage = "Nae: " & oFirst.Name & chr(13) & "Address: " & _            oFirst.Address & chr(13) & "Type: " & oFirst.Type         msgbox txtMessage     End Sub

DisplayType Property

The DisplayType property represents the type of object in the directory. This property can be a number of constants, including olUser (0), olDistList (1), and olPrivateDistList (5). (The constant olPrivateDistList is available only in the Personal Address Book.) DisplayType is a read-only property that allows you to quickly query the directory entry to see what type of entry it is. Your application can then take the appropriate action based on this information. For example, you can color-code distribution lists of users differently from individual users on a form. The following example shows you how to retrieve and display the DisplayType property:

     Sub CommandButton1_Click         set oNS = Application.GetNameSpace("MAPI")         set oALs = oNS.AddressLists         set oALPAB = oALs("Personal Address Book")         set oALPABEntries = oALPAB.AddressEntries         set oFirst = oALPABEntries.GetFirst         Select Case oFirst.DisplayType             Case "0"                 txtMessage = "User"             Case "1"                 txtMessage = "Distribution List"             Case "2"                 txtMessage = "Forum"             Case "3"                 txtMessage = "Agent"             Case "4"                 txtMessage = "Organization"             Case "5"                 txtMessage = "Private Distribution List"             Case "6"                 txtMessage = "Remote User"         End Select         msgbox oFirst.Name & " is of type " & txtMessage     End Sub

Manager Property

The Manager property returns an AddressEntry object that corresponds to the manager of the currently selected AddressEntry object. This property allows you to query for organizational information in the directory. You can then use this information in your application to route information dynamically throughout a company's organization. For example, you could look up the manager of the current user in an expense report application, and if that user's expense is over a certain amount of money, you could route the expense report for approval to the manager. If the manager's information is not available in the directory, the Manager property will return Nothing. The following example creates an e-mail message for the current user and adds the manager of the user as a recipient. In order for this sample to work, you must be using an address-book provider that supports storing organizational information, and the manager's information must be filled in for the current user.

     Sub CommandButton1_Click         set oNS = Application.GetNameSpace("MAPI")         set oNewMessage = Application.CreateItem(0)         set oCurrentUser = oNS.CurrentUser         set oCurrentUserAE = oCurrentUser.AddressEntry         set oManager = oCurrentUserAE.Manager         if oManager is Nothing then             msgbox "Manager property returned Nothing."         else             oNewMessage.Recipients.Add oManager.Name             oNewMessage.Display         end if     End Sub

Members Property

The Members property returns an AddressEntries collection if the current AddressEntry object is a distribution list. The AddressEntries collection that is returned contains the AddressEntry objects that represent the users in the distribution list. This property will return Nothing if the current AddressEntry is not a distribution list. You can also check to see if an AddressEntry object is a distribution list by checking the DisplayType property for the constants olDistList (1) or olPrivateDistList (5). The following example shows you how to retrieve only the distribution lists in an AddressEntries collection and then display all the members of the distribution lists by using the Members property:

     Sub CommandButton1_Click         set oNS = Application.GetNameSpace("MAPI")         set oALPAB = oNS.AddressLists("Personal Address Book")         set oALPABEntries = oALPAB.AddressEntries         For each AddressEntry in oALPABEntries         if AddressEntry.DisplayType = 1 or _         AddressEntry.DisplayType = 5 then             msgbox AddressEntry.Name & " is a Dist. List."             set oMembers = AddressEntry.Members             for i = 1 to oMembers.Count             txtMemberList = txtMemberList & chr(13) & _                 oMembers.Item(i).Name             next             msgbox "The members are: " & txtMemberList             end if         next     End Sub

AddressEntry Object Methods

The AddressEntry object provides methods that allow you to manipulate and display the information stored inside the address lists that you are using for your application. Below are some of the methods you can use.

Details Method

The Details method displays a modal dialog box that allows you to display as well as manipulate the information stored about a particular directory entry. The controls and tabs on the dialog box change according to the type of entry you are calling the Details method on. For example, if the entry was copied from an Exchange Server Global Address List, the user would be presented with the standard Exchange Server details dialog box, as shown in Figure C-6. However, if the entry was copied from an Outlook contact address book, the details dialog box box would look different. For the Details method to work, the AddressEntry Name property must be filled in. Furthermore, the Details method returns a run-time error if the user clicks on the Cancel button to exit the Details modal dialog box.

click to view at full size.

Figure C-6 The details for a user are retrieved from the Exchange Server directory by using the Details method.

The following example shows you how to use the Details method as well as handle the run-time error that is produced when a user clicks on the Cancel button in its dialog box:

     Sub CommandButton1_Click         set oNS = Application.GetNameSpace("MAPI")         set oALPAB = oNS.AddressLists("Personal Address Book")         set oALPABEntries = oALPAB.AddressEntries         set oFirst = oALPABEntries.GetFirst         On Error Resume Next    'To handle clicking on Cancel         oFirst.Details         if Err.Number <> 0 then    'Clicked on Cancel             exit sub         End if     End Sub

GetFreeBusy Method

The GetFreeBusy method allows you to query the calendaring free/busy information of the user to find out the calendar status of the user over the next 30 days. For example, you can use this method to retrieve and then display when the user will be in the office or out of the office. The GetFreeBusy method takes as its parameters the StartDate as a date, the Interval representing the time slots that the returned information should be divided into, and a Boolean named CompleteFormat, which specifies how detailed the returned information should be. Once these parameters are passed in, the GetFreeBusy method returns a string with integers that represent the free/busy status for the individual.

With the StartDate parameter, you must pass in a valid date. Outlook will automatically return the free/busy information for the next 30 days following that date if the information is published. By default, Outlook only publishes two months of free/busy information from the current date. At a maximum, you can set Outlook to publish up to 12 months of free/busy information from the current date.

With the Interval parameter, you can have Outlook query and divide the returned string into different intervals. For example, if you were to pass 15 in as the Interval parameter, Outlook would break the string into 15-minute intervals for the free/busy information. This would return a string that is 2,880 characters in length, with each character representing the free/busy status of the user for that 15-minute interval.

The returned characters are determined by the parameter you pass in for CompleteFormat. If you specify True, you will receive the following:

0, when the person is free

1, when the user has marked tentative for an appointment on his calendar

2, where there is at least one confirmed time commitment, indicating the user is busy during the time period

3, when the user has marked his time as Out of the Office.

If there are conflicting appointments during the interval you specified—for example, a user has an appointment during only part of the interval, and the remaining time in the interval is free, the GetFreeBusy method returns the most committed state. In this case, it would return 2, indicating that the user is busy during the interval.

The method cannot return the free/busy information for the individual users on the distribution list. To get the free/busy time, you need to write code in your program to return the individual free/busy information for each distribution list member.

     Sub CommandButton1_Click         set oNS = Application.GetNameSpace("MAPI")         set oALPAB = oNS.AddressLists("Personal Address Book")         set oALPABEntries = oALPAB.AddressEntries         set oFirst = oALPABEntries.GetFirst         On Error Resume Next    'In case no F/B         txtFB = oFirst.GetFreeBusy(#5/20/98#,30,True)         if err.number <> 0 then             msgbox "Could not retrieve the Free/Busy information."         end if     End Sub

Update Method

The Update method posts changes or new additions for the AddressEntry objects. Any changes or new entries will not be considered permanent in the address book until you call the Update method. The Update method takes two parameters, makePermanent (default value is True) and refreshObject (default value is False). If you call the Update method with makePermanent set to False and refreshObject set to True, Outlook will flush its cache and reload the values for the AddressEntry from its address book. The following example shows you how you can modify the Name property for a user in your Personal Address Book and then call the Update method to commit those changes:

     Sub CommandButton1_Click         set oNS = Application.GetNameSpace("MAPI")         set oALPAB = oNS.AddressLists("Personal Address Book")         set oALPABEntries = oALPAB.AddressEntries         set oFirst = oALPABEntries.GetFirst         msgbox "The original name: " & oFirst.Name         oFirst.Name = "Ted"         oFirst.Update         msgbox "The name after the update: " & oFirst.Name     End Sub