ABMultiValue Reference

Overview

The ABMultiValue opaque type (objects of which are know as multivalues) implements a property that can have multiple values. All the contained values must be of the same type. Each value has a unique identifier and a nonunique label, which may be one of the provided labels or user defined.

For example, in a multivalue property is used to store phone numbers, there may be multiple “Work” phone numbers. These have the same label, but different unique identifiers.

Multivalue properties are immutable. To use mutable multivalue properties, see ABMutableMultiValue.

Functions by Task

Getting Values and Labels

• ABMultiValueCopyValueAtIndex
• ABMultiValueCopyArrayOfAllValues
• ABMultiValueGetCount
• ABMultiValueGetFirstIndexOfValue
• ABMultiValueCopyLabelAtIndex

Getting Value Identifiers

• ABMultiValueGetIdentifierAtIndex
• ABMultiValueGetIndexForIdentifier

Getting Property Information

• ABMultiValueGetPropertyType

Functions

ABMultiValueCopyArrayOfAllValues

Returns an array with the values in a multivalue property.

CFArrayRef ABMultiValueCopyArrayOfAllValues (
   ABMultiValueRef multiValue
);

Parameters

multiValue

The multivalue property whose values to return.

ABMultiValueCopyLabelAtIndex

Returns the label for a value in a multivalue property.

CFStringRef ABMultiValueCopyLabelAtIndex (
   ABMultiValueRef multiValue,
   CFIndex index
);

Parameters

multiValue

The multivalue property with the value whose label to return.

index

Location of the value within multiValue whose label to return.

Raises an exception when out of bounds.

Discussion

If there is no label for the value at index, returns NULL.

ABMultiValueCopyValueAtIndex

Returns the value at a particular location within a multivalue property.

CFTypeRef ABMultiValueCopyValueAtIndex (
   ABMultiValueRef multiValue,
   CFIndex index
);

Parameters

multiValue

The multivalue property from which to obtain the value.

index

Location of the desired value within multiValue.

Raises an exception when out of bounds.

ABMultiValueGetCount

Returns the number of values in a multivalue property.

CFIndex ABMultiValueGetCount (
   ABMultiValueRef multiValue
);

Parameters

multiValue

The multivalue property whose value-count to return.

ABMultiValueGetFirstIndexOfValue

Returns the first location of a value in a multivalue property.

CFIndex ABMultiValueGetFirstIndexOfValue (
   ABMultiValueRef multiValue,
   CFTypeRef index
);

Parameters

multiValue

The multivalue property in which to search for value.

value

The value to search for in multiValue.

ABMultiValueGetIdentifierAtIndex

Returns the identifier of a value in a multivalue property.

ABMultiValueIdentifier ABMultiValueGetIdentifierAtIndex (
   ABMultiValueRef multiValue,
   CFIndex index
);

Parameters

multiValue

The multivalue property with the identifier to return.

index

Location of the value within multiValue whose identifier to return.

ABMultiValueGetIndexForIdentifier

Returns the location (within a multivalue property) of a value with a given identifier.

CFIndex ABMultiValueGetIndexForIdentifier (
   ABMultiValueRef multiValue,
   ABMultiValueIdentifier identifier
);

Parameters

multiValue

The multivalue property in which to look for the identifier value identifier.

identifier

The identifier of the value whose location within multiValue to return.

ABMultiValueGetPropertyType

Returns the type of the values contained in a multivalue property.

ABPropertyType ABMultiValueGetPropertyType (
   ABMultiValueRef multiValue
);

Parameters

multiValue

The multivalue property whose type to return.

See Also

• ABMultiValueCreateMutable

Data Types

ABMultiValueRef

Reference to a multivalue property.

typedef CFTypeRef ABMultiValueRef;

ABMultiValueIdentifier

Identifies multivalue properties.

typedef int32_t ABMultiValueIdentifier;

Discussion

See “Invalid Multivalue-Property Identifier”.

Constants

Invalid Multivalue-Property Identifier

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

#define kABMultiValueInvalidIdentifier -1

Constants

kABMultiValueInvalidIdentifier

Invalid multivalue property.

Available in iPhone OS 2.0 and later.

Declared in ABMultiValue.h.

Discussion

See ABMultiValueIdentifier.

---