IPOutlookItemCollection::Find

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

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

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

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.

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

See Also

Tasks

Finding a PIM Item Within a Collection

Reference

IPOutlookItemCollection::FindNext
IPOutlookItemCollection
Pocket Outlook Object Model Interfaces