Visual Studio Tools for Office: Using Visual Basic 2005 with Excel, Word, Outlook, and InfoPath

2017-07-07 02:10:07

A companion object to the Application object is the NameSpace object, which is retrieved by using the Application object's Session property. As noted earlier, some confusion can arise because functionality that you would expect to be on the Application object is actually often found on the NameSpace object. Further increasing the confusion is the Application.GetNameSpace method, which is an older way to get to a NameSpace object. This method takes a string for the type of NameSpace to return, implying that you can get different types of NameSpace objects. In reality, the GetNameSpace method accepts only one string ("MAPI"). In this chapter, we use the Application object's Session property (added in Outlook 98) to get a NameSpace object rather than the older GetNameSpace method.

Working with the Root Folders of the Open Outlook Stores

The NameSpace object's Folders property returns a Folders collection, allowing you to iterate over all the root folders that are open within Outlook. Each root folder is the root of what is called a Store. A root folder could correspond to an Exchange account or some other e-mail account. It could also correspond to an Outlook data file, such as a .PST file. All folders and Outlook items under a particular root folder share a StoreID.

You can iterate over the Folders collection using Visual Basic's For Each loop. You can also get to a particular MAPIFolder in the Folders collection using the index operator (). The index operator can be passed a String representing the name of the Folder in the Folders collection or a 1-based index representing the index of the Folder within the Folders collection.

Although the Folders collection provides Add and Remove methods, these methods are not applicable to root folders, because root folders represent accounts that are added and removed by adding and removing e-mail accounts or adding and removing Outlook data files. The following section discusses how a Store is added and removed programmatically.

Listing 11.10 illustrates iterating over the Folders collection using For Each. It also shows how to get a MAPIFolder using the index operator on the Folders collection. Finally, it shows how to add a new Folder to an existing store using the Folders collection's Add method.

Listing 11.10. A VSTO Add-In That Iterates over the Root Folders and Adds a New Folder

Public Class ThisApplication Private Sub ThisApplication_Startup(ByVal sender As Object, _ ByVal e As System.EventArgs) Handles Me.Startup For Each folder As Outlook.MAPIFolder In Me.Session.Folders MsgBox(folder.Name) Next Dim rootFolder As Outlook.MAPIFolder = Me.Session.Folders(1) Dim NewFolder As Outlook.MAPIFolder NewFolder = rootFolder.Folders.Add( _ "Test Notes Folder", _ Outlook.OlDefaultFolders.olFolderNotes) MsgBox(String.Format( _ "A new folder has been created in the store {0}.", _ rootFolder.Name)) End Sub End Class

Adding and Removing Outlook Stores

To add a Store programmatically, you can use the NameSpace object's AddStore or AddStoreEx method. The AddStore method takes a Store parameter of type Object. You can pass a String representing the complete filename of the PST file to add. If the PST file you provide does not exist, Outlook creates the file for you. AddStoreEx takes the same Store parameter of type Object that AddStore does. It also takes a second Type parameter of type OlStoreType. To this parameter, you can pass a member of the OlStoreType enumeration, which will control the format in which the PST file will be created should you pass a PST file that does not exist. The possible values you can pass are olStoreDefault, olStoreUnicode, and olStoreANSI.

Use the NameSpace object's RemoveStore method to remove a Store programmatically. RemoveStore removes the Store from Outlook but does not delete the actual PST file or mailbox on the server associated with the Store. RemoveStore takes a Folder parameter of type MAPIFolder. This parameter must be one of the root folders in the NameSpace object's Folders collection.

Determining the Current User

The NameSpace object's CurrentUser property returns a Recipient object representing the logged-in user. Given a Recipient object, you can use the Recipient object's Name property to get the name of the logged-in user.

Checking Whether Outlook Is Offline

You can determine whether Outlook is offline by getting the value of the NameSpace object's Offline property. This property returns true if Outlook is offline and not connected to a server.

Getting Standard Folders Such As the Inbox Folder

A method already used in several examples in this chapter to get standard Outlook folders, such as the Inbox folder, is the NameSpace object's GetDefaultFolder method. This method takes a FolderType parameter of type OlDefaultFolders and returns a MAPIFolder object. Table 11.6 lists the members of the OlDefaultFolders enumeration that can be passed to GetDefaultFolder and the standard Outlook folder that is returned.

Table 11.6. Members of the OlDefaultFolders Enumeration That Can Be Passed to NameSpace Object's GetDefaultFolder Method
Enumeration Member	GetDefaultFolder Result
`olFolderCalendars`	Returns the Calendar folder
`olFolderConflicts`	Returns the Conflicts folder
`olFolderContacts`	Returns the Contacts folder
`olFolderDeletedItems`	Returns the Deleted Items folder
`olFolderDrafts`	Returns the Drafts folder
`olFolderInbox`	Returns the Inbox folder
`olFolderJournal`	Returns the Journal folder
`olFolderJunk`	Returns the Junk E-Mail folder
`olFolderLocalFailures`	Returns the Local Sync Failures folder
`olFolderNotes`	Returns the Notes folder
`olFolderOutbox`	Returns the Outbox folder
`olFolderSentMail`	Returns the Sent Items folder
`olFolderServerFailures`	Returns the Server Sync Failures folder
`olFolderSyncIssues`	Returns the Sync Issues folder
`olFolderTasks`	Returns the Tasks folder
`olPublicFoldersAllPublicFolders`	Returns the Public Folders folder

Getting a Folder or Outlook Item by ID

All Outlook items and folders are uniquely identified by an EntryID and a StoreID. All Outlook items and folders within a given Store share a StoreID. The EntryID is unique within a given Store. So the combination of an EntryID and StoreID uniquely identifies a folder or an Outlook item. When you have created a new Outlook item using the Items collection's Add method or the Application object's CreateItem method, the newly created Outlook item will not be assigned an EntryID until you call the Save method on the newly created item.

Both a MAPIFolder and the 16 Outlook item types have an EntryID property that returns the EntryID for the folder or item as a String. But only MAPIFolders have a StoreID property. To determine the StoreID that corresponds to a particular Outlook item, you must get the parent MAPIFolder using the Parent property of an Outlook item and then determine the StoreID from the parent folder.

The NameSpace object's GetFolderFromID method takes an EntryID parameter as a String and an optional StoreID parameter as an Object to which you can pass the StoreID as a String. If you omit the StoreID parameter by passing Type.Missing, Outlook assumes that it should look in the default Store (the Store in which the default Inbox and Calendar are located). The GetFolderFromID method returns the MAPIFolder object identified by the EntryID and StoreID.

The NameSpace object's GetItemFromID method takes an EntryID parameter as a String and an optional StoreID parameter as an Object to which you can pass the StoreID as a String. If you omit the StoreID parameter, Outlook assumes that it should look in the default Store. The GetItemFromID method returns the Object for the Outlook item identified by the EntryID and StoreID. Then you can cast the returned Object to 1 of the 16 Outlook item types listed in Table 10.1 in Chapter 10, "Working with Outlook Events."

Listing 11.11 illustrates getting a folder and an Outlook item by EntryID and StoreID.

Listing 11.11. A VSTO Add-In That Uses the NameSpace Object's GetFolderFromID and GetItemFromID Methods

Public Class ThisApplication Private Sub ThisApplication_Startup(ByVal sender As Object, _ ByVal e As System.EventArgs) Handles Me.Startup Dim inbox As Outlook.MAPIFolder inbox = Me.Session.GetDefaultFolder( _ Outlook.OlDefaultFolders.olFolderInbox) Dim inboxStoreID As String = inbox.StoreID Dim inboxEnTryID As String = inbox.EntryID Dim outlookItem As Object = inbox.Items(1) Dim itemStoreID As String = inboxStoreID Dim itemEntryID As String = outlookItem.EntryID Dim theFolder As Outlook.MAPIFolder theFolder = Me.Session.GetFolderFromID( _ inboxStoreID, inboxEnTryID) MsgBox(theFolder.Name) Dim theItem As Object = Me.Session.GetItemFromID( _ itemEntryID, itemStoreID) MsgBox(theItem.Subject) End Sub End Class

Accessing Address Books and Address Entries

The NameSpace object's AddressLists property returns the AddressLists collection. The AddressLists collection is a collection containing all the available address books as AddressList objects. The AddressList object has an AddressEntries collection, which is a collection of AddressEntry objects. Each AddressEntry object represents an address in an address book.

Listing 11.12 iterates over the available address books and displays the name of each address book. It also displays the name of the first address entry in each address book.

Listing 11.12. A VSTO Add-In That Iterates over Available Address Books

Public Class ThisApplication Private Sub ThisApplication_Startup(ByVal sender As Object, _ ByVal e As System.EventArgs) Handles Me.Startup Dim lists As Outlook.AddressLists = Me.Session.AddressLists For Each list As Outlook.AddressList In lists MsgBox(String.Format( _ "{0} has {1} address entries.", _ list.Name, list.AddressEntries.Count)) If list.AddressEntries.Count > 0 Then MsgBox(String.Format( _ "The first address in this address book is {0}.", _ list.AddressEntries(1).Name)) End If Next End Sub End Class

Displaying the Outlook Select Folder Dialog Box

The NameSpace object provides a method that allows you to display Outlook's Select Folder dialog box, shown in Figure 11.7. The Select Folder dialog box provides a way for the user to pick a folder, as well as create a new folder. The NameSpace object's PickFolder method displays the Select Folder dialog box as a modal dialog box. The method returns the MAPIFolder object corresponding to the folder the user picked in the dialog box. If the user cancels the dialog box, this method will return Nothing.