Enumerating, Searching, and Filtering Items in a Folder
The Outlook object model provides several entry points that support enumerating, searching, and filtering items in a folder.
Enumerating Items
The Items, Table, and Selection objects all support enumerating items in a folder. However, there are specific scenarios where you would choose one over the others.
You can obtain an Items collection by calling Folder.Items which returns the items in the folder. Each item object in the collection is complete with all its explicit built-in properties and custom properties, and supports read-write operations. The Items collection also supports filters and events that fire when items are added, changed, or removed from the collection.
You can use Folder.GetTable or Search.GetTable to obtain a Table object that represents a set of items in a folder or search folder. In both cases, you can specify a filter to obtain a subset of the items in the folder, or, if you do not specify any filter, obtain all the items in the folder. By default, each item in the returned Table contains only a default subset of its properties. You can view each row of a Table as an item in the folder, each column as a property of the item, and the Table is an in-memory light-weight rowset that allows fast enumeration and filtering of items in the folder. Although additions and deletions of the underlying folder are reflected by the rows in the Table, the Table does not support any events for adding, changing, and removing rows. If you require a writeable object from the Table row, obtain the Entry ID for that row from the default EntryID column in the Table and then use the GetItemFromID method of the NameSpace object to obtain a full item, such as a MailItem or ContactItem, that supports read-write operations. For more information on default columns in a Table, see Default Properties Displayed in a Table Object.
The Selection object supports enumerating items that a user has currently selected in an explorer. Since the explorer displays the contents of a folder, the Selection object supports enumeration of items in that folder as per the user's selection.
Note
A folder in Outlook can contain heterogeneous items. For example, the Contacts folder supports creating contact items and distribution list items by default. Since the Items, Table, and Selection objects encapsulate items in a folder or search folder, the items in them do not necessarily have the same message class. When enumerating items in these collections and objects, it is a good practice to first check for the message class of each item before accessing the item's properties.
Searching and Filtering Items
The Items, Table, Application, and View objects support searching and filtering of items in a folder. The following table describes and compares these entry points:
Entry Point |
Action |
Object of Search Filter |
Jet Filter Support |
DASL Filter Support |
Comments |
Sets the criteria for a Search object and returns the Search object. Search.Results specifies the search results. Search.Save updates a search folder with the search results. |
Folder |
No |
Yes |
||
Folder.GetTable |
Returns a Table of items in a folder based on any given filter. |
Folder |
Yes |
Yes |
Certain properties are not supported in the Table filter, including binary properties, and HTML or RTF body content. For more information, see Unsupported Properties in a Table Object or Table Filter. |
Searches for first item that satisfies the specified filter. |
Folder |
Yes |
No |
Certain properties are not supported in the filter, including Body. For more information, see Items.Find. |
|
Filters given set of items based on specified restrictions and returns another Items collection. |
Folder |
Yes |
Yes |
Certain properties are not supported in the filter, for example, Body. For more information, see Items.Restrict. |
|
Search.GetTable |
Returns a Table of items in a search folder based on any filter derived from Application.AdvancedSearch. |
Search folder |
No |
Yes |
Search.GetTable derives its filter from the Search object (specifically the Search.Filter property) returned from Application.AdvancedSearch. |
Filters rows in the given table based on a specified filter and returns another Table object. |
Folder |
Yes |
Yes |
Certain properties are not supported in the Table filter, including binary properties, and HTML or RTF body content. For more information, see Unsupported Properties in a Table Object or Table Filter. |
|
Sets a view's filter without changing the view's XML. Setting the filter for a view only changes the view in the user interface and does not result in a filtered Items collecton. |
Folder |
No |
Yes |
||
Gets or sets the XML for a view. Modifying the <Filter> node changes the view's filter. Setting the XML for a view only changes the view in the user interface and does not result in a filtered Items collecton. |
Folder |
No |
Yes |
View XML is being deprecated. Use the View object model to program views. |