ABRecord Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AddressBook.framework
Availability
Available in OS X v10.2 and later.
Companion guide
Declared in
ABRecord.h
Related sample code

Overview

ABRecord is an abstract superclass providing a common interface to, and defining common properties for, all Address Book records. A property is a field in the database record, such as the first or last name of a person record. ABRecord defines the types of properties supported, and basic methods for getting, setting, and removing property values.

The ABRecord class is “toll-free bridged” with its procedural C opaque-type counterpart. This means that the ABRecordRef type is interchangeable in function or method calls with instances of the ABRecord class.

Tasks

Initializing Records

Retrieving and Setting Values

Retrieving a Specific Record

Determining Properties

Instance Methods

init

Initializes a record using the shared address book.

- (id)init
Discussion

On OS X v10.5 and later, this is equivalent to initWithAddressBook:[ABAddressBook addressBook].

Availability
  • Available in OS X v10.5 and later.
Declared In
ABRecord.h

initWithAddressBook:

Initializes a record using the given address book.

- (id)initWithAddressBook:(ABAddressBook *)addressBook
Parameters
addressBook

The address book with which to initialize the record.

Discussion

The record is added to addressBook but is not visible to other address books until addressBook is saved. This method is the designated initializer for this class.

Availability
  • Available in OS X v10.5 and later.
Declared In
ABRecord.h

isReadOnly

Returns whether a record is read-only.

- (BOOL)isReadOnly
Return Value

YES if the record is read-only; otherwise, NO.

Availability
  • Available in OS X v10.4 and later.
Declared In
ABRecord.h

removeValueForProperty:

Removes the value for a given property.

- (BOOL)removeValueForProperty:(NSString *)property
Parameters
property

The property whose value will be removed.

Return Value

YES if the value is removed successfully; otherwise, NO.

Discussion

When you next call valueForProperty: on that property, it returns nil.

If property is nil, this method raises an exception.

For a list of the available properties, see “Accessing Address Book Records” in Address Book Programming Guide for Mac.

Availability
  • Available in OS X v10.2 and later.
Declared In
ABRecord.h

setValue:forProperty:

Sets the value of a given property for a record.

- (BOOL)setValue:(id)value forProperty:(NSString *)property
Parameters
value

The value to set for property.

property

The property whose value will be set.

Return Value

YES if the value was set successfully; otherwise, NO.

Discussion

The type of the value must match the property’s type (see “Property Types” in Address Book Objective-C Constants Reference for a list of possible property types). If property is nil or if value is not of the correct type, this method raises an exception. If property is a multivalue list property, this method checks to see if the values in the multivalue list are the same type. If the multivalue list contains mixed types, the value will not be set successfully.

For a list of the available properties, see “Accessing Address Book Records” in Address Book Programming Guide for Mac.

Availability
  • Available in OS X v10.2 and later.
Related Sample Code
Declared In
ABRecord.h

setValue:forProperty:error:

Sets the value of a given property for a record, returning error information.

- (BOOL)setValue:(id)value forProperty:(NSString *)property error:(NSError **)error
Parameters
value

The value to set for property.

property

The property whose value will be set.

error

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

Return Value

YES if the value was set successfully; otherwise, NO.

Discussion

The type of the value must match the property’s type (see “Property Types” in Address Book Objective-C Constants Reference for a list of possible property types). If property is nil or if value is not of the correct type, this method raises an exception. If property is a multivalue list property, this method checks to see if the values in the multivalue list are the same type. If the multivalue list contains mixed types, the value will not be set successfully.

For a list of the available properties, see “Accessing Address Book Records” in Address Book Programming Guide for Mac.

Availability
  • Available in OS X v10.7 and later.
Declared In
ABRecord.h

uniqueId

Returns the unique ID for a record.

- (NSString *)uniqueId
Return Value

The unique ID.

Discussion

This method is equivalent to invoking valueForProperty:, passing kABUIDProperty as the argument.

Availability
  • Available in OS X v10.2 and later.
See Also
Declared In
ABRecord.h

valueForProperty:

Returns the value of a given property for a record.

- (id)valueForProperty:(NSString *)property
Parameters
property

The property whose value will be returned.

Return Value

The value of the given property.

Discussion

The type of the value depends on the property type (see “Property Types” in Address Book Objective-C Constants Reference for a list of possible property types). Note that the returned value is always of an immutable type (for example, an NSString type, not an NSMutableString type, is returned).

If property is nil, this method raises an exception. If property is invalid, this method returns nil.

For a list of the available properties, see “Accessing Address Book Records” in Address Book Programming Guide for Mac.

Availability
  • Available in OS X v10.2 and later.
Related Sample Code
Declared In
ABRecord.h