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

ABMultiValueRef

Reference to a multivalue property.

typedef CFTypeRef ABMultiValueRef;
Availability
  • Available in iOS 2.0 and later.
Declared In
ABMultiValue.h

ABMultiValueIdentifier

Identifies multivalue properties.

typedef int32_t ABMultiValueIdentifier;
Availability
  • Available in iOS 2.0 and later.
Declared In
ABMultiValue.h

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 iOS 2.0 and later.

Declared in ABMultiValue.h.

Discussion

See ABMultiValueIdentifier.