| Derived from | |
| Framework | AddressBook/ABAddressBookC.h |
| Companion guide | |
| Declared in | ABAddressBookC.h |
The ABMultiValue and ABMutableMultiValue opaque types are used to represent properties that might have multiple values. Each value in a multi-value list must be the same type, and has an associated pre-defined or user-defined label, and unique identifier. The labels, however, need not be unique. For example, you can have multiple “Home” phone numbers. Each multi-value object may have a primary identifier—used to lookup a default value when a label is not provided. For example, a person record may have multiple addresses with the labels “Home” and “Work”, where “Work” is designated as the primary value. Instances of this class are immutable, see ABMutableMultiValue for functions that manipulate the content of a multi-value list.
You can access values using a numeric index (similar to an
array). Use the ABMultiValueCopyIdentifierAtIndex function
to get an identifier, the ABMultiValueCopyLabelAtIndex function
to get a label, and the ABMultiValueCopyValueAtIndex function
to get a value. However, a numeric index is temporary since a multi-value
list may change. Each value or entry in a multi-value list has a
unique identifier which can be used to save a reference to a specific
value—the identifier is guaranteed never to change.
Use the ABMultiValueCopyPrimaryIdentifier function
to get the primary identifier (the identifier associated with the
primary value).
The ABMultiValue opaque type is “toll-free bridged” with
its Objective-C counterpart. This means that the ABMultiValueRef type
is interchangeable in function or method calls with instances of
the ABMultiValue class.
Returns the identifier at the given index.
CFStringRef ABMultiValueCopyIdentifierAtIndex ( ABMultiValueRef multiValue, CFIndex index );
The multi-value list that you wish to access.
The index of the identifier you wish to obtain. If this parameter is out of bounds, this function raises an exception.
The identifier at index in multiValue. You are responsible for releasing this object.
Each value in a multi-value list must be the same type, and
has an associated pre-defined or user-defined label, and unique
identifier. Use the ABMultiValueCopyLabelAtIndex function
to get a label, and the ABMultiValueCopyValueAtIndexfunction
to get a value.
ABAddressBookC.hReturns the label for the given index.
CFStringRef ABMultiValueCopyLabelAtIndex ( ABMultiValueRef multiValue, CFIndex index );
The multi-value list that you wish to access.
The index of the identifier you wish to obtain. If this parameter is out of bounds, this function raises an exception.
The label at index in multiValue. You are responsible for releasing this object.
Each value in a multi-value list must be the same type, and
has an associated pre-defined or user-defined label, and unique
identifier. Use the ABMultiValueCopyIdentifierAtIndex function
to get a identifier, and the ABMultiValueCopyValueAtIndexfunction
to get a value.
ABAddressBookC.hReturns the identifier for the primary value.
CFStringRef ABMultiValueCopyPrimaryIdentifier ( ABMultiValueRef multiValue );
The multi-value list that you wish to access.
The unique identifier for the primary value. You are responsible for releasing this object.
Use the ABMultiValueCopyIdentifierAtIndex function
to get index for the returned identifier, and the ABMultiValueCopyValueAtIndexfunction
to get its value.
ABAddressBookC.hReturns the value for the given index.
CFTypeRef ABMultiValueCopyValueAtIndex ( ABMultiValueRef multiValue, CFIndex index );
The multi-value list that you wish to access.
The index of the identifier you wish to obtain. If this parameter is out of bounds, this function raises an exception.
The value at index in multiValue. You are responsible for releasing this object.
Each value in a multi-value list must be the same type, and
has an associated pre-defined or user-defined label, and unique
identifier. Use the ABMultiValueCopyIdentifierAtIndex function
to get a identifier, and the ABMultiValueCopyLabelAtIndexfunction
to get a label.
ABAddressBookC.hReturns the number of entries in a multi-value list.
CFIndex ABMultiValueCount ( ABMultiValueRef multiValue );
The multi-value list that you wish to access.
The number of entries in multiValue.
ABAddressBookC.hReturns a new ABMultiValue object.
ABMultiValueRef ABMultiValueCreate ( void );
A new ABMultiValue object. You are responsible for releasing this object.
ABAddressBookC.hReturns a copy of a multi-value object.
ABMultiValueRef ABMultiValueCreateCopy ( ABMultiValueRef multiValue );
The multi-value object you wish to copy. You are responsible for releasing this object.
A copy of multiValue.
ABAddressBookC.hReturns a mutable copy of a multi-value object.
ABMutableMultiValueRef ABMultiValueCreateMutableCopy ( ABMultiValueRef multiValue );
The multi-value object you wish to copy.
A mutable copy of multiValue. You are responsible for releasing this object.
ABAddressBookC.hReturns the index for the given identifier.
CFIndex ABMultiValueIndexForIdentifier ( ABMultiValueRef multiValue, CFStringRef identifier );
The multi-value list that you wish to access.
The identifier whose index you wish to obtain.
The index of identifier.
ABAddressBookC.hReturns the type for the values in a multi-value list.
ABPropertyType ABMultiValuePropertyType ( ABMultiValueRef multiValue );
The multi-value list whose property type you wish to obtain.
The property type
of multiValue. If the list is empty
or its values are of different types, returns kABErrorInProperty.
ABAddressBookC.hA reference to an ABMultiValue or ABMutableMultiValue object.
typedef const struct __ABMultiValue *ABMultiValueRef;
ABAddressBookC.hLast updated: 2003-08-20