Contacts Namespace

Provides classes that model a person's contact information.

Classes

CNContact

Represents a contact such as a person or business and holds their data, such as name, phone numbers, etc.

CNContactFetchRequest

Holds the parameters for a search request of the CNContactStore.

CNContactFormatter

A custom formatter for CNContact objects.

CNContactKey

Provides string constants whose values are the names of the possibly-available keys for CNContact objects.

CNContactProperty

A tuple of values for a contact property, including the contact, the property's key and value and, for labeled values, the identifier and label.

CNContactRelation

Defines a relationship between two CNContact objects, as specified by a CNLabelContactRelationKey.

CNContactStore

The system's contact database.

CNContactStore.Notifications

Contains contact store notifications.

CNContactsUserDefaults

Holds default values, such as CountryCode, for CNContact objects.

CNContactVCardSerialization

Provides vCard serialization for CNContact objects.

CNContainer

An object such as an Exchange or CalDAV account that contains zero or more CNContact objects.

CNContainer_PredicatesExtension

Extension methods for CNContainer.

CNContainerKey

Provides string constants whose values should be used as keys when referencing properties of CNContainer objects.

CNErrorCodeExtensions

Extension methods for the Contacts.CNErrorCode enumeration.

CNErrorUserInfoKey

Provides string constants whose values identify the form of an error.

CNGroup

A group that contains CNContact objects.

CNGroup_PredicatesExtension

Extension methods for CNGroup.

CNGroupKey

Provides string constants whose values are the names of properties common to all CNGroup objects.

CNInstantMessageAddress

Defines an address for an instant-message service.

CNInstantMessageAddressKey

Provides string constants whose values are the common properties of all instant-message providers.

CNInstantMessageServiceKey

Provides string constants whose values are the names of common providers of instant messaging services.

CNLabelContactRelationKey

Defines string constants whose values define various interpersonal relationships.

CNLabeledValue<ValueType>

An object that holds a value and the label for that value.

CNLabelKey

Defines string constants whose values define the names of various CNLabeledValue<ValueType> objects.

CNLabelPhoneNumberKey

Defines string constants whose values are labels for various types of phones.

CNMutableContact

A CNContact that can be modified after creation.

CNMutableGroup

A CNGroup whose values can change after initialization.

CNMutablePostalAddress

A CNPostalAddress whose values can be modified after initialization.

CNPhoneNumber

An immutable phone number.

CNPostalAddress

A mailing address for a contact.

CNPostalAddressFormatter

Formats postal addresses in the manner appropriate to the addresses.

CNPostalAddressKey

Defines string contents whose values are the properties of CNPostalAddress objects.

CNPostalAddressKeyOptionExtensions
CNSaveRequest

A request that performs a save operation for contacts.

CNSocialProfile

A profile for a social network, such as Facebook or Twitter.

CNSocialProfileKey

Provides string constants whose values specify the properties of social services that are always fetched.

CNSocialProfileServiceKey

Provides string constants naming known social networks.

Interfaces

ICNKeyDescriptor

Interface representing the required methods (if any) of the protocol ICNKeyDescriptor.

Enums

CNAuthorizationStatus

Enumerates the application's current authorization to access the CNContactStore.

CNContactDisplayNameOrder

Enumerates how contacts should be sorted for display.

CNContactFormatterStyle

Enumerates whether or not a contact name should be spelled out phonetically.

CNContactOptions

Flagging enumeration that specifies keys that can be checked with IsKeyAvailable(NSString) and AreKeysAvailable<T>(T[]).

CNContactSortOrder

Enumerates the manner in which contacts should be sorted.

CNContactType

Enumerates whether a contact represents an individual or an organization.

CNContainerType

Enumerates known CNContainer types.

CNEntityType

An enumeration whose only value (Contacts) is used by some methods in CNContactStore.

CNErrorCode

Enumerates kinds of error encountered while working with contacts.

CNInstantMessageAddressOption

Enumeration of values used by all instant-message services.

CNInstantMessageServiceOption

Enumerates common providers of instant messaging.

CNPostalAddressFormatterStyle

Enumerates postal address formatter styles.

CNPostalAddressKeyOption

Enumeration of properties of a CNPostalAddress.

CNSocialProfileOption

Enumerates properties of social services that are always fetched.

CNSocialProfileServiceOption

Enumerates known social services.

Delegates

CNContactStoreEnumerateContactsHandler

Completion handler in calls to EnumerateContacts(CNContactFetchRequest, NSError, CNContactStoreListContactsHandler).

CNContactStoreListContactsHandler
CNContactStoreRequestAccessHandler

Completion handler for calls to RequestAccess(CNEntityType, CNContactStoreRequestAccessHandler)

Remarks

The Contacts namespace provides classes that model the contact information of people. Since contact data is rarely updated, the namespace is optimized for thread-safe, primarily read-only performance. Because the underlying library is highly optimized, incorrect use (such as attempting to manipulate a field for which the data has not been retrieved) may lead to a crash rather than an exception.

A CNContact object has a large number of fields. Rather than entirely populate all these fields when retrieiving a CNContact object, the developer creates an array of CNContactKey objects for the fields are of interest.

The most common way to retrieve Contacts datastore is done by using a NSPredicate that specifies a string to be matched against the contact's given or family name. The predicate generated by the M:Contacts.CNContact.GetPredicateForContacts(string) method will match a substring ("Thom" will match "Thomas") but does not have knowledge of nicknames ("Tom" will not match "Thomas").

public IEnumerable<CNContact> ContactBirthdaysForName(string givenOrFamilyName)
{
    var fetchKeys = new [] { CNContactKey.GivenName, CNContactKey.FamilyName, CNContactKey.Birthday };
    NSError error;
    using (var predicate = CNContact.GetPredicateForContacts(givenOrFamilyName)) 
    {
        using (var store = new CNContactStore())
        {
            var contacts = store.GetUnifiedContacts(predicate, fetchKeys, out error);
            if (error == null)
            {
                foreach (var contact in contacts)
                {
                    yield return contact;
                }
            } 
            else
            {
                throw new Exception(error.ToString());    
            }
        }
    }
}

Developers should ensure that they have specified the needed CNContactKeykeys before manipulating data. As discussed previously, the Contacts runtime functionality is optimized and is more likely to crash than to throw a diagnostic exception.

CNContact objects are immutable. Developers who wish to modify and store contact data must use CNMutableContact objects.

The M:Contacts.CNContactStore.MutableCopy* method can be used on a fetched T:Contact.CNContact to create a modifiable contact.

//contact fetched as per previous example
var mutableContact = contact.MutableCopy() as CNMutableContact;
var homeEmail = new CNLabeledValue<NSString>(CNLabelKey.Home, (NSString)"john@appleseed.com");
var emailList = new List<CNLabeledValue<NSString>>(mutableContact.EmailAddresses);
emailList.Add(homeEmail);
mutableContact.EmailAddresses = emailList.ToArray();

var saveRequest = new CNSaveRequest();
saveRequest.UpdateContact(mutableContact);
using(var store = new CNContactStore())
{
    NSError error = null;
    store.ExecuteSaveRequest(saveRequest, out error);
    if(error == null)
    {
//...etc...