---

CBIdentity Class Reference

Overview

A CBIdentity object is used for accessing the attributes of an identity stored in an identity authority. You can use an identity object for finding identities, and storing them in an access control list (ACL). If you need to edit these attributes, take advantage of the CSIdentity class in Core Services.

You can obtain a CBIdentity object from one of the following class factory methods: identityWithName:authority:, identityWithUUIDString:authority:, identityWithPersistentReference:, or identityWithCSIdentity:.

A CBIdentity object has methods to support for interoperability with the Core Services Identity API. Send CSIdentity to your CBIdentity object to return an opaque object for use in the Core Services Identity API. Similarly, call identityWithCSIdentity: to use an Core Services Identity opaque object in the Collaboration framework.

There are two subclasses of CBIdentity: CBGroupIdentity and CBUserIdentity. If you are working specifically with a group identity, use CBGroupIdentity. Similarly, if you are working with a user identity, use CBUserIdentity.

Tasks

Finding Identities

• + identityWithCSIdentity:
• + identityWithName:authority:
• + identityWithPersistentReference:
• + identityWithUUIDString:authority:

Getting Identity Attributes

• – aliases
• – authority
• – emailAddress
• – fullName
• – image
• – isHidden
• – isMemberOfGroup:
• – posixName
• – UUIDString

Storing Identities

• – CSIdentity
• – persistentReference

Class Methods

identityWithCSIdentity:

Returns an identity object created from the specified Core Services Identity opaque object.

+ (CBIdentity *)identityWithCSIdentity:(CSIdentityRef)csIdentity

Parameters

csIdentity

The Core Services Identity opaque object.

Return Value

The identity object for use with the Collaboration framework.

Discussion

This method is used for interoperability with the Core Services Identity API.

Availability

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

Declared In

CBIdentity.h

identityWithName:authority:

Returns the identity object with the given name from the specified identity authority.

+ (CBIdentity *)identityWithName:(NSString *)name authority:(CBIdentityAuthority *)authority

Parameters

name

The name of the identity.

authority

The identity authority to search.

Return Value

The identity object, or nil if no identity is found with the specified name.

Discussion

The name is compared against all valid identity names, including full names, short names, email addresses, and aliases.

Availability

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

Declared In

CBIdentity.h

identityWithPersistentReference:

Returns the identity object matching the persistent reference data.

+ (CBIdentity *)identityWithPersistentReference:(NSData *)data

Parameters

data

The persistent data object that refers to an identity.

Return Value

The identity object matching the persistent data object, or nil if the identity is not found.

Discussion

A persistent reference is an opaque data object suitable for persistent storage.

Availability

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

Declared In

CBIdentity.h

identityWithUUIDString:authority:

Returns the identity object with the given UUID from the specified identity authority.

+ (CBIdentity *)identityWithUUIDString:(NSString *)uuid authority:(CBIdentityAuthority *)authority

Parameters

uuid

The UUID of the identity you are searching for.

authority

The identity authority to search.

Return Value

The identity object, or nil if no identity is found with the matching criteria.

Availability

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

Declared In

CBIdentity.h

Instance Methods

aliases

Returns an array of aliases (alternate names) for the identity.

- (NSArray *)aliases

Return Value

An array of NSString objects containing the alternate names for the identity.

Discussion

An identity can have zero or more aliases. Like the full and short names, two identities cannot share an alias.

Availability

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

Declared In

CBIdentity.h

authority

Returns the identity authority where the identity is stored.

- (CBIdentityAuthority *)authority

Return Value

The identity authority where the identity is stored.

Availability

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

Declared In

CBIdentity.h

CSIdentity

Returns an opaque object for use with the Core Services Identity API.

- (CSIdentityRef)CSIdentity

Return Value

The opaque object for use with the Core Services Identity API.

Discussion

This method, along with identityWithCSIdentity:, is used for interoperability with the Core Services Identity API.

Availability

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

Declared In

CBIdentity.h

emailAddress

Returns the email address of an identity.

- (NSString *)emailAddress

Return Value

The email address of an identity or nil if none exists.

Availability

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

Declared In

CBIdentity.h

fullName

Returns the full name of the identity.

- (NSString *)fullName

Return Value

The full name for the identity.

Availability

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

Declared In

CBIdentity.h

image

Returns the image associated with an identity.

- (NSImage *)image

Return Value

The image associated with an identity, or nil if none exists.

Availability

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

Declared In

CBIdentity.h

isHidden

Returns a Boolean value indicating the state of the identity’s hidden property.

- (BOOL)isHidden

Return Value

YES if the identity is hidden; NO if it is not.

Discussion

A hidden identity does not show up in the Identity Picker. A hidden identity refers to system identities such as root, www, and wheel.

Availability

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

Declared In

CBIdentity.h

isMemberOfGroup:

Returns a Boolean value indicating whether the identity is a member of the specified group.

- (BOOL)isMemberOfGroup:(CBGroupIdentity *)group

Parameters

group

The group to check for membership.

Return Value

YES if the identity is a member of the group; NO if it is not.

Availability

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

Declared In

CBIdentity.h

persistentReference

Returns a persistent reference to store a reference to an identity.

- (NSData *)persistentReference

Return Value

A data object that uniquely references an identity.

Discussion

A persistent reference data object is an object generated from an identity. Persistent data objects can be written to and read from a file, making them extremely useful for storing identities in an ACL.

Availability

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

Declared In

CBIdentity.h

posixName

Returns the POSIX name of the identity.

- (NSString *)posixName

Return Value

The POSIX name of the identity.

Discussion

The POSIX name is also referred to as the “short name” for an identity. It can only contain the characters A-Z, a-z, 0-9, -, _, ., and @.

Availability

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

Declared In

CBIdentity.h

UUIDString

Returns the UUID of the identity as a string.

- (NSString *)UUIDString

Return Value

The UUID string of the identity.

Discussion

The UUID string is generated so it is unique across all identity authorities. When storing ACLs, one method is to store the UUID of each identity. However, it is recommended that you use a persistent data object instead (see persistentReference).

Availability

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

Declared In

CBIdentity.h

---