Iphone SDK : Working with the Address Book Database - Property Types, Accessing Single-Value Properties

9/30/2012 2:33:12 AM

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.

Top 10
New App for Women ‘Remix’ Offers Fashion Advice & Style Tips
SG50 Ferrari F12berlinetta : Prancing Horse for Lion City's 50th
The latest Audi TT : New angles for TT
Era of million-dollar luxury cars
Game Review : Hearthstone - Blackrock Mountain
Game Review : Battlefield Hardline
Google Chromecast
Keyboards for Apple iPad Air 2 (part 3) - Logitech Ultrathin Keyboard Cover for iPad Air 2
Keyboards for Apple iPad Air 2 (part 2) - Zagg Slim Book for iPad Air 2
Keyboards for Apple iPad Air 2 (part 1) - Belkin Qode Ultimate Pro Keyboard Case for iPad Air 2
- First look: Apple Watch

- 3 Tips for Maintaining Your Cell Phone Battery (part 1)

- 3 Tips for Maintaining Your Cell Phone Battery (part 2)
Popular Tags
Video Tutorail Microsoft Access Microsoft Excel Microsoft OneNote Microsoft PowerPoint Microsoft Project Microsoft Visio Microsoft Word Active Directory Exchange Server Sharepoint Sql Server Windows Server 2008 Windows Server 2012 Windows 7 Windows 8 Adobe Flash Professional Dreamweaver Adobe Illustrator Adobe Photoshop CorelDRAW X5 CorelDraw 10 windows Phone 7 windows Phone 8 Iphone