iOS Reference Library Apple Developer
Search

ABRecord Reference

Derived from
CFTypeRef
Framework
AddressBook/AddressBook.h
Declared in
ABRecord.h

Overview

The ABRecord opaque type (whose objects are known as 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

Managing Property Values

Functions

ABRecordCopyCompositeName

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

CFStringRef ABRecordCopyCompositeName (
   ABRecordRef record
);
Parameters
record

The record whose name is being returned.

Return Value
Discussion

The behavior of this function is not defined for source records.

Availability
Declared In
ABRecord.h

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 is being returned. See properties in “Constants” in ABPerson Reference and “Constants” in ABGroup Reference.

Return Value

The value of property in record.

Availability
Declared In
ABRecord.h

ABRecordGetRecordID

Returns the unique ID of a record.

ABRecordID ABRecordGetRecordID (
   ABRecordRef record
);
Parameters
record

The record whose ID is being returned.

Return Value

The unique ID of record when the record exists in the Address Book database.

kABRecordInvalidID when the record hasn’t been saved to the database.

Availability
Declared In
ABRecord.h

ABRecordGetRecordType

Returns the type of a record.

ABRecordType ABRecordGetRecordType (
   ABRecordRef record
);
Parameters
record

The record whose type is being returned.

Return Value

The record type of record, which can be one of these:

Availability
See Also
Declared In
ABRecord.h

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 is being removed. See properties in “Constants” in ABPerson Reference and “Constants” in ABGroup Reference.

error

On failure, information about its cause.

Return Value

true on success, false otherwise.

Availability
Declared In
ABRecord.h

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 is being 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.

Return Value

true when successful, false otherwise.

Availability
Declared In
ABRecord.h

Data Types

ABRecordRef

Reference to a record.

typedef CFTypeRef ABRecordRef;
Availability
Declared In
ABRecord.h

ABRecordID

Integer that identifies a record.

typedef int32_t ABRecordID;
Discussion

Valid record IDs are positive integers.

See “Invalid Record ID”.

Availability
Declared In
ABRecord.h

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

Availability
Declared In
ABRecord.h

ABRecordType

Integer that identifies a record type.

typedef uint32_t ABRecordType;
Discussion

See “Record Types”.

Availability
Declared In
ABRecord.h

ABPropertyType

Integer that identifies a record property type.

typedef uint16_t ABPropertyType;
Discussion

See “Record Property Types”.

Availability
Declared In
ABRecord.h

Constants

Record Types

These constants identify record types.

enum {
    kABPersonType = 0,
    kABGroupType  = 1
};
Constants
kABPersonType

Person record.

Available in iOS 2.0 and later.

Declared in ABRecord.h.

kABGroupType

Group record.

Available in iOS 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 iOS 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 iOS 2.0 and later.

Declared in ABRecord.h.

kABStringPropertyType

String property. Returned as a CFStringRef object.

Available in iOS 2.0 and later.

Declared in ABRecord.h.

kABIntegerPropertyType

Integer property. Returned as a CFNumberRef object.

Available in iOS 2.0 and later.

Declared in ABRecord.h.

kABRealPropertyType

Real property. Returned as a CFNumberRef object.

Available in iOS 2.0 and later.

Declared in ABRecord.h.

kABDateTimePropertyType

Date-time property. Returned as a CFDateRef object.

Available in iOS 2.0 and later.

Declared in ABRecord.h.

kABDictionaryPropertyType

Dictionary property. Returned as a CFDictionaryRef object.

Available in iOS 2.0 and later.

Declared in ABRecord.h.

kABMultiStringPropertyType

Multistring property. Returned as an ABMultiValueIdentifier of CFStringRef objects.

Available in iOS 2.0 and later.

Declared in ABRecord.h.

kABMultiIntegerPropertyType

Multiinteger property. Returned as an ABMultiValueIdentifier of CFNumberRef objects.

Available in iOS 2.0 and later.

Declared in ABRecord.h.

kABMultiRealPropertyType

Multireal property. Returned as an ABMultiValueIdentifier of CFNumberRef objects.

Available in iOS 2.0 and later.

Declared in ABRecord.h.

kABMultiDateTimePropertyType

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

Available in iOS 2.0 and later.

Declared in ABRecord.h.

kABMultiDictionaryPropertyType

Multidictionary property. Returned as an ABMultiValueIdentifier of CFDictionaryRef objects.

Available in iOS 2.0 and later.

Declared in ABRecord.h.

Discussion

See ABPropertyType.

Invalid Values

These macros identify invalid values 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 iOS 2.0 and later.

Declared in ABRecord.h.

kABPropertyInvalidID

Indicates an invalid value for a property ID.

Available in iOS 3.0 and later.

Declared in ABRecord.h.



Last updated: 2010-05-18

Did this document help you? Yes It's good, but... Not helpful...