---

ABGroup Class Objective-C Reference

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 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 members method to get all the members of a group, use the addMember: method to add people to a group, and the removeMember: method to remove people from a group. Use the addSubgroup: method to create a subgroup.

Use the addPropertiesAndTypes: method 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 searchElementForProperty:label:key:value:comparison: method to create an ABSearchElement object containing your query. Then use the ABAddressBook recordsMatchingSearchElement: method, passing the ABSearchElement as the argument, to query the database. See ABSearchElement for methods that create compound queries.

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

• + addPropertiesAndTypes:
• + removeProperties:
• + properties
• + typeOfProperty:

Managing Persons

• – addMember:
• – removeMember:
• – members

Managing Subgroups

• – addSubgroup:
• – removeSubgroup:
• – parentGroups
• – subgroups

Distribution Lists

• – distributionIdentifierForProperty:person:
• – setDistributionIdentifier:forProperty:person:

Searching

• + searchElementForProperty:label:key:value:comparison:

Class Methods

addPropertiesAndTypes:

+ (NSInteger)addPropertiesAndTypes:(NSDictionary *)properties

Discussion

Adds the given properties to all records of this type in the Address Book database, and returns the number of properties successfully added. 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 “Constants” in ABRecord.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• + removeProperties:

Declared In

ABGroup.h

properties

+ (NSArray *)properties

Discussion

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

Availability

• Available in Mac OS X v10.2 and later.

See Also

• + typeOfProperty:

Declared In

ABGroup.h

removeProperties:

+ (NSInteger)removeProperties:(NSArray *)properties

Discussion

Removes the given properties from all the records of this type in the Address Book database, and returns the number of properties successfully removed.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• + addPropertiesAndTypes:

Declared In

ABGroup.h

searchElementForProperty:label:key:value:comparison:

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

Discussion

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

• property is the name of the property to search on. It cannot be nil. For a full list of the properties, see “Constants” and “Constants” in ABRecord.

• label is the label name for a multi-value 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 multi-value list properties.

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

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

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

Availability

• Available in Mac OS X v10.2 and later.

See Also

• + searchElementForProperty:label:key:value:comparison: (ABPerson)
• + searchElementForConjunction:children: (ABSearchElement)
• – recordsMatchingSearchElement: (ABAddressBook)

Declared In

ABGroup.h

typeOfProperty:

+ (ABPropertyType)typeOfProperty:(NSString *)property

Discussion

Returns the type for a given property. If the property does not exist, this method returns kABErrorInProperty.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• + properties

Declared In

ABGroup.h

Instance Methods

addMember:

- (BOOL)addMember:(ABPerson *)person

Discussion

Adds a person to a group. Returns YES if successful. If the person argument is already part of the group, this method does nothing and returns NO. If person is nil, this method raises an exception.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• – removeMember:
• – addSubgroup:
• – members

Declared In

ABGroup.h

addSubgroup:

- (BOOL)addSubgroup:(ABGroup *)group

Discussion

Adds a subgroup to another group. Returns YES if successful. 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 Mac OS X v10.2 and later.

See Also

• – removeSubgroup:
• – addMember:
• – subgroups

Declared In

ABGroup.h

distributionIdentifierForProperty:person:

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

Discussion

Returns the distribution identifier for the given property and person. If a distribution identifier is not set, this method returns the multi-value’s primary identifier. If either the property or person arguments are nil, this method returns nil. Also, returns nil if property is not a multi-value list property.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• – setDistributionIdentifier:forProperty:person:
• – primaryIdentifier (ABMultiValue)

Declared In

ABGroup.h

members

- (NSArray *)members

Discussion

Returns an array of persons in a group. If this group doesn’t contain any people, this method returns an empty array.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• – addMember:
• – removeMember:
• – subgroups

Declared In

ABGroup.h

parentGroups

- (NSArray *)parentGroups

Discussion

Returns an array containing a group’s parents—the groups that a group belongs to. If this group doesn’t belong to any groups, this method returns an empty array.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• – subgroups

Declared In

ABGroup.h

removeMember:

- (BOOL)removeMember:(ABPerson *)person

Discussion

Removes a person from a group. Returns YES if successful. 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 Mac OS X v10.2 and later.

See Also

• – addMember:
• – members
• – removeSubgroup:

Declared In

ABGroup.h

removeSubgroup:

- (BOOL)removeSubgroup:(ABGroup *)group

Discussion

Removes a subgroup from a group. Returns YES if successful. 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 Mac OS X v10.2 and later.

See Also

• – addSubgroup:
• – subgroups
• – removeMember:

Declared In

ABGroup.h

setDistributionIdentifier:forProperty:person:

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

Discussion

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). The default distribution identifier is a multi-value list’s primary identifier. Use this method 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 method passing kABEmailWorkLabel as the identifier argument, kABEmailProperty as the property argument, and John’s person object as the person argument. Pass nil for the identifier argument to reset the distribution identifier to its default. If person is nil, this method raises an exception. Returns YES if successful, NO otherwise.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• – distributionIdentifierForProperty:person:
• – setPrimaryIdentifier: (ABMutableMultiValue)

Declared In

ABGroup.h

subgroups

- (NSArray *)subgroups

Discussion

Returns an array containing a group’s subgroups. If this group doesn’t contain any groups, this method returns an empty array.

Availability

• Available in Mac OS X v10.2 and later.

See Also

• – addSubgroup:
• – removeSubgroup:
• – members

Declared In

ABGroup.h

Constants

This is one of the properties that an ABGroup record contains by default.ABRecord describes some properties that all records contain, in “Constants”

---