Partager via

FindMatchingContact (Compact 7)

  • Article

3/12/2014

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. This includes Short Message Service (SMS).

    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 ID's.

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.

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

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;

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

    hr = FindMatchingContactExample2(pPoom, _T("4254440100"), FMCF_FINDPHONE, &bstrSenderName);
    SysFreeString(bstrSenderName);

    return;
}

Code Example

The following code example demonstrates how to use FindMatchingContact to 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. 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.

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.

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

Header

pimstore.h

Library

Pimstore.lib

See Also

Reference

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