iOS Guides | Samples

MonoTouch.Contacts Namespace

Provides classes that model a person's contact information.

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 CNContact.GetPredicateForContacts(string) method will match a substring ("Thom" will match "Thomas") but does not have knowledge of nicknames ("Tom" will not match "Thomas").

C# Example

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 CNContactStore.MutableCopy method can be used on a fetched CNContact to create a modifiable contact.

C# Example

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

Classes

TypeReason
CNAuthorizationStatusEnumerates the application's current authorization to access the CNContactStore.
CNContactRepresents a contact such as a person or business and holds their data, such as name, phone numbers, etc.
CNContactDisplayNameOrderEnumerates how contacts should be sorted for display.
CNContactFetchRequestHolds the parameters for a search request of the CNContactStore.
CNContactFormatterA custom formatter for CNContact objects.
CNContactFormatterStyleEnumerates whether or not a contact name should be spelled out phonetically.
CNContactKeyProvides string constants whose values are the names of the possibly-available keys for CNContact objects.
CNContactOptionsFlagging enumeration that specifies keys that can be checked with CNContact.IsKeyAvailable and CNContact.AreKeysAvailable.
CNContactPropertyA tuple of values for a contact property, including the contact, the property's key and value and, for labeled values, the identifier and label.
CNContactRelationDefines a relationship between two CNContact objects, as specified by a CNLabelContactRelationKey.
CNContactSortOrderEnumerates the manner in which contacts should be sorted.
CNContactStoreThe system's contact database.
CNContactStore+NotificationsContains contact store notifications.
CNContactStoreEnumerateContactsHandlerCompletion handler in calls to CNContactStore.EnumerateContacts.
CNContactStoreListContactsHandler
CNContactStoreRequestAccessHandlerCompletion handler for calls to CNContactStore.RequestAccess
CNContactsUserDefaultsHolds default values, such as CNContactUserDefaults.CountryCode, for CNContact objects.
CNContactTypeEnumerates whether a contact represents an individual or an organization.
CNContactVCardSerializationProvides vCard serialization for CNContact objects.
CNContainerAn object such as an Exchange or CalDAV account that contains zero or more CNContact objects.
CNContainer_PredicatesExtensionExtension methods for CNContainer.
CNContainerKeyProvides string constants whose values should be used as keys when referencing properties of CNContainer objects.
CNContainerTypeEnumerates known CNContainer types.
CNEntityTypeAn enumeration whose only value (CNEntityType.Contacts) is used by some methods in CNContactStore.
CNErrorCodeEnumerates kinds of error encountered while working with contacts.
CNErrorCodeExtensionsProvides an extension method for CNErrroCode that retrieves the domain of the error.
CNErrorUserInfoKeyProvides string constants whose values identify the form of an error.
CNGroupA group that contains CNContact objects.
CNGroup_PredicatesExtensionExtension methods for CNGroup.
CNGroupKeyProvides string constants whose values are the names of properties common to all CNGroup objects.
CNInstantMessageAddressDefines an address for an instant-message service.
CNInstantMessageAddressKeyProvides string constants whose values are the common properties of all instant-message providers.
CNInstantMessageAddressOptionEnumeration of values used by all instant-message services.
CNInstantMessageServiceKeyProvides string constants whose values are the names of common providers of instant messaging services.
CNInstantMessageServiceOptionEnumerates common providers of instant messaging.
CNLabelContactRelationKeyDefines string constants whose values define various interpersonal relationships.
CNLabeledValue<ValueType>An object that holds a value and the label for that value.
CNLabelKeyDefines string constants whose values define the names of various CNLabeledValue objects.
CNLabelPhoneNumberKeyDefines string constants whose values are labels for various types of phones.
CNMutableContactA CNContact that can be modified after creation.
CNMutableGroupA CNGroup whose values can change after initialization.
CNMutablePostalAddressA CNPostalAddress whose values can be modified after initialization.
CNPhoneNumberAn immutable phone number.
CNPostalAddressA mailing address for a contact.
CNPostalAddressFormatterFormats postal addresses in the manner appropriate to the addresses.
CNPostalAddressFormatterStyleEnumerates postal address formatter styles.
CNPostalAddressKeyDefines string contents whose values are the properties of CNPostalAddress objects.
CNPostalAddressKeyOptionEnumeration of properties of a CNPostalAddress.
CNPostalAddressKeyOptionExtensions
CNSaveRequestA request that performs a save operation for contacts.
CNSocialProfileA profile for a social network, such as Facebook or Twitter.
CNSocialProfileKeyProvides string constants whose values specify the properties of social services that are always fetched.
CNSocialProfileOptionEnumerates properties of social services that are always fetched.
CNSocialProfileServiceKeyProvides string constants naming known social networks.
CNSocialProfileServiceOptionEnumerates known social services.
ICNKeyDescriptorInterface representing the required methods (if any) of the protocol CNKeyDescriptor.