Search Identities Synchronously

To perform a CSIdentityQuery search synchronously, call the method CSIdentityQueryExecute on your identity query object. The method returns only when it has completed the search. If the query is executed successfully, CSIdentityQueryExecute returns TRUE; otherwise, it returns FALSE. Assuming the query was successful, run the CSIdentityQueryCopyResults method to return an array of identity objects. When you have finished retrieving the identities, make sure to release the CSIdentityQuery object. Listing 3-2 shows an example of this.

Listing 3-2  Finding identities synchronously

CSIdentityQueryRef query;

CFErrorRef error;

CFArrayRef identityArray;

// create the identity query based on name

query = CSIdentityQueryCreateForName(kCFAllocatorDefault,

                                     CFSTR("David"),

                                     kCSIdentityQueryStringBeginsWith,

                                     kCSIdentityClassUser,

                                     CSGetDefaultIdentityAuthority());

// execute the query

if (CSIdentityQueryExecute(query, kCSIdentityQueryGenerateUpdateEvents, &error))

{

    // retrieve the results of the identity query

    identityArray = CSIdentityQueryCopyResults(query);

    // do something with identityArray

}

CFRelease(query);

Search Identities Asynchronously

Performing an identity query asynchronously is similar to performing a query synchronously but differs in an important way. With a synchronous query, you execute the query, wait for it to complete, and then ask for the results. In contrast, with an asynchronous query, you start the query and your callback function will be passed the results as they become available. The process for setting up asynchronous callbacks is similar in theory and in practice to other Core Services callbacks.

To search for an identity asynchronously requires two main steps: setting up a callback function and adding the identity query object to a run loop. First, set up your callback function. The callback function must be a void function and must accept five arguments:

• CSIdentityQueryRef query, the identity query object

• CSIdentityQueryEvent event, the event that caused the callback function to be run

• CFArrayRef identities, the results of the query as an array identities

• CFErrorRef error, the error that occurred as a result of the identity query, if applicable

• void *info, any data placed in the CSIdentityQueryClientContext, to be sent to the callback function

A callback function might look like Listing 3-3.

Listing 3-3  Identity query callback function

void myIdentityQueryCallback (CSIdentityQueryRef query,

                              CSIdentityQueryEvent event,

                              CFArrayRef identities,

                              CFErrorRef error,

                              void *info) {

    // See what event triggered the callback

    switch ( event ) {

        case kCSIdentityQueryEventResultsAdded:

        // An identity was added to the list of results

        break;

        case kCSIdentityQueryEventSearchPhaseFinished:

        // The query was completed

        break;

    }

}

To add the identity query object to a run loop, first create the object. Then create a CSIdentityQueryClientContext structure. In the CSIdentityQueryClientContext structure, define the name of the callback function to be run. With the CSIdentityQueryClientContext structure set up, call the CSIdentityQueryExecuteAsynchronously method to add the query to a run loop.

CSIdentityQueryExecuteAsynchronously requires five arguments: the identity query object to be executed, the execution options (from CSIdentityQueryFlags), a pointer to your CSIdentityQueryClientContext structure, the run loop on which to schedule callbacks, and the run loop mode. If the query is added to the run loop, the function returns TRUE and any errors as a result of the query are sent to your callback function. See Listing 3-4 to see how this looks in code.

Listing 3-4  Adding an identity query object to a run loop

CSIdentityQueryRef query;

CSIdentityQueryClientContext queryclient =

    {0, NULL, NULL, NULL, NULL, myIdentityQueryCallback};

// create the identity query based on name

query = CSIdentityQueryCreateForName(kCFAllocatorDefault,

                                     CFSTR("David"),

                                     kCSIdentityQueryStringBeginsWith,

                                     kCSIdentityClassUser,

                                     CSGetDefaultIdentityAuthority());

// add the identity query object to the current run loop

if (!CSIdentityQueryExecuteAsynchronously(query,

                                          kCSIdentityQueryGenerateUpdateEvents,

                                          &queryclient,

                                          CFRunLoopGetCurrent(),

                                          kCFRunLoopCommonModes))

{

    // query was not added to the run loop

}

When an event is triggered based on your query, your callback function is run. The event that causes your callback function to run is passed to the callback function along with an array of identities. If identities from the query are added, removed, or modified, the array contains only those identities that have been affected. If the search is completed, then the array is NULL. In this case, use CSIdentityQueryCopyResults to get the full list of identities.

After the query has completed, you need to remove the identity query object from the run loop. To do this, call the CSIdentityQueryStop method and pass it the identity query object. Then, release the identity query object. This should look like the code in Listing 3-5.

Listing 3-5  Invalidating an identity query object

CSIdentityQueryStop(query);

CFRelease(query);