Next Page >

Hide TOC

ABPerson C Reference

Derived from	ABRecord : CFType
Framework	AddressBook/ABAddressBookC.h
Companion guide	Address Book Programming Guide
Declared in	ABAddressBookC.h ABGlobals.h ABGlobalsC.h

Overview

The ABPerson opaque type 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 opaque type defines properties such as the person’s name, company, address, email addresses, and phone numbers.

You get a person’s property value using the ABRecordCopyValue function. See ABRecord for more functions that 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.

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. 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 ABAddPropertiesAndTypes function—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 in 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 ABPersonSetImageData function, or get an image using the ABPersonCopyImageDatafunction.

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. Theses images take time to download, so ABPerson provides an asynchronous API for fetching remote images.

Use the ABBeginLoadingImageDataForClient function if an image file is not local and you want to perform an asynchronous fetch. The ABBeginLoadingImageDataForClient function will return an image tracking number. The tracking number and the fetched image will be passed to your callback function. Implement your callback function to handle the fetched image. Use the ABCancelLoadingImageDataForTag function if for some reason you want to cancel an asynchronous fetch.

Person records may belong to multiple groups. Use the ABPersonCopyParentGroups function 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 ABPersonCreateSearchElement function to create an ABSearchElement object containing your query. Then use the ABAddressBook ABCopyArrayOfMatchingRecords function, passing the ABSearchElement as the argument, to query the database. See ABSearchElement for more functions that create compound queries.

Your application can also import and export persons in the vCard file format using the ABPersonCreateWithVCardRepresentation and ABPersonCopyVCardRepresentation functions.

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

Functions

ABBeginLoadingImageDataForClient

Starts an asynchronous fetch for image data in all locations, and returns a non-zero tag for tracking.

CFIndex ABBeginLoadingImageDataForClient (
   ABPersonRef person,
   ABImageClientCallback callback,
   void *refcon
);

Parameters

person: The person whose image data you wish to fetch.
callback: The function to call when the fetch is completed.
info: An untyped pointer to program-defined data that will be passed to the callback.

Return Value

A non-zero tag for tracking

Discussion

Use this function to begin an asynchronous fetch. Implement your callback function to receive the fetched image. Use the ABCancelLoadingImageDataForTag function to cancel an asynchronous fetch.

Availability

Available in Mac OS X v10.2 and later.

Declared In

ABAddressBookC.h

ABCancelLoadingImageDataForTag

Cancels an asynchronous fetch of an image for the given tag.

void ABCancelLoadingImageDataForTag (
   CFIndex tag
);

Parameters

tag: Used to track an asynchronous fetch. This parameter should have been returned from a previous call to the ABBeginLoadingImageDataForClient function.

Discussion

Use the ABBeginLoadingImageDataForClient function to begin an asynchronous fetch. Implement your callback function to receive the fetched image. Use this function to cancel an asynchronous fetch.

Availability

Available in Mac OS X v10.2 and later.

Declared In

ABAddressBookC.h

ABPersonCopyImageData

Returns data that contains a picture of a person.

CFDataRef ABPersonCopyImageData (
   ABPersonRef person
);

Parameters

person: The person whose image you wish to obtain.

Return Value

The data representing an image of person. You are responsible for releasing this object.

Availability

Available in Mac OS X v10.2 and later.

Declared In

ABAddressBookC.h

ABPersonCopyParentGroups

Returns an array of groups that a person belongs to.

CFArrayRef ABPersonCopyParentGroups (
   ABPersonRef person
);

Parameters

person: The person whose parent groups you wish to obtain.

Return Value

An array of ABGroup objects which person belongs to. You are responsible for releasing this object.

Availability

Available in Mac OS X v10.2 and later.

Declared In

ABAddressBookC.h

ABPersonCopyVCardRepresentation

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

CFDataRef ABPersonCopyVCardRepresentation (
   ABPersonRef person
);

Parameters

person: The person whose vCard representation you wish to obtain.

Return Value

The vCard representation of person as a data object in vCard format. You are responsible for releasing this object.

Availability

Available in Mac OS X v10.2 and later.

Declared In

ABAddressBookC.h

ABPersonCreate

Returns a newly created person object.

ABPersonRef ABPersonCreate (
   void
);

Return Value

A newly created person object. You are responsible for releasing this object.

Availability

Available in Mac OS X v10.2 and later.

Declared In

ABAddressBookC.h

ABPersonCreateSearchElement

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

ABSearchElementRef ABPersonCreateSearchElement (
   CFStringRef property,
   CFStringRef label,
   CFStringRef key,
   CFTypeRef value,
   ABSearchComparison comparison
);

Parameters

property: The name of the property to search on. It cannot be NULL. For a full list of the properties, see “Person Properties” and Common Properties in ABRecord.
label: The label name for a multi-value list. If property does not have multiple values, pass NULL. If property does have multiple values, pass NULL to search all the values.
key: The key name for a dictionary. If property is not a dictionary, pass NULL. If property is a dictionary, pass NULL to search all keys.
value: The value you are searching for. It cannot be NULL
comparison: Specifies the type of comparison to perform, such as kABEqual or kABPrefixMatchCaseInsensitive. For a full list, see ABSearchComparison.

Return Value

A search element object that specifies a query according to the above parameters. You are responsible for releasing this object.

Discussion

Use the ABAddressBook ABCopyArrayOfMatchingRecords function to actually perform the query. Also, see ABSearchElement for more functions that create compound queries.

Availability

Available in Mac OS X v10.2 and later.

Declared In

ABAddressBookC.h

ABPersonCreateWithVCardRepresentation

Returns a new ABPerson object initialized with the given data in vCard format.

ABPersonRef ABPersonCreateWithVCardRepresentation (
   CFDataRef vCard
);

Parameters

vCard: The data in vCard format to initialize the new ABPerson object with.

Return Value

A new ABPerson object initialized with the given data in vCard format. You are responsible for releasing this object.

Availability

Available in Mac OS X v10.2 and later.

Declared In

ABAddressBookC.h

ABPersonSetImageData

Sets the image for this person to the given data.

bool ABPersonSetImageData (
   ABPersonRef person,
   CFDataRef imageData
);

Parameters

person: The person whose image data you wish to set.
imageData: The image data to use as the image for person.

Return Value

true if successful, false otherwise.

Availability

Available in Mac OS X v10.2 and later.

Declared In

ABAddressBookC.h

Callbacks

ABImageClientCallback

Prototype of a callback function used to notify an application when an asynchronous image fetch is complete.

typedef void (*ABImageClientCallback) (
   CFDataRef imageData,
   int tag,
   void *info
);

If you name your function MyCallBack, you would declare it like this:

const void MyCallback (
   CFDataRef imageData,
   int tag,
   void *info
);

Parameters

imageData: The image data in Quicktime compatible format that was loaded from an asynchronous fetch. NULL if the fetch failed.
tag: The tracking number for this fetch that should have been obtained from a previous call to the ABBeginLoadingImageDataForClient function.
info: An untyped pointer to program-defined data that was passed to the ABBeginLoadingImageDataForClient function.

Discussion

Use the ABBeginLoadingImageDataForClient function to begin an asynchronous fetch, and the ABCancelLoadingImageDataForTag function to cancel an asynchronous fetch.

Availability

Available in Mac OS X v10.2 and later.

Declared In

ABAddressBookC.h

Data Types

ABPersonRef

A reference to an ABPerson object.

typedef struct __ABPerson *ABPersonRef;

Availability

Available in Mac OS X v10.2 and later.

Declared In

ABAddressBookC.h

Constants

Person Properties

CFPlugIn defines the following domain qualifier constants.

CFStringRef kABFirstNameProperty;
CFStringRef kABLastNameProperty;
CFStringRef kABFirstNamePhoneticProperty;
CFStringRef kABLastNamePhoneticProperty;
CFStringRef kABBirthdayProperty;
CFStringRef kABOrganizationProperty;
CFStringRef kABJobTitleProperty;
CFStringRef kABHomePageProperty;
CFStringRef kABURLsProperty;
CFStringRef kABCalendarURIsProperty;
CFStringRef kABEmailProperty;
CFStringRef kABAddressProperty;
CFStringRef kABPhoneProperty;
CFStringRef kABAIMInstantProperty;
CFStringRef kABJabberInstantProperty;
CFStringRef kABMSNInstantProperty;
CFStringRef kABYahooInstantProperty;
CFStringRef kABICQInstantProperty;
CFStringRef kABNoteProperty;
CFStringRef kABMiddleNameProperty;
CFStringRef kABMiddleNamePhoneticProperty;
CFStringRef kABTitleProperty;
CFStringRef kABSuffixProperty;
CFStringRef kABNicknameProperty;
CFStringRef kABMaidenNameProperty;
CFStringRef kABOtherDatesProperty;
CFStringRef kABRelatedNamesProperty;
CFStringRef kABDepartmentProperty;
CFStringRef kABPersonFlags;

Constants

kABFirstNameProperty

First name (string).

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

kABLastNameProperty

Last name (string).

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

kABFirstNamePhoneticProperty

First name phonetic (string).

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

kABLastNamePhoneticProperty

Last name phonetic (string).

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

kABBirthdayProperty

Birth date (date).

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

kABOrganizationProperty

Company name (string)

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

kABJobTitleProperty

Job Title (string).

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

kABHomePageProperty

Home Web page (string). Deprecated in Mac OS X version 10.4.

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

kABURLsProperty

Web pages (multi-string).

Available in Mac OS X v10.4 and later.

Declared in ABGlobals.h

kABCalendarURIsProperty

Calendar URIs(multi-string).

Available in Mac OS X v10.5 and later.

Declared in ABGlobals.h

kABEmailProperty

email(s) (multi-string).

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

kABAddressProperty

Street Addresses (multi-dictionary).

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

kABPhoneProperty

Generic phone number (multi-string).

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

kABAIMInstantProperty

AIM Instant Messaging (multi-string).

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

kABJabberInstantProperty

Jabber Instant Messaging (multi-string).

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

kABMSNInstantProperty

MSN Instant Messaging (multi-string).

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

kABYahooInstantProperty

Yahoo Instant Messaging (multi-string).

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

kABICQInstantProperty

ICQ Instant Messaging (multi-string).

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

kABNoteProperty

Note (string).

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

kABMiddleNameProperty

Middle name (string). Not supported in the AddressBook UI.

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

kABMiddleNamePhoneticProperty

Middle name phonetic (string). Not supported in the AddressBook UI.

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

kABTitleProperty

Title as in “Sir”, “Duke”, “General”, “Cardinal”, or “Lord” (string). Not supported in the AddressBook UI.

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

kABSuffixProperty

Suffix as in “Sr.”, “Jr.”, “III”, or “Esq.” (string). Not supported in the AddressBook UI.

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

kABNicknameProperty

Nickname (string). Not supported in the AddressBook UI.

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

kABMaidenNameProperty

Maiden name (string). Not supported in the AddressBook UI.

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

kABOtherDatesProperty

Dates associated with a person (ABMultiDateProperty containing dates).

Available in Mac OS X v10.3 and later.

Declared in ABGlobals.h

kABRelatedNamesProperty

Names of people related to a person (ABMultiStringProperty containing names).

Available in Mac OS X v10.3 and later.

Declared in ABGlobals.h

kABDepartmentProperty

Department name (string).

Available in Mac OS X v10.3 and later.

Declared in ABGlobals.h

kABPersonFlags

Property that specifies the name ordering and user configuration of a record in the Address Book application.

Available in Mac OS X v10.3 and later.

Declared in ABGlobals.h

Person Flags

The ABPersonFlags property is used to access the following settings:

#define kABShowAsPerson 000000
#define kABShowAsCompany 000001
#define kABShowAsMask 000007
#define kABDefaultNameOrdering 000000
#define kABFirstNameFirst 000040
#define kABLastNameFirst 000020
#define kABNameOrderingMask 000070

Constants

kABShowAsPerson

Record is displayed as a person.

Available in Mac OS X v10.3 and later.

Declared in ABGlobals.h

kABShowAsCompany

Record is displayed as a company.

Available in Mac OS X v10.3 and later.

Declared in ABGlobals.h

kABShowAsMask

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

Available in Mac 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) in the Address Book application.

Available in Mac OS X v10.3 and later.

Declared in ABGlobals.h

kABFirstNameFirst

First name is displayed first in Address Book.

Available in Mac OS X v10.3 and later.

Declared in ABGlobals.h

kABLastNameFirst

Last name is displayed first in Address Book.

Available in Mac OS X v10.3 and later.

Declared in ABGlobals.h

kABNameOrderingMask

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

Available in Mac OS X v10.3 and later.

Declared in ABGlobals.h

Availability

Available in Mac OS X v10.3 and later.

Email Labels

Labels used by the email property.

CFStringRef kABEmailWorkLabel;
CFStringRef kABEmailHomeLabel;

Constants

kABEmailWorkLabel

Work email.

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

kABEmailHomeLabel

Home email.

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

Address Labels

Labels used by the address property.

CFStringRef kABAddressWorkLabel;
CFStringRef kABAddressHomeLabel;

Constants

kABAddressWorkLabel

Work address.

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

kABAddressHomeLabel

Home address.

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

Address Keys

Keys used by the address property.

CFStringRef kABAddressStreetKey;
CFStringRef kABAddressCityKey;
CFStringRef kABAddressStateKey;
CFStringRef kABAddressZIPKey;
CFStringRef kABAddressCountryKey;
CFStringRef kABAddressCountryCodeKey;

Constants

kABAddressStreetKey

Street (string).

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

kABAddressCityKey

City (string).

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

kABAddressStateKey

State (string).

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

kABAddressZIPKey

Zip (string).

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

kABAddressCountryKey

Country (string).

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

kABAddressCountryCodeKey

Country Code (string).

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

Phone Labels

Labels used by the phone property.

CFStringRef kABPhoneWorkLabel;
CFStringRef kABPhoneHomeLabel;
CFStringRef kABPhoneMobileLabel;
CFStringRef kABPhoneMainLabel;
CFStringRef kABPhoneHomeFAXLabel;
CFStringRef kABPhoneWorkFAXLabel;
CFStringRef kABPhonePagerLabel;

Constants

kABPhoneWorkLabel

Work phone.

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

kABPhoneHomeLabel

Home phone.

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

kABPhoneMobileLabel

Cell phone.

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

kABPhoneMainLabel

Main phone.

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

kABPhoneHomeFAXLabel

FAX number.

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

kABPhoneWorkFAXLabel

FAX number.

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

kABPhonePagerLabel

Pager number.

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

Web Page Labels

Labels used by the kABURLsProperty property.

CFStringRef kABHomePageLabel;

Constants

kABHomePageLabel

Web page URL.

Available in Mac OS X v10.4 and later.

Declared in ABGlobals.h

Related Names Labels

Labels used by the related-names property.

CFStringRef kABMotherLabel;
CFStringRef kABFatherLabel;
CFStringRef kABParentLabel;
CFStringRef kABSisterLabel;
CFStringRef kABBrotherFAXLabel;
CFStringRef kABChildLabel;
CFStringRef kABFriendLabel;
CFStringRef kABSpouseLabel;
CFStringRef kABPartnerLabel;
CFStringRef kABAssistantLabel;
CFStringRef kABManagerLabel;

Constants

kABMotherLabel

Mother.

Available in Mac OS X v10.3 and later.

Declared in ABGlobals.h

kABFatherLabel

Father.

Available in Mac OS X v10.3 and later.

Declared in ABGlobals.h

kABParentLabel

Parent.

Available in Mac OS X v10.3 and later.

Declared in ABGlobals.h

kABSisterLabel

Sister.

Available in Mac OS X v10.3 and later.

Declared in ABGlobals.h

kABBrotherLabel

Brother.

Available in Mac OS X v10.3 and later.

Declared in ABGlobals.h

kABChildLabel

Child.

Available in Mac OS X v10.3 and later.

Declared in ABGlobals.h

kABFriendLabel

Friend.

Available in Mac OS X v10.3 and later.

Declared in ABGlobals.h

kABSpouseLabel

Spouse.

Available in Mac OS X v10.3 and later.

Declared in ABGlobals.h

kABPartnerLabel

Partner.

Available in Mac OS X v10.3 and later.

Declared in ABGlobals.h

kABAssistantLabel

Assistant

Available in Mac OS X v10.3 and later.

Declared in ABGlobals.h

kABManagerLabel

Manager.

Available in Mac OS X v10.3 and later.

Declared in ABGlobals.h

Availability

Available in Mac OS X v10.3 and later.

AIM Instant Labels

Labels used by the AIM instance property.

CFStringRef kABAIMWorkLabel;
CFStringRef kABAIMHomeLabel;

Constants

kABAIMWorkLabel

Work AIM.

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

kABAIMHomeLabel

Home AIM.

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

Jabber Instant Labels

Labels used by the Jabber instance property.

CFStringRef kABJabberWorkLabel;
CFStringRef kABJabberHomeLabel;

Constants

kABJabberWorkLabel

Work Jabber.

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

kABJabberHomeLabel

Home Jabber.

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

MSN Instant Labels

Labels used by the MSN instance property.

CFStringRef kABMSNWorkLabel;
CFStringRef kABMSNHomeLabel;

Constants

kABMSNWorkLabel

Work MSN.

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

kABMSNHomeLabel

Home MSN.

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

Yahoo Instant Labels

Labels used by the Yahoo instance property.

CFStringRef kABYahooWorkLabel;
CFStringRef kABYahooHomeLabel;

Constants

kABYahooWorkLabel

Work Yahoo.

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

kABYahooHomeLabel

Home Yahoo.

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

ICQ Instant Labels

Labels used by the ICQ instance property.

CFStringRef kABICQWorkLabel;
CFStringRef kABICQHomeLabel;

Constants

kABICQWorkLabel

Work ICQ.

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

kABICQHomeLabel

Home ICQ.

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

Other Dates Labels

Labels for values contained in ABOtherDatesProperty multi-value properties.

kABAnniversaryLabel

Constants

kABAnniversaryLabel

Anniversary date.

Available in Mac OS X v10.3 and later.

Declared in ABGlobals.h

Availability

Available in Mac OS X v10.3 and later.

Generic Labels

Generic labels that may apply to any multi-value list property.

CFStringRef kABWorkLabel;
CFStringRef kABHomeLabel;
CFStringRef kABOtherLabel;

Constants

kABWorkLabel

All kABXXXXWorkLabel constants are equivalent to this label.

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

kABHomeLabel

All kABXXXXHomeLabel constants are equivalent to this label.

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

kABOtherLabel

Can be used with any multi-value property.

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

Record Type

Constants used to indicate a specific type of record.

CFStringRef kABPersonRecordType;

Constants

kABPersonRecordType

Indicates record of an ABPerson object.

Available in Mac OS X v10.2 and later.

Declared in ABGlobalsC.h

Next Page >

Hide TOC

Last updated: 2006-07-26

Did this document help you?
Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.




	Get information on Apple products. Visit the Apple Store online or at retail locations. 1-800-MY-APPLE Copyright © 2007 Apple Inc. All rights reserved. \| Terms of use \| Privacy Notice