What is ABMultiValueAddValueAndLabel outIdentifier?

Question

I've been working around with this AddressBook method and I don't get to understand what is the outIdentifier used for:

bool ABMultiValueAddValueAndLabel (
   ABMutableMultiValueRef multiValue,
   CFTypeRef value,
   CFStringRef label,
   ABMultiValueIdentifier *outIdentifier
);

The docs don't clear things for me:

outIdentifier

The address at which to place the identifier of the added value. Pass NULL to ignore the identifier.

Do someone know what is this parameter used for?

Thanks in advance!

Answer 1

I did a little research about this, and am half surprised about this strange parameter.

So I went into Xcode, imported the framework, and found the documentation for the ABMultiValueIdentifier. This is it:

ABMultiValueIdentifier

Identifies multivalue properties.

typedef int32_t ABMultiValueIdentifier;

Discussion See “Invalid Multivalue-Property Identifier”.

Availability Available in iOS 2.0 and later. Declared In ABMultiValue.h

The first thing I notice is that it is of type int32_t. This means that it is indeed a pointer to the value (also notice the *outIdentifier)

Underneath is the definition of a constant, kABMultiValueInvalidIdentifier. The documentation says,

This preprocessor definition identifies an multivalue property with values whose type does not match its declared type.

This constant confuses me, but I feel like the outIdentifier may be a pointer to the value's location. It is possible that this is supposed to be a way to change values in an immutable ABMultiValueRef by using the pointer to the value. It may also be a check to see if you already added the value.

As you have seen, the way you create the ABAddressBookRef is by using ABAddressBookCreateWithOptions(NULL, nil). The NULL parameter is reserved and you are told to use NULL in the documentation. This is likely something Apple uses for its inner workings. It is possible that the outIdentifier is another secret parameter Apple uses and does not want developers to.

However, as it does not say Restricted in this case, I am guessing that this outIdentifier is a pointer to the value so it can be altered. I have always passed nil, and for stability, it may be smart for you to as well. I have never seen anyone use this parameter since I started using the Address Book.

I was most intrigued because I had never thought to ask what it was for.

DISCLAIMER- I am not definite that I am correct. This is no more than an educated guess based on what I have read in the documentation and the experience I have with the framework.