Mac Developer Library

Developer

AddressBook Framework Reference ABMutableMultiValue C Reference

Options
Deployment Target:

On This Page
Language:

ABMutableMultiValue C Reference

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 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 functions that access the content of a multi-value list.

You can use either the ABMultiValueAdd or ABMultiValueInsert functions to add value/label pairs to a multi-value list. You can remove an entry in a multi-value list using the ABMultiValueRemove function. You can also replace values and labels using the ABMultiValueReplaceLabeland ABMultiValueReplaceValue functions.

Use the ABMultiValueSetPrimaryIdentifier function to set the primary identifier—that is, designate the corresponding value as the default value for a multi-value list. Use the ABMultiValueCopyIdentifierAtIndex function to get the unique identifier for a value/label pair.

The ABMutableMultiValue opaque type is “toll-free bridged” with its Objective-C counterpart. This means that the ABMutableMultiValueRef type is interchangeable in function or method calls with instances of the ABMutableMultiValue class.

Functions

  • Adds a value and its label to a multi-value list.

    Declaration

    Swift

    func ABMultiValueAdd(_ multiValue: ABMutableMultiValue!, _ value: AnyObject!, _ label: CFString!, _ outIdentifier: UnsafeMutablePointer<Unmanaged<CFString>?>) -> Bool

    Objective-C

    bool ABMultiValueAdd ( ABMutableMultiValueRef multiValue, CFTypeRef value, CFStringRef label, CFStringRef *outIdentifier );

    Parameters

    multiValue

    The multi-value list you wish to modify.

    value

    An object representing a value in a multi-value list--it must be of the correct type. For example, if multiValue is the value for a property of type kABMultiStringProperty, then value needs to be a CFString object. See Property Types for a list of supported types in a multi-value list (see descriptions of the kABMulti... constants). If value is NULL, this function raises an exception.

    label

    The label for value—it need not be unique. If label is NULL, this function raises an exception.

    outIdentifier

    If value is added successfully, this parameter returns the new identifier.

    Return Value

    true if successfully, false otherwise.

    Discussion

    This function 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 multi-value list whose values are not all of the same type, functions, such as the ABRecord ABRecordSetValue function, will returns NULL or kABErrorInProperty.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

  • Returns a newly created mutable multi-value list object.

    Declaration

    Swift

    func ABMultiValueCreateMutable() -> Unmanaged<ABMutableMultiValue>!

    Objective-C

    ABMutableMultiValueRef ABMultiValueCreateMutable ( void );

    Return Value

    A newly created ABMutableMultiValue object. You are responsible for releasing this object.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

  • Inserts a value and its label at the given index in a multi-value list.

    Declaration

    Swift

    func ABMultiValueInsert(_ multiValue: ABMutableMultiValue!, _ value: AnyObject!, _ label: CFString!, _ index: CFIndex, _ outIdentifier: UnsafeMutablePointer<Unmanaged<CFString>?>) -> Bool

    Objective-C

    bool ABMultiValueInsert ( ABMutableMultiValueRef multiValue, CFTypeRef value, CFStringRef label, CFIndex index, CFStringRef *outIdentifier );

    Parameters

    multiValue

    The multi-value list you wish to modify.

    value

    An object representing a value in a multi-value list--it must be of the correct type. For example, if multiValue is the value for a property of type kABMultiStringProperty, then value needs to be a CFString object. See Property Types for a list of supported types in a multi-value list (see descriptions of the kABMulti... constants). If value is NULL, this function raises an exception.

    label

    The label for value—it need not be unique. If label is NULL, this function raises an exception.

    index

    The index to insert value at. If index is out of bounds, this function raises an exception.

    outIdentifier

    If value is added successfully, this parameter returns the new identifier.

    Return Value

    true if successfully, false otherwise.

    Discussion

    This function 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 multi-value list whose values are not all of the same type, functions, such as the ABRecord ABRecordSetValue function, will returns NULL or kABErrorProperty.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

  • Removes the value and label at the given index.

    Declaration

    Swift

    func ABMultiValueRemove(_ multiValue: ABMutableMultiValue!, _ index: CFIndex) -> Bool

    Objective-C

    bool ABMultiValueRemove ( ABMutableMultiValueRef multiValue, CFIndex index );

    Parameters

    multiValue

    The multi-value list you wish to modify.

    index

    The index of the entry to be removed. If index is out of bounds, this function raises an exception.

    Return Value

    true if successfully, false otherwise.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

  • Replaces the label at the given index.

    Declaration

    Swift

    func ABMultiValueReplaceLabel(_ multiValue: ABMutableMultiValue!, _ label: CFString!, _ index: CFIndex) -> Bool

    Objective-C

    bool ABMultiValueReplaceLabel ( ABMutableMultiValueRef multiValue, CFStringRef label, CFIndex index );

    Parameters

    multiValue

    The multi-value list you wish to modify.

    label

    The new label at index—it need not be unique. If label is NULL, this function raises an exception.

    index

    The index of the entry to be modified. If index is out of bounds, this function raises an exception.

    Return Value

    true if successfully, false otherwise.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

  • Replaces the value at the given index.

    Declaration

    Swift

    func ABMultiValueReplaceValue(_ multiValue: ABMutableMultiValue!, _ value: AnyObject!, _ index: CFIndex) -> Bool

    Objective-C

    bool ABMultiValueReplaceValue ( ABMutableMultiValueRef multiValue, CFTypeRef value, CFIndex index );

    Parameters

    multiValue

    The multi-value list you wish to modify.

    value

    An object representing the new value in a multi-value list--it must be of the correct type. For example, if multiValue is the value for a property of type kABMultiStringProperty, then value needs to be a CFString object. See Property Types for a list of supported types in a multi-value list (see descriptions of the kABMulti... constants). If value is NULL, this function raises an exception.

    index

    The index of the entry to be modified. If index is out of bounds, this function raises an exception.

    Return Value

    true if successfully, false otherwise.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

  • Sets the primary value to be the value for the given identifier.

    Declaration

    Swift

    func ABMultiValueSetPrimaryIdentifier(_ multiValue: ABMutableMultiValue!, _ identifier: CFString!) -> Bool

    Objective-C

    bool ABMultiValueSetPrimaryIdentifier ( ABMutableMultiValueRef multiValue, CFStringRef identifier );

    Parameters

    multiValue

    The multi-value list you wish to modify.

    identifier

    The identifier corresponding to the value you wish to designate as the primary value for this multi-value list. Use the ABMultiValueCopyIdentifierAtIndex function to get the identifier given the index. If identifier is NULL, this function raises an exception.

    Return Value

    true if successfully, false otherwise.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

Data Types

  • A reference to an ABMutableMultiValue object.

    Declaration

    Swift

    typealias ABMutableMultiValueRef = ABMutableMultiValue

    Objective-C

    typedef struct __ABMultiValue *ABMutableMultiValueRef;

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.2 and later.