iOS开发之-AddressBook Guide

官方文档 Address Book Programming Guide

Introduction 

1. The technology has several parts:

  • The Address Book framework provides access to the contact information.
  • The Address Book UI framework provides the user interface to display the information.
  • The Address Book database stores the information.
  • The Contacts application provides a way for users to access their contact information.

Records and Properties

1. Address Books

(1) To use an address book, declare an instance of  ABAddressBookRef and set it to the value returned from the function ABAddressBook. You can create multiple address book objects, but they are all backed by the same shared database.

ABAddressBookRef addressBook;
bool wantToSaveChanges = YES;
bool didSave;
CFErrorRef error = NULL;
 
addressBook = ABAddressBookCreate();
 
/* ... Work with the address book. ... */
 
if (ABAddressBookHasUnsavedChanges(addressBook)) {
    if (wantToSaveChanges) {
        didSave = ABAddressBookSave(addressBook, &error);
        if (!didSave) {/* Handle error here. */}
    } else {
        ABAddressBookRevert(addressBook);
    }
}
 
CFRelease(addressBook);

(2) Your application can request to receive a notification when Address Book database changes. 

Use the function ABAddressBookRegisterExternalChangeCallback to register a function of the prototypeABExternalChangeCallback.You can also unregister the function using ABAddressBookUnregisterExternalChangeCallback.

 

2. Records


(1) In the Address Book database, information is stored in records, represented byABRecordRef objects. Each record represents a person or group. The functionABRecordGetRecordType returns kABPersonType if the record is a person, and kABGroupType if it is a group. 

ABRecordRef person = ABPersonCreate();
ABRecordCopyValue
ABRecordSetValue
ABRecordRemoveValue

(2) Person records are made up of both single-value and multi-value properties.

(3) Single Value Property

ABRecordRef aRecord = ABPersonCreate();
CFErrorRef anError = NULL;
bool didSet;
 
didSet = ABRecordSetValue(aRecord, kABPersonFirstNameProperty, CFSTR("Katie"), &anError);
if (!didSet) {/* Handle error here. */}
 
didSet = ABRecordSetValue(aRecord, kABPersonLastNameProperty, CFSTR("Bell"), &anError);
if (!didSet) {/* Handle error here. */}
 
CFStringRef firstName, lastName;
firstName = ABRecordCopyValue(aRecord, kABPersonFirstNameProperty);
lastName  = ABRecordCopyValue(aRecord, kABPersonLastNameProperty);
 
/* ... Do something with firstName and lastName. ... */
 
CFRelease(aRecord);
CFRelease(firstName);
CFRelease(lastName);

(4) Multi Value Property

ABMutableMultiValueRef multi =
        ABMultiValueCreateMutable(kABMultiStringPropertyType);
CFErrorRef anError = NULL;
ABMultiValueIdentifier multivalueIdentifier;
bool didAdd, didSet;
 
// Here, multivalueIdentifier is just for illustration purposes; it isn't
// used later in the listing.  Real-world code can use this identifier to
// reference the newly-added value.
didAdd = ABMultiValueAddValueAndLabel(multi, @"(555) 555-1234",
                      kABPersonPhoneMobileLabel, &multivalueIdentifier);
if (!didAdd) {/* Handle error here. */}
 
didAdd = ABMultiValueAddValueAndLabel(multi, @"(555) 555-2345",
                      kABPersonPhoneMainLabel, &multivalueIdentifier);
if (!didAdd) {/* Handle error here. */}
 
ABRecordRef aRecord = ABPersonCreate();
didSet = ABRecordSetValue(aRecord, kABPersonPhoneProperty, multi, &anError);
if (!didSet) {/* Handle error here. */}
CFRelease(multi);
 
/* ... */
 
CFStringRef phoneNumber, phoneNumberLabel;
multi = ABRecordCopyValue(aRecord, kABPersonPhoneProperty);
 
for (CFIndex i = 0; i < ABMultiValueGetCount(multi); i++) {
    phoneNumberLabel = ABMultiValueCopyLabelAtIndex(multi, i);
    phoneNumber      = ABMultiValueCopyValueAtIndex(multi, i);
 
    /* ... Do something with phoneNumberLabel and phoneNumber. ... */
 
    CFRelease(phoneNumberLabel);
    CFRelease(phoneNumber);
}
 
CFRelease(aRecord);
CFRelease(multi);

Multi value properties consist of a list of values. Each value has a text label and an identifier associated with it. There can be more than one value with the same label, but the identifier is always unique. 

The individual values of a multivalue property are referred to by identifier or by index, depending on the context. Use the functionsABMultiValueGetIndexForIdentifier and ABMultiValueGetIdentifierAtIndex to convert between indices and multivalue identifiers.

The index will change if values are added or removed. The identifier is guaranteed not to change except across devices.

Multivalue objects are immutable; to change one you need to make a mutable copy using the functionABMultiValueCreateMutableCopy. You can also create a new mutable multivalue object using the functionABMultiValueCreateMutable.

The following functions let you modify mutable multivalue properties:


User Interface


(1)  The Address Book UI framework provides three view controllers and one navigation controller for common tasks related to working with the Address Book database and contact information. 

  • ABPeoplePickerNavigationController prompts the user to select a person record from their address book.
  • ABPersonViewController displays a person record to the user and optionally allows editing.
  • ABNewPersonViewController prompts the user create a new person record.
  • ABUnknownPersonViewController prompts the user to complete a partial person record, optionally allows them to add it to the address book.
(2) ABPeoplePickerNavigationController

ABPeoplePickerNavigationController *picker =
        [[ABPeoplePickerNavigationController alloc] init];
picker.peoplePickerDelegate = self;
[self presentModalViewController:picker animated:YES];
[picker release];

Optionally, set displayedProperties to the array of properties you want displayed. The relevant constants are defined as integers; wrap them in anNSNumber object using the numberWithInt: method to get an object that can be put in an array.


ABPeoplePickerNavigationControllerDelegate


(3) ABPersonViewController


ABPersonViewController *view = [[ABPersonViewController alloc] init];
 
view.personViewDelegate = self;
view.displayedPerson = person; // Assume person is already defined.
 
[self.navigationController pushViewController:view animated:YES];
[view release];


If the user taps on a property in the view, the person view controller calls thepersonViewController:shouldPerformDefaultActionForPerson:property:identifier: method of the delegate to determine if the default action for that property should be taken. To perform the default action for the selected property, such as dialing a phone number or composing a new email, returnYES; otherwise returnNO.


(4) ABNewPersonViewController

ABNewPersonViewController *view = [[ABNewPersonViewController alloc] init];
view.newPersonViewDelegate = self;
 
UINavigationController *newNavigationController = [[UINavigationController alloc]
                                                  initWithRootViewController:view];
[self presentModalViewController:newNavigationController
                        animated:YES];
 
[view release];
[newNavigationController release];

When the user taps the Save or Cancel button, the new-person view controller calls the methodnewPersonViewController:didCompleteWithNewPerson: of the delegate, with the resulting person record. If the user saved, the new record is first added to the address book. If the user cancelled, the value ofperson isNULL. The delegate must dismiss the new-person view controller using the navigation controller’sdismissModalViewControllerAnimated: method. 


(5) ABUnknownPersonViewController

ABUnknownPersonViewController *view = [[ABUnknownPersonViewController alloc] init];
 
view.unknownPersonViewDelegate = self;
view.displayedPerson = person; // Assume person is already defined.
view.allowsAddingToAddressBook = YES;
 
[self.navigationController pushViewController:view animated:YES];
[view release];


When the user finishes creating a new contact or adding the properties to an existing contact, the unknown-person view controller calls the methodunknownPersonViewController:didResolveToPerson: of the delegate with the resulting person record. If the user canceled, the value ofperson isNULL.


Programmatically Accessing the Database


1. Record

To get the record identifier of a record, use the functionABRecordGetRecordID. To find a person record by identifier, use the functionABAddressBookGetPersonWithRecordID. To find a group by identifier, use the functionABAddressBookGetGroupWithRecordID. To find a person record by name, use the functionABAddressBookCopyPeopleWithName.


2. Working with person records


You can add and remove records from the Address Book database using the functionsABAddressBookAddRecord and ABAddressBookRemoveRecord.

ABAddressBookRef addressBook = ABAddressBookCreate();
CFArrayRef people = ABAddressBookCopyArrayOfAllPeople(addressBook);
CFMutableArrayRef peopleMutable = CFArrayCreateMutableCopy(
                                          kCFAllocatorDefault,
                                          CFArrayGetCount(people),
                                          people
                                  );
 
 
CFArraySortValues(
        peopleMutable,
        CFRangeMake(0, CFArrayGetCount(peopleMutable)),
        (CFComparatorFunction) ABPersonComparePeopleByName,
        (void*) ABPersonGetSortOrdering()
);
 
CFRelease(addressBook);
CFRelease(people);
CFRelease(peopleMutable);




                
评论 2
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值