AddressBook_iPhoneOS_Framework

Address Book Framework Reference for iOSContentsIntroduction5Opaque Types6ABAddressBook Reference7 Overview7Functions by Task7Functions8Callbacks17Data Types18Constants19ABMultiValue Reference22 Overview22Functions by Task22Functions23Data Types28Constants29ABMutableMultiValue Reference30 Overview30Functions by Task30Functions31Data Types36ABRecord Reference38Overview38Functions by Task38Functions39Data Types43Constants45Other References49ContentsABGroup Reference50 Overview50Functions by Task50Functions51Constants57ABPerson Reference59 Overview59Functions by Task59Functions61Data Types75Constants76ABSource Reference92 Overview92Functions92Data Types94Constants94Document Revision History97ListingsABAddressBook Reference7Listing1-‐1Sample implementation using ABAddressBookRequestAccessCompletionHandler18IntroductionFramework/System/Library/Frameworks/AddressBook.frameworkHeader file directories/System/Library/Frameworks/AddressBook.framework/HeadersDeclared in ABAddressBook.hABGroup.hABMultiValue.hABPerson.hABRecord.hABSource.hThe Address Book framework provides access to a centralized contacts database,called the Address Book database,that stores a user’s contacts.Applications such as Mail and Messages use this database to present information about known and unknown persons.Opaque TypesABAddressBook ReferenceDerived from CFTypeRefFramework AddressBook/AddressBook.hDeclared in ABAddressBook.hOverviewThe ABAddressBook opaque type(whose instances are known as address books)provides a programming interface to the Address Book—a centralized database used by multiple applications to store personal information about people.The Address Book database also supports the notion of a“group”containing one or more persons.People may belong to multiple groups,and groups may also belong to other groups.The ABAddressBook opaque type provides functions for creating references to the Address Book database, saving changes,discarding changes,and registering for changes made externally(by other threads or processes) to the database.Functions by TaskManaging Address BooksABAddressBookCreate (page 10)Creates a new address book object with data from the Address Book database.(e the ABAddressBookCreateWithOptions (page 10)function instead.) ABAddressBookCreateWithOptions (page 10)Creates a new address book object with data from the Address Book database. ABAddressBookGetAuthorizationStatus (page 11)Returns the authorization status of your app for accessing address book data. ABAddressBookRequestAccessWithCompletion (page 14)Requests access to address book data from the user.ABAddressBookHasUnsavedChanges (page 12)Indicates whether an address book has changes that have not been saved to the Address Book database. ABAddressBookSave (page 15)Saves any unsaved changes to the Address Book database.ABAddressBookRevert (page 15)Discards unsaved changes in an address book.Managing Address Book RecordsABAddressBookAddRecord (page 8)Adds a record to an address book.ABAddressBookRemoveRecord (page 13)Removes a record from an address book.Getting Address Book Change Notifications ABAddressBookRegisterExternalChangeCallback (page 12)Registers a callback to receive notifications when the Address Book database is modified. ABAddressBookUnregisterExternalChangeCallback (page 16)Unregisters a callback.Localizing TextABAddressBookCopyLocalizedLabel (page 9)Returns a localized version of a record-‐property label.FunctionsABAddressBookAddRecordAdds a record to an address book.bool ABAddressBookAddRecord(ABAddressBookRef addressBook,ABRecordRef record,CFErrorRef*error);ParametersaddressBookThe address book to which record is added.recordThe record to add to addressBook.errorOn error,contains error information.See“Address Book Errors” (page 21).Return Valuetrue when successful,false otherwise.AvailabilityAvailable in iOS2.0and later.Related Sample CodeABUIGroupsDeclared inABAddressBook.hABAddressBookCopyLocalizedLabelReturns a localized version of a record-property label.CFStringRef ABAddressBookCopyLocalizedLabel(CFStringRef label);ParameterslabelThe label to localize.Return ValueThe label localized to the user’s locale.AvailabilityAvailable in iOS2.0and later.Declared inABAddressBook.hABAddressBookCreateCreates a new address book object with data from the Address Book database.(Deprecated in e the ABAddressBookCreateWithOptions (page 10)function instead.)ABAddressBookRef ABAddressBookCreate(void);Return ValueAn address book object.DiscussionChanges made to the returned address book are reflected in the Address Book database only after saving the address book with ABAddressBookSave (page 15).Important: You must ensure that an instance of ABAddressBookRef is used by only one thread.AvailabilityAvailable in iOS2.0and later.Deprecated in iOS6.0.Declared inABAddressBook.hABAddressBookCreateWithOptionsCreates a new address book object with data from the Address Book database.ABAddressBookRef ABAddressBookCreateWithOptions(CFDictionaryRef options,CFErrorRef*error);ParametersoptionsReserved.Pass NULL.errorOn error,contains error information.See“Address Book Errors” (page 21).Return ValueAn address book object,NULL,or an empty database.DiscussionChanges made to the returned address book are reflected in the Address Book database only after saving the address book with ABAddressBookSave (page 15).On iOS6.0and later,if the caller does not have access to the Address Book database:●For apps linked against iOS6.0and later,this function returns NULL.●For apps linked against previous version of iOS,this function returns an empty read-‐only database.If your app syncs information with the database,it must not sync data when it does not have access to the database.Important: You must ensure that an instance of ABAddressBookRef is used by only one thread.AvailabilityAvailable in iOS6.0and later.Related Sample CodeABUIGroupsChecking and Requesting Access to Data Classes in Privacy SettingsQuickContactsDeclared inABAddressBook.hABAddressBookGetAuthorizationStatusReturns the authorization status of your app for accessing address book data.ABAuthorizationStatus ABAddressBookGetAuthorizationStatus(void);Return ValueThe authorization status for your app.AvailabilityAvailable in iOS6.0and later.Related Sample CodeABUIGroupsChecking and Requesting Access to Data Classes in Privacy SettingsQuickContactsDeclared inABAddressBook.hABAddressBookHasUnsavedChangesIndicates whether an address book has changes that have not been saved to the Address Book database.bool ABAddressBookHasUnsavedChanges(ABAddressBookRef addressBook);ParametersaddressBookThe address book in question.Return Valuetrue when addressBook contains unsaved changes,false otherwise.AvailabilityAvailable in iOS2.0and later.Declared inABAddressBook.hABAddressBookRegisterExternalChangeCallbackRegisters a callback to receive notifications when the Address Book database is modified.void ABAddressBookRegisterExternalChangeCallback(ABAddressBookRef addressBook,ABExternalChangeCallback callback,void*context);ParametersaddressBookThe address book used to interact with the Address Book database. callBackThe function to invoke when the Address Book database changes. contextThe object to pass to the callback function.AvailabilityAvailable in iOS2.0and later.See AlsoABExternalChangeCallback (page 17) ABAddressBookUnregisterExternalChangeCallback (page 16)Related Sample CodeChecking and Requesting Access to Data Classes in Privacy SettingsDeclared inABAddressBook.hABAddressBookRemoveRecordRemoves a record from an address book.bool ABAddressBookRemoveRecord(ABAddressBookRef addressBook,ABRecordRef record,CFErrorRef*error);ParametersaddressBookThe address book from which record is to be removed.recordThe record to remove from addressBook.errorOn error,contains error information.See“Address Book Errors” (page 21). Return Valuetrue when successful,false otherwise.AvailabilityAvailable in iOS2.0and later.Related Sample CodeABUIGroupsDeclared inABAddressBook.hABAddressBookRequestAccessWithCompletionRequests access to address book data from the user.void ABAddressBookRequestAccessWithCompletion(ABAddressBookRef addressBook,ABAddressBookRequestAccessCompletionHandler completion);ParametersaddressBookThe address book in question.completionThe completion handler,called once access has been granted or denied by the user.DiscussionUse this function to request access to address book data.This call will not block while the user is being asked for access,allowing your app to continue running.Until access has been granted,any address book references your app has will not contain any data,and any attempt to modify data will fail with an error type of kABOperationNotPermittedByUserError (page 21).The user is only asked for permission the first time you request ter calls use the permission granted by the user.The completion handler is called on an arbitrary queue.If your app uses an address book throughout the app, you are responsible for ensuring that all usage of that address book is dispatched to a single queue to ensure correct thread-‐safe operation.AvailabilityAvailable in iOS6.0and later.Related Sample CodeABUIGroupsChecking and Requesting Access to Data Classes in Privacy SettingsQuickContactsDeclared inABAddressBook.hABAddressBookRevertDiscards unsaved changes in an address book.void ABAddressBookRevert(ABAddressBookRef addressBook);ParametersaddressBookThe address book to revert.DiscussionThe address book is loaded with the information in the Address Book database.AvailabilityAvailable in iOS2.0and later.Declared inABAddressBook.hABAddressBookSaveSaves any unsaved changes to the Address Book database.bool ABAddressBookSave(ABAddressBookRef addressBook,CFErrorRef*error);ParametersaddressBookThe address book to save.errorOn error,contains error information.See“Address Book Errors” (page 21).Return Valuetrue when successful,false otherwise.AvailabilityAvailable in iOS2.0and later.Related Sample CodeABUIGroupsDeclared inABAddressBook.hABAddressBookUnregisterExternalChangeCallbackUnregisters a callback.void ABAddressBookUnregisterExternalChangeCallback(ABAddressBookRef addressBook,ABExternalChangeCallback callback,void*context);ParametersaddressBookThe address book used to interact with the Address Book database.callBackThe function to invoke when the Address Book database changes.The signature of the function must match ABExternalChangeCallback (page 17).contextThe object to pass to the callback function.AvailabilityAvailable in iOS2.0and later.See AlsoABExternalChangeCallback (page 17) ABAddressBookRegisterExternalChangeCallback (page 12)Related Sample CodeChecking and Requesting Access to Data Classes in Privacy SettingsDeclared inABAddressBook.hCallbacksABExternalChangeCallbackPrototype for a function callback invoked on an address book when the Address Book database is modified by another address book instance.typedef void(*ABExternalChangeCallback)(ABAddressBookRef addressBook,CFDictionaryRef info,void*context);If you name your callback function MyAddressBookExternalChangeCallback,you declare it like this:void MyAddressBookExternalChangeCallback(ABAddressBookRef addressBook,CFDictionaryRef info,void*context);ParametersaddressBookAn address book used to interact with the Address Book database.infoAlways NULL.contextThe object to pass to the callback function.DiscussionUse ABAddressBookRegisterExternalChangeCallback (page 12)to register and ABAddressBookUnregisterExternalChangeCallback (page 16)to unregister the callback function.You can register for a callback with different contexts or callback functions.The run loop on the thread that registered the callback invokes the callback.The addressBook object does not take any action to flush or synchronize cached state with the Address Book database.If you want to ensure that addressBook doesn’t contain stale values,use ABAddressBookRevert (page 15).AvailabilityAvailable in iOS2.0and later.Declared inABAddressBook.hData TypesABAddressBookRefReference to an object used to interact with the Address Book database.typedef CFTypeRef ABAddressBookRef;AvailabilityAvailable in iOS2.0and later.Declared inABAddressBook.hABAddressBookRequestAccessCompletionHandlerDefinition for a block callback invoked when an access request has completed.typedef void(^ABAddressBookRequestAccessCompletionHandler)(bool granted,CFErrorRef error);DiscussionAddress book request access completion handler blocks are used with ABAddressBookCreateWithOptions (page 10).If you had a view controller that wanted to display the count of users with the name“Smith”in the address book,you might implement something like the code shown in the following code listing.Listing1-1Sample implementation using ABAddressBookRequestAccessCompletionHandler@implementation APLViewController-(void)viewDidLoad{[super viewDidLoad];//Do any additional setup after loading the viewCFErrorRef myError=NULL;ABAddressBookRef myAddressBook=ABAddressBookCreateWithOptions(NULL,&myError);APLViewController*__weak weakSelf=self;//avoid capturing self in the blockABAddressBookRequestAccessWithCompletion(myAddressBook,^(bool granted,CFErrorRef error){if(granted){NSArray*theSmiths=CFBridgingRelease(ABAddressBookCopyPeopleWithName(myAddressBook,CFSTR("Smith")));weakSelf.numberOfSmiths=[theSmiths count];}else{//Handle the case of being denied access and/or the error.}CFRelease(myAddressBook);});}...@endAvailabilityAvailable in iOS6.0and later.Declared inABAddressBook.hConstantsAddress Book Error DomainError domain under which Address Book errors are grouped.const CFStringRef ABAddressBookErrorDomain;ConstantsABAddressBookErrorDomainThe main error domain for Address Book framework operations.Available in iOS2.0and later.Declared in ABAddressBook.h.ABAuthorizationStatusDifferent possible values for the authorization status of an app with respect to address book data.typedef CF_ENUM(CFIndex,ABAuthorizationStatus){kABAuthorizationStatusNotDetermined=0,kABAuthorizationStatusRestricted,kABAuthorizationStatusDenied,kABAuthorizationStatusAuthorized};ConstantskABAuthorizationStatusNotDeterminedNo authorization status could be determined.Available in iOS6.0and later.Declared in ABAddressBook.h.kABAuthorizationStatusRestrictedThe app is not authorized to access address book data.The user cannot change this access,possibly due to restrictions such as parental controls.Available in iOS6.0and later.Declared in ABAddressBook.h.kABAuthorizationStatusDeniedThe user explicitly denied access to address book data for this app.Available in iOS6.0and later.Declared in ABAddressBook.h.kABAuthorizationStatusAuthorizedThe app is authorized to access address book data.Available in iOS6.0and later.Declared in ABAddressBook.h.ABAddressBook ReferenceConstantsAddress Book ErrorsErrors that can be raised under the Address Book error domain.enum{kABOperationNotPermittedByStoreError=0,kABOperationNotPermittedByUserError};ConstantskABOperationNotPermittedByStoreErrorThe operation is not allowed by the Address Book database,because the contact’s source does not support it.Available in iOS2.0and later.Declared in ABAddressBook.h.kABOperationNotPermittedByUserErrorThe operation is not allowed because the user denied access to the Address Book database.Available in iOS6.0and later.Declared in ABAddressBook.h.ABMultiValue ReferenceDerived from CFTypeRefFramework AddressBook/AddressBook.hDeclared in ABMultiValue.hOverviewThe ABMultiValue opaque type(whose objects are known as multivalues)implements a property that can have multiple values.All the contained values must be of the same type.Each value has a unique identifier and a nonunique label,which may be one of the provided labels or one defined by the user.For example,if a multivalue property is used to store phone numbers,there may be multiple work phone numbers.These have the same label,but different unique identifiers.Multivalue properties are immutable.To use mutable multivalue properties,see ABMutableMultiValue Reference.Functions by TaskGetting Values and LabelsABMultiValueCopyValueAtIndex (page 24)Returns the value at a particular location within a multivalue property. ABMultiValueCopyArrayOfAllValues (page 23)Returns an array with the values in a multivalue property.ABMultiValueGetCount (page 25)Returns the number of values in a multivalue property. ABMultiValueGetFirstIndexOfValue (page 26)Returns the first location of a value in a multivalue property.ABMultiValueCopyLabelAtIndex (page 24)Returns the label for a value in a multivalue property.Getting Value IdentifiersABMultiValueGetIdentifierAtIndex (page 26)Returns the identifier of a value in a multivalue property. ABMultiValueGetIndexForIdentifier (page 27)Returns the location(within a multivalue property)of a value with a given identifier. Getting Property InformationABMultiValueGetPropertyType (page 27)Returns the type of the values contained in a multivalue property.FunctionsABMultiValueCopyArrayOfAllValuesReturns an array with the values in a multivalue property.CFArrayRef ABMultiValueCopyArrayOfAllValues(ABMultiValueRef multiValue);ParametersmultiValueThe multivalue property whose values are being return.Return ValueArray containing the values in multiValue.AvailabilityAvailable in iOS2.0and later.Declared inABMultiValue.hABMultiValueCopyLabelAtIndexReturns the label for a value in a multivalue property.CFStringRef ABMultiValueCopyLabelAtIndex(ABMultiValueRef multiValue,CFIndex index);ParametersmultiValueThe multivalue property with the value whose label to return.indexLocation of the value within multiValue whose label to return.Raises an exception when out of bounds.Return ValueLabel for the value at index within multiValue.DiscussionIf there is no label for the value at index,returns NULL.This function takes an index.If you have an identifier,use the ABMultiValueGetIndexForIdentifier (page 27)function to get the corresponding index.AvailabilityAvailable in iOS2.0and later.Declared inABMultiValue.hABMultiValueCopyValueAtIndexReturns the value at a particular location within a multivalue property.CFTypeRef ABMultiValueCopyValueAtIndex(ABMultiValueRef multiValue,CFIndex index);ParametersmultiValueThe multivalue property from which to obtain the value.indexLocation of the desired value within multiValue.Raises an exception when out of bounds.Return ValueThe value at index in multiValue.DiscussionThis function takes an index.If you have an identifier,use the ABMultiValueGetIndexForIdentifier (page 27)function to get the corresponding index.AvailabilityAvailable in iOS2.0and later.Declared inABMultiValue.hABMultiValueGetCountReturns the number of values in a multivalue property.CFIndex ABMultiValueGetCount(ABMultiValueRef multiValue);ParametersmultiValueThe multivalue property whose value are being counted.Return ValueThe number of values in multiValue.AvailabilityAvailable in iOS2.0and later.Declared inABMultiValue.hABMultiValueGetFirstIndexOfValueReturns the first location of a value in a multivalue property.CFIndex ABMultiValueGetFirstIndexOfValue(ABMultiValueRef multiValue,CFTypeRef value);ParametersmultiValueThe multivalue property in which to search for value.valueThe value to search for in multiValue.Return ValueLocation of value within multiValue,-1if value is not present in multiValue.AvailabilityAvailable in iOS2.0and later.Declared inABMultiValue.hABMultiValueGetIdentifierAtIndexReturns the identifier of a value in a multivalue property.ABMultiValueIdentifier ABMultiValueGetIdentifierAtIndex( ABMultiValueRef multiValue,CFIndex index);ParametersmultiValueThe multivalue property with the identifier to return.indexLocation of the value within multiValue whose identifier is being returned.Return ValueIdentifier of the value at index within multiValue.AvailabilityAvailable in iOS2.0and later.Declared inABMultiValue.hABMultiValueGetIndexForIdentifierReturns the location(within a multivalue property)of a value with a given identifier. CFIndex ABMultiValueGetIndexForIdentifier(ABMultiValueRef multiValue,ABMultiValueIdentifier identifier);ParametersmultiValueThe multivalue property in which to look for the identifier value identifier.identifierThe identifier of the value whose location within multiValue is being returned.Return ValueLocation within multiValue that contains the value with identifier as its identifier.AvailabilityAvailable in iOS2.0and later.Declared inABMultiValue.hABMultiValueGetPropertyTypeReturns the type of the values contained in a multivalue property.ABPropertyType ABMultiValueGetPropertyType(ABMultiValueRef multiValue);ParametersmultiValueThe multivalue property whose type is being returned.Return ValueThe type of the values contained in multiValue or kABInvalidPropertyType when multiValue is empty or contains values of different types.AvailabilityAvailable in iOS2.0and later.See AlsoABMultiValueCreateMutable (page 32)Declared inABMultiValue.hData TypesABMultiValueRefReference to a multivalue property.typedef CFTypeRef ABMultiValueRef;AvailabilityAvailable in iOS2.0and later.Declared inABMultiValue.hABMultiValueIdentifierIdentifies multivalue properties.typedef int32_t ABMultiValueIdentifier;DiscussionSee“Invalid Multivalue-Property Identifier” (page 29).AvailabilityAvailable in iOS2.0and later.Declared inABMultiValue.hConstantsInvalid Multivalue-Property IdentifierThis preprocessor definition identifies an multivalue property with values whose type does not match its declared type.#define kABMultiValueInvalidIdentifier-1ConstantskABMultiValueInvalidIdentifierInvalid multivalue property.Available in iOS2.0and later.Declared in ABMultiValue.h.DiscussionSee ABMultiValueIdentifier (page 28).ABMutableMultiValue ReferenceDerived from CFTypeRefFramework AddressBook/AddressBook.hDeclared in ABMultiValue.hOverviewThe ABMutableMultiValue opaque type(whose objects are known as mutable multivalues)implements a mutable multivalue property—that is,a property whose value set can be modified.This opaque type extends the capabilities of ABMultiValue.Functions by TaskCreating PropertiesABMultiValueCreateMutable (page 32)Returns a new,empty,mutable multivalue property.Getting PropertiesABMultiValueCreateMutableCopy (page 32)Returns a mutable copy of a multivalue property.Managing Property ValuesABMultiValueAddValueAndLabel (page 31)Adds a value and its corresponding label to a multivalue property.ABMultiValueReplaceValueAtIndex (page 36)Replaces a value in a multivalue property with another value. ABMultiValueReplaceLabelAtIndex (page 35)Replaces a label in a multivalue property with another label. ABMultiValueInsertValueAndLabelAtIndex (page 33)Inserts a value and a label into a multivalue property. ABMultiValueRemoveValueAndLabelAtIndex (page 34)Removes a value from a multivalue property.FunctionsABMultiValueAddValueAndLabelAdds a value and its corresponding label to a multivalue property.bool ABMultiValueAddValueAndLabel(ABMutableMultiValueRef multiValue,CFTypeRef value,CFStringRef label,ABMultiValueIdentifier*outIdentifier);ParametersmultiValueThe multivalue property to add value and label to.valueThe value to add to multiValue.labelThe label for value.outIdentifierThe address at which to place the identifier of the added value.Pass NULL to ignore the identifier.Return Valuetrue when value is added to multiValue successfully,false otherwise.DiscussionThis function performs no type checking.It allows the addition of values whose type does not match the type declared for multiValue.AvailabilityAvailable in iOS2.0and later.See AlsoABMultiValueCreateMutable (page 32)Related Sample CodeQuickContactsDeclared inABMultiValue.hABMultiValueCreateMutableReturns a new,empty,mutable multivalue property.ABMutableMultiValueRef ABMultiValueCreateMutable( ABPropertyType type);ParameterstypeThe type of the values that the new property will contain. Return ValueAn empty multivalue property whose values will be of type type. AvailabilityAvailable in iOS2.0and later.See AlsoABMultiValueGetPropertyType (page 27)Related Sample CodeQuickContactsDeclared inABMultiValue.h ABMultiValueCreateMutableCopyReturns a mutable copy of a multivalue property.ABMutableMultiValueRef ABMultiValueCreateMutableCopy( ABMultiValueRef multiValue);ParametersmultiValueThe multivalue property being copied.Return ValueA mutable copy of multiValue.AvailabilityAvailable in iOS2.0and later.Declared inABMultiValue.hABMultiValueInsertValueAndLabelAtIndexInserts a value and a label into a multivalue property.bool ABMultiValueInsertValueAndLabelAtIndex(ABMutableMultiValueRef multiValue,CFTypeRef value,CFStringRef label,CFIndex index,ABMultiValueIdentifier*outIdentifier);ParametersmultiValueThe multivalue property into which to insert value.valueThe value to insert.labelThe label to insert.indexThe location,in multiValue,at which to insert value and label.Raises an exception when out of bounds.outIdentifierOn output,the identifier of the added value.Return Valuetrue when value and label are inserted successfully into multiValue,false otherwise.DiscussionThis function performs no type checking.It allows the insertion of values whose type does not match the type declared for multiValue.This function takes an index.If you have an identifier,use the ABMultiValueGetIndexForIdentifier (page 27)function to get the corresponding index.AvailabilityAvailable in iOS2.0and later.See AlsoABMultiValueCreateMutable (page 32)Declared inABMultiValue.hABMultiValueRemoveValueAndLabelAtIndexRemoves a value from a multivalue property.bool ABMultiValueRemoveValueAndLabelAtIndex(ABMutableMultiValueRef multiValue,CFIndex index);ParametersmultiValueThe multivalue property from which to remove the value at index.indexThe location,in multiValue,of the value being removed.Raises an exception when out of bounds.Return Valuetrue when successful,false otherwise.。