Contact filtering and matching for Windows Phone 8

[ This article is for Windows Phone 8 developers. If you’re developing for Windows 10, see the latest documentation. ]

You can search for contact data in your applications that target Windows Phone OS 7.1 by using the built-in search filters. You can search for all contacts or for the contacts pinned to the Start screen, or you can search by name, phone number, or email address.

This topic discusses read-only access to user’s contact data. For information on creating a custom contact store for your app that provides read and write access, see Custom contact store for Windows Phone 8.

This topic contains the following sections.

Search Filters

The general process for accessing contact data is to get a reference to the Contacts object, perform an asynchronous search on it by calling the SearchAsync method, and then capture the results as a collection of Contact objects in the SearchCompleted event handler. For more information, see How to access contact data for Windows Phone 8.

The following table shows the different filters and samples of the kinds of searches that you can perform using them.

Filter kind

Sample search

Description

None

SearchAsync(String.Empty, FilterKind.None, "State String 1")

Searches for all contacts.

PinnedToStart

SearchAsync(String.Empty, FilterKind.PinnedToStart, "State String 2")

Searches for all contacts that are pinned to the Start screen.

DisplayName

SearchAsync("A", FilterKind.DisplayName, "State String 3")

Searches by the display name.

EmailAddress

SearchAsync("Chris@example.com", FilterKind.EmailAddress, "State String 4")

Searches by email address.

PhoneNumber

SearchAsync("555-0004", FilterKind.PhoneNumber, "State String 5")

Searches by phone number.

Search Matching

There are built-in search filters that allow you to search for contacts by name, phone number, or email address. These searches are indexed to be fast against the underlying database. You can also search for all contacts and then use LINQ to query the result collection, but that is slower than using the built-in searches.

Matching by Name

Names are matched by the prefix substring of the first, middle, and last names. The following table shows some examples.

Filter String

Name

Match?

Har

Harry Miller

Yes

Har

Phyllis Harris

Yes

Har

Jón Harry Óskarsson

Yes

har

Charlotte Weiss

No

har

Dave Natsuhara

No

Matching by Phone Number

Phone numbers are matched by exact and smart matching. Differences such as area codes and international dialing codes are ignored. The last six digits of the numbers must match. All punctuation is ignored. The following table shows some examples.

Filter string

Phone number

Match?

4255551212

(425) 555-1212

Yes

2065551212

(425) 555-1212

Yes

5551212

(425) 555-1212

Yes

425555

(425) 555-1212

No

Matching by Email Address

Email addresses are matched by exact and smart matching. The name portion before the @ symbol must match exactly. The following table shows some examples.

Filter string

Email address

Match?

john@cohowinery.com

john@cohowinery.com

Yes

jon@cohowinery.com

john@cohowinery.com

No

john@exchange.cohowinery.com

john@cohowinery.com

Yes

john@exchange.com

john@cohowinery.com

No

john@com

john@cohowinery.com

Yes (false match)

john@cohowinery

john@cohowinery.com

No

john@coho.com

john@cohowinery.com

Yes (false match)

LINQ

You can search for all contacts and then use LINQ to query the result collection, but that is slower than using the built-in searches. If possible, you should use the built-in search filters that allow you to search for contacts by name, phone number, or email address. For examples of using LINQ with contact and appointment data, see How to access contact data for Windows Phone 8 and How to access calendar data for Windows Phone 8.

See Also

Reference

Microsoft.Phone.UserData

Other Resources

Walkthrough: Accessing contact and calendar data for Windows Phone 8

Code Samples for Windows Phone