Working with Individual Folders: The MAPIFolder Object

[Previous] [Next]

As you saw earlier in the supplement, the Items collection is returned by the MAPIFolder Items property. The objects contained in the collection correspond to Outlook items such as contacts, tasks, and your custom forms (which are based on the Outlook items). When accessing a specific item in the collection, you need to use the specific Outlook object that corresponds to the item type. For example, if you are working with a contact item in the collection, you need to use the properties and methods of the ContactItem object. You will see all major Outlook item object methods and properties later in this supplement. The following section describes the properties and methods of the Items collection.

Items Collection Properties

You probably will use only two properties on the Items collection in your Outlook applications. The first is the Count property, which returns the number of items in the folder. The second, which requires some more explanation, is the IncludeRecurrences property.

IncludeRecurrences Property

The IncludeRecurrences property is a Boolean property that specifies whether the Items collection should contain recurrence patterns for appointments. The default value for the property is False. You can only set the property to True if the collection contains appointments and the collection is not sorted using any other property than the Start property, in ascending order. If there are recurring appointments in the collection that have no end date, the Count property for the collection may be infinite. Be sure to test for this case when scrolling through the collection using the Count property as the maximum value for a counter variable. The following code sample shows how to count the number of items in your calendar before including recurrences and after including recurrences. If you have recurrences that never end, you will see the Count property jump to a very large number:

     Sub CommandButton1_Click         set oNS = Application.GetNameSpace("MAPI")         set oCalendar = oNS.GetDefaultFolder(9)         set oItems = oCalendar.Items         intCount = oItems.Count         msgbox "There are " & intCount & _             " items in the folder before recurrences."         oItems.Sort "[Start]"         oItems.IncludeRecurrences = True         intCount = oItems.Count         msgbox "There are " & intCount & _             " items in the folder after recurrences."     End Sub 

Items Collection Methods

The methods of the Items collection are some of the most important methods that you can learn in the Outlook object library. These methods allow you to create new items based on custom forms, filter and sort the items for your applications, and quickly find items that correspond to certain criteria in your applications. The following section describes the key methods of the Items collection. For a complete list of all of the methods, refer to the Olform.hlp file on the companion CD.

Add Method

The Add not only allows you to add standard Outlook items to an Items collection, it also allows you to create a custom Outlook form by passing the message class to it. Remember that the message class is the unique identifier for your form, such as IPM.Contact.My Contact. Add is the only method in Outlook that allows you to create custom items. Before you can create a custom item using Add, the associated form for the custom item must exist in a forms library. Otherwise, Outlook just uses the standard form for the base form type. For example, if you try to create a custom contact form but the form is not installed in a forms library, Outlook will bring up the standard contact form instead. By default, if you do not specify the type of form you want to create, Outlook will use the default type for the folder. The following example shows you how to use the Add method by creating a standard Outlook form and a custom Outlook form:

     Sub CommandButton1_Click         set oNS = Application.GetNameSpace("MAPI")         set oInbox = oNS.GetDefaultFolder(6)         set oItems = oInbox.Items         set oNewStandardItem = oItems.Add("IPM.Note")         oNewStandardItem.Display         msgbox "This is a standard MailItem"         set oNewCustomItem = oItems.Add("IPM.Note.My Custom Note")         oNewCustomItem.Display         msgbox "This is a custom MailItem"     End Sub 

Find and FindNext Methods

The Find method allows you to specify conditions that the items in the collection must meet, and then it returns the first item that meets these conditions. The filter is a string expression that can contain multiple AND, OR, or NOT operators as well as custom and system fields. The filter can also contain comparison operators such as greater than (>), less than (<), greater than or equal to (>=), less than or equal to (<=), equal to (=), and not equal to (<>). After you use the Find method on an Items collection, you can use the FindNext method to find the next item that meets your criteria. The following code sample shows some of the different types of filters you can create as well as different operators you can use in the filters. Note that you must include the Outlook field name, even if it is a built-in field, in brackets in your filter.

     Sub CommandButton1_Click         set oNS = Application.GetNameSpace("MAPI")         set oInbox = oNS.GetDefaultFolder(6)         set oItems = oInbox.Items         set oFindItem = oItems.Find("[ReceivedTime] <= '5/19/98'")         oFindItem.Display         set oFindNext = oItems.FindNext         oFindNext.Display         set oFindItem = oItems.Find( _              "[ReceivedTime] <= '5/19/98 9:00 PM' And [Unread] = True")         oFindItem.Display     End Sub 

SetColumns and ResetColumns Methods

Outlook provides you with the SetColumns method to make your applications faster. You can use this method to tell Outlook which properties to cache so that access to these properties is very fast. The properties you do not include in the parameters sent to SetColumns will return empty.

ResetColumns resets the properties so that your application can access all the properties in the items. You can then use the SetColumns method again to cache a different set of properties. The following code sample shows you how to use the SetColumns method:

     Sub CommandButton1_Click         set oNS = Application.GetNameSpace("MAPI")         set oInbox = oNS.GetDefaultFolder(6)         set oItems = oInbox.Items         oItems.SetColumns "[Subject],[SenderName],[To]"     End Sub 

Restrict Method

Similar to the Find method, the Restrict method allows you to specify a filter such that only the items that meet the filter condition will be returned. The difference between the two methods is that the Restrict method returns a collection of items that meet the filter, whereas the Find method returns the first item to meet the filter. The following code sample shows you how to use the Restrict method:

     Sub CommandButton1_Click         set oNS = Application.GetNameSpace("MAPI")         set oInbox = oNS.GetDefaultFolder(6)         set oItems = oInbox.Items         set oResItems = oItems.Restrict( _             "[ReceivedTime] < '5/19/98' and [Unread] = True")         msgbox "There are " & oResItems.Count &              " items in the collection"     End Sub 

Sort Method

The Sort method allows you to specify the property you want to sort the collection by and in what order, either descending or ascending. Please note that you cannot sort the collection using a multivalued property such as the Categories property. Outlook will return an error if you try to do this. The following code shows you how to use the Sort method by sorting your Inbox by the property ReceivedTime, in descending order:

     Sub CommandButton1_Click         set oNS = Application.GetNameSpace("MAPI")         set oInbox = oNS.GetDefaultFolder(6)         set oItems = oInbox.Items         oItems.Sort "[ReceivedTime]",True     End Sub