ABGroup Class Reference

Inherits from
ABRecord : NSObject
Conforms to
NSObject (NSObject)
Framework
/System/Library/Frameworks/AddressBook.framework
Availability
Available in OS X v10.2 and later.
Companion guide
Address Book Programming Guide for Mac
Declared in
ABGroup.h

Overview

The ABGroup class 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 unless the relationship causes 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 also allow you to create email distribution lists.

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

Tasks

Managing Properties

Managing Persons

Managing Subgroups

Managing Distribution Lists

Searching

Class Methods

addPropertiesAndTypes:

Adds the given properties to all records of this type in the Address Book database.

+ (NSInteger)addPropertiesAndTypes:(NSDictionary *)properties
Parameters
properties

A dictionary of properties to be added and their types.

Return Value

The number of properties successfully added.

Discussion

In each dictionary entry, the key is a string with the property’s name, and the value is a constant with the property’s type. The property’s name must be unique. You may want to use Java-style package names for your properties, for example, org.dogclub.dogname or com.mycompany.groupID. The property type must be one of the constants described in “Property Types” in Address Book Objective-C Constants Reference.

Availability
  • Available in OS X v10.2 and later.
See Also
Declared In
ABGroup.h

properties

Returns an array of the names of all the properties for this record type in the Address Book database.

+ (NSArray *)properties
Availability
  • Available in OS X v10.2 and later.
See Also
Declared In
ABGroup.h

removeProperties:

Removes the given properties from all the records of this type in the Address Book database.

+ (NSInteger)removeProperties:(NSArray *)properties
Parameters
properties

An array of the properties to be removed.

Return Value

The number of properties successfully removed.

Discussion

Only custom properties can be removed. This method is not implemented.

Availability
  • Available in OS X v10.2 and later.
See Also
Declared In
ABGroup.h

searchElementForProperty:label:key:value:comparison:

Returns a search element object that searches for records of this type.

+ (ABSearchElement *)searchElementForProperty:(NSString *)property label:(NSString *)label key:(NSString *)key value:(id)value comparison:(ABSearchComparison)comparison
Parameters
property

The name of the property to search on. It cannot be nil. For a full list of the properties, see “Default Record Properties” in Address Book Objective-C Constants Reference and “Default Group Properties” in Address Book Objective-C Constants Reference.

label

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

key

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

value

What you’re searching for. If nil, the only supported value for comparison is kABEqual or kABNotEqual.

comparison

The type of comparison to perform and is an ABSearchComparison, such as kABEqual or kABPrefixMatchCaseInsensitive.

Availability
  • Available in OS X v10.2 and later.
See Also
Declared In
ABGroup.h

typeOfProperty:

Returns the type for a given property.

+ (ABPropertyType)typeOfProperty:(NSString *)property
Parameters
property

The property whose type will be returned.

Return Value

The property type of property.

Discussion

If the property does not exist, this method returns kABErrorInProperty.

Availability
  • Available in OS X v10.2 and later.
See Also
Declared In
ABGroup.h

Instance Methods

addMember:

Adds a person to a group.

- (BOOL)addMember:(ABPerson *)person
Parameters
person

The person record to be added.

Return Value

YES if successful; otherwise, NO.

Discussion

If the person argument is already part of the group, this method does nothing and returns YES. If the person argument is nil, this method raises an exception.

Special Considerations

Prior to OS X v10.6, if the person record is already in the group, this method does nothing and returns NO.

Availability
  • Available in OS X v10.2 and later.
See Also
Declared In
ABGroup.h

addSubgroup:

Adds a subgroup to another group.

- (BOOL)addSubgroup:(ABGroup *)group
Parameters
group

The group to add as a subgroup.

Return Value

YES if successful; otherwise, NO.

Discussion

If the group argument is already part of the receiver, this method does nothing and returns NO. If adding the group would create a recursion, this method also does nothing and returns NO. (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 method won’t allow.) If the group argument is nil, this method raises an exception.

Availability
  • Available in OS X v10.2 and later.
See Also
Declared In
ABGroup.h

distributionIdentifierForProperty:person:

Returns the distribution identifier for the given property and person.

- (NSString *)distributionIdentifierForProperty:(NSString *)property person:(ABPerson *)person
Parameters
property

The property whose distribution identifier will be returned.

person

The person whose distribution identifier will be returned.

Return Value

The distribution identifier for the given property and person.

Discussion

If a distribution identifier is not set, this method returns the multivalue’s primary identifier. If either the property or the person argument is nil, this method returns nil. This method also returns nil if property is not a multivalue list property, or if person is not a member of the group.

Distribution identifiers let you use groups as distribution lists, by indicating which value in a multivalue property should be used when addressing the group. See “Using Address Book Groups as Distribution Lists” for more detailed discussion.

Availability
  • Available in OS X v10.2 and later.
See Also
Declared In
ABGroup.h

members

Returns an array of persons in a group.

- (NSArray *)members
Discussion

If this group doesn’t contain any people, this method returns an empty array.

Availability
  • Available in OS X v10.2 and later.
See Also
Declared In
ABGroup.h

parentGroups

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

- (NSArray *)parentGroups
Discussion

If this group doesn’t belong to any groups, this method returns an empty array.

Availability
  • Available in OS X v10.2 and later.
See Also
Declared In
ABGroup.h

removeMember:

Removes a person from a group.

- (BOOL)removeMember:(ABPerson *)person
Parameters
person

The person to be removed.

Return Value

YES if successful; otherwise, NO.

Discussion

If the person argument is not in the group, this method does nothing and returns NO. If person is nil, this method raises an exception.

Availability
  • Available in OS X v10.2 and later.
See Also
Declared In
ABGroup.h

removeSubgroup:

Removes a subgroup from a group.

- (BOOL)removeSubgroup:(ABGroup *)group
Parameters
group

The subgroup to be removed.

Return Value

YES if successful; otherwise, NO.

Discussion

If the group argument is not a subgroup, this method does nothing and returns NO. If group is nil, this method raises an exception.

Availability
  • Available in OS X v10.2 and later.
See Also
Declared In
ABGroup.h

setDistributionIdentifier:forProperty:person:

Assigns a specific distribution identifier for a person’s multivalue list property so that the group can be used as a distribution list.

- (BOOL)setDistributionIdentifier:(NSString *)identifier forProperty:(NSString *)property person:(ABPerson *)person
Parameters
identifier

The identifier to be set as the distribution identifier

property

The property whose distribution identifier will be set.

person

The person whose distribution identifier will be.

Return Value

YES if successful; otherwise, NO.

Discussion

The default distribution identifier is a multivalue list’s primary identifier. If person is nil, this method raises an exception.

Distribution identifiers let you use groups as distribution lists, by indicating which value in a multivalue property should be used when addressing the group. See “Using Address Book Groups as Distribution Lists” for more detailed discussion.

Availability
  • Available in OS X v10.2 and later.
See Also
Declared In
ABGroup.h

subgroups

Returns an array containing a group’s subgroups.

- (NSArray *)subgroups
Discussion

If this group doesn’t contain any groups, this method returns an empty array.

Availability
  • Available in OS X v10.2 and later.
See Also
Declared In
ABGroup.h


© 2011 Apple Inc. All Rights Reserved. (Last updated: 2011-01-05)

Did this document help you? Yes It's good, but... Not helpful...