IOS系统通讯录的使用

第一次写东西，只想做一些对sdk做一些注释，帮助自己梳理一下知识点，如有不对之处，请帮忙指正，谢谢。

IOS提供了两个框架供通讯录使用：AddressBook.framework和AddressBookUI.framework，使用这两个框架可以在程序中访问并显示iPhone数据库中的联系人信息。

AddressBookUI.framework使用较为简单，暂不做介绍，后期有空补上（SDK5.0）。

ABAddressBook.h

（1）ABAddressBookRef ABAddressBookCreate(void);创建通讯录//获取本地通讯录数据库，相当于通讯录的一个引用，该对象非常重要，后面对通讯录的操作都离不开此对象。

（2）extern bool ABAddressBookSave(ABAddressBookRef addressBook, CFErrorRef* error);//保存修改后的通讯录，如增删改等操作。

（3）extern bool ABAddressBookHasUnsavedChanges(ABAddressBookRef addressBook);//判断当前通讯录实例是否有待保存项。

（4）extern bool ABAddressBookAddRecord(ABAddressBookRef addressBook, ABRecordRef record, CFErrorRef* error);//在通讯录中新增联系人

（5）extern bool ABAddressBookRemoveRecord(ABAddressBookRef addressBook, ABRecordRef record, CFErrorRef* error);//在通讯录中删除联系人

（6）extern CFStringRef ABAddressBookCopyLocalizedLabel(CFStringRef label);

（7）typedef void (*ABExternalChangeCallback)(ABAddressBookRef addressBook, CFDictionaryRef info, void *context);//通讯录外部修改后，回调函数的定义形式。

（8）extern void ABAddressBookRegisterExternalChangeCallback(ABAddressBookRef addressBook, ABExternalChangeCallback callback, void *context);//注册通讯录外部修改后的回调通知，并指定回调函数。注：注册的回调方法有个注意点，在程序运行时，如果进行修改通讯录操作，其注册的回调方法亦会触发，且每修改一条记录，都会触发一次，因此在程序运行时，建议取消注册，程序退到后台时，再重新注册

（9）extern void ABAddressBookUnregisterExternalChangeCallback(ABAddressBookRef addressBook, ABExternalChangeCallback callback, void *context);//取消通讯录外部修改后的回调通知。

（10）void ABAddressBookRevert(ABAddressBookRef addressBook);//还原系统通讯录。

ABAddressBookRef addressBookRef =ABAddressBookCreate();//创建通讯录实例
    
    CFArrayRef personsRef = ABAddressBookCopyArrayOfAllPeople(addressBookRef);//获取通讯录中全部联系人记录
    
    ABRecordRef personRef = NULL;
    
    if (CFArrayGetCount(personsRef) > 0) {
        
        personRef = CFArrayGetValueAtIndex(personsRef, 0);//获取通讯录中第一条记录
    }
    
    CFErrorRef err = NULL;
    
    bool success = ABAddressBookRemoveRecord(addressBookRef, personRef, &err);//从该通讯录中移除该记录
    //success = ABAddressBookAddRecord(addressBookRef, personRef, &err);//向该通讯录中新增某条记录
    if (success) {
        
        NSLog(@"删除/新增成功");
    }
    else {
        
        NSLog(@"删除/新增失败");
        CFShow(err);
    }
    
    bool hasUnsavedChanges = ABAddressBookHasUnsavedChanges(addressBookRef);//判断当前通讯录是否有做更改
    
    if (hasUnsavedChanges) {
        
        NSLog(@"有未保存项");
        
        CFErrorRef err = NULL;
        
        bool success = ABAddressBookSave(addressBookRef, &err);//保存通讯录中未保存项
        
        if (success) {
            
            NSLog(@"通讯录保存成功");
        }
        else {
            
            NSLog(@"通讯录保存失败");
            CFShow(err);
        }
    }
    else
        NSLog(@"通讯录未作修改");

ABRecord.h

（1）extern ABRecordID ABRecordGetRecordID(ABRecordRef record);//返回 ABRecordID ，代表了 记录在底层数据库中的ID号。具有唯一性。
（2）extern ABRecordType ABRecordGetRecordType(ABRecordRef record);//返回记录类型。可以是 kABPersonType 和 kABGroupType。

（3）extern CFTypeRef ABRecordCopyValue(ABRecordRef record, ABPropertyID property);//根据标签获取对应的属性值

（4）bool ABRecordSetValue(ABRecordRef record, ABPropertyID property, CFTypeRef value, CFErrorRef* error);//设置对应标签的属性值

（5）bool ABRecordRemoveValue(ABRecordRef record, ABPropertyID property, CFErrorRef* error);//移除对应的标签属性的值

（6）CFStringRef ABRecordCopyCompositeName(ABRecordRef record);//获取联系人的全名

ABRecordID recordID = ABRecordGetRecordID(personRef);//获取该记录的id号
    
    NSLog(@"%d",recordID);
    
    ABRecordType recordType = ABRecordGetRecordType(personRef);//获取该记录的类型,有kABPersonType,kABGroupType,kABSourceType三种
    
    NSLog(@"%d",recordType);
    
    CFTypeRef firstName = ABRecordCopyValue(personRef, kABPersonFirstNameProperty);//根据标签获取对应的属性值,以FirstName为例
    
    CFShow(firstName);
    
    success = ABRecordSetValue(personRef, kABPersonFirstNameProperty, (CFTypeRef)@"john", &err);//设置标签对应的属性值,以FirstName为例
    
    success = ABRecordRemoveValue(personRef, kABPersonFirstNameProperty, &err);//移除标签对应的属性值,以FirstName为例
    
    CFStringRef compositeName = ABRecordCopyCompositeName(personRef);//获取该联系人的全名

    CFShow(compositeName);

ABPerson.h

（1）extern ABRecordRef ABPersonCreate(void);//创建新的联系人。这样可以得到一个空记录，然后就可以向其中填充信息;

（2）extern ABRecordRef ABPersonCreateInSource(ABRecordRef source);

（3）extern ABRecordRef ABPersonCopySource(ABRecordRef person);

（4）extern CFArrayRef ABPersonCopyArrayOfAllLinkedPeople(ABRecordRef person);

（5）extern ABPropertyType ABPersonGetTypeOfProperty(ABPropertyID property);

（6）extern CFStringRef ABPersonCopyLocalizedPropertyName(ABPropertyID property);//根据应用设置的语言，可以国际化标签kABPersonNicknameProperty在中文环境下会得到“昵称”

（7）extern bool ABPersonSetImageData(ABRecordRef person, CFDataRef imageData, CFErrorRef* error);//设置联系人头像

（8）extern CFDataRef ABPersonCopyImageData(ABRecordRef person);//获取联系人头像，头像图片为原始图片

（9）extern CFDataRef ABPersonCopyImageDataWithFormat(ABRecordRef person, ABPersonImageFormat format);//获取联系人头像，format: kABPersonImageFormatThumbnail获取的头像图片为缩略图，kABPersonImageFormatOriginalSize获取的头像图片原始大小图片

（10）extern bool ABPersonHasImageData(ABRecordRef person);//判断该联系人是否有头像

（11）extern bool ABPersonRemoveImageData(ABRecordRef person, CFErrorRef* error);//移除该联系人的头像

（12）extern CFComparisonResult ABPersonComparePeopleByName(ABRecordRef person1, ABRecordRef person2, ABPersonSortOrdering ordering);

（13）extern CFIndex ABAddressBookGetPersonCount(ABAddressBookRef addressBook);//获取通讯录中的联系人总数

（14）extern ABRecordRef ABAddressBookGetPersonWithRecordID(ABAddressBookRef addressBook, ABRecordID recordID);//根据recordID，获取对应的联系人实例

（15）extern CFArrayRef ABAddressBookCopyArrayOfAllPeople(ABAddressBookRef addressBook);//获取通讯录中所有联系人

（16）extern CFArrayRef ABAddressBookCopyArrayOfAllPeopleInSource(ABAddressBookRef addressBook, ABRecordRef source)

（17）extern CFArrayRef ABAddressBookCopyArrayOfAllPeopleInSourceWithSortOrdering(ABAddressBookRef addressBook, ABRecordRef source, ABPersonSortOrdering sortOrdering)

（18）extern CFArrayRef ABAddressBookCopyPeopleWithName(ABAddressBookRef addressBook, CFStringRef name)//根据名字获取对应的联系人记录

（19）extern CFArrayRef ABPersonCreatePeopleInSourceWithVCardRepresentation(ABRecordRef source, CFDataRef vCardData)

（20）extern CFDataRef ABPersonCreateVCardRepresentationWithPeople(CFArrayRef people)

方法的话注释的都是已经用于项目上的，还有一些未注释的待后续继续调研。

在调研过程中，还有一个东西需要略微注意一下，便是kABWorkLabel，kABHomeLabel，kABOtherLabel这三个通用标签。对于单值的标签如姓，名等很容易获取，对于多值标签的话，则有些属性需要这三个标签进行配合，不知道sdk有什么用意，对于下面的一组标签，让我一开始走了歪路

// Phone numbers
extern const ABPropertyID kABPersonPhoneProperty;              // Generic phone number - kABMultiStringPropertyType
extern const CFStringRef kABPersonPhoneMobileLabel;//移动电话
extern const CFStringRef kABPersonPhoneIPhoneLabel __OSX_AVAILABLE_STARTING(__MAC_NA,__IPHONE_3_0);//iPhone电话
extern const CFStringRef kABPersonPhoneMainLabel;//主要电话
extern const CFStringRef kABPersonPhoneHomeFAXLabel;//家庭传真
extern const CFStringRef kABPersonPhoneWorkFAXLabel;//工作传真
extern const CFStringRef kABPersonPhoneOtherFAXLabel __OSX_AVAILABLE_STARTING(__MAC_NA,__IPHONE_5_0);//其他传真
extern const CFStringRef kABPersonPhonePagerLabel;//呼机

由于上面api上已经明确的写明了家庭传真，工作传真与其他传真，在对比系统通讯录时，发现这组标签中缺少工作电话，住宅电话和其他电话，让我不解了好一会儿（惭愧惭愧）。

其中电话号码、邮件、主页空间等是多值，分别对应着工作，住宅，其他标签。因此需要小小的注意下。

ABMultiValue.h

（1）extern ABPropertyType ABMultiValueGetPropertyType(ABMultiValueRef multiValue);//获取当前的多值对象是对应哪种类型，可以配合CFStringRef ABPersonCopyLocalizedPropertyName(ABPropertyID property);来显示类型

（2）extern CFIndex ABMultiValueGetCount(ABMultiValueRef multiValue);//获取当前多值里面含有value的总数

（3）extern CFTypeRef ABMultiValueCopyValueAtIndex(ABMultiValueRef multiValue, CFIndex index);//根据索引获取对应的value

（4）extern CFArrayRef ABMultiValueCopyArrayOfAllValues(ABMultiValueRef multiValue);//获取里面所有的value

（5）extern CFStringRef ABMultiValueCopyLabelAtIndex(ABMultiValueRef multiValue, CFIndex index);//根据索引获取其对应的标签，可以配合CFStringRef ABAddressBookCopyLocalizedLabel(CFStringRef label);来显示类型

（6）extern CFIndex ABMultiValueGetIndexForIdentifier(ABMultiValueRef multiValue, ABMultiValueIdentifier identifier);

（7）extern ABMultiValueIdentifier ABMultiValueGetIdentifierAtIndex(ABMultiValueRef multiValue, CFIndex index);

（8）extern CFIndex ABMultiValueGetFirstIndexOfValue(ABMultiValueRef multiValue, CFTypeRef value);

（9）extern ABMutableMultiValueRef ABMultiValueCreateMutable(ABPropertyType type);//根据type创建对应多值对象

（10）extern ABMutableMultiValueRef ABMultiValueCreateMutableCopy(ABMultiValueRef multiValue);

（11）extern bool ABMultiValueAddValueAndLabel(ABMutableMultiValueRef multiValue, CFTypeRef value, CFStringRef label, ABMultiValueIdentifier *outIdentifier);//在多值里面添加新的属性。

（12）extern bool ABMultiValueInsertValueAndLabelAtIndex(ABMutableMultiValueRef multiValue, CFTypeRef value, CFStringRef label, CFIndex index, ABMultiValueIdentifier *outIdentifier);

（13）extern bool ABMultiValueRemoveValueAndLabelAtIndex(ABMutableMultiValueRef multiValue, CFIndex index);//根据索引删除标签及value

（14）extern bool ABMultiValueReplaceValueAtIndex(ABMutableMultiValueRef multiValue, CFTypeRef value, CFIndex index);//根据索引替换对应的value

（15）extern bool ABMultiValueReplaceLabelAtIndex(ABMutableMultiValueRef multiValue, CFStringRef label, CFIndex index);//根据索引替换对应的标签

ABSource.h、ABGroup.h目前还未使用，待学习时补充