IPOutlookItemCollection::Find
A version of this page is also available for
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.
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 |
See Also
Tasks
Finding a PIM Item Within a Collection
Reference
IPOutlookItemCollection::FindNext
IPOutlookItemCollection
Pocket Outlook Object Model Interfaces