CSIdentityQuery

Overview

A CSIdentityQuery object provides synchronous or asynchronous access to a collection of identities managed by an identity authority. Clients call one of the CSIdentityQueryCreate* functions to define the query criteria. A query can be executed exactly once, in either synchronous or asynchronous mode.

For synchronous execution, the client calls CSIdentityQueryExecute. This function will return when all identies matching the criteria have been found. The results are accessed as an array via CSIdentityQueryCopyResults(). No live updates to the results array are provided in synchronous mode.

To execute in asynchronous mode, the client calls CSIdentityQueryExecuteAsynchronously, specifying a client object to receive callbacks and a runloop/mode on which callbacks are scheduled.

CSIdentityQueryExecuteAsynchronously returns immediately, and events will be reported to the callback function as results are added by the query. The client may request live updates to the query which will track changes to the results as changes are made to the identity authority by other processes. Currently, only changes to the local identity authority are monitored.

Asynchronous clients must call CSIdentityQueryStop when done processing query results to prevent the client callbacks from being called again.

Functions

CSIdentityQueryCopyResults

Retrieve the results of executing an identity query

CSIdentityQueryCreate

Creates an identity query object for all identities in the specified authority

CSIdentityQueryCreateForCurrentUser

Creates a query for the current session user's identity

CSIdentityQueryCreateForName

Creates an identity query object based on a name

CSIdentityQueryCreateForPersistentReference

Creates an identity query object based on an identity reference data object

CSIdentityQueryCreateForPosixID

Creates an identity query object based on a POSIX ID

CSIdentityQueryCreateForUUID

Creates an identity query object based on a UUID

CSIdentityQueryExecute

Execute an identity query synchronously

CSIdentityQueryExecuteAsynchronously

Execute an identity query asynchronously

CSIdentityQueryGetTypeID

Retrieve the CFTypeID of the CSIdentityQuery class

CSIdentityQueryStop

Invalidate an identity query client

Retrieve the results of executing an identity query

extern CFArrayRef CSIdentityQueryCopyResults( 
    CSIdentityQueryRef query );  

Parameters

query

The query object to access

Return Value

An array of zero or more CSIdentityRefs

Discussion

Returns an immutable array of CSIdentityRefs, reflecting the current results of the query's execution.

Creates an identity query object for all identities in the specified authority

extern CSIdentityQueryRef CSIdentityQueryCreate( 
    CFAllocatorRef allocator, 
    CSIdentityClass identityClass, 
    CSIdentityAuthorityRef authority );  

Parameters

allocator

The allocator to use for this instance

identityClass

The class of identity to find

authority

The identity authority to query

Return Value

A new CSIdentityQuery object

Discussion

The results of this query include all of the identities in the specified authority's database.

Creates a query for the current session user's identity

extern CSIdentityQueryRef CSIdentityQueryCreateForCurrentUser( 
    CFAllocatorRef allocator );  

Parameters

allocator

The allocator to use for this instance

Return Value

A new CSIdentityQuery object

Creates an identity query object based on a name

extern CSIdentityQueryRef CSIdentityQueryCreateForName( 
    CFAllocatorRef allocator, 
    CFStringRef name, 
    CSIdentityQueryStringComparisonMethod comparisonMethod, 
    CSIdentityClass identityClass, 
    CSIdentityAuthorityRef authority );  

Parameters

allocator

The allocator to use for this instance

name

The name criteria for the query.

comparisonMethod

The comparision function (equal or begins with)

identityClass

The class of identity to find

authority

The identity authority to query

Return Value

A new CSIdentityQuery object

Discussion

The query finds identities by name. It searches the full names, posix names and aliases for matches.

Creates an identity query object based on an identity reference data object

extern CSIdentityQueryRef CSIdentityQueryCreateForPersistentReference( 
    CFAllocatorRef allocator, 
    CFDataRef referenceData );  

Parameters

allocator

The allocator to use for this instance

referenceData

The reference data that fully describes an identity

Return Value

A new CSIdentityQuery object

Discussion

Finds an identity by reference data obtained from CSIdentityCreateReferenceData

Creates an identity query object based on a POSIX ID

extern CSIdentityQueryRef CSIdentityQueryCreateForPosixID( 
    CFAllocatorRef allocator, 
    id_t posixID, 
    CSIdentityClass identityClass, 
    CSIdentityAuthorityRef authority );  

Parameters

allocator

The allocator to use for this instance

posixID

The UID or GID of the identity to find

identityClass

The class of identity to find

authority

The identity authority to query

Return Value

A new CSIdentityQuery object

Discussion

Finds an identity by its UID or GID

Creates an identity query object based on a UUID

extern CSIdentityQueryRef CSIdentityQueryCreateForUUID( 
    CFAllocatorRef allocator, 
    CFUUIDRef uuid, 
    CSIdentityAuthorityRef authority );  

Parameters

allocator

The allocator to use for this instance

uuid

The UUID of the identity to find

authority

The identity authority to query

Return Value

A new CSIdentityQuery object

Discussion

Finds an identity by its UUID

Execute an identity query synchronously

extern Boolean CSIdentityQueryExecute( 
    CSIdentityQueryRef query, 
    CSIdentityQueryFlags flags, 
    CFErrorRef *error );  

Parameters

query

The query object to execute

flags

Execution options

error

Optional pointer to a CFError object which must be released by the caller if CSIdentityQueryExecute returns false

Return Value

Returns true if the query executed successfully, false if an error occurred.

Execute an identity query asynchronously

extern Boolean CSIdentityQueryExecuteAsynchronously( 
    CSIdentityQueryRef query, 
    CSIdentityQueryFlags flags, 
    const CSIdentityQueryClientContext *clientContext, 
    CFRunLoopRef runLoop, 
    CFStringRef runLoopMode );  

Parameters

query

The query object to execute

flags

Execution options

clientContext

The client context and callbacks to be used during execution

runLoop

The run loop on which to schedule callbacks

runLoopMode

The run loop mode in which callbacks may be scheduled

Return Value

Returns true if query execution started, false if the query has already been executed.

Retrieve the CFTypeID of the CSIdentityQuery class

extern CFTypeID CSIdentityQueryGetTypeID(
    void );  

Invalidate an identity query client

extern void CSIdentityQueryStop(
    CSIdentityQueryRef query );  

Parameters

query

The query to access

Discussion

Invalidate a query client so that its callback will never be called in the future. Clients should call CSIdentityQueryStop when an query will no longer be used, prior to releasing the final query reference.

Typedefs

The client event callback function for receiving asynchronous query events

typedef extern void ( *CSIdentityQueryReceiveEventCallback )( 
    CSIdentityQueryRef query, 
    CSIdentityQueryEvent event, 
    CFArrayRef identities, 
    CFErrorRef error, 
    void *info );  

Parameters

query

The identity query object that has completed an event

event

The event the identity query object has completed

identities

a CFArray containing identities resulting from the query

error

A CFError object if there was an error from the query

info

Any other information you want passed to the callback function

Structs and Unions

Client structure specifying callbacks and private context data

struct CSIdentityQueryClientContext { 
    CFIndex version; 
    void *info; 
    CFAllocatorRetainCallBack retainInfo; 
    CFAllocatorReleaseCallBack releaseInfo; 
    CFAllocatorCopyDescriptionCallBack copyInfoDescription; 
    CSIdentityQueryReceiveEventCallback receiveEvent; 
};  

Enumerations

Results from executing an asynchronous query

enum { 
    kCSIdentityQueryEventSearchPhaseFinished = 1, 
    kCSIdentityQueryEventResultsAdded = 2, 
    kCSIdentityQueryEventResultsChanged = 3, 
    kCSIdentityQueryEventResultsRemoved = 4, 
    kCSIdentityQueryEventErrorOccurred = 5 
};  

Constants

kCSIdentityQueryEventSearchPhaseFinished

Event generated when the initial lookup of identities has finished. Live update events will follow if caller requests the kCSIdentityQueryGenerateUpdateEvents option.

kCSIdentityQueryEventResultsAdded

Event generated when identities are added to the query results

kCSIdentityQueryEventResultsChanged

Event generated when identities already in the query results have been modified

kCSIdentityQueryEventResultsRemoved

Event generated when identities are removed from the query results

kCSIdentityQueryEventErrorOccurred

Used to report an error. Query execution stops (permanently) if this event is sent.

Discussion

Events generated during asynchronous query execution

Execution options for an identity query

enum { 
    kCSIdentityQueryGenerateUpdateEvents = 0x0001, 
    kCSIdentityQueryIncludeHiddenIdentities = 0x0002 
};  

Constants

kCSIdentityQueryGenerateUpdateEvents

After the intial query phase is complete, monitor the result set for live updates

kCSIdentityQueryIncludeHiddenIdentities

Include all matching identities in the result set, including hidden "system" users and groups (root, www, etc.)

Discussion

A bit mask for setting execution options on a query

Options for querying the database by name

enum { 
    kCSIdentityQueryStringEquals = 1, 
    kCSIdentityQueryStringBeginsWith = 2 
};  

Constants

kCSIdentityQueryStringEquals

The identity name must equal the search string

kCSIdentityQueryStringBeginsWith

The identity name must begin with the search string

Discussion

When searching for identities by name, this value specifies the string comparison function