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.

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 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.

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

Application.AdvancedSearch

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.

Items.Find

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.

Items.Restrict

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.

Table.Restrict

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.

View.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

View.XML

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.

Show:
© 2014 Microsoft