IPOutlookItemCollection::Find

Article
08/28/2006

The Find method finds the first POOM item in a collection that passes 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.
ppolItem
[out] Reference to the item found by the method. 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
The method completed successfully.

Remarks

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.

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.

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

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 Contacts Items collection.
    pFolder->get_Items(&polItems);

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

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

    // Release objects.
    pFolder->Release();
    polItems->Release();
    pContact->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