Mac Developer Library

Developer

AddressBook Framework Reference ABAddressBook Class Reference

Options
Deployment Target:

On This Page
Language:

ABAddressBook

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). More...

Inheritance


Conforms To


Import Statement


import AddressBook @import AddressBook;

Availability


Available in OS X v10.2 and later.
  • Returns the unique shared instance of ABAddressBook, or nil if the Address Book database can’t be initialized.

    Declaration

    Swift

    class func sharedAddressBook() -> ABAddressBook!

    Objective-C

    + (ABAddressBook *)sharedAddressBook

    Return Value

    The unique shared instance of ABAddressBook, or nil if the Address Book database can’t be initialized.

    Discussion

    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 initWithAddressBook: method of ABPerson can yield significant performance improvements. See Accessing the Address Book in Address Book Programming Guide for Mac for more details.

    If the user denies your application access to the Address Book database, this method returns nil.

    Import Statement

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

    See Also

    + addressBook

  • Returns a new instance of ABAddressBook, or nil if the Address Book database can’t be initialized.

    Declaration

    Objective-C

    + (ABAddressBook *)addressBook

    Return Value

    A new instance of ABAddressBook, or nil if the Address Book database can’t be initialized.

    Discussion

    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. See Accessing the Address Book in Address Book Programming Guide for Mac for more details.

    If the user denies your application access to the Address Book database, this method returns nil.

    Import Statement

    Availability

    Available in OS X v10.5 and later.

  • Returns an array of all the groups in the Address Book database.

    Declaration

    Swift

    func groups() -> [AnyObject]!

    Objective-C

    - (NSArray *)groups

    Return Value

    An array of all the groups in the Address Book database.

    Discussion

    If the database doesn’t contain any groups, this method returns an empty array.

    Import Statement

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

    See Also

    – people

  • Returns an array of all the people in the Address Book database.

    Declaration

    Swift

    func people() -> [AnyObject]!

    Objective-C

    - (NSArray *)people

    Return Value

    An array of all the people in the Address Book database.

    Discussion

    If the database doesn’t contain any people, this method returns an empty array.

    Import Statement

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

    See Also

    – groups

  • Returns the ABPerson record that represents the logged-in user.

    Declaration

    Swift

    func me() -> ABPerson!

    Objective-C

    - (ABPerson *)me

    Return Value

    The ABPerson record that represents the logged-in user.

    Discussion

    If the user never specified such a record, this method returns nil.

    Import Statement

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

    See Also

    – setMe:

  • Sets the record that represents the logged-in user.

    Declaration

    Swift

    func setMe(_ person: ABPerson!)

    Objective-C

    - (void)setMe:(ABPerson *)person

    Parameters

    person

    The person to set as representing the logged-in user.

    Discussion

    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 record, if one is set.

    Import Statement

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

    See Also

    – me

  • Returns the person or group record that matches the given unique ID.

    Declaration

    Swift

    func recordForUniqueId(_ uniqueId: String!) -> ABRecord!

    Objective-C

    - (ABRecord *)recordForUniqueId:(NSString *)uniqueId

    Parameters

    uniqueId

    The unique ID of the record. This value must not be nil; otherwise, an exception is raised.

    Return Value

    The person or group record that matches the given unique ID.

    Discussion

    If no record has the given ID, this method returns nil.

    Import Statement

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

    See Also

    uniqueId (ABRecord)

  • Returns the class name of the record that matches the given unique ID.

    Declaration

    Swift

    func recordClassFromUniqueId(_ uniqueId: String!) -> String!

    Objective-C

    - (NSString *)recordClassFromUniqueId:(NSString *)uniqueId

    Parameters

    uniqueId

    The unique ID of the record.

    Return Value

    The name of the class of the record, for example ABPerson.

    Import Statement

    import AddressBook

    Availability

    Available in OS X v10.3 and later.

  • Returns an attributed string containing the formatted address.

    Declaration

    Swift

    func formattedAddressFromDictionary(_ address: [NSObject : AnyObject]!) -> NSAttributedString!

    Objective-C

    - (NSAttributedString *)formattedAddressFromDictionary:(NSDictionary *)address

    Parameters

    address

    The dictionary containing a street address.

    Return Value

    An attributed string containing the formatted address.

    Discussion

    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.

    Import Statement

    import AddressBook

    Availability

    Available in OS X v10.3 and later.

  • Returns the default country code for records with unspecified country codes.

    Declaration

    Swift

    func defaultCountryCode() -> String!

    Objective-C

    - (NSString *)defaultCountryCode

    Return Value

    The default country code.

    Discussion

    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 in ABPerson Class Reference.

    Import Statement

    import AddressBook

    Availability

    Available in OS X v10.3 and later.

  • Returns the default name ordering defined by the user in the Address Book application’s preferences.

    Declaration

    Swift

    func defaultNameOrdering() -> Int

    Objective-C

    - (NSInteger)defaultNameOrdering

    Return Value

    The default name ordering defined by the user in the Address Book application’s preferences.

    Discussion

    The possible values are kABFirstNameFirst and kABLastNameFirst.

    Import Statement

    import AddressBook

    Availability

    Available in OS X v10.3 and later.

  • Adds an ABPerson or ABGroup record to the Address Book database.

    Declaration

    Swift

    func addRecord(_ record: ABRecord!, error error: NSErrorPointer) -> Bool

    Objective-C

    - (BOOL)addRecord:(ABRecord *)record error:(NSError **)error

    Parameters

    record

    The record to add.

    error

    A pointer to an error object that is set to an NSError instance if an error occurs.

    Return Value

    YEStrue if the record was added successfully; otherwise NOfalse.

    Discussion

    If the record argument is nil, this method raises an exception. Your changes are not committed until you call the save method.

    It is more efficient to use the ABRecord method initWithAddressBook: when possible.

    Import Statement

    import AddressBook

    Availability

    Available in OS X v10.7 and later.

  • Adds an ABPerson or ABGroup record to the Address Book database.

    Declaration

    Swift

    func addRecord(_ record: ABRecord!) -> Bool

    Objective-C

    - (BOOL)addRecord:(ABRecord *)record

    Parameters

    record

    The record to add.

    Return Value

    YEStrue if the record was added successfully; otherwise NOfalse.

    Discussion

    If the record argument is nil, this method raises an exception. Your changes are not committed until you call the save method.

    It is more efficient to use the ABRecord method initWithAddressBook: when possible.

    Import Statement

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

  • Removes an ABPerson or ABGroup record from the Address Book database.

    Declaration

    Swift

    func removeRecord(_ record: ABRecord!, error error: NSErrorPointer) -> Bool

    Objective-C

    - (BOOL)removeRecord:(ABRecord *)record error:(NSError **)error

    Parameters

    record

    The record to be removed.

    error

    A pointer to an error object that is set to an NSError instance if an error occurs.

    Return Value

    YEStrue if the record was removed successfully; otherwise, NOfalse.

    Discussion

    If record is nil, this method raises an exception. Your changes are not committed until you call the save method.

    Import Statement

    import AddressBook

    Availability

    Available in OS X v10.7 and later.

    See Also

    – addRecord:

  • Removes an ABPerson or ABGroup record from the Address Book database.

    Declaration

    Swift

    func removeRecord(_ record: ABRecord!) -> Bool

    Objective-C

    - (BOOL)removeRecord:(ABRecord *)record

    Parameters

    record

    The record to be removed.

    Return Value

    YEStrue if the record was removed successfully; otherwise, NOfalse.

    Discussion

    If record is nil, this method raises an exception. Your changes are not committed until you call the save method.

    Import Statement

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

    See Also

    – addRecord:

  • Indicates whether an address book has changes that have not been saved to the Address Book database.

    Declaration

    Swift

    func hasUnsavedChanges() -> Bool

    Objective-C

    - (BOOL)hasUnsavedChanges

    Return Value

    YEStrue if there are unsaved changes; otherwise, NOfalse.

    Discussion

    The unsaved changes flag is set automatically whenever changes are made.

    Import Statement

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

  • Saves all the changes made since the last save.

    Declaration

    Swift

    func save() -> Bool

    Objective-C

    - (BOOL)save

    Return Value

    YEStrue if successful or there were no changes; otherwise, NOfalse.

    Import Statement

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

  • Saves all the changes made since the last save.

    Declaration

    Swift

    func saveAndReturnError(_ error: NSErrorPointer) -> Bool

    Objective-C

    - (BOOL)saveAndReturnError:(NSError **)error

    Parameters

    error

    A pointer to an error object that is set to an NSError instance if an error occurs.

    Return Value

    YEStrue if successful or there were no changes; otherwise, NOfalse.

    Import Statement

    import AddressBook

    Availability

    Available in OS X v10.5 and later.

  • Keys contained by the user-info dictionary of the notifications posted by the Address Book framework.

    Declaration

    Swift

    let kABInsertedRecords: NSString! let kABUpdatedRecords: NSString! let kABDeletedRecords: NSString!

    Objective-C

    NSString * const kABInsertedRecords; NSString * const kABUpdatedRecords; NSString * const kABDeletedRecords;

    Constants

    • kABInsertedRecords

      kABInsertedRecords

      Records that have been inserted.

      Available in OS X v10.3 and later.

    • kABUpdatedRecords

      kABUpdatedRecords

      Records that have been updated.

      Available in OS X v10.3 and later.

    • kABDeletedRecords

      kABDeletedRecords

      Records that have been deleted.

      Available in OS X v10.3 and later.

    Import Statement

  • Errors codes returned by the Address Book Framework.

    Declaration

    Swift

    var ABAddRecordsError: Int { get } var ABRemoveRecordsError: Int { get } var ABPropertyValueValidationError: Int { get } var ABPropertyUnsupportedBySourceError: Int { get } var ABPropertyReadOnlyError: Int { get }

    Objective-C

    enum { ABAddRecordsError = 1001, ABRemoveRecordsError = 1002, ABPropertyValueValidationError = 1012, ABPropertyUnsupportedBySourceError = 1013, ABPropertyReadOnlyError = 1014 };

    Constants

    • ABAddRecordsError

      ABAddRecordsError

      The records could not be added

      Available in OS X v10.7 and later.

    • ABRemoveRecordsError

      ABRemoveRecordsError

      The records could not be removed.

      Available in OS X v10.7 and later.

    • ABPropertyValueValidationError

      ABPropertyValueValidationError

      The property value is not valid.

      Available in OS X v10.7 and later.

    • ABPropertyUnsupportedBySourceError

      ABPropertyUnsupportedBySourceError

      The property is not supported by the source.

      Available in OS X v10.7 and later.

    • ABPropertyReadOnlyError

      ABPropertyReadOnlyError

      The property is read only.

      Available in OS X v10.7 and later.

    Import Statement

  • Posted when this process has changed the Address Book database.

    Depending on the operation performed on the address book, one or more of the following keys may be included in the user-info dictionary: 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.

    Import Statement

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

  • Posted when a process other than the current one has changed the Address Book database.

    Depending on the operation performed on the address book, one or more of the following keys may be included in the user-info dictionary: 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.

    Import Statement

    import AddressBook

    Availability

    Available in OS X v10.2 and later.