Restrict Method

Applies a filter to the Items collection, returning a new collection containing all items from the original which match the filter. This method is an alternative to using the Find method or FindNext method to iterate over specific items within a collection. The Find or FindNext methods are faster than filtering if there are a small number of items. The Restrict method is significantly faster if there is a large number of items in the collection, especially if only a few items in the large collection are expected to be found.

Note  If you are using user-defined fields as part of a Find or Restrict clause, the user-defined fields must exist in the folder, otherwise the code will generate an error stating that the field is unknown. You can add a field to a folder by displaying the Field Chooser and clicking New.

expression    Required. An expression that returns an Items object.

Filter   Required String. A filter string expression to be applied. For details, see the Find method.

Remarks

This method cannot be used, and will cause an error, with the following properties:

Body Categories Children Class Companies CompanyLastFirstNoSpace CompanyLastFirstSpaceOnly ContactNames Contacts ConversationIndex DLName Email1EntryID Email2EntryID Email3EntryID EntryID HTMLBody IsOnlineMeeting LastFirstAndSuffix LastFirstNoSpace

LastFirstNoSpaceCompany LastFirstSpaceOnly LastFirstSpaceOnlyCompany MemberCount NetMeetingAlias NetMeetingAutoStart NetMeetingOrganizerAlias NetMeetingServer NetMeetingType RecurrenceState ReplyRecipients ReceivedByEntryID RecevedOnBehalfOfEntryID ResponseState Saved Sent Submitted VotingOptions

Example

This Visual Basic for Applications example uses the Restrict method to get all Inbox items dealing with Project X and moves them to the Project X folder.

Set myOlApp = CreateObject("Outlook.Application")
Set myNameSpace = myOlApp.GetNameSpace("MAPI")
Set myFolder =  _
    myNameSpace.GetDefaultFolder(olFolderInbox)
Set myItems = myFolder.Items
Set myRestrictItems = myItems.Restrict _     ("[Categories] = 'Project X'")
For Each myItem In myRestrictItems
    myItem.Move myFolder.Folders("Project X")
Next

If you use VBScript, you do not create the Application object, and you cannot use named constants. This example shows how to perform the same task using VBScript.

Set myNameSpace = Application.GetNameSpace("MAPI")
Set myFolder = myNameSpace.GetDefaultFolder(6)
Set myItems = myFolder.Items
Set myRestrictItems = myItems.Restrict _     ("[Categories] = 'Project X'")
For Each myItem In myRestrictItems
    myItem.Move myFolder.Folders("Project X")
Next

This Visual Basic for Applications example uses the Restrict method to apply a filter to the Contact items based on the item's LastModificationTime property.

Public Sub ContactDateCheck()
   Set myOlApp = CreateObject("Outlook.Application")
   Set myNameSpace = myOlApp.GetNamespace("MAPI")
   Set myContacts = myNameSpace.GetDefaultFolder(olFolderContacts).Items
   Set myItems = myContacts.Restrict("[LastModificationTime] > '05/15/97'")
   For Each myItem In myItems
       MsgBox myItem.FullName & ": " & MyItem.LastModificationTime
   Next
End Sub

The following Visual Basic for Applications example is the same as the example above, except that it demonstrates the use of a variable in the filter.

Public Sub ContactDateCheck()
   Set myOlApp = CreateObject("Outlook.Application")
   Set myNameSpace = myOlApp.GetNamespace("MAPI")
   Set myContacts = myNameSpace.GetDefaultFolder(olFolderContacts).Items
   DateStart = #6/11/97#
   DateToCheck$ = "[LastModificationTime] >= """ & DateStart & """"
   Set myRestrictItems = myContacts.Restrict(DateToCheck$)
   For Each myItem In myRestrictItems
      MsgBox myItem.FullName & ": " & MyItem.LastModificationTime
   Next
End Sub