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: |
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.
CSIdentityQueryCopyResults |
Retrieve the results of executing an identity query
extern CFArrayRef CSIdentityQueryCopyResults( CSIdentityQueryRef query );
query
An array of zero or more CSIdentityRefs
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 );
allocator
identityClass
authority
A new CSIdentityQuery object
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 );
allocator
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 );
allocator
name
comparisonMethod
identityClass
authority
A new CSIdentityQuery object
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 );
allocator
referenceData
A new CSIdentityQuery object
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 );
allocator
posixID
identityClass
authority
A new CSIdentityQuery object
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 );
allocator
uuid
authority
A new CSIdentityQuery object
Finds an identity by its UUID
CSIdentityQueryExecute |
Execute an identity query synchronously
extern Boolean CSIdentityQueryExecute( CSIdentityQueryRef query, CSIdentityQueryFlags flags, CFErrorRef *error );
query
flags
error
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 );
query
flags
clientContext
runLoop
runLoopMode
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 );
query
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.
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 );
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
CSIdentityQueryClientContext |
Client structure specifying callbacks and private context data
struct CSIdentityQueryClientContext { CFIndex version; void *info; CFAllocatorRetainCallBack retainInfo; CFAllocatorReleaseCallBack releaseInfo; CFAllocatorCopyDescriptionCallBack copyInfoDescription; CSIdentityQueryReceiveEventCallback receiveEvent; };
CSIdentityQueryEvent |
Results from executing an asynchronous query
enum { kCSIdentityQueryEventSearchPhaseFinished = 1, kCSIdentityQueryEventResultsAdded = 2, kCSIdentityQueryEventResultsChanged = 3, kCSIdentityQueryEventResultsRemoved = 4, kCSIdentityQueryEventErrorOccurred = 5 };
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.
Events generated during asynchronous query execution
CSIdentityQueryFlags |
Execution options for an identity query
enum { kCSIdentityQueryGenerateUpdateEvents = 0x0001, kCSIdentityQueryIncludeHiddenIdentities = 0x0002 };
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.)
A bit mask for setting execution options on a query
CSIdentityQueryStringComparisonMethod |
Options for querying the database by name
enum { kCSIdentityQueryStringEquals = 1, kCSIdentityQueryStringBeginsWith = 2 };
kCSIdentityQueryStringEquals
- The identity name must equal the search string
kCSIdentityQueryStringBeginsWith
- The identity name must begin with the search string
When searching for identities by name, this value specifies the string comparison function