IPOutlookItemCollection::Restrict

Article
08/28/2006

The Restrict method creates a new Items collection that contains only items that pass a specified restriction.

Syntax

HRESULT Restrict(
  BSTR pwszRestriction,
  IPOutlookItemCollection ** ppolItems
);

Parameters

pwszRestriction
[in] Reference to a null-terminated Unicode string that defines which items to include in the new collection. This must contain a Boolean expression that evaluates to TRUE or FALSE for any item. Enclose property names between brackets. You can combine with AND and OR. Comparison operators are the following: <, <=, >, >=, = or <>.

For example, the restriction string [CompanyName] = "Microsoft" gets a collection of items with Microsoft as the company.
ppolItems
[out] Pointer that points to the new collection of items. This is set to NULL if no item passes the restriction.

Return Values

This method returns the standard values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and E_FAIL, as well as the following:

S_OK
If no item matches the restriction, the return value is S_OK and polItem is set to NULL.

Remarks

A restriction match requires that the item include a value for the property. For example, if you do not set the e-mail address for a contact, the contact cannot be found by using the restriction string [Email1Address]<>someone@example.com, even though "no address" is a logical match for "not someone@example.com."

Parenthesizeing a restrict query has the effect of causing the query to be evaluated from right-to-left, as opposed to left-to-right. For example, the two queries below yield different results. The only difference is the usage of parenthesis.

Query 1: [Categories] = "Health" AND [SourceId]] = 16 OR [Subject] = "Water"

Query 2: ( ( [Categories] = "Health" AND [SourceId]] = 16) OR [Subject] = "Water" )

Code Example

The following code example restricts contacts to those with the company name Microsoft.

Note To make the following code example easier to read, security checking and error handling are not included. This code example should not be used in a release configuration unless it has been modified to include them.

void RestrictContacts(IPOutlookApp * polApp)
{
    IFolder * pFolder;
    IPOutlookItemCollection * pItems;
    IPOutlookItemCollection * pItemsRestrict;

    // Get the Contacts folder.
    polApp->GetDefaultFolder(olFolderContacts, &pFolder);

    // Get the Contacts Items collection.
    pFolder->get_Items(&pItems);

    // Restrict the collection to Contacts with Company Name Sset to Microsoft.
    pItems->Restrict(TEXT("[CompanyName] = \"Microsoft\""), &pItemsRestrict);

    // Release objects.
    pItemsRestrict->Release();
    pItems->Release();
    pFolder->Release();
}

Requirements

Pocket PC: Pocket PC 2000 and later
Smartphone: Smartphone 2002 and later
OS Versions: Windows CE 3.0 and later
Header: pimstore.h
Library: pimstore.lib