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

2017-07-07 02:10:07

This chapter has already covered how to iterate over Folders collections, how to get a MAPIFolder out of a Folders collection using the index operator, how to access Outlook's default folders, how to get a MAPIFolder by EntryID and StoreID, and how to use Outlook's Select Folder dialog box to get a MAPIFolder. This section examines some additional properties and methods associated with the MAPIFolder object.

Other Identifiers for a Folder

The MAPIFolder object's Name property returns the display name of a folder as a String. The default server sync failures folder identified by OlDefaultFolders.olFolderServerFailures, for example, returns the string "Server Failures" for its Name property.

The MAPIFolder object's FolderPath property returns the full name of the folder as a String, including the names of the containing folders. The default server sync failures folder identified by OlDefaultFolders.olFolderServerFailures, for example, returns the string "\\Eric Carter\Sync Issues\Server Failures" for its FolderPath property. For this example, the Server Failures folder is contained in a folder called Sync Issues in the Store called Eric Carter.

The MAPIFolder object's Description property returns a String containing the description of the folder. This is a read/write property that can be set to any String value. The MAPIFolder object's ShowItemCount property controls whether the folder shows the unread item count, total item count, or no count when displayed in the Outlook Navigation pane folder list. It can return or be set to a member of the OlShowItemCount enumeration: olNoItemCount, olShowTotalItemCount, or olShowUnreadItemCount. If you want to determine the number of unread items in a particular folder, use the MAPIFolder object's UnReadItemCount property, which returns an Integer value representing the unread item count.

Accessing Subfolders Contained in a Folder

A MAPIFolder may contain subfolders. The MAPIFolder object's Folders property returns a Folders collection, which contains any additional MAPIFolder objects that are subfolders of the given folder.

As described earlier, you can iterate over the subfolders contained in the Folders collection for a MAPIFolder using Visual Basic's For Each loop. You can also get to a particular MAPIFolder in the Folders collection by 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.

The Folders collection's Add method enables you to add a new subfolder to the subfolders associated with a MAPIFolder. The Add method takes the name of the new folder as a String parameter. It also takes as an optional Object parameter the Outlook folder type to use for the new folder. You can pass this parameter a subset of the OlDefaultFolders constants: olFolderCalendar, olFolderContacts, olFolderDrafts, olFolderInbox, olFolderJournal, olFolderNotes, olPublicFoldersAllPublicFolders, or olFolderTasks. If you omit this parameter, the Outlook folder type of the newly created folder matches the folder type of the parent folder. Also note that a folder of type olPublicFoldersAllPublicFolders can be added only somewhere under the root public folder returned by the NameSpace object's GetdefaultFolder(olPublicFoldersAllPublicFolders).

The Folders collection's Remove method enables you to remove a subfolder by passing the 1-based index of the folder in the Folders collection. Figuring out what the 1-based index is can be a bit of a pain; it usually is easier just to call the Delete method on the MAPIFolder object representing the subfolder you want to remove.

Listing 11.13 shows a VSTO add-in that iterates over the subfolders of the Inbox folder and then adds a new folder using the Folders collection's Add method. Then it deletes the newly added folder using the MAPIFolder object's Delete method rather than the Folders collection's Remove method.

Listing 11.13. A VSTO Add-In That Iterates over Subfolders of the Inbox Folder, Adds a New Subfolder, and Then Deletes It

Public Class ThisApplication Private Sub ThisApplication_Startup(ByVal sender As Object, _ ByVal e As System.EventArgs) Handles Me.Startup Dim folder As Outlook.MAPIFolder folder = Me.Session.GetDefaultFolder( _ Outlook.OlDefaultFolders.olFolderInbox) MsgBox(String.Format( _ "There are {0} subfolders in the Inbox.", _ folder.Folders.Count)) For Each subFolder As Outlook.MAPIFolder In folder.Folders MsgBox(String.Format("Sub folder {0}.", subFolder.Name)) Next Dim NewSubFolder As Outlook.MAPIFolder NewSubFolder = folder.Folders.Add( _ "New Temporary Folder") MsgBox("A new subfolder was added in the Inbox folder") NewSubFolder.Delete() MsgBox("The new subfolder was just deleted.") End Sub End Class

Accessing Items Contained in a Folder

A MAPIFolder's main purpose in life is to contain Outlook items. When you create a new folder, you have to specify the type of folder it is. This type constrains the types of Outlook items it can contain. Figure 11.8 shows Outlook's Create New Folder dialog box, which appears when you right-click a folder or root folder (Store) in Outlook and choose New Folder. The Create New Folder dialog box makes the user decide what kind of items the folder can contain: Calendar Items, Contact Items, Journal Items, Mail and Post Items, Note Items, or Task Items. This constraint is enforced by Outlook. If you try to drag a Mail item to a folder that was created to contain Calendar items, the item type will be changed to Calendar.

Figure 11.8. Outlook's Create New Folder dialog box.

The MAPIFolder object's Items property returns an Items collection containing Outlook items in the folder. Each Outlook item in the folder is returned as an Object. You can use the fact that folders are constrained to contain certain types of Outlook items when iterating over items in a folder. If you check the type of item that folder contains by looking at the DefaultItemType property, you can write code that tries to cast the objects returned from the Items collection only to the Outlook item types that are allowed in that folder. So, for example, if you are iterating over items in a Folder whose DefaultItemType property returns olContactItem, objects returned from the Items collection can be cast to either a ContactItem or a DistListItem.

Table 11.7 shows how the member of the OlDefaultFolders enumeration you pass in when you create the folder using Folders.Add corresponds to the returned DefaultItemType and what possible Outlook item types could be found in that folder.

Table 11.7. Relationship Between Folders.Add Folder Type (OlDefaultFolders), DefaultItemType Value, and Outlook Item Types Found in a Folder
Folder Created with `OlDefaultFolders` Enumeration Member	DefaultItemType Returns `OlItemType` Enumeration Member	Possible Outlook Item Types in Folder
`olFolderCalendar`	`olAppointmentItem`	AppointmentItem
`olFolderContacts`	`olContactItem`	ContactItem, DistListItem
`olFolderJournal`	`olJournalItem`	JournalItem
`olFolderInbox olFolderDrafts`	`olMailItem`	MailItem, PostItem, MeetingItem, RemoteItem, ReportItem, DocumentItem, TaskRequestAcceptItem, TaskRequestDeclineItem, TaskRequestItem, TaskRequestUpdateItem
`olFolderNotes`	`olNoteItem`	NoteItem
`olPublicFolders AllPublicFolders`	`olPostItem`	PostItem
`olFderTasks`	`olTaskItem`	TaskItem

Listing 11.14 shows an add-in that iterates over the top-level folders in each open Store and iterates over the items in each of those folders. It uses the DefaultItemType property to determine which kinds of items a particular folder might have in it and casts the objects returned from the Items collection to one of the expected types in the folder. Note that there is a case where the expected cast might fail. An object that is a MailItem that has restricted permissions cannot be cast to a MailItem unless the item has been opened in Outlook in an inspector window with security permissions verified.

Listing 11.14. A VSTO Add-In That Iterates over Items in Folders and Performs Appropriate Casts

Public Class ThisApplication Private Sub ThisApplication_Startup(ByVal sender As Object, _ ByVal e As System.EventArgs) Handles Me.Startup Dim rootFolders As Outlook.Folders = Me.Session.Folders Dim folder As Outlook.MAPIFolder For Each folder In rootFolders Dim subFolders As Outlook.Folders = folder.Folders Dim subfolder As Outlook.MAPIFolder For Each subfolder In subFolders IterateFolder(subfolder) Next Next End Sub Public Sub IterateFolder(ByVal folder As Outlook.MAPIFolder) Dim subject As New System.Text.StringBuilder subject.AppendLine(folder.Name) For Each item As Object In folder.Items subject.AppendLine(GetSubject(item, _ folder.DefaultItemType)) Next MsgBox(subject.ToString()) End Sub Public Function GetSubject(ByVal item As Object, _ ByVal ptype As Outlook.OlItemType) As Object Select Case ptype Case Outlook.OlItemType.olAppointmentItem If TypeOf item Is Outlook.AppointmentItem Then Dim appointment As Outlook.AppointmentItem = item Return appointment.Subject End If Exit Select Case Outlook.OlItemType.olContactItem Case Outlook.OlItemType.olDistributionListItem If TypeOf item Is Outlook.ContactItem Then Dim contact As Outlook.ContactItem = item Return contact.Subject End If If TypeOf item Is Outlook.DistListItem Then Dim distlist As Outlook.DistListItem = item Return distlist.Subject End If Exit Select Case Outlook.OlItemType.olJournalItem If TypeOf item Is Outlook.JournalItem Then Dim journal As Outlook.JournalItem = item Return journal.Subject End If Exit Select Case Outlook.OlItemType.olMailItem If TypeOf item Is Outlook.MailItem Then Dim mail As Outlook.MailItem = item Return mail.Subject End If If TypeOf item Is Outlook.PostItem Then Dim post As Outlook.PostItem = item Return post.Subject End If If TypeOf item Is Outlook.MeetingItem Then Dim meeting As Outlook.MeetingItem = item Return meeting.Subject End If If TypeOf item Is Outlook.RemoteItem Then Dim remote As Outlook.RemoteItem = item Return remote.Subject End If If TypeOf item Is Outlook.ReportItem Then Dim report As Outlook.ReportItem = item Return report.Subject End If If TypeOf item Is Outlook.DocumentItem Then Dim doc As Outlook.DocumentItem = item Return doc.Subject End If If TypeOf item Is Outlook.TaskRequestAcceptItem Then Dim tra As Outlook.TaskRequestAcceptItem = item Return tra.Subject End If If TypeOf item Is Outlook.TaskRequestDeclineItem Then Dim trd As Outlook.TaskRequestDeclineItem = item Return trd.Subject End If If TypeOf item Is Outlook.TaskRequestItem Then Dim tr As Outlook.TaskRequestItem = item Return tr.Subject End If If TypeOf item Is Outlook.TaskRequestUpdateItem Then Dim tru As Outlook.TaskRequestUpdateItem = item Return tru.Subject End If Exit Select Case Outlook.OlItemType.olNoteItem Dim note As Outlook.NoteItem = item If note IsNot Nothing Then Return note.Subject End If Exit Select Case Outlook.OlItemType.olPostItem Dim post2 As Outlook.PostItem = item If post2 IsNot Nothing Then Return post2.Subject End If Exit Select Case Outlook.OlItemType.olTaskItem Dim task As Outlook.TaskItem = item If task IsNot Nothing Then Return task.Subject End If Exit Select End Select MsgBox(String.Format( _ "Couldn't cast item with subject {0} and class {1}.", _ item.Subject, _ item.Class)) Return "" End Function End Class

Working with a Folder's View Settings

A MAPIFolder has a Views property that returns a Views collection. The Views collection contains all the available View objects for a folder that correspond to the views shown in the Custom View Organizer dialog box, shown in Figure 11.4 earlier in this chapter. You can determine the view being used by the folder by accessing the MAPIFolder object's CurrentView property, which returns a View object. The CurrentView property is read-only; you cannot change the current view by setting the CurrentView property to another View object. Instead, you must access one of the View objects in the Views collection and call the View object's Apply method to make the view associated with the folder the active view.

Listing 11.15 shows add-in code that gets the name of the current view for the Inbox folder. Then it iterates over the available views for the Inbox folder and applies each view.

Listing 11.15. A VSTO Add-In That Iterates over Available Views for the Inbox Folder and Applies Each View

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) Me.ActiveExplorer().CurrentFolder = inbox MsgBox(String.Format("Current inbox view is {0}.", _ inbox.CurrentView.Name)) Dim view As Outlook.View For Each view In inbox.Views view.Apply() MsgBox(String.Format("Current inbox view is now {0}.", _ inbox.CurrentView.Name)) Next End Sub End Class

Copying or Moving a Folder to a New Location

You can copy a folder and its dependent folders and items to a new location using the MAPIFolder object's CopyTo method. The CopyTo method takes a DestinationFolder parameter of type MAPIFolder, which will be the parent folder for the copied folder. It returns a MAPIFolder for the newly copied folder. The copy is a "deep copy" because all the items and subfolders rooted at the folder you call the CopyTo method on are copied to the new location.

You can move a folder and its dependent folders and items to a new location using the MAPIFolder's MoveTo method. The MoveTo method takes a DestinationFolder parameter of type MAPIFolder, which will be the parent folder for the moved folder. The folder is moved, along with all dependent folders and items, to the new location.

Displaying a Folder in an Explorer View

You can open a MAPIFolder in a new Explorer view by calling the MAPIFolder object's Display method. To use an existing Explorer view, you can set the Explorer object's CurrentFolder to the MAPIFolder you want to display in the existing Explorer view. Listing 11.15 uses this approach.