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