ABMultiValue Reference

Derived from	CFTypeRef
Framework	AddressBook/AddressBook.h
Declared in	ABMultiValue.h

Overview

The ABMultiValue opaque type (whose objects are known 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 one defined by the user.

For example, if 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 Reference.

Functions by Task

Getting Values and Labels

Getting Value Identifiers

Getting Property Information

Functions

ABMultiValueCopyArrayOfAllValues

Returns an array with the values in a multivalue property.

CFArrayRef ABMultiValueCopyArrayOfAllValues (
   ABMultiValueRef multiValue
);

Parameters

multiValue: The multivalue property whose values are being return.

Return Value

Array containing the values in multiValue.

Availability

Available in iOS 2.0 and later.

Declared In

ABMultiValue.h

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.

Return Value

Label for the value at index within multiValue.

Discussion

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

This function takes an index. If you have an identifier, use the ABMultiValueGetIndexForIdentifier function to get the corresponding index.

Availability

Available in iOS 2.0 and later.

Declared In

ABMultiValue.h

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.

Return Value

The value at index in multiValue.

Discussion

This function takes an index. If you have an identifier, use the ABMultiValueGetIndexForIdentifier function to get the corresponding index.

Availability

Available in iOS 2.0 and later.

Declared In

ABMultiValue.h

ABMultiValueGetCount

Returns the number of values in a multivalue property.

CFIndex ABMultiValueGetCount (
   ABMultiValueRef multiValue
);

Parameters

multiValue: The multivalue property whose value are being counted.

Return Value

The number of values in multiValue.

Availability

Available in iOS 2.0 and later.

Declared In

ABMultiValue.h

ABMultiValueGetFirstIndexOfValue

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

CFIndex ABMultiValueGetFirstIndexOfValue (
   ABMultiValueRef multiValue,
   CFTypeRef value
);

Parameters

multiValue: The multivalue property in which to search for value.
value: The value to search for in multiValue.

Return Value

Location of value within multiValue, -1 if value is not present in multiValue.

Availability

Available in iOS 2.0 and later.

Declared In

ABMultiValue.h

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 is being returned.

Return Value

Identifier of the value at index within multiValue.

Availability

Available in iOS 2.0 and later.

Declared In

ABMultiValue.h

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 is being returned.

Return Value

Location within multiValue that contains the value with identifier as its identifier.

Availability

Available in iOS 2.0 and later.

Declared In

ABMultiValue.h

ABMultiValueGetPropertyType

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

ABPropertyType ABMultiValueGetPropertyType (
   ABMultiValueRef multiValue
);

Parameters

multiValue: The multivalue property whose type is being returned.

Return Value

The type of the values contained in multiValue or kABInvalidPropertyType when multiValue is empty or contains values of different types.

Availability

Available in iOS 2.0 and later.

Declared In

ABMultiValue.h

Data Types