ABRecord Reference

Overview

The ABRecord opaque type (objects of which are known as a records) provides a common interface to the records in the Address Book database. It defines common properties for all records. A property is a field in a record such as the first or last name of a person record.

Each record in the Address Book database has a unique ID, which you obtain using the ABRecordGetRecordID function.

Functions by Task

Getting Record Information

• ABRecordGetRecordID
• ABRecordGetRecordType

Managing Property Values

• ABRecordSetValue
• ABRecordCopyValue
• ABRecordRemoveValue
• ABRecordCopyCompositeName

Functions

ABRecordCopyCompositeName

Returns an appropriate, human-friendly name for the record.

CFStringRef ABRecordCopyCompositeName (
   ABRecordRef record
);

Parameters

record

The record whose name to return.

ABRecordCopyValue

Returns the value of a record property.

CFTypeRef ABRecordCopyValue (
   ABRecordRef record,
   ABPropertyID property
);

Parameters

record

The record containing the property in question.

property

The property of record whose value to return. See properties in “Constants” in ABPerson Reference and “Constants” in ABGroup Reference.

ABRecordGetRecordID

Returns the unique ID of a record.

ABRecordID ABRecordGetRecordID (
   ABRecordRef record
);

Parameters

record

The record whose ID to return.

ABRecordGetRecordType

Returns the type of a record.

ABRecordType ABRecordGetRecordType (
   ABRecordRef record
);

Parameters

record

The record whose type to return.

See Also

• ABPersonCreate
• ABGroupCreate

ABRecordRemoveValue

Removes the value of a record property.

bool ABRecordRemoveValue (
   ABRecordRef record,
   ABPropertyID property,
   CFErrorRef *error
);

Parameters

record

The record with the property in question.

property

The property, in record, whose value to remove. See properties in “Constants” in ABPerson Reference and “Constants” in ABGroup Reference.

error

On failure, information about its cause.

ABRecordSetValue

Sets the value of a record property.

bool ABRecordSetValue (
   ABRecordRef record,
   ABPropertyID property,
   CFTypeRef value,
   CFErrorRef *error
);

Parameters

record

The record containing the property in question.

property

The property whose value to set. See properties in “Constants” in ABPerson Reference and “Constants” in ABGroup Reference.

value

The new value. Pass NULL to remove the property from record.

error

On failure, information about its cause.

Data Types

ABRecordRef

Reference to a record.

typedef CFTypeRef ABRecordRef;

ABRecordID

Integer that identifies a record.

typedef int32_t ABRecordID;

Discussion

Valid record IDs are positive integers.

See “Invalid Record ID”.

ABPropertyID

Integer that identifies a record property.

typedef int32_t ABPropertyID;

Discussion

See properties listed in “Constants” in ABPerson Reference and “Constants” in ABGroup Reference

ABRecordType

Integer that identifies a record type.

typedef uint32_t ABRecordType;

Discussion

See “Record Types”.

ABPropertyType

Integer that identifies a record property type.

typedef uint16_t ABPropertyType;

Discussion

See “Record Property Types”.

Constants

Record Types

These constants identify record types.

enum {
    kABPersonType = 0,
    kABGroupType  = 1
};

Constants

kABPersonType

Person record.

Available in iPhone OS 2.0 and later.

Declared in ABRecord.h.

kABGroupType

Group record.

Available in iPhone OS 2.0 and later.

Declared in ABRecord.h.

Discussion

See ABRecordType.

Multivalue Properties

Indicates a multivalue property.

#define kABMultiValueMask (1 << 8)

Constants

kABMultiValueMask

Indicates a multivalue property.

Available in iPhone OS 2.0 and later.

Declared in ABRecord.h.

Record Property Types

These constants identify record property types.

enum {
   kABInvalidPropertyType         = 0x0,
   kABStringPropertyType          = 0x1,
   kABIntegerPropertyType         = 0x2,
   kABRealPropertyType            = 0x3,
   kABDateTimePropertyType        = 0x4,
   kABDictionaryPropertyType      = 0x5,
   kABMultiStringPropertyType     = kABMultiValueMask | kABStringPropertyType
   kABMultiIntegerPropertyType    = kABMultiValueMask | kABIntegerPropertyType
   kABMultiRealPropertyType       = kABMultiValueMask | kABRealPropertyType
   kABMultiDateTimePropertyType   = kABMultiValueMask | kABDateTimePropertyType
   kABMultiDictionaryPropertyType = kABMultiValueMask | kABDictionaryPropertyType
};

Constants

kABInvalidPropertyType

Invalid property.

Available in iPhone OS 2.0 and later.

Declared in ABRecord.h.

kABStringPropertyType

String property. Returned as CFStringRef object.

Available in iPhone OS 2.0 and later.

Declared in ABRecord.h.

kABIntegerPropertyType

Integer property. Returned as a CFNumberRef object.

Available in iPhone OS 2.0 and later.

Declared in ABRecord.h.

kABRealPropertyType

Real property. Returned as a CFNumberRef object.

Available in iPhone OS 2.0 and later.

Declared in ABRecord.h.

kABDateTimePropertyType

Date-time property. Returned as a CFDateRef object.

Available in iPhone OS 2.0 and later.

Declared in ABRecord.h.

kABDictionaryPropertyType

Dictionary property. Returned as a CFDictionaryRef object.

Available in iPhone OS 2.0 and later.

Declared in ABRecord.h.

kABMultiStringPropertyType

Multistring property. Returned as an ABMultiValueIdentifier of CFStringRef objects.

Available in iPhone OS 2.0 and later.

Declared in ABRecord.h.

kABMultiIntegerPropertyType

Multiinteger property. Returned as an ABMultiValueIdentifier of CFNumberRef objects.

Available in iPhone OS 2.0 and later.

Declared in ABRecord.h.

kABMultiRealPropertyType

Multireal property. Returned as an ABMultiValueIdentifier of CFNumberRef objects.

Available in iPhone OS 2.0 and later.

Declared in ABRecord.h.

kABMultiDateTimePropertyType

Multi–date-time property. Returned as an ABMultiValueIdentifier of CFDateRef objects.

Available in iPhone OS 2.0 and later.

Declared in ABRecord.h.

kABMultiDictionaryPropertyType

Multidictionary property. Returned as an ABMultiValueIdentifier of CFDictionaryRef objects.

Available in iPhone OS 2.0 and later.

Declared in ABRecord.h.

Discussion

See ABPropertyType.

Invalid Values

These macros identify invalid for record and property identifiers.

#define kABRecordInvalidID -1
#define kABPropertyInvalidID -1

Constants

kABRecordInvalidID

Records with this ID have not been saved to the Address Book database.

Available in iPhone OS 2.0 and later.

Declared in ABRecord.h.

kABPropertyInvalidID

Indicates an invalid value for a property ID.

Available in iPhone OS 3.0 and later.

Declared in ABRecord.h.

---