IPOutlookItemCollection::Restrict

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

The Restrict method creates a new IPOutlookItemCollection that contains only those items that meet a specified restriction.

Syntax

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

Parameters

• pwszRestriction
  [in] Pointer to a BSTR, which is an array of wide characters (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. For information on the BSTR type, see BSTR.

• ppolItems
  [out] Pointer to the new IPOutlookItemCollection of items. This is set to NULL if no item passes the restriction.

Return Value

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

Parenthesizing 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" )

When specifying a date in your restriction query, you have the option of using the C-style ULONG number format. You can do this by prefixing the date with the Less-than symbol (<). You can also specify the number of decimal places by using the decimal mark (.) symbol. For example, the following code example uses the StringCchPrintf function to format a ULONG date value, and populate the pwszRestriction input parameter to IPOutlookItemCollection::Restrict.

ULONG lDate = (ULONG)CAL_MAXDATE;

WCHAR szRestrict[250];

StringCchPrintf(szRestrict, ARRAYSIZE(szRestrict), TEXT("[Start] >= <%lu.00"), lDate);

pItems->Restrict(szRestrict, &pItemsRestrict);

When specifying a BOOLEAN value in your restriction query, use TRUE and FALSE, or 1 and 0—do not use quotation marks (for example, "TRUE").

Example

The following code example creates a new Item collection consisting of Contact items with a Company Name of "Microsoft."

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);
}

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.

Requirements

Header	pimstore.h
Library	Pimstore.lib
Windows Embedded CE	Windows CE 2.0 and later
Windows Mobile	Windows Mobile Version 5.0 and later

See Also

Reference

Pocket Outlook Object Model Interfaces

Other Resources