FindMatchingContact

Article
08/28/2006

The FindMatchingContact function returns the Contact item with a property value that most closely matches a search string.

Syntax

HRESULT FindMatchingContact(
  IPOutlookApp * pPOOM,
  LPCWSTR pszFind,
  DWORD dwFlags,
  IItem ** ppContact,
  CEPROPID * ppropid
);

Parameters

pPOOM
[in] Reference to the Outlook Mobile Application Object.
pszFind
[in] The search string.

dwFlags
[in] Bitmask of flags that indicates which Contact properties to search. The following table shows the values the parameter can take.

Option	Value	Description
FMCF_FINDPHONE	0x00000001	Search the phone properties.
FMCF_FINDEMAIL	0x00000002	Search the messaging properties. This includes Short Message Service (SMS).
FMCF_FINDFILEAS	0x00000004	Search the File As property.

ppContact
[out] Reference to the most closely matching Contact item.
ppropid
[out] Reference to the ID of the property value that contained the match. For example, if you are searching on E-mail, ppropid might return PIMPR_EMAIL2_EMAIL_ADDRESS.

Return Values

This method returns the standard values HRESULT_FROM_WIN32(GetLastError()), E_INVALIDARG, and S_FAIL, as well as the following:

S_OK
The method completed successfully.

Remarks

The returned Contact item is of the generic type IItem.

The FindMatchingContact method returns a single Contact only, even if there are multiple matches; and only a single property ID, even if there are multiple properties that match.

In the case of multiple matches that are not exact matches, Outlook Mobile chooses the Contact item with the property value that matches the search string the closest. For example, a search string of "johnd@dogfood.exchange.woodgrovebank.com" would match a Contact with an e-mail address of "John Doe <johnd@woodgrovebank.com>". If another Contact had an e-mail of "Jonathon Doe <johnd@exchange.woodgrovebank.com>", that Contact would be considered a closer match because more of the e-mail address is contained in the search string. However, a Contact with the e-mail address "johnd@dogfood.exchange.woodgrovebank.ca.com" would not match because the domain path does not match.

Note The example companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted herein are fictitious. No association with any real company, organization, product, domain name, email address, logo, person, places, or events is intended or should be inferred.

Code Example

The following code example demonstrates how to use FindMatchingContact.

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 FindMatchingContactExample1(IPOutlookApp2* pPoom)
{

    BSTR    bstrSenderName;
    HRESULT hr = E_FAIL;

    // Find the Contact item with the closest matching e-mail address.
    hr = FindMatchingContactExample2(pPoom, _T("someone@example.com"), FMCF_FINDEMAIL, &bstrSenderName);

    // Free memory from the FindMatchingContact call.
    SysFreeString(bstrSenderName);

    // Find the Contact item with the closest matching phone number.
    hr = FindMatchingContactExample2(pPoom, _T("4254440100"), FMCF_FINDPHONE, &bstrSenderName);

    // Free memory from the FindMatchingContact call.
    SysFreeString(bstrSenderName);

    return;

}

HRESULT FindMatchingContactExample2(IPOutlookApp2* pPoom, LPTSTR pszSenderAddress, DWORD dwFlag, BSTR* pbstrSenderName)
{

    HRESULT  hr          = E_FAIL;
    IItem    *pItem      = NULL;
    IContact *pContact   = NULL;
    CEPROPID propidFound = 0;
 
    // Find the Contact item with a property value that most closely matches 
    // pszSenderAddress. The result is pItem, which is an IItem handle to the 
    // contact. The propidFound returns the specific CEPROPID which matched the 
    // pszSenderAddress passed in.
    hr = FindMatchingContact(pPoom, pszSenderAddress, dwFlag, &pItem, &propidFound);

    // Use QueryInterface on pItem because you only want one property.
    // You could use GetProps if you wanted more properties.
    hr = pItem->QueryInterface(IID_IContact, (LPVOID*)&pContact);
    hr = pContact->get_FirstName(pbstrSenderName);

    // Perform any additional processing here.

    // Free memory.
    pContact->Release();
    pItem->Release();

    return hr;

}

Requirements

Pocket PC: Windows Mobile Version 5.0 and later
Smartphone: Windows Mobile Version 5.0 and later
OS Versions: Windows CE 5.01 and later
Header: pimstore.h
Library: pimstore.lib