FindMatchingContact

4/8/2010

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. For more information, see IPOutlookApp.

• 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, which includes the following communication methods: •E-mail •Short Message Service (SMS) •Instant Messaging (IM)
  FMCF_FINDFILEAS	0x00000004	Search the File As property.

• ppContact
  [out] Reference to the most closely matching Contact item. For more information, see IItem.

• ppropid
  [out] Reference to the Property 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. For more information, see Contact Property IDs.

Return Value

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.

Code Example

The following code example demonstrates how to use FindMatchingContact to find the Contact item with the closest matching e-mail address (passing-in a dwFlags value of FMCF_FINDEMAIL), and to find the Contact item with the closest matching phone number (passing-in a dwFlags value of FMCF_FINDPHONE).

In FindMatchingContactExample2, FindMatchingContact returns results to pItem and propidFound. pItem is an IItem handle to the contact. propidFound returns the specific Property ID which matches the pszSenderAddress passed in. You can use IUnknown::QueryInterface on pItem because you only want one property. If you wanted more, you could use IItem::GetProps.

void FindMatchingContactExample1(IPOutlookApp2* pPoom)
{
    BSTR    bstrSenderName;
    HRESULT hr = E_FAIL;

    hr = FindMatchingContactExample2(pPoom, _T("someone@example.com"), FMCF_FINDEMAIL, &bstrSenderName);
    SysFreeString(bstrSenderName);

    hr = FindMatchingContactExample2(pPoom, _T("4254440100"), FMCF_FINDPHONE, &bstrSenderName);
    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;

    hr = FindMatchingContact(pPoom, pszSenderAddress, dwFlag, &pItem, &propidFound);
    hr = pItem->QueryInterface(IID_IContact, (LPVOID*)&pContact);
    hr = pContact->get_FirstName(pbstrSenderName);

    // Perform any additional processing here.

    pContact->Release();
    pItem->Release();

    return hr;
}

Requirements

See Also

Reference

Pocket Outlook Object Model Functions
CHOOSECONTACT Structure
ChooseContact
GetItemIndexFromOid
ChooseContact Property ID's