---

Deprecated Search Kit Functions

A function identified as deprecated has been superseded and may become unsupported in the future.

Deprecated in Mac OS X v10.4

SKSearchGroupCopyIndexes

Obtains the indexes for a search group. (Deprecated in Mac OS X v10.4. Use asynchronous searching with SKSearchCreate instead, which does not employ search groups.)

CFArrayRef SKSearchGroupCopyIndexes (
   SKSearchGroupRef    inSearchGroup
);

Parameters

inSearchGroup

The search group whose indexes you want to copy.

Return Value

A CFArray object containing the indexes in the search group.

Discussion

Although the search functions SKSearchResultsCreateWithQuery and SKSearchResultsCreateWithDocuments operate directly on search groups, many Search Kit functions, such as SKIndexCompact, operate on one index at a time. When you want to examine or manage all the indexes in a search group, use SKSearchGroupCopyIndexes to get the search group’s list of indexes.

Availability

• Available in Mac OS X v10.3 and later.
• Deprecated in Mac OS X v10.4.

Declared In

SKSearch.h

SKSearchGroupCreate

Creates a search group as an array of references to indexes. (Deprecated in Mac OS X v10.4. Use asynchronous searching with SKSearchCreate instead, which does not employ search groups.)

SKSearchGroupRef SKSearchGroupCreate (
   CFArrayRef      inArrayOfInIndexes
);

Parameters

inArrayOfInIndexes

A CFArray object containing the indexes to put into the search group.

Return Value

An SKSearchGroup opaque type.

Discussion

Creates a search group as an array of references to indexes.

You create a search group to search one or more indexes, and then typically use the resulting SKSearchGroupRef opaque type with SKSearchResultsCreateWithQuery or SKSearchResultsCreateWithDocuments.

When your application no longer needs the search group, dispose of it by calling CFRelease.

Availability

• Available in Mac OS X v10.3 and later.
• Deprecated in Mac OS X v10.4.

Declared In

SKSearch.h

SKSearchResultsCopyMatchingTerms

Obtains the terms in a document that match a query. (Deprecated in Mac OS X v10.4. Use SKSearchCreate instead.)

CFArrayRef SKSearchResultsCopyMatchingTerms (
   SKSearchResultsRef  inSearchResults,
   CFIndex             inItem
);

Parameters

inSearchResults

The search results to examine.

inItem

An integer that corresponds to a document URL object (SKDocumentRef) in the search results. A value of ‘1’ identifies the first document URL object in the search results, a value of ‘2’ identifies the second, and so on.

If you’ve created the search results using SKSearchResultsCreateWithQuery, the document URL objects are sorted in ranking order with the top-ranked one first. See SKSearchResultsGetInfoInRange for a description of how to get a particular document URL object, or set of them, from a search result.

Return Value

A CFArray object containing term IDs.

Discussion

When using a prefix search, or a search for which the user entered more than one word, there may be multiple terms that match the query. This function returns an array of the term IDs corresponding to these matches.

For example, a user could enter ‘App’ when performing a prefix search. If a document represented in the search group contains the words ‘Apple,’ ‘application,’ and ‘appendectomy,’ the IDs for all of these terms would then appear in the CFArray object that SKSearchResultsCopyMatchingTerms returns.

See SKSearchResultsCreateWithQuery for a description of how to perform a search and get search results. See SKSearchResultsGetInfoInRange for how to extract information, including document URL objects, from a search result. See “Deprecated Search Keys” for a description of the various categories of search.

Availability

• Available in Mac OS X v10.3 and later.
• Deprecated in Mac OS X v10.4.

Declared In

SKSearch.h

SKSearchResultsCreateWithDocuments

Finds documents similar to given example documents. (Deprecated in Mac OS X v10.4. Use SKSearchCreate instead.)

SKSearchResultsRef SKSearchResultsCreateWithDocuments (
   SKSearchGroupRef                inSearchGroup,
   CFArrayRef                      inExampleDocuments,
   CFIndex                         inMaxFoundDocuments,
   void                            *inContext,
   SKSearchResultsFilterCallBack   inFilterCallBack
);

Parameters

inSearchGroup

A search group containing the indexes which, in turn, contain the document URL objects (SKDocumentRefs) representing the documents you want to search by similarity. The search group must also contains the indexes that contain the textual content of the example documents.

inExampleDocuments

An array of document URL objects (SKDocumentRefs), each representing an example document.

inMaxFoundDocuments

The maximum number of found items to return. Your application must pass in a positive value.

inContext

An application-specified context for use by the SKSearchResultsFilterCallBack callback function. Can be NULL.

inFilterCallBack

A callback function for hit testing during searching—see SKSearchResultsFilterCallBack. In a similarity search, your application would typically use this function to exclude the example documents from the search results. This parameter can be NULL, in which case your application receives the returned results directly and without any custom postprocessing.

Return Value

A search results object containing a list of document URL objects (SKDocumentRefs) representing documents similar to the example documents.

Discussion

This function searches the on-disk indexes in a search group for document URL objects (SKDocumentRefs) representing documents similar to those provided as examples. Build the search group in three steps:

1. Collect the index IDs from the search groups you want to search: for each search group, call the SKSearchGroupCopyIndexes function.

2. Add the document URL objects representing the example documents to a memory-based index (if they’re not already in an index) by calling SKIndexCreateWithMutableData, and get that index’s ID.

3. Create a new search group that contains the indexes to search, and also containing the example-documents index, using SKSearchGroupCreate.

Before invoking a search, call SKIndexFlush on all indexes in the search group to ensure that changes to the indexes have been written to disk.

Once you’ve obtained the results of a search, get the specifics—including which documents match the user’s similarity query, and the ranking scores for each document—by calling SKSearchResultsGetInfoInRange.

When your application no longer needs the search result, dispose of it by calling CFRelease.

Availability

• Available in Mac OS X v10.3 and later.
• Deprecated in Mac OS X v10.4.

Declared In

SKSearch.h

SKSearchResultsCreateWithQuery

Queries the indexes in a search group. (Deprecated in Mac OS X v10.4. Use SKSearchCreate instead.)

SKSearchResultsRef SKSearchResultsCreateWithQuery (
   SKSearchGroupRef        inSearchGroup,
   CFStringRef             inQuery,
   SKSearchType            inSearchType,
   CFIndex                 inMaxFoundDocuments,
   void                    *inContext,
   SKSearchResultsFilterCallBackinFilterCallBack
);

Parameters

inSearchGroup

The search group to query.

inQuery

The query string to search for.

inSearchType

The category of search to perform. See the “Deprecated Search Keys” enumeration for options.

inMaxFoundDocuments

The maximum number of found items to return. Your application must pass in a positive integer value.

inContext

An application-specified context for use by the SKSearchResultsFilterCallBack. Can be NULL, but if you want to use the callback you must supply a context.

inFilterCallBack

A callback function for hit testing during searching. Can be NULL, in which case your application receives the returned results directly and without any custom postprocessing. If non-NULL, you must supply a context. See SKSearchResultsFilterCallBack.

Return Value

A search results object.

Discussion

This function searches the on-disk indexes in a search group. Before invoking a search, call SKIndexFlush on all indexes in the search group to ensure that changes to the indexes have been flushed to disk.

Once you’ve obtained the results of a search, get the specifics—including which documents match the user’s query, and the ranking scores for each document—by calling SKSearchResultsGetInfoInRange. You can extract other information by calling SKSearchResultsCopyMatchingTerms and SKSearchResultsGetCount.

When your application no longer needs the search result, dispose of it by calling CFRelease.

Special Considerations

This deprecated function performs searches synchronously. Apple recommends using the asynchronous SKSearchCreate function instead.

In the current implementation of Search Kit, unary Boolean operators are not implemented. A search, for example, for ‘not blue’, returns zero documents no matter what their content.

Availability

• Available in Mac OS X v10.3 and later.
• Deprecated in Mac OS X v10.4.

Declared In

SKSearch.h

SKSearchResultsGetCount

Gets the total number of found items in a search. (Deprecated in Mac OS X v10.4. Use SKSearchCreate instead.)

CFIndex SKSearchResultsGetCount (
   SKSearchResultsRef  inSearchResults
);

Parameters

inSearchResults

A search results object containing the results of a query.

Return Value

A CFIndex object containing the total number of found items in a search.

Availability

• Available in Mac OS X v10.3 and later.
• Deprecated in Mac OS X v10.4.

Declared In

SKSearch.h

SKSearchResultsGetInfoInRange

Extracts information from a Search Kit query result. (Deprecated in Mac OS X v10.4. Use SKSearchCreate instead.)

CFIndex SKSearchResultsGetInfoInRange (
   SKSearchResultsRef  inSearchResults,
   CFRange             inRange,
   SKDocumentRef       *outDocumentsArray,
   SKIndexRef          *outIndexesArray,
   float               *outScoresArray
);

Parameters

inSearchResults

The search results whose information you want to extract.

inRange

The starting ranking and total number of found items to obtain, specified as (Location, Length). ‘Location’ specifies the starting item by ranking, with the top-ranked item having a location of 0. ‘Length’ specifies the total number of items to include in the results. For example, (0,1) indicates the first item, which is also the highest-ranking item. (1,1) indicates the second item, which is also the second-highest-ranking item. (0,5) means to get the first 5 items.

outDocumentsArray

On output, points to an array of found document URL objects (SKDocumentRefs).

outIndexesArray

On output, points to an array of indexes in which the found document URL objects reside. Can be NULL on input, provided that your application doesn’t need this information.

outScoresArray

On output, points to an array of correspondence scores for found items. Can be NULL on input, provided that your application doesn’t need this information.

Return Value

The number of items returned—usually the same number as specified by the length item in the inRange parameter.

Discussion

This function provides results to its output parameters in the order in which they are found, to reduce latency and to support search-as-you-type functionality.

Availability

• Available in Mac OS X v10.3 and later.
• Deprecated in Mac OS X v10.4.

Declared In

SKSearch.h

---