ADC Home > Reference Library > Reference > Networking > Core Foundation > Core Services Identity Reference

 


CSIdentityQuery

Framework:
/System/Library/Frameworks/CoreServices.framework/Frameworks/OSServices.framework
See Also:
Includes:

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

CSIdentityQueryCopyResults


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.


CSIdentityQueryCreate


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.


CSIdentityQueryCreateForCurrentUser


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


CSIdentityQueryCreateForName


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.


CSIdentityQueryCreateForPersistentReference


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


CSIdentityQueryCreateForPosixID


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


CSIdentityQueryCreateForUUID


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


CSIdentityQueryExecute


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.


CSIdentityQueryExecuteAsynchronously


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.


CSIdentityQueryGetTypeID


Retrieve the CFTypeID of the CSIdentityQuery class

extern CFTypeID CSIdentityQueryGetTypeID(
    void );  


CSIdentityQueryStop


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


CSIdentityQueryReceiveEventCallback


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


CSIdentityQueryClientContext


Client structure specifying callbacks and private context data

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

Enumerations


CSIdentityQueryEvent


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


CSIdentityQueryFlags


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


CSIdentityQueryStringComparisonMethod


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


Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.
Last Updated: 2008-03-11