Mac Developer Library

Developer

Collaboration Framework Reference CBIdentity Class Reference

Options
Deployment Target:

On This Page
Language:

CBIdentity

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.

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

    Declaration

    Objective-C

    + (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 OS X v10.5 and later.

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

    Declaration

    Swift

    init?(name name: String, authority authority: CBIdentityAuthority)

    Objective-C

    + (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 OS X v10.5 and later.

  • Returns the identity object matching the persistent reference data.

    Declaration

    Swift

    init?(persistentReference data: NSData)

    Objective-C

    + (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 OS X v10.5 and later.

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

    Declaration

    Swift

    init?(UUIDString uuid: String, authority authority: CBIdentityAuthority)

    Objective-C

    + (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 OS X v10.5 and later.

    Deprecated in OS X v10.11.

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

    Declaration

    Swift

    var aliases: [String] { get }

    Objective-C

    @property(readonly, nonatomic) NSArray<NSString *> *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 OS X v10.5 and later.

  • Returns the identity authority where the identity is stored.

    Declaration

    Swift

    var authority: CBIdentityAuthority { get }

    Objective-C

    @property(readonly, nonatomic) CBIdentityAuthority *authority

    Return Value

    The identity authority where the identity is stored.

    Availability

    Available in OS X v10.5 and later.

  • Returns the email address of an identity.

    Declaration

    Swift

    var emailAddress: String? { get }

    Objective-C

    @property(readonly, nonatomic) NSString *emailAddress

    Return Value

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

    Availability

    Available in OS X v10.5 and later.

  • Returns the full name of the identity.

    Declaration

    Swift

    var fullName: String { get }

    Objective-C

    @property(readonly, nonatomic) NSString *fullName

    Return Value

    The full name for the identity.

    Availability

    Available in OS X v10.5 and later.

  • Returns the image associated with an identity.

    Declaration

    Swift

    var image: NSImage? { get }

    Objective-C

    @property(readonly, nonatomic) NSImage *image

    Return Value

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

    Availability

    Available in OS X v10.5 and later.

  • isHidden() - isHidden Available in OS X v10.5 through OS X v10.10.3

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

    Declaration

    Swift

    func isHidden() -> Bool

    Objective-C

    - (BOOL)isHidden

    Return Value

    YEStrue if the identity is hidden; NOfalse 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 OS X v10.5 through OS X v10.10.3.

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

    Declaration

    Swift

    func isMemberOfGroup(_ group: CBGroupIdentity) -> Bool

    Objective-C

    - (BOOL)isMemberOfGroup:(CBGroupIdentity *)group

    Parameters

    group

    The group to check for membership.

    Return Value

    YEStrue if the identity is a member of the group; NOfalse if it is not.

    Availability

    Available in OS X v10.5 and later.

  • Returns the POSIX name of the identity.

    Declaration

    Swift

    var posixName: String { get }

    Objective-C

    @property(readonly, nonatomic) 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 OS X v10.5 and later.

  • Returns the UUID of the identity as a string.

    Declaration

    Swift

    var UUIDString: String { get }

    Objective-C

    @property(readonly, nonatomic) 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 OS X v10.5 and later.

    Deprecated in OS X v10.11.

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

    Declaration

    Objective-C

    @property(readonly) 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 OS X v10.5 and later.

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

    Declaration

    Swift

    var persistentReference: NSData? { get }

    Objective-C

    @property(readonly, nonatomic) 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 OS X v10.5 and later.