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
• Search Matching
• LINQ
• Related Topics

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