Export (0) Print
Expand All
Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

IPOutlookItemCollection::Restrict

Windows Mobile 6.5
A version of this page is also available for
4/8/2010

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


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

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.

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.

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

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.

Headerpimstore.h
LibraryPimstore.lib
Windows Embedded CEWindows CE 2.0 and later
Windows MobileWindows Mobile Version 5.0 and later

Community Additions

Show:
© 2015 Microsoft