Mac Developer Library

Developer

AddressBook Framework Reference ABMultiValue C Reference

Options
Deployment Target:

On This Page
Language:

ABMultiValue C Reference

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import AddressBook

Objective-C

@import AddressBook;

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.

Functions

  • Returns the identifier at the given index.

    Declaration

    Swift

    func ABMultiValueCopyIdentifierAtIndex(_ multiValue: ABMultiValue!, _ index: CFIndex) -> Unmanaged<CFString>!

    Objective-C

    CFStringRef ABMultiValueCopyIdentifierAtIndex ( ABMultiValueRef multiValue, CFIndex index );

    Parameters

    multiValue

    The multi-value list that you wish to access.

    index

    The index of the identifier you wish to obtain. If this parameter is out of bounds, this function raises an exception.

    Return Value

    The identifier at index in multiValue. You are responsible for releasing this object.

    Discussion

    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.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

  • Returns the label for the given index.

    Declaration

    Swift

    func ABMultiValueCopyLabelAtIndex(_ multiValue: ABMultiValue!, _ index: CFIndex) -> Unmanaged<CFString>!

    Objective-C

    CFStringRef ABMultiValueCopyLabelAtIndex ( ABMultiValueRef multiValue, CFIndex index );

    Parameters

    multiValue

    The multi-value list that you wish to access.

    index

    The index of the identifier you wish to obtain. If this parameter is out of bounds, this function raises an exception.

    Return Value

    The label at index in multiValue. You are responsible for releasing this object.

    Discussion

    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.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

  • Returns the identifier for the primary value.

    Declaration

    Swift

    func ABMultiValueCopyPrimaryIdentifier(_ multiValue: ABMultiValue!) -> Unmanaged<CFString>!

    Objective-C

    CFStringRef ABMultiValueCopyPrimaryIdentifier ( ABMultiValueRef multiValue );

    Parameters

    multiValue

    The multi-value list that you wish to access.

    Return Value

    The unique identifier for the primary value. You are responsible for releasing this object.

    Discussion

    Use the ABMultiValueCopyIdentifierAtIndex function to get index for the returned identifier, and the ABMultiValueCopyValueAtIndexfunction to get its value.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

  • Returns the value for the given index.

    Declaration

    Swift

    func ABMultiValueCopyValueAtIndex(_ multiValue: ABMultiValue!, _ index: CFIndex) -> Unmanaged<AnyObject>!

    Objective-C

    CFTypeRef ABMultiValueCopyValueAtIndex ( ABMultiValueRef multiValue, CFIndex index );

    Parameters

    multiValue

    The multi-value list that you wish to access.

    index

    The index of the identifier you wish to obtain. If this parameter is out of bounds, this function raises an exception.

    Return Value

    The value at index in multiValue. You are responsible for releasing this object.

    Discussion

    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.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

  • Returns the number of entries in a multi-value list.

    Declaration

    Swift

    func ABMultiValueCount(_ multiValue: ABMultiValue!) -> CFIndex

    Objective-C

    CFIndex ABMultiValueCount ( ABMultiValueRef multiValue );

    Parameters

    multiValue

    The multi-value list that you wish to access.

    Return Value

    The number of entries in multiValue.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

  • Returns a new ABMultiValue object.

    Declaration

    Swift

    func ABMultiValueCreate() -> Unmanaged<ABMultiValue>!

    Objective-C

    ABMultiValueRef ABMultiValueCreate ( void );

    Return Value

    A new ABMultiValue 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.

  • Returns a copy of a multi-value object.

    Declaration

    Swift

    func ABMultiValueCreateCopy(_ multiValue: ABMultiValue!) -> Unmanaged<ABMultiValue>!

    Objective-C

    ABMultiValueRef ABMultiValueCreateCopy ( ABMultiValueRef multiValue );

    Parameters

    multiValue

    The multi-value object you wish to copy. You are responsible for releasing this object.

    Return Value

    A copy of multiValue.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

  • Returns a mutable copy of a multi-value object.

    Declaration

    Swift

    func ABMultiValueCreateMutableCopy(_ multiValue: ABMultiValue!) -> Unmanaged<ABMutableMultiValue>!

    Objective-C

    ABMutableMultiValueRef ABMultiValueCreateMutableCopy ( ABMultiValueRef multiValue );

    Parameters

    multiValue

    The multi-value object you wish to copy.

    Return Value

    A mutable copy of multiValue. 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.

  • Returns the index for the given identifier.

    Declaration

    Swift

    func ABMultiValueIndexForIdentifier(_ multiValue: ABMultiValue!, _ identifier: CFString!) -> CFIndex

    Objective-C

    CFIndex ABMultiValueIndexForIdentifier ( ABMultiValueRef multiValue, CFStringRef identifier );

    Parameters

    multiValue

    The multi-value list that you wish to access.

    identifier

    The identifier whose index you wish to obtain.

    Return Value

    The index of identifier.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

  • Returns the type for the values in a multi-value list.

    Declaration

    Swift

    func ABMultiValuePropertyType(_ multiValue: ABMultiValue!) -> ABPropertyType

    Objective-C

    ABPropertyType ABMultiValuePropertyType ( ABMultiValueRef multiValue );

    Parameters

    multiValue

    The multi-value list whose property type you wish to obtain.

    Return Value

    The property type of multiValue. If the list is empty or its values are of different types, returns kABErrorInProperty.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

Data Types

  • A reference to an ABMultiValue or ABMutableMultiValue object.

    Declaration

    Swift

    typealias ABMultiValueRef = ABMultiValue

    Objective-C

    typedef const struct __ABMultiValue *ABMultiValueRef;

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.2 and later.