IPOutlookItemCollection::Find

8/28/2008

The Find method finds the first POOM item in a collection that satisfies the specified restriction.

Syntax


HRESULT Find (
   BSTR pwszRestriction,
   IDispatch ** ppolItem
);

Parameters

pwszRestriction

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

For example, the restriction string [CompanyName] = "Microsoft" gets the first item that has Microsoft as the company. For information on the BSTR type, see BSTR.

ppolItem: [out] Reference to the item found by the method. Set to NULL if no item passes the restriction. For information about IDispatch, see IDispatch.

Return Value

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

S_OK: The method completed successfully.

Remarks

For All Platforms

Queries must be formatted properly.

String values must be enclosed between quotes. For example, [CompanyName] = "Microsoft".
int/long/enum values must not be enclosed between quotes. For example, [Importance] = 1.
date/time values must be in 24 hr format. For example, [End] = "05/10/1961 20:30".

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

Use IPOutlookItemCollection::FindNext to find subsequent items in a collection that pass the restriction.

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

You can create complex queries. For example:

"[Categories] = \"Business\" AND [Categories] <> \"Personal\""

You can create locale specific date queries. For example:

GetTimeFormat(LOCALE_USER_DEFAULT, TIME_NOSECONDS, &stForLocale, NULL, szLocaleSpecificStartTime, TEMP_BUFFER);

GetDateFormat(LOCALE_USER_DEFAULT, DATE_SHORTDATE, &stForLocale, NULL, szLocaleSpecificStartDate, TEMP_BUFFER);

StringCchPrintf(szRestrict, ARRAYSIZE(szRestrict), L"[Start] >= \"%s %s\" ", szLocaleSpecificStartDate, szLocaleSpecificStartTime);

hr = pItems->Restrict(szRestrict, &pItems2);

For Windows Embedded CE

IPOutlookItemCollection::Find does not support restrictions based on the following item properties: ReminderTime, Recipients, and CEVT_BLOB, CEVT_PIM_STREAM (Pictures and BinaryBody properties).

For Windows Mobile

IPOutlookItemCollection::Find does not support restrictions based on the following item properties: ReminderTime, Recipients, CEVT_BLOB, CEVT_PIM_STREAM (Pictures and BinaryBody properties), and Recurring Property ID's.

Code Example

The following code example shows how to set a specified Contact's information.

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 SetContactInfo(IPOutlookApp * polApp)
{
    IFolder                 * pFolder;
    IPOutlookItemCollection * polItems;
    IContact                * pContact;

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

    // Get the Contact Items collection.
    pFolder->get_Items(&polItems);

    // Find a Contact by LastName.
    polItems->Find(TEXT("[LastName] = \"Doe\""), (IDispatch**)&pContact);

    // Set the company name to Microsoft.
    pContact->put_CompanyName(TEXT("Microsoft"));

    // Release resources.
    pFolder->Release();
    polItems->Release();
    pContact->Release();
}

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

Tasks

Finding a PIM Item Within a Collection

Reference

IPOutlookItemCollection::FindNext
IPOutlookItemCollection
Pocket Outlook Object Model Interfaces