Working with the MAPIFolder Object

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.