| Derived from | |
| Framework | AddressBook/ABAddressBookC.h |
| Companion guide | |
| Declared in | ABAddressBookC.h ABGlobals.h ABGlobalsC.h |
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.
Adds a subgroup to another group.
bool ABGroupAddGroup ( ABGroupRef group, ABGroupRef groupToAdd );
The group you wish to add a subgroup to. If NULL,
this function raises an exception.
The subgroup you wish to add to group.
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.
ABAddressBookC.hAdds a person to a group.
bool ABGroupAddMember ( ABGroupRef group, ABPersonRef personToAdd );
The group you wish to add person to.
The person to add to group.
If person is NULL,
this function raises an exception.
true if
successful, false otherwise. For example, if person is
already in group, this function does
nothing but returns false.
ABAddressBookC.hReturns an array of persons in a group.
CFArrayRef ABGroupCopyArrayOfAllMembers ( ABGroupRef group );
The ABGroup object whose members you wish to obtain.
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.
ABAddressBookC.hReturns an array containing a group’s subgroups.
CFArrayRef ABGroupCopyArrayOfAllSubgroups ( ABGroupRef group );
The ABGroup object whose subgroups you wish to obtain.
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.
ABAddressBookC.hReturns the distribution identifier for the given property and person.
CFStringRef ABGroupCopyDistributionIdentifier ( ABGroupRef group, ABPersonRef person, CFStringRef property );
The group object that person belongs to.
A person object whose distribution identifier you want to obtain.
The name of a person’s multi-value list property whose distribution identifier you want to obtain.
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.
Use the ABGroupSetDistributionIdentifier function
to set the distribution identifier for a person’s multi-value
list property.
ABAddressBookC.hReturns an array containing a group’s parents—the groups that a group belongs to.
CFArrayRef ABGroupCopyParentGroups ( ABGroupRef group );
The group whose parent groups you wish to obtain.
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.
ABAddressBookC.hReturns a new ABGroup object.
ABGroupRef ABGroupCreate ( void );
A newly created ABGroup object. You are responsible for releasing this object.
ABAddressBookC.hCreates an ABSearchElement object that specifies a query for ABGroup records.
ABSearchElementRef ABGroupCreateSearchElement ( CFStringRef property, CFStringRef label, CFStringRef key, CFTypeRef value, ABSearchComparison comparison );
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.
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.
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.
The value you are searching for. It cannot
be NULL
Specifies the type of comparison to perform,
such as kABEqual or kABPrefixMatchCaseInsensitive.
For a full list, see ABSearchComparison.
A search element object that specifies a query according to the above parameters. You are responsible for releasing this object.
Use the ABAddressBook ABCopyArrayOfMatchingRecords function
to actually perform the query. Also, see ABSearchElement for
more functions that create compound queries.
ABAddressBookC.hRemoves a subgroup from a group.
bool ABGroupRemoveGroup ( ABGroupRef group, ABGroupRef groupToRemove );
If NULL, this
function raises an exception.
The subgroup to be removed from group.
true if
successful. If the group parameter
is not a subgroup, this function does nothing and returns false.
ABAddressBookC.hRemoves a person from a group.
bool ABGroupRemoveMember ( ABGroupRef group, ABPersonRef personToRemove );
The group that you wish to remove person from.
The member that you wish to remove from group.
true if
successful. If the person parameter
is not in group, this function does nothing
and returns false.
ABAddressBookC.hAssigning 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 );
The group that person belongs to.
The person whose distribution identifier for property you
wish to change. If NULL, this function
raises an exception.
The multi-value list property whose distribution identifier you wish to change.
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.
true if
successful, false otherwise.
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.
ABAddressBookC.hA reference to an ABGroup object.
typedef struct __ABGroup *ABGroupRef;
ABAddressBookC.hProperties specific to ABGroup objects.
CFStringRef kABGroupNameProperty;
kABGroupNamePropertyName of the group.
Available in Mac OS X v10.2 and later.
Declared in ABGlobals.h.
Used to designate record types.
CFStringRef kABGroupRecordType;
kABGroupRecordTypeIndicates record of an ABGroup object.
Available in Mac OS X v10.2 and later.
Declared in ABGlobalsC.h.
Last updated: 2003-08-20
