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

See Also

Reference

Pocket Outlook Object Model Interfaces

Other Resources