Next Page > Hide TOC

ABPerson Class Reference

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.

Some of these properties have multiple values that are accessed via standard and user-defined labels. For example, a person may have a home, work, mobile, and fax phone numbers. Therefore, the phone attribute is defined as an ABMultiValue object containing NSString objects for each number. For example, you might get a person’s primary phone number as follows:

ABMultiValue *phones = [aPerson valueForProperty:kABPhoneProperty];

id value = [phones valueAtIndex:[phones indexForIdentifier:

                [phones primaryIdentifier]]];

See ABRecord for common methods to get and set properties. See the “Constants” section for a list of all the properties, labels, and keys used to access fields in a person record. See ABMultiValue for more details on multi-value lists and how primary values work.

You can add your own properties to person records too using the addPropertiesAndTypes: method—that is, attach additional program-defined data to each person record. Because the Address Book database is stored as a property list, these program-defined properties can be ignored by other applications. Note that the AddressBook database is accessed by multiple application and is not encrypted so your application should not store any sensitive information in the database like credit card numbers.

A person may also have an associated picture or image. The image is not actually stored in the Address Book database (a property list)—it’s stored in a separate image file. You can set a person’s image using the setImageData: method, or get an image using the imageData method. Use the NSImage initWithData: method to convert an NSData object, returned by the imageData method, to an NSImage object.

Image files may be local or remote. Local images are any images in .../Library/Images/People or images the user has set using the Address Book application. Remote images are images stored on the network. These images take time to download, so ABPerson provides an asynchronous API for fetching remote images.

Use the beginLoadingImageDataForClient: method if an image file is not local and you want to perform an asynchronous fetch. You pass a client object that implements the ABImageClient protocol as an argument to this method. The beginLoadingImageDataForClient: method will return an image tracking number. A consumeImageData:forTag: message is sent to your client object when the fetch is done. Implement this method to handle the new fetched image. Use the cancelLoadingImageDataForTag:class method if for some reason you want to cancel an asynchronous fetch.

Person records may belong to multiple groups. Use the parentGroups method to get the groups a person belongs to. See ABGroup for more information about groups.

You can also search for records matching a particular “query” you specify by creating an ABSearchElement object. Use the searchElementForProperty:label:key:value:comparison: method to create an ABSearchElement object containing your query. Then use the ABAddressBook recordsMatchingSearchElement: method, passing the ABSearchElement as the argument, to query the database. See ABSearchElement for more methods that create compound queries.

Your application can also import and export persons in the vCard file format using the initWithVCardRepresentation:and vCardRepresentation methods.

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

• + addPropertiesAndTypes:
• + removeProperties:
• + properties
• + typeOfProperty:

Managing Groups

• – parentGroups

Managing Images

• + cancelLoadingImageDataForTag:
• – beginLoadingImageDataForClient:
• – imageData
• – setImageData:

Searching

• + searchElementForProperty:label:key:value:comparison:

Importing and Exporting VCard Formatted Files

• – initWithVCardRepresentation:
• – vCardRepresentation

Getting Identity Properties

• – identityUniqueId
• – identity

Class Methods

addPropertiesAndTypes:

+ (NSInteger)addPropertiesAndTypes:(NSDictionary *)properties

Discussion

Adds the given properties to all the records of this type in the Address Book database, and returns the number of properties successfully added. 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 “Constants” in ABRecord. Returns -1 if an error occurs.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

cancelLoadingImageDataForTag:

+ (void)cancelLoadingImageDataForTag:(NSInteger)tag

Discussion

Cancels an asynchronous fetch of the images for a given tag. The tag argument should have been returned from a previous call to the beginLoadingImageDataForClient: method.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• – beginLoadingImageDataForClient:
• – consumeImageData:forTag: (ABImageClient)

Declared In

properties

+ (NSArray *)properties

Discussion

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

Availability

• Available in Mac OS X v10.2 and later.

See Also

• + typeOfProperty:

Declared In

removeProperties:

+ (NSInteger)removeProperties:(NSArray *)properties

Discussion

Removes the given properties from all the records of this type in the Address Book database, and returns the number of properties successfully removed. Returns -1 if an error occurs.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

searchElementForProperty:label:key:value:comparison:

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

Discussion

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

• property is the name of the property to search on, such as kABAddressProperty or kABLastNameProperty. It cannot be nil. For a full list of the properties, see “Constants” and “Constants” in ABRecord.

• label is the label name for a multi-value 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 “Constants.”

• key is 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 “Constants”

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

• comparison specifies the type of comparison to perform and is an ABSearchComparison, such as kABEqual or kABPrefixMatchCaseInsensitive.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• + searchElementForProperty:label:key:value:comparison: (ABGroup)
• + searchElementForConjunction:children: (ABSearchElement)
• – recordsMatchingSearchElement: (ABAddressBook)

Related Sample Code

• AddressBookCocoa
• Birthdays

Declared In

typeOfProperty:

+ (ABPropertyType)typeOfProperty:(NSString *)property

Discussion

Returns the type for a given property. If the property does not exist, this method returns kABErrorInProperty.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• + properties

Declared In

Instance Methods

beginLoadingImageDataForClient:

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

Discussion

Starts an asynchronous fetch for image data in all locations, and returns a non-zero tag for tracking. 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 Mac OS X v10.2 and later.

See Also

• – imageData

Declared In

identity

Returns the CSIdentityRef object associated with a person.

- (CSIdentityRef)identity

Return Value

A CSIdentityRef object associated with the receiver or NULL if it doesn’t exist.

See Also

• – identityUniqueId
• – beginSheetModalForWindow:modalDelegate:didEndSelector:contextInfo:
• – runModalIdentityPicker

identityUniqueId

Returns the unique identifier for a person.

- (NSString*)identityUniqueId

Return Value

A unique identifier for the receiver or nil if it doesn’t exist.

See Also

• – identity
• – beginSheetModalForWindow:modalDelegate:didEndSelector:contextInfo:
• – runModalIdentityPicker

imageData

- (NSData *)imageData

Discussion

Returns data that contains a picture of this person. 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 Mac OS X v10.2 and later.

See Also

• – beginLoadingImageDataForClient:
• – setImageData:

Declared In

initWithVCardRepresentation:

- (id)initWithVCardRepresentation:(NSData *)vCardData

Discussion

Returns an ABPerson instance initialized with the given data. If vCardData is nil or is not a valid vCard format, this method returns nil.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• – vCardRepresentation

Declared In

parentGroups

- (NSArray *)parentGroups

Discussion

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

Availability

• Available in Mac OS X v10.2 and later.

Declared In

setImageData:

- (BOOL)setImageData:(NSData *)data

Discussion

Sets the image for this person to the given data. 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 Mac OS X v10.2 and later.

See Also

• – imageData
• – beginLoadingImageDataForClient:

Declared In

vCardRepresentation

- (NSData *)vCardRepresentation

Discussion

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

Availability

• Available in Mac OS X v10.2 and later.

See Also

• – initWithVCardRepresentation:

Declared In

Constants

These are the properties that an ABPerson record contains by default. ABRecord describes additional properties that all records contain, in “Constants”. Note that some of these properties are not displayed in the Address Book application. Developers can add their own properties with the ABRecord method addPropertiesAndTypes:.

The ABPersonFlags property is used to access the following settings:

These are the default labels contained in the Address Book database for specifying different values in a multi-value list. Users can also add their own labels.

Use these labels in searches to match all work, home, or other labels. For example, kABWorkLabel can be used in place of kABEmailWorkLabel or kABAddressWorkLabel.

These are the keys contained in each address dictionary. Neither developers nor users can add more keys.

The kABAddressCountryCodeKey must be one of the following ISO country codes.

Next Page > Hide TOC