第一次写东西,只想做一些对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目前还未使用,待学习时补充