Working with Controls on Pages: The Controls Collection | Programming Microsoft Outlook and Microsoft Exchange, Second Edition (DV-MPS Programming)

[Previous] [Next]

The objects we've been looking have mostly dealt with user-interface elements. The next set of objects we'll examine deal more with manipulating data. The first object, the Namespace object, is the primary way to access objects that manipulate data stored in Exchange Server by using Outlook. You access the Namespace object by using the GetNameSpace method of the Application object. With the NameSpace object, you can pass in the type of data your application needs to access. The following section covers the properties and methods of the NameSpace object.

NOTE
Currently, Outlook supports only a MAPI NameSpace object. In the future, this NameSpace object could be extended to support other types of namespaces as well.

NameSpace Object Properties

There are three properties of the NameSpace object that are particularly important to developers. These properties, which are covered in the following sections, are AddressLists, CurrentUser, and Folders.

AddressLists Property

The AddressLists property returns the collection of the available address lists for the current session. Since Outlook can support multiple address lists, such as the personal address book, the Outlook address book, and the Exchange Server Global Address List, the types of address lists returned by this property can vary greatly. You should check the name or type of address list being returned before attempting to use the property. Furthermore, Outlook allows your users to synchronize their address lists offline, so when designing your application, you have to take into account support for an offline address list. The following example shows you how to retrieve the address lists in Outlook:

     Sub CommandButton1_Click         set oNS = Application.GetNameSpace("MAPI")         set oALs = oNS.AddressLists         msgbox "There are " & oALs.Count & " AddressLists."     End Sub

CurrentUser Property

The CurrentUser property returns the current user in the Outlook session. The return value from this property is actually a Recipient object, so you can access more information about the user than just the user name, although the name of the currently logged-on user is probably the most used property of the Recipient object. (The Recipient object is covered in more detail later in this supplement.) You can use this property and its corresponding Recipient object to customize the user interface for your forms based on the user who is logged on and custom security. For example, you can automatically populate text boxes that ask for a user name with the name of the currently logged-on user. With custom security, you can programmatically hide or show fields based on who the user is. The following sample shows you both of these customizations:

     Sub CommandButton1_Click         set oNS = Application.GetNameSpace("MAPI")         set oCurrentUser = oNS.CurrentUser         set oControls = Item.GetInspector. _             ModifiedFormPages("P.2").Controls         Select Case oCurrentUser.Name             case "Thomas Rizzo (Exchange)"                 oControls("TextBox1").Visible = True             case "Stacy Eckstein"                 oControls("Label1").Visible = True                 oControls("TextBox1").Visible = False         end select         oControls("TextBox2").Text = oCurrentUser.Name     End Sub

Folders Property

The Folders property returns a collection of all the available folders in the current namespace. You can then use the properties and methods of the MAPIFolder object to perform specific actions on the folder. The following code sample shows you how to display the name of all the root folders in your folder hierarchy:

     Sub CommandButton1_Click         set oNS = Application.GetNameSpace("MAPI")         set oFolders = oNS.Folders         set oFolder = oFolders.GetFirst         for i = 1 to oFolders.Count             msgbox oFolders.Item(i).Name         next     End Sub

NameSpace Object Methods

You will use all the NameSpace object methods at some point when you develop application with Outlook. The NameSpace object methods provide a lot of functionality, such as enabling you to do the following: create recipients; display the standard Outlook folder picker; retrieve items, recipients, and folders by their unique IDs; and allow users with proper permissions to access another user's information.

GetDefaultFolder Method

Outlook gives you the ability to quickly retrieve the standard Outlook folders, such as Inbox, Contact, and Task folders—you don't have to search through the folder hierarchy to find them. Instead, you can just pass to the GetDefaultFolder method the Outlook constant that corresponds to the folder you wish to retrieve. Remember that VBScript in Outlook does not support constants, so you have to use the number that corresponds to the constant, as shown in the following code sample:

     Sub CommandButton1_Click         set oNS = Application.GetNameSpace("MAPI")         set oContacts = oNS.GetDefaultFolder(10)         oContacts.Display     End Sub

NOTE
For a complete list of all the Outlook constants and their associated values, refer to the Olform.hlp file on the companion CD.

CreateRecipient Method

The CreateRecipient method takes a string as its argument. This string should correspond to the user's display name. If a successful object is returned to you, you know that the recipient is in one of the address lists. At that point, you can pass the returned Recipient object to the GetSharedDefaultFolder method in order to open that recipient's shared personal folders. The following code shows you how to use the CreateRecipient method. It uses the returned object to display the e-mail address of the user.

     Sub CommandButton1_Click         set oNS = Application.GetNameSpace("MAPI")         set oRecip = oNS.CreateRecipient("Thomas Rizzo (Exchange)")         msgbox oRecip.Address     End Sub

GetSharedDefaultFolder Method

One of the most requested collaborative applications by users is the ability to view other user's calendars in a single window. With Outlook, you can build this type of application easily by using the GetSharedDefaultFolder method. This method takes a Recipient object and a constant that defines the default folder, such as the Inbox, the Calendar, or the Tasks folder, that the user wants to try and open. This method is best used in the delegation scenario where certain users have permissions on other users' folders. If the user of the application does not have permissions on the other user's folders, Outlook returns an error. The GetSharedDefaultFolder method is shown here:

     Sub CommandButton1_Click         set oNS = Application.GetNameSpace("MAPI")         set oRecip = oNS.CreateRecipient("John")         set oJohnTasks = oNS.GetSharedDefaultFolder(oRecip, 13)         oJohnTasks.Display     End Sub

GetFolderFromID, GetRecipientFromID, GetItemFromID Methods

The GetFolderFromID, GetRecipientFromID, and GetItemFromID methods, when passed the EntryID (a globally unique identifier in Exchange Server and Outlook) and, optionally, the StoreID (normally not passed in) for each of their respective item types will return back that item. These methods are available to help when you know the item's unique ID and need to access the item quickly and don't have time to search through the Exchange Server information store. The following example shows you how to use the GetFolderFromID and GetItemFromID methods:

     Sub CommandButton1_Click         set oNS = Application.GetNameSpace("MAPI")         'Get the inbox         set oFolder = oNS.GetDefaultFolder(6)         txtFolderID = oFolder.EntryID         'Get a message         set oItem = oFolder.Items.GetFirst         txtItemID = oItem.EntryID         set oGetFolderFromID = oNS.GetFolderFromID(txtFolderID)         oGetFolderFromID.Display         set oGetItemFromID = oNS.GetItemFromID(txtItemID)         oGetItemFromID.Display     End Sub

PickFolder Method

In the applications you build with Outlook, there may be times when you want your users to select where to save their items or where the application will find the correct information it needs. Outlook can support many different types of information stores, such as multiple personal stores, an Exchange Server private information store, and an Exchange Server public folder store. You would have difficulty writing a program that displayed all of these different stores, from which the user would have to pick the correct one. To help you, Outlook provides the PickFolder method, which calls the same dialog box that the Outlook program displays when it needs users to decide where information should be saved or queried from. The PickFolder method displays a modal dialog box so that the user will either have to pick a folder or cancel the dialog box in order to continue. The return value from this method is a MAPIFolder object that corresponds to the folder picked by the user. If the user cancels the dialog box, the method returns Nothing. This example shows how to use the PickFolder method and then display the folder that the user picked:

     Sub CommandButton1_Click         set oNS = Application.GetNameSpace("MAPI")         set oFolder = oNS.PickFolder()         if oFolder is Nothing then             msgbox "You did not pick a folder"         else             oFolder.Display         end if     End Sub