Mac Developer Library

Developer

AddressBook Framework Reference ABGroup C Reference

Options
Deployment Target:

On This Page
Language:

ABGroup C Reference

The ABGroup opaque type supports the concept of a “group” containing one or more persons. People may belong to multiple groups, and groups may also belong to other groups as long as the relationship does not cause a circular reference. The only predefined property of a group is its name. However, similar to person records, you can add your own properties to group records. Groups not only help to organize person records, but allow you to create email distribution lists.

Use the ABGroupCopyArrayOfAllMembers function to get all the members of a group, use the ABGroupAddMember function to add people to a group, and the ABGroupRemoveMember function to remove people from a group. Use the ABGroupAddGroup function to create a subgroup.

Use the ABAddressBook ABAddPropertiesAndTypes function to add additional program-defined properties to group records. Because the Address Book database is stored as a property list, these program-defined properties may be ignored by other applications. Note that the Address Book database is accessed by multiple application and is not encrypted so your application should not store any sensitive information in the database.

You can also search for records matching a particular “query” you specify by creating an ABSearchElement object. Use the ABGroupCreateSearchElement function to create an ABSearchElement object containing your query. Then use the ABAddressBook ABCopyArrayOfMatchingRecords function, passing the ABSearchElement as the argument, to query the database. See ABSearchElement for functions that create compound queries.

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

Functions

  • Adds a subgroup to another group.

    Declaration

    Swift

    func ABGroupAddGroup(_ group: ABGroup!, _ groupToAdd: ABGroup!) -> Bool

    Objective-C

    bool ABGroupAddGroup ( ABGroupRef group, ABGroupRef groupToAdd );

    Parameters

    group

    The group you wish to add a subgroup to. If NULL, this function raises an exception.

    groupToAdd

    The subgroup you wish to add to group.

    Return Value

    Returns true if successful. If the group argument is already part of the receiver, this function does nothing and returns false. If adding the group would create a recursion, this function also does nothing and returns false. For example, if the group “Animal Lovers” is in “Dog Lovers,” and you add “Dog Lovers” to “Animal Lovers,” that would create a recursion, which this function won’t allow.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

  • Adds a person to a group.

    Declaration

    Swift

    func ABGroupAddMember(_ group: ABGroup!, _ person: ABPerson!) -> Bool

    Objective-C

    bool ABGroupAddMember ( ABGroupRef group, ABPersonRef personToAdd );

    Parameters

    group

    The group you wish to add person to.

    person

    The person to add to group. If person is NULL, this function raises an exception.

    Return Value

    true if successful, false otherwise. For example, if person is already in group, this function does nothing but returns false.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

  • Returns the distribution identifier for the given property and person.

    Declaration

    Swift

    func ABGroupCopyDistributionIdentifier(_ group: ABGroup!, _ person: ABPerson!, _ property: CFString!) -> Unmanaged<CFString>!

    Objective-C

    CFStringRef ABGroupCopyDistributionIdentifier ( ABGroupRef group, ABPersonRef person, CFStringRef property );

    Parameters

    group

    The group object that person belongs to.

    person

    A person object whose distribution identifier you want to obtain.

    property

    The name of a person’s multi-value list property whose distribution identifier you want to obtain.

    Return Value

    The distribution identifier for person and property if it was set, otherwise returns the property’s primary identifier. If either person or property are NULL, this function returns NULL. Also, returns NULL if property is not a multi-value list property. You are responsible for releasing this object.

    Discussion

    Use the ABGroupSetDistributionIdentifier function to set the distribution identifier for a person’s multi-value list property.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

  • Returns an array of persons in a group.

    Declaration

    Swift

    func ABGroupCopyArrayOfAllMembers(_ group: ABGroup!) -> Unmanaged<CFArray>!

    Objective-C

    CFArrayRef ABGroupCopyArrayOfAllMembers ( ABGroupRef group );

    Parameters

    group

    The ABGroup object whose members you wish to obtain.

    Return Value

    An array of ABPerson objects representing the people in group. If this group doesn’t contain any people, this function returns an empty array. 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 an array containing a group’s subgroups.

    Declaration

    Swift

    func ABGroupCopyArrayOfAllSubgroups(_ group: ABGroup!) -> Unmanaged<CFArray>!

    Objective-C

    CFArrayRef ABGroupCopyArrayOfAllSubgroups ( ABGroupRef group );

    Parameters

    group

    The ABGroup object whose subgroups you wish to obtain.

    Return Value

    An array of ABGroup objects representing the subgroups of group. If group doesn’t contain any groups, this function returns an empty array. 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 an array containing a group’s parents—the groups that a group belongs to.

    Declaration

    Swift

    func ABGroupCopyParentGroups(_ group: ABGroup!) -> Unmanaged<CFArray>!

    Objective-C

    CFArrayRef ABGroupCopyParentGroups ( ABGroupRef group );

    Parameters

    group

    The group whose parent groups you wish to obtain.

    Return Value

    An array containing ABGroup objects representing the parents of group. If group doesn’t belong to any groups, this function returns an empty array. 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 new ABGroup object.

    Declaration

    Swift

    func ABGroupCreate() -> Unmanaged<ABGroup>!

    Objective-C

    ABGroupRef ABGroupCreate ( void );

    Return Value

    A newly created ABGroup 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.

  • Creates an ABSearchElement object that specifies a query for ABGroup records.

    Declaration

    Swift

    func ABGroupCreateSearchElement(_ property: CFString!, _ label: CFString!, _ key: CFString!, _ value: AnyObject!, _ comparison: ABSearchComparison) -> Unmanaged<ABSearchElement>!

    Objective-C

    ABSearchElementRef ABGroupCreateSearchElement ( CFStringRef property, CFStringRef label, CFStringRef key, CFTypeRef value, ABSearchComparison comparison );

    Parameters

    property

    The name of the property to search on. It cannot be NULL. For a full list of the properties, see Group Properties and Common Properties.

    label

    The label name for a multi-value list. If property does not have multiple values, pass NULL. If property does have multiple values, pass NULL to search all the values. By default, ABGroup records don’t contain any multi-value list properties.

    key

    The key name for a dictionary. If property is not a dictionary, pass NULL. If property is a dictionary, pass NULL to search all keys. By default, ABGroup records don’t contain any properties that are dictionaries.

    value

    The value you are searching for. It cannot be NULL

    comparison

    Specifies the type of comparison to perform, such as kABEqual or kABPrefixMatchCaseInsensitive. For a full list, see ABSearchComparison.

    Return Value

    A search element object that specifies a query according to the above parameters. You are responsible for releasing this object.

    Discussion

    Use the ABAddressBook ABCopyArrayOfMatchingRecords function to actually perform the query. Also, see ABSearchElement for more functions that create compound queries.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

  • Removes a subgroup from a group.

    Declaration

    Swift

    func ABGroupRemoveGroup(_ group: ABGroup!, _ groupToRemove: ABGroup!) -> Bool

    Objective-C

    bool ABGroupRemoveGroup ( ABGroupRef group, ABGroupRef groupToRemove );

    Parameters

    group

    If NULL, this function raises an exception.

    groupToRemove

    The subgroup to be removed from group.

    Return Value

    true if successful. If the group parameter is not a subgroup, this function does nothing and returns false.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

  • Removes a person from a group.

    Declaration

    Swift

    func ABGroupRemoveMember(_ group: ABGroup!, _ person: ABPerson!) -> Bool

    Objective-C

    bool ABGroupRemoveMember ( ABGroupRef group, ABPersonRef personToRemove );

    Parameters

    group

    The group that you wish to remove person from.

    person

    The member that you wish to remove from group.

    Return Value

    true if successful. If the person parameter is not in group, this function does nothing and returns false.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

  • Assigning a specific distribution identifier for a person’s multi-value list property so that the group can be used as a distribution list (mailing list, in the case of an email property).

    Declaration

    Swift

    func ABGroupSetDistributionIdentifier(_ group: ABGroup!, _ person: ABPerson!, _ property: CFString!, _ identifier: CFString!) -> Bool

    Objective-C

    bool ABGroupSetDistributionIdentifier ( ABGroupRef group, ABPersonRef person, CFStringRef property, CFStringRef identifier );

    Parameters

    group

    The group that person belongs to.

    person

    The person whose distribution identifier for property you wish to change. If NULL, this function raises an exception.

    property

    The multi-value list property whose distribution identifier you wish to change.

    identifier

    The new distribution identifier, a label used by a multi-value list such as kABAddressHomeLabel for a kABAddressProperty. Pass NULL to reset the distribution identifier to its default, a multi-value list’s primary identifier.

    Return Value

    true if successful, false otherwise.

    Discussion

    The default distribution identifier is a multi-value list’s primary identifier. Use this function if you need to change the distribution identifier for a particular person. For example, if the default identifier is a person’s home email but you want to use John’s work email, invoke this function passing kABEmailWorkLabel as the identifier parameter, kABEmailProperty as the property parameter, and John’s person object as the person parameter.

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

Data Types

  • A reference to an ABGroup object.

    Declaration

    Swift

    typealias ABGroupRef = ABGroup

    Objective-C

    typedef struct __ABGroup *ABGroupRef;

    Import Statement

    Objective-C

    @import AddressBook;

    Swift

    import AddressBook

    Availability

    Available in OS X v10.2 and later.

Constants

  • Properties specific to ABGroup objects.

    Declaration

    Swift

    let kABGroupNameProperty: NSString!

    Objective-C

    CFStringRef kABGroupNameProperty;

    Constants

    • kABGroupNameProperty

      kABGroupNameProperty

      Name of the group.

      Available in OS X v10.2 and later.

  • Used to designate record types.

    Declaration

    Objective-C

    CFStringRef kABGroupRecordType;

    Constants

    • kABGroupRecordType

      kABGroupRecordType

      Indicates record of an ABGroup object.