---

ABRecord C Reference

Overview

ABRecord is an abstract opaque type providing a common interface to and defining common properties for all records in the Address Book database. A property is a field in the database record such as the first or last name of a person record. ABRecord defines the types of properties supported, and basic functions for getting, setting, and removing property values.

Use ABRecordCopyValue to get a record’s property value, use ABRecordSetValue to set a value, and ABRecordRemoveValue to remove a value.

Each record in the Address Book database has a corresponding unique ID obtained using the ABRecordCopyUniqueId function. The unique ID is used by other functions in the AddressBook framework.

You can check if a record is read-only by using the ABRecordIsReadOnly function.

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

Functions

ABRecordCopyRecordType

Returns the type of the given record.

CFStringRef ABRecordCopyRecordType (
   ABRecordRef record
);

Parameters

record

The record whose type you wish to obtain.

Return Value

The type of record, one of the kAB...RecordType constants. You are responsible for releasing this object.

Availability

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

Declared In

ABAddressBookC.h

ABRecordCopyUniqueId

Returns the unique ID of the receiver.

CFStringRef ABRecordCopyUniqueId (
   ABRecordRef record
);

Parameters

record

The record whose unique ID you wish to obtain.

Return Value

The unique ID corresponding to record. You are responsible for releasing this object.

Availability

• Available in Mac OS X 10.2 and later.

Declared In

ABAddressBookC.h

ABRecordCopyValue

Returns the value of the given property.

CFTypeRef ABRecordCopyValue (
   ABRecordRef record,
   CFStringRef property
);

Parameters

record

The record whose value you wish to obtain.

property

The property name in record whose value you wish to obtain. May be a pre-defined or program-defined property. See Common Properties for a list of properties all records have, and specific ABRecord derived opaque types for any additional properties.

Return Value

The value for property in record. The type of the returned value depends on the property type (see Property Types for a list of possible property types). You are responsible for releasing this object.

Availability

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

Declared In

ABAddressBookC.h

ABRecordCreateCopy

Returns a copy of the given record.

ABRecordRef ABRecordCreateCopy (
   ABRecordRef record
);

Parameters

record

The record you wish to copy.

Return Value

A copy of the specified ABRecordRef.

Availability

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

Declared In

ABAddressBookC.h

ABRecordIsReadOnly

Returns whether or not the record is read-only.

bool ABRecordIsReadOnly (
   ABRecordRef record
);

Parameters

record

The record you wish to check.

Return Value

true if record is read-only, false otherwise.

Availability

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

Declared In

ABAddressBookC.h

ABRecordRemoveValue

Removes the value of the given property.

bool ABRecordRemoveValue (
   ABRecordRef record,
   CFStringRef property
);

Parameters

record

The record whose value you wish to remove.

property

The property name in record whose value you wish to remove. May be a pre-defined or program-defined property. See Common Properties for a list of properties all records have, and specific ABRecord derived opaque types for any additional properties.

Return Value

The value for property in record. The type of the returned value depends on the property type (see Property Types for a list of possible property types). You are responsible for releasing this object.

Availability

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

Declared In

ABAddressBookC.h

ABRecordSetValue

Sets the value of a given property for a record.

bool ABRecordSetValue (
   ABRecordRef record,
   CFStringRef property,
   CFTypeRef value
);

Parameters

record

The record you wish to modify.

property

The property whose value you wish to set. May be a pre-defined or program-defined property. See Common Properties for a list of properties all records have, and specific ABRecord derived opaque types for any additional properties. If NULL, this function raises an exception.

value

The new value for property in record. If NULL or not the correct type, this function raises an exception.

Return Value

If property is a multi-value list property, this method checks to see if the values in the multi-value list are the same type. If the multi-value list contains mixed types, this method returns false. Returns true if successful, false otherwise.

Availability

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

Declared In

ABAddressBookC.h

Data Types

ABRecordRef

A reference to an ABRecord object or any of its derived opaque types.

typedef void *ABRecordRef;

Availability

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

Declared In

ABAddressBookC.h

Constants

Common Properties

Properties common to all record types.

CFStringRef kABUIDProperty;
CFStringRef kABCreationDateProperty;
CFStringRef kABModificationDateProperty

Constants

kABUIDProperty

The UID property.

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

kABCreationDateProperty

Creation date (when first saved).

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

kABModificationDateProperty

Modification date (when last saved).

Available in Mac OS X v10.2 and later.

Declared in ABGlobals.h

---