ABPerson Reference

Framework	AddressBook/AddressBook.h
Declared in	ABPerson.h

Overview

The ABPerson opaque type (whose objects are known as person records) represents a person record. Person records store information about a person, such as first name, last name, address, email, phone number, and so on.

Person records don’t necessarily have to be stored on the Address Book database or an address book. You can use person records as a way to group contact information in memory and present it to the user through, for example, a person view controller (ABPersonViewController).

Functions by Task

Creating Persons

Sorting Persons

Getting Person Property Information

Managing Pictures

Accessing the Persons in an Address Book

Getting Name Format and Sort Preferences

Functions

ABAddressBookCopyPeopleWithName

Performs a prefix search on the composite names of people in an address book and returns an array of persons that match the search criteria.

CFArrayRef ABAddressBookCopyPeopleWithName (
   ABAddressBookRef addressBook,
   CFStringRef name
);

Parameters

addressBook: The address book in which to search.
prefixQuery: The search terms. Examples: "Mary", "Smi*", "Hu Yan".

Return Value

Array containing person records (ABRecordRef objects) that match prefixQuery.

Availability

Available in iPhone OS 2.0 and later.

Declared In

ABPerson.h

ABAddressBookGetPersonWithRecordID

Returns the person record with a given record ID.

ABRecordRef ABAddressBookGetPersonWithRecordID (
   ABAddressBookRef addressBook,
   ABRecordID recordID
);

Parameters

addressBook: The address book in which to search for recordID.
recordID: The record identifier to seek in addressBook.

Return Value

If found, the person record with recordID as its identifier, otherwise NULL.

Availability

Available in iPhone OS 2.0 and later.

Declared In

ABPerson.h

ABPersonComparePeopleByName

Indicates how two person records get sorted.

CFComparisonResult ABPersonComparePeopleByName (
   ABRecordRef person1,
   ABRecordRef person2,
   ABPersonSortOrdering ordering
);

Parameters

person1: The first person.
person2: The second person.
ordering: Indicates whether to sort by first name or by last name. See “Sort Order”.

Return Value

kCFCompareLessThan when person1 goes before person2.
kCFCompareEqualTo when person1 and person2 have the same name.
kCFCompareGreaterThan when person1 goes after person2.

Availability

Available in iPhone OS 2.0 and later.

Declared In

ABPerson.h

ABPersonCopyImageData

Returns the picture for a person.

CFDataRef ABPersonCopyImageData (
   ABRecordRef person
);

Parameters

person: The person record whose picture to return.

Return Value

The picture for person. NULL when the person has no picture.

Availability

Available in iPhone OS 2.0 and later.

Declared In

ABPerson.h

ABPersonCopyLocalizedPropertyName

Returns the localized name of a person property

CFStringRef ABPersonCopyLocalizedPropertyName (
   ABPropertyID property
);

Parameters

property: The person property whose localized name to return.

Return Value

The localized name of property.

Availability

Available in iPhone OS 2.0 and later.

Declared In

ABPerson.h

ABPersonCreate

Creates a person.

ABRecordRef ABPersonCreate (
   void
);

Return Value

New person.

Discussion

To be added to the Address Book database, you must add the newly created person to an address book using ABAddressBookAddRecord.

Availability

Available in iPhone OS 2.0 and later.

Declared In

ABPerson.h

ABPersonGetCompositeNameFormat

Returns the person-name display format.

ABPersonCompositeNameFormat ABPersonGetCompositeNameFormat (
   void
);

Return Value

A constant indicating person-name display order; see “Composite Name Format”.

Availability

Available in iPhone OS 2.0 and later.

Declared In

ABPerson.h

ABPersonGetSortOrdering

Returns the user’s sort ordering preference for lists of persons.

ABPersonSortOrdering ABPersonGetSortOrdering (
   void
);

Return Value

The user’s sort ordering preference:

Sort by first name
Sort by last name

Discussion

See “Sort Order”.

Availability

Available in iPhone OS 2.0 and later.

Declared In

ABPerson.h

ABPersonGetTypeOfProperty

Returns the type of a person property.

ABPropertyType ABPersonGetTypeOfProperty (
   ABPropertyID property
);

Parameters

property: The person property whose type to return.

Return Value

The type of property.

Availability

Available in iPhone OS 2.0 and later.

Declared In

ABPerson.h

ABPersonHasImageData

Indicates whether a person has a picture.

bool ABPersonHasImageData (
   ABRecordRef person
);

Parameters

person: The person record in question.

Return Value

true when person has a picture, false otherwise.

Availability

Available in iPhone OS 2.0 and later.

Declared In

ABPerson.h

ABPersonRemoveImageData

Removes a person’s picture.

bool ABPersonRemoveImageData (
   ABRecordRef person,
   CFErrorRef *error
);

Parameters

person: The person record whose picture to remove.
error: On error, information about the cause.

Return Value

true when successful, false otherwise.

Availability

Available in iPhone OS 2.0 and later.

Declared In

ABPerson.h

ABPersonSetImageData

Sets a person’s picture.

bool ABPersonSetImageData (
   ABRecordRef person,
   CFDataRef imageData,
   CFErrorRef *error
);

Parameters

person: The person record whose picture to set.
imageData: The picture to assign to person.
error: On error, information about the cause.

Return Value

true when successful, false otherwise.

Availability

Available in iPhone OS 2.0 and later.

Declared In

ABPerson.h

Data Types

ABPersonSortOrdering

Indicates a person sort ordering.

typedef uint32_t ABPersonSortOrdering;

Discussion

See “Sort Order”.

Availability

Available in iPhone OS 2.0 and later.

Declared In

ABPerson.h

ABPersonCompositeNameFormat

Indicates a person-name display format.

typedef uint32_t ABPersonCompositeNameFormat;

Discussion

See “Composite Name Format”.

Availability

Available in iPhone OS 2.0 and later.

Declared In

ABPerson.h

Constants

Special Considerations

The value of these constants is undefined until one of the following has been called: ABAddressBookCreate, ABPersonCreate, ABGroupCreate.

Sort Order

These constants identify sort order for person lists.

enum {
   kABPersonSortByFirstName = 0,
   kABPersonSortByLastName  = 1
};

Constants

kABPersonSortByFirstName

Order by first name.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonSortByLastName

Order by last name.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

Discussion

See ABPersonSortOrdering and ABPersonGetSortOrdering.

Composite Name Format

These constants identify the format to use for a person’s composite name order for persons.

enum  {
   kABPersonCompositeNameFormatFirstNameFirst = 0,
   kABPersonCompositeNameFormatLastNameFirst  = 1
};

Constants

kABPersonCompositeNameFormatFirstNameFirst

First name first.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonCompositeNameFormatLastNameFirst

Last name first.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

Discussion

See ABPersonCompositeNameFormat and ABRecordCopyCompositeName.

Personal Information Properties

These constants identify person properties used to store personal information.

const ABPropertyID kABPersonFirstNameProperty;
const ABPropertyID kABPersonLastNameProperty;
const ABPropertyID kABPersonMiddleNameProperty;
const ABPropertyID kABPersonPrefixProperty;
const ABPropertyID kABPersonSuffixProperty;
const ABPropertyID kABPersonNicknameProperty;
const ABPropertyID kABPersonFirstNamePhoneticProperty;
const ABPropertyID kABPersonLastNamePhoneticProperty;
const ABPropertyID kABPersonMiddleNamePhoneticProperty;
const ABPropertyID kABPersonOrganizationProperty;
const ABPropertyID kABPersonJobTitleProperty;
const ABPropertyID kABPersonDepartmentProperty;
const ABPropertyID kABPersonEmailProperty;
const ABPropertyID kABPersonBirthdayProperty;
const ABPropertyID kABPersonNoteProperty;
const ABPropertyID kABPersonCreationDateProperty;
const ABPropertyID kABPersonModificationDateProperty;

Constants

kABPersonFirstNameProperty

First name. Type: kABStringPropertyType.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonLastNameProperty

Last name. Type: kABStringPropertyType.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonMiddleNameProperty

Middle name. Type: kABStringPropertyType.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonPrefixProperty

Prefix (“Sir,” “Duke,” “General”). Type: kABStringPropertyType.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonSuffixProperty

Suffix (“Jr.,” “Sr.,” “III”). Type: kABStringPropertyType.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonNicknameProperty

Nickname. Type: kABStringPropertyType.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonFirstNamePhoneticProperty

First name phonetic. Type: kABStringPropertyType.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonLastNamePhoneticProperty

Last name phonetic. Type: kABStringPropertyType.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonMiddleNamePhoneticProperty

Middle name phonetic. Type: kABStringPropertyType.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonOrganizationProperty

Organization name. Type: kABStringPropertyType.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonJobTitleProperty

Job title. Type: kABStringPropertyType.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonDepartmentProperty

Department. Type: kABStringPropertyType.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonEmailProperty

Email address. Type: kABMultiStringPropertyType.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonBirthdayProperty

Birthday. Type: kABDateTimePropertyType.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonNoteProperty

Note. Type: kABStringPropertyType.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonCreationDateProperty

Creation date. Type: kABDateTimePropertyType.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonModificationDateProperty

Modification date. Type: kABDateTimePropertyType.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

Address Property

These constants implement the person address property (a multivalue property of type kABMultiDictionaryPropertyType) and the labels used to identify each of the property’s values.

const ABPropertyID kABPersonAddressProperty;
const CFStringRef kABPersonAddressStreetKey;
const CFStringRef kABPersonAddressCityKey;
const CFStringRef kABPersonAddressStateKey;
const CFStringRef kABPersonAddressZIPKey;
const CFStringRef kABPersonAddressCountryKey;
const CFStringRef kABPersonAddressCountryCodeKey;

Constants

kABPersonAddressProperty

Identifier for the address multivalue property.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonAddressStreetKey

Street.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonAddressCityKey

City.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonAddressStateKey

State.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonAddressZIPKey

Zip code.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonAddressCountryKey

Country.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonAddressCountryCodeKey

Country code.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

Discussion

These are the country codes ABPerson supports:

ar: Argentina
at: Austria
au: Australia
ba: Bosnia, Herzegovina
bg: Bulgaria
bh: Bahrain
br: Brazil
ca: Canada
ch: Switzerland
cn: China
cz: Czech
de: Germany
dk: Denmark
eg: Egypt
es: Spain
fi: Finland
fr: France
gr: Greece
gl: Greenland
hk: Hong Kong
hr: Croatia
hu: Hungary
ie: Ireland
il: Israel
id: Indonesia
in: India
is: Iceland
it: Italy
jp: Japan
kr: South Korea
kw: Kuwait
lb: Lebanon
lu: Luxembourg
mk: Macedonia
mx: Mexico
nl: Netherlands
no: Norway
nz: New Zealand
om: Oman
pl: Poland
pt: Portugal
qa: Qatar
ro: Romania
ru: Russian Federation
sa: Saudi Arabia
se: Sweden
sg: Singapore
si: Slovenia
sk: Slovakia
sy: Syrian Arab Republic
tw: Taiwan
tr: Turkey
ua: Ukraine
uk: United Kingdom
us: United States
ye: Yemen
za: South Africa

Date Properties

These constants implement the person dates property (a multivalue property of type kABMultiDateTimePropertyType) and the labels used to identify each of the property’s values.

const ABPropertyID kABPersonDateProperty;
const CFStringRef kABPersonAnniversaryLabel;

Constants

kABPersonDateProperty

Identifier for the dates multivalue property.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonAnniversaryLabel

Birthdate.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

Person Type Property

These constants implement the person type property (a property of type kABIntegerPropertyType), which indicates whether a person record represents a human being or an organization.

const ABPropertyID kABPersonKindProperty;
const CFNumberRef kABPersonKindPerson;
const CFNumberRef kABPersonKindOrganization;

Constants

kABPersonKindProperty

Identifier for the type property.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonKindPerson

Identifies a person.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonKindOrganization

Identifies an organization.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

Phone Number Property

These constants implement the person phone number property (a multivalue property of type kABMultiStringPropertyType) and the labels used to identify each of the property’s values.

const ABPropertyID kABPersonPhoneProperty;
const CFStringRef kABPersonPhoneMobileLabel;
const CFStringRef kABPersonPhoneIPhoneLabel;
const CFStringRef kABPersonPhoneMainLabel;
const CFStringRef kABPersonPhoneHomeFAXLabel;
const CFStringRef kABPersonPhoneWorkFAXLabel;
const CFStringRef kABPersonPhonePagerLabel;

Constants

kABPersonPhoneProperty

Identifier for the phone number multivalue property.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonPhoneMobileLabel

Mobile phone number.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonPhoneIPhoneLabel

iPhone number.

Available in iPhone OS 3.0 and later.

Declared in ABPerson.h.

kABPersonPhoneMainLabel

Main phone number.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonPhoneHomeFAXLabel

Fax phone number.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonPhoneWorkFAXLabel

Work phone number.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonPhonePagerLabel

Pager phone number.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

Instant Message Property

These constants implement the person instant message property (a multivalue property of type kABMultiDictionaryPropertyType) and the labels used to identify each of the property’s values.

const ABPropertyID kABPersonInstantMessageProperty;
const CFStringRef kABPersonInstantMessageServiceKey;
const CFStringRef kABPersonInstantMessageServiceYahoo;
const CFStringRef kABPersonInstantMessageServiceJabber;
const CFStringRef kABPersonInstantMessageServiceMSN;
const CFStringRef kABPersonInstantMessageServiceICQ;
const CFStringRef kABPersonInstantMessageServiceAIM;
const CFStringRef kABPersonInstantMessageUsernameKey;

Constants

kABPersonInstantMessageProperty

Identifier for the instant message multivalue property.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonInstantMessageServiceKey

Instant message service.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonInstantMessageServiceYahoo

Yahoo instance message service.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonInstantMessageServiceJabber

Jabber instant message service.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonInstantMessageServiceMSN

MSN instant message service.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonInstantMessageServiceICQ

ICQ instant message service.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonInstantMessageServiceAIM

AIM instant message service

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonInstantMessageUsernameKey

Instant message service username.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

Discussion

An instant message multivalue property may have the following structure.

kABPersonInstantMessageServiceKey
- Yahoo
- <username>@yahoo.com
kABPersonInstantMessageServiceKey
- AIM
- <username>@mac.com

URL Property

This constant implements the person URL property (a multivalue property of type kABMultiStringPropertyType) and the label used to identify the property’s sole value.

const ABPropertyID kABPersonURLProperty;
const CFStringRef kABPersonHomePageLabel;

Constants

kABPersonURLProperty

Identifier for the URL multivalue property.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonHomePageLabel

Home page.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

Related Name Property

These constants implement the person related name property (a multivalue property of type kABMultiStringPropertyType) and the labels used to identify each of the property’s values.

const ABPropertyID kABPersonRelatedNamesProperty;
const CFStringRef kABPersonMotherLabel;
const CFStringRef kABPersonFatherLabel;
const CFStringRef kABPersonParentLabel;
const CFStringRef kABPersonSisterLabel;
const CFStringRef kABPersonBrotherLabel;
const CFStringRef kABPersonChildLabel;
const CFStringRef kABPersonFriendLabel;
const CFStringRef kABPersonSpouseLabel;
const CFStringRef kABPersonPartnerLabel;
const CFStringRef kABPersonManagerLabel;
const CFStringRef kABPersonAssistantLabel;

Constants

kABPersonRelatedNamesProperty

Identifier for the related name multivalue property.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonMotherLabel

Mother.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonFatherLabel

Father.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonParentLabel

Parent.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonSisterLabel

Sister.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonBrotherLabel

Brother.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonChildLabel

Child.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonFriendLabel

Friend.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonSpouseLabel

Spouse.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonPartnerLabel

Partner.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonManagerLabel

Manager.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABPersonAssistantLabel

Assistant.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

Generic Property Labels

These constants contain generic property labels.

const CFStringRef kABWorkLabel;
const CFStringRef kABHomeLabel;
const CFStringRef kABOtherLabel;

Constants

kABWorkLabel

“Work” label.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABHomeLabel

“Home” label.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

kABOtherLabel

“Other” label.

Available in iPhone OS 2.0 and later.

Declared in ABPerson.h.

Last updated: 2009-05-26

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.