ABPerson Class Reference

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

Overview

The ABPerson class encapsulates all information about a person in the Address Book database—an instance of ABPerson corresponds to a single person record in the database. The ABPerson class defines properties such as the person’s name, company, address, email addresses, and phone numbers.

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

Tasks

Managing Properties

Managing Linked People

Managing Groups

Managing Images

Searching

Importing and Exporting VCard Formatted Files

Class Methods

addPropertiesAndTypes:

Adds the given properties to all the records of this type in the Address Book database.

+ (NSInteger)addPropertiesAndTypes:(NSDictionary *)properties
Parameters
properties

A dictionary of properties to add, and their types.

Return Value

The number of properties successfully added, or -1 if an error occurs.

Discussion

In each dictionary entry, the key is a string with the property’s name, and the value is a constant with the property’s type. The property’s name must be unique. You may want to use Java-style package names for your properties, for example, org.dogclub.dogname or com.mycompany.customerID. The property type must be one of the constants described in “Property Types” in Address Book Objective-C Constants Reference.

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

cancelLoadingImageDataForTag:

Cancels an asynchronous fetch of the images for a given tag.

+ (void)cancelLoadingImageDataForTag:(NSInteger)tag
Parameters
tag

The tag of the asynchronous fetch to be canceled.

Discussion

The tag is returned from the previous call to the beginLoadingImageDataForClient: method that started the asynchronous fetch.

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

properties

Returns an array of the names of all the properties for the record in the Address Book database.

+ (NSArray *)properties
Availability
  • Available in OS X v10.2 and later.
Declared In
ABPerson.h

removeProperties:

Removes the given properties from all the records of this type in the Address Book database.

+ (NSInteger)removeProperties:(NSArray *)properties
Parameters
properties

An array of properties to remove.

Return Value

The number of properties successfully removed, or -1 if an error occurs.

Discussion

Only custom properties can be removed. This method is not implemented.

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

searchElementForProperty:label:key:value:comparison:

Returns a search element object that specifies a query for records of this type.

+ (ABSearchElement *)searchElementForProperty:(NSString *)property label:(NSString *)label key:(NSString *)key value:(id)value comparison:(ABSearchComparison)comparison
Parameters
property

The name of the property to search on, such as kABAddressProperty or kABLastNameProperty. This name cannot be nil. For a full list of the properties, see “Default Record Properties” in Address Book Objective-C Constants Reference and “Default Person Properties” in Address Book Objective-C Constants Reference.

label

The label name for a multivalue list, such as kABAddressHomeLabel, kABPhoneWorkLabel, or a user-specified label, such as Summer Home. If the specified property does not have multiple values, pass nil. If the specified property does have multiple values, pass nil to search all the values. For a full list of label names, see “Default Multivalue List Labels” in Address Book Objective-C Constants Reference and “Generic Multivalue List Labels” in Address Book Objective-C Constants Reference.

key

The key name for a dictionary, such as kABAddressCityKey or kABAddressStreetKey. If the specified property is not a dictionary, pass nil. If the specified property is a dictionary, pass nil to search all keys. For a full list of key names, see “Address Keys” in Address Book Objective-C Constants Reference.

value

What you’re searching for. If nil, then the only supported value for comparison is kABEqual or kABNotEqual.

comparison

The type of comparison to perform, such as kABEqual or kABPrefixMatchCaseInsensitive.

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

typeOfProperty:

Returns the type of a given property.

+ (ABPropertyType)typeOfProperty:(NSString *)property
Parameters
property

The property whose type will be returned.

Discussion

If the property does not exist, this method returns kABErrorInProperty.

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

Instance Methods

beginLoadingImageDataForClient:

Starts an asynchronous fetch for image data in all locations

- (NSInteger)beginLoadingImageDataForClient:(id < ABImageClient >)client
Parameters
client

The object to be notified when the image finishes loading.

Return Value

A nonzero tag for tracking. This tag is used by the cancelLoadingImageDataForTag: method to cancel a fetch operation.

Discussion

The client object should conform to the ABImageClient protocol. A consumeImageData:forTag: message is sent to client when the fetch is done. Use the cancelLoadingImageDataForTag: method if you need to cancel an asynchronous fetch.

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

imageData

Returns data that contains a picture of this person.

- (NSData *)imageData
Return Value

Data containing a picture of this person

Discussion

This method searches only the local file system and operates synchronously. To perform an asynchronous search or to search over a network, use beginLoadingImageDataForClient:.

The returned data is in a QuickTime-compatible format. To create an image from it, use the NSImage method initWithData:.

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

initWithVCardRepresentation:

Returns an ABPerson instance initialized with the given data.

- (id)initWithVCardRepresentation:(NSData *)vCardData
Parameters
vCardData

A data object containing a vCard representation of a person record.

Return Value

An ABPerson instance initialized with the given data.

Discussion

Version 2.1 and 3.0 of the vCard format are supported. If vCardData is nil or is not a valid vCard format, this method returns nil.

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

linkedPeople

Returns the array of all person records that are linked to the person this record represents.

- (NSArray *)linkedPeople
Return Value

The array of all person records that are linked to the person this record represents.

Discussion

Linked records contain information about the same person, and typically come from different sources.

Availability
  • Available in OS X v10.8 and later.
Declared In
ABPerson.h

parentGroups

Returns an array of the address book groups that this person belongs to.

- (NSArray *)parentGroups
Discussion

If the person doesn’t belong to any groups, this method returns an empty array.

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

setImageData:

Sets the image for this person to the given data.

- (BOOL)setImageData:(NSData *)data
Parameters
data

The image to be set.

Discussion

The data argument must be in a QuickTime-compatible format. Pass nil to specify that there is no image for this person.

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

vCardRepresentation

Returns the vCard representation of the person record as a data object in vCard format.

- (NSData *)vCardRepresentation
Return Value

A data object containing the vCard representation of the person record.

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

Constants

Person Flags

Settings that determine how person records are displayed.

#define kABShowAsMask                           000007
#define kABShowAsPerson                         000000
#define kABShowAsCompany                        000001
#define kABShowAsResource                       000002
#define kABShowAsRoom                           000003
#define kABNameOrderingMask                     000070
#define kABDefaultNameOrdering                  000000
#define kABFirstNameFirst                       000040
#define kABLastNameFirst                        000020
Constants
kABShowAsMask

Used in conjunction with kABShowAsPerson, kABShowAsCompany, kABShowAsResource, and kABShowAsRoom to determine record configuration.

Available in OS X v10.3 and later.

Declared in ABGlobals.h.

kABShowAsPerson

Record is displayed as a person.

Available in OS X v10.3 and later.

Declared in ABGlobals.h.

kABShowAsCompany

Record is displayed as a company.

Available in OS X v10.3 and later.

Declared in ABGlobals.h.

kABShowAsResource

Record is displayed as a resource.

Available in OS X v10.6 and later.

Declared in ABGlobals.h.

kABShowAsRoom

Record is displayed as a room.

Available in OS X v10.6 and later.

Declared in ABGlobals.h.

kABNameOrderingMask

Used in conjunction with kABDefaultNameOrdering, kABFirstNameFirst, and kABLastNameFirst to determine name ordering.

Available in OS X v10.3 and later.

Declared in ABGlobals.h.

kABDefaultNameOrdering

Default name ordering (whether a person’s first name or last name is displayed first) the Address Book application.

Available in OS X v10.3 and later.

Declared in ABGlobals.h.

kABFirstNameFirst

First name is displayed first in Address Book.

Available in OS X v10.3 and later.

Declared in ABGlobals.h.

kABLastNameFirst

Last name is displayed first in Address Book.

Available in OS X v10.3 and later.

Declared in ABGlobals.h.