Click to Rate and Give Feedback

  Switch on low bandwidth view
IPOutlookItemCollection::Find
Windows Mobile SupportedWindows Embedded CE Supported
8/28/2008

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


HRESULT Find (
   BSTR pwszRestriction,
   IDispatch ** ppolItem
);
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.

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.

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, and CEVT_BLOB, CEVT_PIM_STREAM (Pictures and BinaryBody properties).

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.

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();
}
Headerpimstore.h
LibraryPimstore.lib
Windows Embedded CEWindows CE 2.0 and later
Windows MobileWindows Mobile Version 5.0 and later
Tags What's this?: Add a tag
Community Content   What is Community Content?
Add new content RSS  Annotations
Processing
© 2009 Microsoft Corporation. All rights reserved. Terms of Use  |  Trademarks  |  Privacy Statement
Page view tracker