1. Property Types
There are ten record property
types available to you. Five of those are for single-value properties
and the other five are for multi-value properties.
String. The single-value property type is defined as kABStringPropertyType while the multi-value property type is defined as kABMultiStringPropertyType. The value retrieved from a single-value property is of type CFStringRef which is equivalent to NSString*. The values retrieved from multi-value property are all of type CFStringRef.
Integer. The single-value is referred to using kABIntegerPropertyType while the multi-value is referred to using kABMultiIntegerPropertyType. The value retrieved from a single-value property is of type CFNumberRef which is equivalent to NSNumber*. Thevalues retrieved from multi-value property are all of type NSNumber*.
Date. kABDateTimePropertyType is used for single-value and kABMultiDateTimePropertyType is used for multi-value. The values are of type CFDateRef or NSDate*.
Real. kABRealPropertyType is used for single-value and kABMultiRealPropertyType for multi-value properties. The values are of type CFNumberRef or NSNumber*.
Dictionary. kABDictionaryPropertyType is used for single-value and kABMultiDictionaryPropertyType for multi-value properties. The values are of type CFDictionaryRef or NSDictionary*.
2. Accessing Single-Value Properties
In this section, we discuss the functions used to manipulate single-value properties for person and group records.
2.1. Retrieving single-value properties
To retrieve the value for a single-value property, you need to copy that value from a record. The function ABRecordCopyValue is used for this purpose. The function is declared as follows:
CFTypeRef ABRecordCopyValue(ABRecordRef record, ABPropertyID property);
The first parameter of
this function is the record you want to retrieve the specific property
value from, and the second parameter is the property identifier. In the
documentation, you can find out what predefined constant identifiers
exist for a given property. For example, the first name of a person has
the property identifier kABPersonFirstNameProperty. The return value depends on the property being retrieved. The core foundation (hence the CF prefix) framework uses the CFTypeRef generic reference as a pointer to any core foundation object. As you might have guessed, it's declared as follows:
typedef const void * CFTypeRef;
The value retrieved is copied. Which means that you are responsible for its release. You release this value using CFRelease function. You can also release it by assigning the value to a Cocoa variable with an equivalent type and sending a release message to it. If you would rather work with the Foundation Framework (classes prefixed by NS), you can cast the retrieved object to the Cocoa type to disable warnings.
Enough talk. Let's see how
we can retrieve the first name of a person. The following retrieves that
value and stores it in the variable firstName.
NSString *firstName =
(NSString*)ABRecordCopyValue(person, kABPersonFirstNameProperty);
To see a list of property identifiers for a person record, command-double-click in XCode the kABPersonFirstNameProperty token.
Let's see another example.
Suppose we have a group object and we want to retrieve the name of the
representative group. The following shows how we can do that:
NSString *groupName =
(NSString*)ABRecordCopyValue(group, kABGroupNameProperty);
Again, command-double-click the kABGroupNameProperty to see other property identifiers for a group record. You will find none. The kABGroupNameProperty is the only predefined property for a group.
The following are some of the single-value property identifiers defined for a person record:
kABPersonLastNameProperty. Returns a string value representing the last name of the person.
kABPersonMiddleNameProperty. Returns a string value representing the middle name of the person.
kABPersonNicknameProperty. Returns a string value representing the nickname of the person.
kABPersonBirthdayProperty. Returns a date value representing the birthday of the person.
kABPersonNoteProperty. Returns a string value for the note associated with the person.
2.2. Setting single-value properties
To change the value for a given property, you use the ABRecordSetValue function. The function is declared as follows:
bool ABRecordSetValue(ABRecordRef record, ABPropertyID property,
CFTypeRef value, CFErrorRef* error
);
You pass in the record object, the property identifier you want to change, the value you want to set, and a reference to an NSError object. The function returns YES if successful and NO, otherwise.
For example, to change the first name of the record in person to Barack, use:
ABRecordSetValue(person, kABPersonFirstNameProperty, @"Barack", NULL);
Here, we are passing NULL for the NSError
reference as we are not interested in dealing with errors. Of course,
you should always write code that does deal with potential errors.
To set the group name for a group record, you can write something like the following:
ABRecordSetValue(group, kABGroupNameProperty, @"Presidents", NULL);
Again, notice that we are using the same function in dealing with group and person records.
