ABGroup C Reference

Derived from
Framework
AddressBook/ABAddressBookC.h
Companion guide
Declared in
ABAddressBookC.h
ABGlobals.h

Overview

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

ABGroupAddGroup

Adds a subgroup to another group.

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
ABAddressBookC.h

ABGroupAddMember

Adds a person to a group.

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
ABAddressBookC.h

ABGroupCopyArrayOfAllMembers

Returns an array of persons in a group.

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
ABAddressBookC.h

ABGroupCopyArrayOfAllSubgroups

Returns an array containing a group’s subgroups.

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
ABAddressBookC.h

ABGroupCopyDistributionIdentifier

Returns the distribution identifier for the given property and person.

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.

Version Notes
Availability
  • Available in OS X v10.2 and later.
Declared In
ABAddressBookC.h

ABGroupCopyParentGroups

Returns an array containing a group’s parents—the groups that a group belongs to.

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
ABAddressBookC.h

ABGroupCreate

Returns a new ABGroup object.

ABGroupRef ABGroupCreate (
   void
);
Return Value

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

Availability
  • Available in OS X v10.2 and later.
Declared In
ABAddressBookC.h

ABGroupCreateSearchElement

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

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
ABAddressBookC.h

ABGroupRemoveGroup

Removes a subgroup from a group.

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
ABAddressBookC.h

ABGroupRemoveMember

Removes a person from a group.

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
ABAddressBookC.h

ABGroupSetDistributionIdentifier

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).

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
ABAddressBookC.h

Data Types

ABGroupRef

A reference to an ABGroup object.

typedef struct __ABGroup *ABGroupRef;
Availability
  • Available in OS X v10.2 and later.
Declared In
ABAddressBookC.h

Constants

Group Properties

Properties specific to ABGroup objects.

CFStringRef kABGroupNameProperty;
Constants
kABGroupNameProperty

Name of the group.

Available in OS X v10.2 and later.

Declared in ABGlobals.h.

Record Type

Used to designate record types.

CFStringRef kABGroupRecordType;
Constants
kABGroupRecordType

Indicates record of an ABGroup object.