| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/AddressBook.framework |
| Availability | Available in Mac OS X v10.2 and later. |
| Companion guide | |
| Declared in | ABMultiValue.h |
| Related sample code |
The ABMultiValue and ABMutableMultiValue classes are used to represent properties that might have multiple values. Each value in a multivalue list must be of the same type, and must have an associated predefined or user-defined label, and unique identifier. The labels, however, need not be unique. For example, you can have multiple Home phone numbers. Each multivalue object may have a primary identifier—used as 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 ABMutableMultiValue are mutable, see ABMultiValue for additional methods that access the content of a multivalue list.
The ABMultiValue class is “toll-free bridged” with its procedural C opaque-type counterpart. This means that the ABMultiValueRef type is interchangeable in function or method calls with instances of the ABMultiValue class.
Adds a value and its label to a multivalue list.
- (NSString *)addValue:(id)value withLabel:(NSString *)label
The value to add.
The label to associate with the value.
The new identifier if value is added successfully; otherwise, nil.
The value argument must be of the correct type. For example, if the receiver is the value for a property of type kABMultiStringProperty, then value needs to be an NSString object. See “Property Types” in Address Book Objective-C Constants Reference for a list of supported types in a multivalue list (see descriptions of the kABMulti... constants). If either the value or the label argument is nil, this method raises an exception.
This method performs no type checking and will let you add a value whose type does not match the types of the other values in the list. However, if you try to use a multivalue list whose values are not all of the same type, other methods, such as the ABRecord setValue:forProperty: method, will return NO or kABErrorInProperty.
ABMultiValue.hInserts a value and its label at the given index in a multivalue list.
- (NSString *)insertValue:(id)value withLabel:(NSString *)label atIndex:(NSUInteger)index
The value to add.
The label to associate with the value.
The index where the value will be inserted.
The identifier of the inserted value and label if they are added successfully; otherwise, nil.
If either the value or the label is nil or if the index is out of bounds, this method raises an exception
This method performs no type checking and will let you add a value whose type does not match the types of the other values in the list. However, if you try to use a multivalue list whose values are not all of the same type, other methods, such as the ABRecord setValue:forProperty: method, will return NO or kABErrorInProperty.
ABMultiValue.hRemoves the value and label at the given index.
- (BOOL)removeValueAndLabelAtIndex:(NSUInteger)index
The index of the value-label pair that will be removed.
YES if successful; otherwise NO.
If the index is out of bounds, this method raises an exception.
ABMultiValue.hReplaces the label at the given index.
- (BOOL)replaceLabelAtIndex:(NSUInteger)index withLabel:(NSString *)label
The index of the label that will be replaced.
The new label.
YES if successful; otherwise, NO.
If the label is nil or if the index is out of bounds, this method raises an exception.
ABMultiValue.hReplaces the value at the given index.
- (BOOL)replaceValueAtIndex:(NSUInteger)index withValue:(id)value
The index of the value that will be replaced.
The new value.
YES if successful; otherwise NO.
If the value is nil or if the index is out of bounds, this method raises an exception.
ABMultiValue.hSets the primary value to be the value for the given identifier.
- (BOOL)setPrimaryIdentifier:(NSString *)identifier
The identifier whose value will be used as the primary value for a multivalue property.
YES if successful; otherwise NO.
If the identifier is nil, this method raises an exception. Use the identifierAtIndex: method to get the identifier given the index.
– primaryIdentifier (ABMultiValue)ABMultiValue.hLast updated: 2009-07-22
Mac OS X Reference Library Data Management: Contact Data ABMutableMultiValue Class Reference