| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/AddressBook.framework |
| Availability | Available in Mac OS X v10.2 and later. |
| Companion guide | |
| Declared in | ABAddressBook.h ABGlobals.h |
| Related sample code |
The ABAddressBook class provides a programming interface to the Address Book—a centralized database used by multiple applications to store contact and other 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 with some restrictions (for example, no circular references are allowed).
The ABAddressBook class is “toll-free bridged” with its procedural C opaque-type counterpart. This means that the ABAddressBookRef type is interchangeable in function or method calls with instances of the ABAddressBook class.
Returns a new instance of ABAddressBook.
+ (ABAddressBook *)addressBook
If you're just making one-off lookups and edits, the sharedAddressBook method is probably more appropriate. If your code is executing a tight loop, the addressBook method can yield significant performance improvements when used with the ABPerson initWithAddressBook: method. For example, you can replace code such as the following:
for (id item in someDataStructure) { |
ABPerson* person = [[ABPerson alloc] init]; |
// Populate the person from the item |
} |
[[ABAddressBook sharedAddressBook] save]; |
With code like the following:
ABAddressBook* tempBook = [ABAddressBook addressBook]; |
for (id item in someDataStructure) { |
ABPerson* person = [[ABPerson alloc] initWithAddressBook:tempBook]; |
// Populate the person from the item |
} |
[tempBook save]; |
+ sharedAddressBookABAddressBook.hReturns the unique shared instance of ABAddressBook.
+ (ABAddressBook *)sharedAddressBook
This method returns the address book for the logged-in user that is shared by every application. If you call this method more than once or try to create a new address book, you will get a pointer to the same shared address book.
If you're just making one-off lookups and edits, this is the appropriate method to use. If your code is executing a tight loop, using the addressBook method with the ABPerson initWithAddressBook: method can yield significant performance improvements.
+ addressBookABAddressBook.hAdds an ABPerson or ABGroup record to the Address Book database.
- (BOOL)addRecord:(ABRecord *)record
The record to add.
YES if the record was added successfully; otherwise NO.
If the record argument is nil, this method raises an exception. Your changes are not committed until you call the save method.
– removeRecord:– initWithVCardRepresentation: (ABPerson)ABAddressBook.hReturns the default country code for records with unspecified country codes.
- (NSString *)defaultCountryCode
The default country code.
This value returned is set by the user in the Address Book application’s general preference. The supported country codes are listed in “Country Codes”.
ABAddressBook.hReturns the default name ordering defined by the user in the Address Book application’s preferences.
- (NSInteger)defaultNameOrdering
The possible values are kABFirstNameFirst and kABLastNameFirst.
ABAddressBook.hReturns an attributed string containing the formatted address.
- (NSAttributedString *)formattedAddressFromDictionary:(NSDictionary *)address
The dictionary containing a street address.
An attributed string containing the formatted address.
The string’s attributes match address dictionary keys, such as kABAddressStreetKey. Each attribute value contains the localized description of the key. (For example, the value of a Canadian kABAddressZIPKey field would be “Postal Code”, while the value of a French one would be “Code Postal”.)
To get the dictionary containing a street address for a person record, use valueForProperty: with the property kABAddressProperty, and then getting one of the values from the multivalue that is returned.
ABAddressBook.hReturns an array of all the groups in the Address Book database.
- (NSArray *)groups
If the database doesn’t contain any groups, this method returns an empty array.
ABAddressBook.hIndicates whether an address book has changes that have not been saved to the Address Book database.
- (BOOL)hasUnsavedChanges
YES if there are unsaved changes; otherwise, NO.
The unsaved changes flag is set automatically whenever changes are made.
ABAddressBook.hReturns the ABPerson record that represents the logged-in user.
- (ABPerson *)me
If the user never specified such a record, this method returns nil.
ABAddressBook.hReturns an array of all the people in the Address Book database.
- (NSArray *)people
If the database doesn’t contain any people, this method returns an empty array.
ABAddressBook.hReturns the class name of the record that matches the given unique ID.
- (NSString *)recordClassFromUniqueId:(NSString *)uniqueId
The unique ID of the record.
The name of the class of the record, for example ABPerson.
ABAddressBook.hReturns the person or group record that matches the given unique ID.
- (ABRecord *)recordForUniqueId:(NSString *)uniqueId
The unique ID of the record. This value must not be nil; otherwise, an exception is raised.
If no record has the given ID, this method returns nil.
– uniqueId (ABRecord)ABAddressBook.hReturns an array of records that match the given search element, or returns an empty array if no records match the search element.
- (NSArray *)recordsMatchingSearchElement:(ABSearchElement *)search
The search element to perform the search against.
An array of records that match the given search element, or an empty array if no records match the search element.
If search is nil, this method raises an exception.
+ searchElementForProperty:label:key:value:comparison: (ABPerson)+ searchElementForProperty:label:key:value:comparison: (ABGroup)+ searchElementForConjunction:children: (ABSearchElement)ABAddressBook.hRemoves an ABPerson or ABGroup record from the Address Book database.
- (BOOL)removeRecord:(ABRecord *)record
The record to be removed.
YES if the record was removed successfully; otherwise, NO.
If record is nil, this method raises an exception. Your changes are not committed until you call the save method.
ABAddressBook.hSaves all the changes made since the last save.
- (BOOL)save
YES if successful or there were no changes; otherwise, NO.
ABAddressBook.hSaves all the changes made since the last save.
- (BOOL)saveAndReturnError:(NSError **)error
A pointer to an error object that is set to an NSError instance if an error occurs.
YES if successful or there were no changes; otherwise, NO.
ABAddressBook.hSets the record that represents the logged-in user.
- (void)setMe:(ABPerson *)person
The person to set as representing the logged-in user.
If you don’t want a record to represent the logged-in user, then pass nil as the person argument. Note that this will not delete the existing “me” card, if one is set.
ABAddressBook.hKeys contained by the user-info dictionary of the notifications posted by the Address Book framework.
NSString * const kABInsertedRecords; NSString * const kABUpdatedRecords; NSString * const kABDeletedRecords;
kABInsertedRecordsRecords that have been inserted.
Available in Mac OS X v10.3 and later.
Declared in ABGlobals.h.
kABUpdatedRecordsRecords that have been updated.
Available in Mac OS X v10.3 and later.
Declared in ABGlobals.h.
kABDeletedRecordsRecords that have been deleted.
Available in Mac OS X v10.3 and later.
Declared in ABGlobals.h.
These notifications are sent when something changes in the Address Book database. These are not sent until the sharedAddressBook class method has been invoked.
Posted when this process has changed the Address Book database.
The process ID of the sender and the effective user ID are always included in the user-info dictionary; you access them through the keys kABSenderProcessID and kABUserUID, respectively. In addition, depending on the operation performed on the address book, one or more of the following keys may be included: kABInsertedRecords, kABUpdatedRecords, and kABDeletedRecords. The values for each of the keys are the unique IDs of the records that were inserted, updated, or deleted, respectively. If the values for all the keys are nil, every record has changes. For example, this happens when the Address Book database is restored from a backup copy.
ABGlobals.hPosted when a process other than the current one has changed the Address Book database.
The process id of the sender and the effective user ID are always included in the user-info dictionary; you access them through the keys kABSenderProcessID and kABUserUID, respectively. In addition, depending on the operation performed on the address book, one or more of the following keys may be included: kABInsertedRecords, kABUpdatedRecords, and kABDeletedRecords. The values for each of the keys are the unique IDs of the records that were inserted, updated, or deleted, respectively. If the values for all the keys are nil, every record has changes. For example, this happens when the Address Book database is restored from a backup copy.
ABGlobals.hLast updated: 2009-07-16
Mac OS X Reference Library Data Management: Contact Data ABAddressBook Class Reference