Export (0) Print
Expand All
2 out of 5 rated this helpful - Rate this topic

Enumerating, Searching, and Filtering Items in a Folder

Office 2007

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.

Bb147574.vs_note(en-us,office.12).gif  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 PointActionObject of Search Filter Jet Filter SupportDASL Filter SupportComments
Application.AdvancedSearchSets 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.FolderNoYes
Folder.GetTableReturns a Table of items in a folder based on any given filter.FolderYesYesCertain 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.FindSearches for first item that satisfies the specified filter. FolderYesNoCertain properties are not supported in the filter, including Body. For more information, see Items.Find.
Items.RestrictFilters given set of items based on specified restrictions and returns another Items collection.FolderYesYesCertain properties are not supported in the filter, for example, Body. For more information, see Items.Restrict.
Search.GetTableReturns a Table of items in a search folder based on any filter derived from Application.AdvancedSearch.Search folderNoYesSearch.GetTable derives its filter from the Search object (specifically the Search.Filter property) returned from Application.AdvancedSearch.
Table.RestrictFilters rows in the given table based on a specified filter and returns another Table object.FolderYesYesCertain 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.FilterSets 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.FolderNoYes
View.XMLGets 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.FolderNoYesView XML is being deprecated. Use the View object model to program views.



Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.