Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

Next Page > Hide TOC

Search Kit Reference

Framework
CoreServices/CoreServices.h
Declared in
SKDocument.h
SKIndex.h
SKSearch.h
SKSummary.h

Overview

Search Kit is a powerful and streamlined C language framework for indexing and searching text in most human languages. It provides fast information retrieval in System Preferences, Address Book, Help Viewer, and Xcode. Apple’s Spotlight technology is built on top of Search Kit to provide content searching in Finder, Mail, and the Spotlight menu.

You can use Search Kit or Spotlight to provide similar functionality and powerful information-access capabilities within your Mac OS X application. The Search Kit API is appropriate when you want your application to have full control over indexing and searching, and when your focus is file content. Search Kit is thread-safe and works with Cocoa, Carbon, and command-line tools.

Beginning with Mac OS X version 10.4, Search Kit supports phrase searches, prefix/suffix/substring searches, improved Boolean searches, and improved relevance ranking. Search Kit now uses Spotlight’s metadata importers when indexing documents, and takes advantage of any additional importers available on a system. Searching and indexing are much faster with Search Kit’s new asynchronous search APIs. And, starting in Mac OS X v10.4, Search Kit provides a summarization API that supplants Find By Content.

Functions by Task

Functions are grouped according to the tasks you perform using them. For an alphabetical list of functions, go to the API index at the end of the document.

Creating, Opening, and Closing Indexes

Search Kit performs its searches not on documents but on its indexes of documents. The functions in this group let your application create memory-based and persistent indexes. Indexes are initially empty. Functions in “Managing Indexes” let you add document content to these indexes.

Managing Indexes

The functions in this section let your application add document content to (and remove document content from) indexes, work with memory- and disk-based indexes, and retrieve metadata from indexes.

Working With Text Importers

Search Kit can import the textual content of file-based documents into indexes using the Spotlight metadata importers.

Working with Documents and Terms

From Search Kit’s perspective, a document is anything that contains text—an RTF document, a PDF file, a Mail message, an Address Book entry, an Internet URL, the result of a database query, and so on.

The functions in this section let your application create new document URL objects (SKDocumentRefs), retrieve metadata from documents, get information on document hierarchies, and work with documents and their terms in the context of Search Kit indexes.

Fast Asynchronous Searching

In Mac OS X v10.4 and later, Search Kit’s fast asynchronous searching replaces synchronous searching. Synchronous searching, which relied on search groups, is deprecated.

Working With Summarization

Search Kit’s Summarization functions supplant those in Apple’s Find by Content API.

Legacy Support for Synchronous Searching

Developers should avoid using the functions listed in this section; instead, use the replacement functions that are recommended. Search Kit retains the functions in this section for backward compatibility.

Functions

SKDocumentCopyURL

Builds a CFURL object from a document URL object.

CFURLRef SKDocumentCopyURL (
   SKDocumentRef   inDocument
);

Parameters
inDocument

The document URL object (SKDocumentRef) that you want a CFURL object for.

Return Value

A CFURL object representing a document location, or NULL on failure.

Discussion

You can use this function to create a CFURL object to represent a document’s location. Do this to gain access to the Core Foundation functionality provided by CFURL. This functionality includes accessing parts of the URL string, getting properties of the URL, and converting the URL to other representations.

Availability
Declared In
SKDocument.h

SKDocumentCreate

Creates a document URL object based on a scheme, parent, and name.

SKDocumentRef SKDocumentCreate (
CFStringRef     inScheme,
SKDocumentRef   inParent,
CFStringRef     inName
);

Parameters
inScheme

The scheme to use—analogous to the scheme of a URL. Only documents referenced with the “file” scheme can be read by the SKIndexAddDocument function. The scheme can be anything you like if you use the SKIndexAddDocumentWithText function. The scheme can be NULL, in which case it will be set to be the same scheme as the document URL object’s (SKDocumentRef’s) parent. For more information on schemes, see http://www.iana.org/assignments/uri-schemes.html.

inParent

The document URL object one step up in the document hierarchy. Can be NULL.

inName

The name of the document that you’re creating a document URL object for. For the “file” scheme, it is the name of the file or the container, not its path. The path can be constructed by following parent links. The maximum length for a document name is 256 bytes.

Return Value

The new document URL object, or NULL on failure.

Discussion

The new document URL object’s (SKDocumentRef’s) parent can be NULL, but you must specify either a scheme or a parent. When your application no longer needs the document URL object, dispose of it by calling CFRelease.

Availability
Declared In
SKDocument.h

SKDocumentCreateWithURL

Creates a document URL object from a CFURL object.

SKDocumentRef SKDocumentCreateWithURL (
   CFURLRef    inURL
);

Parameters
inURL

The URL for the document URL object (SKDocumentRef) you are creating. The scheme of the document URL object gets set to the scheme of the URL used. Only URLs with a scheme of “file” can be used with the SKIndexAddDocument function, but the URL scheme may be anything you like if you use the SKIndexAddDocumentWithText function. For more information on schemes, see http://www.iana.org/assignments/uri-schemes.html.

Return Value

The new document URL object (SKDocumentRef), or NULL if the document URL object could not be created.

Discussion

Use SKDocumentCreateWithURL to create a unique reference to a file or to another, arbitrary URL that your application will use as a document URL object (SKDocumentRef). When your application no longer needs the document URL object, dispose of it by calling CFRelease.

Availability
Declared In
SKDocument.h

SKDocumentGetName

Gets the name of a document URL object.

CFStringRef SKDocumentGetName (
   SKDocumentRef   inDocument
);

Parameters
inDocument

The document URL object (SKDocumentRef) whose name you want to get.

Return Value

A CFString object containing the document URL object’s name, or NULL on failure.

Availability
Declared In
SKDocument.h

SKDocumentGetParent

Gets a document URL object’s parent.

SKDocumentRef SKDocumentGetParent (
   SKDocumentRef   inDocument
);

Parameters
inDocument

The document URL object (SKDocumentRef) whose parent you want to get.

Return Value

The parent document URL object, or NULL on failure.

Discussion

As described in SKDocumentRef, Search Kit manages document locations in terms of URLs as Document URL objects (SKDocumentRefs). The parent document URL object typically contains the document’s URL up to but not including the document name.

Typically, document URL objects contain the complete URL to a file-based document. But you can use this function iteratively to build up the complete file-system path for a document that you are managing as part of a document hierarchy. See SKDocumentRef for more on this.

Availability
Declared In
SKDocument.h

SKDocumentGetSchemeName

Gets the scheme name for a document URL object.

CFStringRef SKDocumentGetSchemeName (
   SKDocumentRef   inDocument
);

Parameters
inDocument

The document URL object (SKDocumentRef) whose scheme you want to get.

Return Value

A CFString object containing the document URL object’s scheme name, or NULL on failure.

Discussion

The scheme of a document URL object (SKDocumentRef), which represents how it can be accessed, can be any character string but is typically “file” or “http”. The scheme is one of a Search Kit document URL object’s three properties—see SKDocumentRef for details.

For more information on schemes, see http://www.iana.org/assignments/uri-schemes.html

Availability
Declared In
SKDocument.h

SKDocumentGetTypeID

Gets the type identifier for Search Kit document URL objects.

CFTypeID SKDocumentGetTypeID (void);

Return Value

A CFTypeID object containing the type identifier for the document URL object (SKDocumentRef).

Discussion

Search Kit represents document URL objects with the SKDocumentRef opaque type. If your code needs to determine whether a particular data type is a document URL object, you can use this function along with the CFGetTypeID function and perform a comparison.

Never hard-code the document URL object type ID because it can change from one release of Mac OS X to another.

Availability
Declared In
SKDocument.h

SKIndexAddDocument

Adds location information for a file-based document, and the document’s textual content, to an index.

Boolean SKIndexAddDocument (
   SKIndexRef      inIndex,
   SKDocumentRef   inDocument,
   CFStringRef     inMIMETypeHint,
   Boolean         inCanReplace
);

Parameters
inIndex

The index you are adding the document URL object to.

inDocument

The document URL object (SKDocumentRef), containing a file-based document’s location information, to add to the index. You can release the document URL object immediately after adding it to the index.

inMIMETypeHint

The MIME type hint for the specified file-based document. Can be NULL. In Search Kit, common MIME type hints include text/plain, text/rtf, text/html, text/pdf, and application/msword.

Specify a MIME type hint to help Spotlight determine which of its metadata importers to use when Search Kit is indexing a file-based document. Search Kit uses filename extensions and type/creator codes in attempting to determine file types when indexing files. See SKLoadDefaultExtractorPlugIns. You can circumvent Search Kit’s file type determination process, or override it, by using a MIME type hint.

inCanReplace

A Boolean value specifying whether Search Kit will overwrite a document’s index entry (true, indicated by 1 or kCFBooleanTrue), or retain the entry if it exists (false, indicated by 0 or kCFBoolenFalse).

Return Value

A Boolean value of true on success, or false on failure. Also returns false if the document has an entry in the index and inCanReplace is set to false.

Discussion

The document scheme must be of type “file” to use this function. If it’s not, call SKIndexAddDocumentWithText instead. For more information on schemes, see http://www.iana.org/assignments/uri-schemes.html.

This function uses the referenced document and the optional MIME type hint to get the document’s textual content using the Spotlight metadata importers. If you do not supply a MIME type hint, Spotlight’s importers will use filename extensions and type/creator codes to guess file types.

Search Kit indexes any nonexecutable file associated with a document URL object (SKDocumentRef) that you hand to this function, even nontext files such as images. Your application takes responsibility for ensuring that the document URL objects you pass to SKIndexAddDocument are in fact the locations of files you want to index.

If your application did not call SKLoadDefaultExtractorPlugIns, Search Kit indexes the first 10 MB of a document. Otherwise, Search Kit indexes the entire document up to the index file size limit of 4 GB.

Search Kit is thread-safe. You can use separate indexing and searching threads. Your application is responsible for ensuring that no more than one process is open at a time for writing to an index.

A single Search Kit index can hold up to 4 billion document URL objects and their associated textual content.

Special Considerations

In the current implementation of Search Kit, some functions do not provide expected results unless you follow SKIndexAddDocument with a call to SKIndexFlush. The affected functions include SKIndexGetDocumentCount, SKIndexGetDocumentTermCount, SKIndexGetDocumentTermFrequency, and SKIndexGetTermDocumentCount. However, in typical use this won’t be an issue, because applications call these functions after a search, and you must call SKIndexFlush before a search.

Version Notes

In versions of Mac OS X prior to Mac OS X v10.4, Search Kit used its own text extractor plug-ins rather than using the Spotlight metadata importers. See SKLoadDefaultExtractorPlugIns and http://developer.apple.com/macosx/tiger/spotlight.html.

Availability
Declared In
SKIndex.h

SKIndexAddDocumentWithText

Adds a document URL object, and the associated document’s textual content, to an index.

Boolean SKIndexAddDocumentWithText (
   SKIndexRef      inIndex,
   SKDocumentRef   inDocument,
   CFStringRef     inDocumentText,
   Boolean         inCanReplace
);

Parameters
inIndex

The index to which you are adding the document URL object (SKDocumentRef).

inDocument

The document URL object to add.

inDocumentText

The document text. Can be NULL.

inCanReplace

A Boolean value specifying whether Search Kit will overwrite a document’s index entry (true, indicated by 1 or kCFBooleanTrue), or retain the entry if it exists (false, indicated by 0 or kCFBoolenFalse).

Return Value

A Boolean value of true on success, or false on failure. Also returns false if the document has an entry in the index and inCanReplace is set to false.

Discussion

Use this function to add the textual contents of arbitrary document types to an index. With this function, your application takes responsibility for getting textual content and handing it to the index as a CFString object. Because of this, your application can define what it considers to be a document—a database record, a tagged field in an XML document, an object in memory, a text file, and so on.

Search Kit will index any size text string that you give it, up to its 4 GB index file size limit.

To add the textual content of file-based documents to a Search Kit index, you can use this function or take advantage of Search Kit’s ability to locate and read certain on-disk, file-based document types—see SKIndexAddDocument.

Search Kit is thread-safe. You can use separate indexing and searching threads. Your application is responsible for ensuring that no more than one process is open at a time for writing to an index.

A single Search Kit index file can be up to 4 GB in size.

Special Considerations

In Mac OS X v10.3, some functions do not provide expected results unless you follow a call to SKIndexAddDocumentWithText with a call to SKIndexFlush. The affected functions include SKIndexGetDocumentCount, SKIndexGetDocumentTermCount, SKIndexGetDocumentTermFrequency, and SKIndexGetTermDocumentCount. However, in typical use this won’t be an issue, because applications call these functions after a search, and you must call SKIndexFlush before a search.

Availability
Declared In
SKIndex.h

SKIndexClose

Closes an index.

void SKIndexClose (
   SKIndexRef      inIndex
);

Parameters
inIndex

The index to close.

Discussion

When your application no longer needs an index that it has opened or created, call SKIndexClose. Calling this function is equivalent to calling CFRelease on an index.

Search Kit is thread-safe. You can use separate indexing and searching threads. Your application is responsible for ensuring that no more than one process is open at a time for writing to an index.

Availability
Declared In
SKIndex.h

SKIndexCompact

Invokes all pending updates associated with an index, compacts the index if compaction is needed, and commits all changes to backing store.

Boolean SKIndexCompact (
   SKIndexRef  inIndex
);

Parameters
inIndex

The index you want to compact.

Return Value

A Boolean value of true on success, or false on failure.

Discussion

Over time, as document URL objects (SKDocumentRefs) and associated contents get added to and removed from an index, the index’s disk or memory footprint may grow due to fragmentation.

Compacting can take a significant amount of time. Do not call SKIndexCompact on the main thread in an application with a user interface. Call it only if the index is significantly fragmented and according to the needs of your application.

Calling SKIndexCompact changes the block allocation for an index’s backing store. Close all clients of an index before calling this function.

Availability
Declared In
SKIndex.h

SKIndexCopyDocumentForDocumentID

Obtains a document URL object from an index.

SKDocumentRef SKIndexCopyDocumentForDocumentID (
   SKIndexRef      inIndex,
   SKDocumentID    inDocumentID
);

Parameters
inIndex

The index containing the document URL object (SKDocumentRef).

inDocumentID

The ID of the document URL object you want to copy.

Return Value

A Search Kit document URL object.

Version Notes

In versions of Mac OS X prior to Mac OS X v10.4, the parameter type for inDocumentID was CFIndex. The parameter type in Mac OS X v10.4 and later is SKDocumentID.

Availability
Declared In
SKIndex.h

SKIndexCopyDocumentIDArrayForTermID

Obtains document IDs for documents that contain a given term.

CFArrayRef SKIndexCopyDocumentIDArrayForTermID (
   SKIndexRef      inIndex,
   CFIndex         inTermID
);

Parameters
inIndex

The index to search.

inTermID

The ID of the term to search for.

Return Value

An array of CFNumbers, each the ID for a document URL object that points to a document containing the search term.

Discussion

SKIndexCopyDocumentIDArrayForTermID searches a single index for documents that contain a given term. The search uses a term ID, not a term string. To get the ID of a term, use SKIndexGetTermIDForTermString.

Term IDs are index-specific; that is, a term has a different ID in each index in which it appears. If you want to search for all the documents containing a term in a set of indexes, call this function in turn for each index, using the index-specific term ID in each case.

Availability
Declared In
SKIndex.h

SKIndexCopyDocumentProperties

Obtains the application-defined properties of an indexed document.

CFDictionaryRef SKIndexCopyDocumentProperties (
   SKIndexRef      inIndex,
   SKDocumentRef   inDocument
);

Parameters
inIndex

The index containing the document URL object (SKDocumentRef) whose properties you want to copy.

inDocument

The document URL object whose properties you want to copy.

Return Value

A CFDictionary object containing the document URL object’s (SKDocumentRef’s) properties, or NULL on failure.

Discussion

Search Kit document URL objects (SKDocumentRefs) can have an optional, application-defined properties dictionary to hold any information you’d like to associate with the document represented by a document URL object—such as timestamp, keywords, and so on. Use SKIndexSetDocumentProperties to add a properties dictionary to a document URL object, and this function to obtain a copy of the dictionary.

Availability
Declared In
SKIndex.h

SKIndexCopyDocumentRefsForDocumentIDs

Gets document URL objects based on document IDs.

void SKIndexCopyDocumentRefsForDocumentIDs (
   SKIndexRef      inIndex,
   CFIndex         inCount,
   SKDocumentID    *inDocumentIDsArray,
   SKDocumentRef   *outDocumentRefsArray
);

Parameters
inIndex

The index containing the document information.

inCount

The number of document IDs in inDocumentIDsArray.

inDocumentIDsArray

Points to an array of document IDs corresponding to the document URL objects (SKDocumentRefs) you want.

outDocumentRefsArray

On input, a pointer to an array for document URL objects. On output, points to the previously allocated array, which now contains document URL objects corresponding to the document IDs in inDocumentIDsArray.

When finished with the document URL objects array, dispose of it by calling CFRelease on each array element.

Discussion

The SKIndexCopyDocumentRefsForDocumentIDs function lets you get a batch of document URL objects (SKDocumentRef objects) in one step, based on a list of document IDs.

If you want to get lightweight URLs in the form of CFURL objects instead, use SKIndexCopyDocumentURLsForDocumentIDs.

Availability
Declared In
SKSearch.h

SKIndexCopyDocumentURLsForDocumentIDs

Gets document URLs based on document IDs.

void SKIndexCopyDocumentURLsForDocumentIDs (
   SKIndexRef      inIndex,
   CFIndex         inCount,
   SKDocumentID    *inDocumentIDsArray,
   CFURLRef        *outDocumentURLsArray
);

Parameters
inIndex

The index containing the document information.

inCount

The number of document IDs in inDocumentIDsArray.

inDocumentIDsArray

Points to an array of document IDs corresponding to the document URLs (CFURL objects) you want.

outDocumentURLsArray

On input, a pointer to an array for document URLs (CFURL objects). On output, points to the previously allocated array, which now contains document URLs corresponding to the document IDs in inDocumentIDArray.

When finished with the document URL array, dispose of it by calling CFRelease on each array element.

Discussion

The SKIndexCopyDocumentURLsForDocumentIDs function lets you get a batch of document URLs (CFURL objects) in one step, based on a list of document IDs.

If you want to get Search Kit Document URL objects (SKDocumentRefs) instead, use SKIndexCopyDocumentRefsForDocumentIDs.

Availability
Declared In
SKSearch.h

SKIndexCopyInfoForDocumentIDs

Gets document names and parent IDs based on document IDs.

void SKIndexCopyInfoForDocumentIDs (
   SKIndexRef      inIndex,
   CFIndex         inCount,
   SKDocumentID    *inDocumentIDsArray,
   CFStringRef     *outNamesArray,
   SKDocumentID    *outParentIDsArray
);

Parameters
inIndex

The index containing the document information.

inCount

The number of document IDs in inDocumentIDsArray.

inDocumentIDsArray

Points to an array of document IDs representing the documents whose names and parent IDs you want.

outNamesArray

On input, a pointer to an array for document names. On output, points to the previously allocated array, which now contains the document names corresponding to the document IDs in inDocumentIDsArray. May be NULL on input if you don’t want to get the document names.

When finished with the names array, dispose of it by calling CFRelease on each array element.

outParentIDsArray

On input, a pointer to an array for parent document IDs. On output, points to the previously allocated array, which now contains document IDs representing the parents of the documents whose IDs are in inDocumentIDsArray. May be NULL on input if you don’t want to get the parent document IDs.

Discussion

The SKIndexCopyInfoForDocumentIDs function lets you get a batch of document names and parent document IDs in one step, based on a list of document IDs.

Availability
Declared In
SKSearch.h

SKIndexCopyTermIDArrayForDocumentID

Obtains the IDs for the terms of an indexed document.

CFArrayRef SKIndexCopyTermIDArrayForDocumentID (
   SKIndexRef      inIndex,
   SKDocumentID    inDocumentID
);

Parameters
inIndex

The index containing the document URL object (SKDocumentRef) and associated textual content.

inDocumentID

The ID of the document whose term IDs you are copying.

Return Value

A CFArray containing CFNumbers, each of which represents the ID for a term in a document.

Discussion

To derive the list of terms contained in a document, use this function to obtain an array of the term IDs, then convert each ID into the corresponding term with the SKIndexCopyTermStringForTermID function.

Version Notes

In versions of Mac OS X prior to Mac OS X v10.4, the parameter type for inDocumentID was CFIndex. In Mac OS X v10.4 and later, the parameter type is SKDocumentID.

Availability
Declared In
SKIndex.h

SKIndexCopyTermStringForTermID

Obtains a term, specified by ID, from an index.

CFStringRef SKIndexCopyTermStringForTermID (
   SKIndexRef      inIndex,
   CFIndex         inTermID
);

Parameters
inIndex

The index whose terms you are searching.

inTermID

The ID of the term whose string you want.

Return Value

A CFString containing the term specified by inTermID.

Discussion

When your application has the ID of a term, perhaps as a result of calling SKIndexCopyTermIDArrayForDocumentID, use this function to derive the term’s text string.

To perform the inverse operation of deriving a term ID from a term string in a given index, use SKIndexGetTermIDForTermString.

Availability
Declared In
SKIndex.h

SKIndexCreateWithMutableData

Creates a named index stored in a CFMutableData object.

SKIndexRef SKIndexCreateWithMutableData (
   CFMutableDataRef    inData,
   CFStringRef         inIndexName,
   SKIndexType         inIndexType,
   CFDictionaryRef     inAnalysisProperties
);

Parameters
inData

An empty CFMutableData object to contain the index being created.

inIndexName

The name of the index. If you call this function with inIndexName set to NULL, Search Kit assigns the index the default index name IADefaultIndex. If you then attempt to create a second index in the same file without assigning a name, no second index is created and this function returns NULL. Search Kit does not currently support retrieving index names from an index.

inIndexType

The index type. See SKIndexType.

inAnalysisProperties

The text analysis properties dictionary, which optionally sets the minimum term length, stopwords, term substitutions, maximum unique terms to index, and proximity support (for phrase-based searches) when creating the index. See Text Analysis Keys. The inAnalysisProperties parameter can be NULL, in which case Search Kit applies the default dictionary, which is NULL.

Return Value

The newly created index.

Discussion

SKIndexCreateWithMutableData creates an index in memory as a CFMutableData object. Search Kit indexes are initially empty. A memory-based index is useful for quick searching and when your application doesn’t need persistent storage. To create a disk-based, persistent index, use SKIndexCreateWithURL.

Search Kit is thread-safe. You can use separate indexing and searching threads. Your application is responsible for ensuring that no more than one process is open at a time for writing to an index.

When your application no longer needs the index, dispose of it by calling SKIndexClose.

Availability
Declared In
SKIndex.h

SKIndexCreateWithURL

Creates a named index in a file whose location is specified with a CFURL object.

SKIndexRef SKIndexCreateWithURL (
   CFURLRef            inURL,
   CFStringRef         inIndexName,
   SKIndexType         inIndexType,
   CFDictionaryRef     inAnalysisProperties
);

Parameters
inURL

The location of the index.

inIndexName

The name of the index. If you call this function with inIndexName set to NULL, Search Kit assigns the index the default index name IADefaultIndex. If you then attempt to create a second index in the same file without assigning a name, no second index is created and this function returns NULL. Search Kit does not currently support retrieving index names from an index.

inIndexType

The index type. See SKIndexType.

inAnalysisProperties

The text analysis properties dictionary, which optionally sets the minimum term length, stopwords, term substitutions, maximum unique terms to index, and proximity support (for phrase-based searches) when creating the index. See Text Analysis Keys. To get the analysis properties of an index, use the SKIndexGetAnalysisProperties function. The inAnalysisProperties parameter can be NULL, in which case Search Kit applies the default dictionary, which is NULL.

Return Value

A unique reference to the newly created index.

Discussion

SKIndexCreateWithURL creates an index in a file. Search Kit indexes are initially empty. Use this function when your application needs persistent storage of an index. To create a memory-based, nonpersistent index, use SKIndexCreateWithMutableData.

A file can contain more than one index. To add a new index to an existing file, use the same value for inURL and supply a new name for inIndexName.

Search Kit is thread-safe. You can use separate indexing and searching threads. Your application is responsible for ensuring that no more than one process is open at a time for writing to an index.

When your application no longer needs the index, dispose of it by calling SKIndexClose.

Availability
Declared In
SKIndex.h

SKIndexDocumentIteratorCopyNext

Obtains the next document URL object from an index using a document iterator.

SKDocumentRef SKIndexDocumentIteratorCopyNext (
   SKIndexDocumentIteratorRef  inIterator
);

Parameters
inIterator

The index-based document iterator. See SKIndexDocumentIteratorCreate for information on creating an document iterator, and SKIndexDocumentIteratorRef for more about iterators.

Return Value

The next document URL object (SKDocumentRef) in the index.

Discussion

This function returns NULL when there are no more document URL objects (SKDocumentRefs) in the index. When finished iterating, your application must call CFRelease on all retrieved document URL objects that are non-NULL.

Search Kit is thread-safe. You can use separate indexing and searching threads. Your application is responsible for ensuring that no more than one process is open at a time for writing to an index.

Availability
Declared In
SKIndex.h

SKIndexDocumentIteratorCreate

Creates an index-based iterator for document URL objects owned by a parent document URL object.

SKIndexDocumentIteratorRef SKIndexDocumentIteratorCreate (
   SKIndexRef      inIndex,
   SKDocumentRef   inParentDocument
);

Parameters
inIndex

The index you want to iterate across.

inParentDocument

The document URL object (SKDocumentRef) that is the parent of the document URL objects you want to examine. Pass NULL to get the top item in an index. See SKDocumentRef for a discussion of how to get the full URL for a document URL object.

Return Value

An index-based document iterator.

Discussion

When you want to iterate across all the documents represented in an index, use this function to create an iterator and then call SKIndexDocumentIteratorCopyNext in turn for each document URL object (SKDocumentRef) in the index.

Document iterators iterate over a single level of an index. Your code is responsible for descending through a hierarchy of documents in an index.

Search Kit is thread-safe. You can use separate indexing and searching threads. Your application is responsible for ensuring that no more than one process is open at a time for writing to an index.

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

Availability
Declared In
SKIndex.h

SKIndexDocumentIteratorGetTypeID

Gets the type identifier for Search Kit document iterators.

CFTypeID SKIndexDocumentIteratorGetTypeID (void);

Return Value

A CFTypeID object containing the type identifier for the SKIndexDocumentIterator opaque type.

Discussion

Search Kit represents document iterators with the SKIndexDocumentIteratorRef opaque type. If your code needs to determine whether a particular data type is a document iterator, you can use this function along with the CFGetTypeID function and perform a comparison.

Search Kit is thread-safe. You can use separate indexing and searching threads. Your application is responsible for ensuring that no more than one process is open at a time for writing to an index.

Never hard-code the document iterator type ID because it can change from one release of Mac OS X to another.

Availability
Declared In
SKIndex.h

SKIndexFlush

Invokes all pending updates associated with an index and commits them to backing store.

Boolean SKIndexFlush (
   SKIndexRef  inIndex
);

Parameters
inIndex

The index you want to update and commit to backing store.

Return Value

A Boolean value of true on success, or false on failure.

Discussion

An on-disk or memory-based index becomes stale when your application updates it by adding or removing a document entry. A search on an index in such a state won’t have access to the nonflushed updates. The solution is to call this function before searching. SKIndexFlush flushes index-update information and commits memory-based index caches to disk, in the case of an on-disk index, or to a memory object, in the case of a memory-based index. In both cases, calling this function makes the state of the index consistent.

Before searching an index, always call SKIndexFlush, even though the flush process may take up to several seconds. If there are no updates to commit, a call to SKIndexFlush does nothing and takes minimal time.

A new Search Kit index does not have term IDs until it is flushed.

Search Kit is thread-safe. You can use separate indexing and searching threads. Your application is responsible for ensuring that no more than one process is open at a time for writing to an index.

Availability
Declared In
SKIndex.h

SKIndexGetAnalysisProperties

Gets the text analysis properties of an index.

CFDictionaryRef SKIndexGetAnalysisProperties (
   SKIndexRef      inIndex
);

Parameters
inIndex

The index whose text-analysis properties you want to get.

Return Value

A CFDictionary object containing the index’s text-analysis properties. On failure, returns NULL.

Discussion

The text analysis properties of an index determine how searches behave when querying the index. You set the analysis properties when creating an index with the SKIndexCreateWithURL or SKIndexCreateWithMutableData functions. For more information on text-analysis properties, see Text Analysis Keys.

Search Kit is thread-safe. You can use separate indexing and searching threads. Your application is responsible for ensuring that no more than one process is open at a time for writing to an index.

Availability
Declared In
SKIndex.h

SKIndexGetDocumentCount

Gets the total number of documents represented in an index.

CFIndex SKIndexGetDocumentCount (
   SKIndexRef      inIndex
);

Parameters
inIndex

The index whose document URL objects (SKDocumentRefs) you want to count.

Return Value

A CFIndex object containing the number of document URL objects in the index. On failure, returns 0.

Discussion

Document URL objects (SKDocumentRefs) added to an index have an indexing state of kSKDocumentStateIndexed. See the SKDocumentIndexState enumeration.

Search Kit is thread-safe. You can use separate indexing and searching threads. Your application is responsible for ensuring that no more than one process is open at a time for writing to an index.

Special Considerations

In the current implementation of Search Kit, SKIndexGetDocumentCount returns the number of documents represented in the on-disk index. If your application has added document URL objects to the index but has not yet called SKIndexFlush, the document count may not be correct.

Availability
Declared In
SKIndex.h

SKIndexGetDocumentID

Gets the ID of a document URL object in an index.

SKDocumentID SKIndexGetDocumentID (
   SKIndexRef      inIndex,
   SKDocumentRef   inDocument
);

Parameters
inIndex

The index containing the text of the document whose document URL object (SKDocumentRef) ID you want.

inDocument

The document URL object whose ID you want.

Return Value

A document ID object.

Discussion

The document ID identifies a document URL object (SKDocumentRef) in an index. The ID is available as soon as you add a document URL object to an index using SKIndexAddDocumentWithText or SKIndexAddDocument.

Availability
Declared In
SKIndex.h

SKIndexGetDocumentState

Gets the current indexing state of a document URL object in an index.

SKDocumentIndexState SKIndexGetDocumentState (
   SKIndexRef      inIndex,
   SKDocumentRef   inDocument
);

Parameters
inIndex

The index containing the document URL object (SKDocumentRef) whose indexing state you want.

inDocument

The document URL object whose indexing state you want.

Return Value

A value indicating the document URL object’s indexing state.

Discussion

A document URL object (SKDocumentRef) can be in one of four states, as defined by the SKDocumentIndexState enumeration: not indexed, indexed, not in the index but will be added after the index is flushed or closed, and in the index but will be deleted after the index is flushed or closed.

Availability
Declared In
SKIndex.h

SKIndexGetDocumentTermCount

Gets the number of terms for a document in an index.

CFIndex SKIndexGetDocumentTermCount (
   SKIndexRef      inIndex,
   SKDocumentID    inDocumentID
);

Parameters
inIndex

The index containing the text of the document whose term count you want.

inDocumentID

The ID of the document URL object (SKDocumentRef) whose term count you want. Obtain a document ID by calling SKIndexGetDocumentID.

Return Value

A CFIndex object containing the number of terms in a document.

Version Notes

versions of Mac OS X prior to Mac OS X v10.4, the parameter type for inDocumentID was CFIndex. In Mac OS X v10.4 and later, the parameter type is SKDocumentID.

Availability
Declared In
SKIndex.h

SKIndexGetDocumentTermFrequency

Gets the number of occurrences of a term in a document.

CFIndex SKIndexGetDocumentTermFrequency (
   SKIndexRef      inIndex,
   SKDocumentID    inDocumentID,
   CFIndex         inTermID
);

Parameters
inIndex

The index containing the text of the document whose term count you are interested in.

inDocumentID

The ID of the document URL object whose associated term count you are interested in. Obtain a document ID by calling SKIndexGetDocumentID.

inTermID

The ID of the term whose number of occurrences you want.

Return Value

A CFIndex object containing the number of occurrences of a term in a document.

Version Notes

In versions of Mac OS X prior to Mac OS X v10.4, the parameter type for inDocumentID was CFIndex. In Mac OS X v10.4 and later, the parameter type is SKDocumentID.

Availability
Declared In
SKIndex.h

SKIndexGetIndexType

Gets the category of an index.

SKIndexType SKIndexGetIndexType (
   SKIndexRef      inIndex
);

Parameters
inIndex

The index whose category you want to know.

Return Value

The category of the index. See the SKIndexType enumeration for a list of the various index categories. On failure, returns a value of kSKIndexUnknown.

Discussion

As described in SKIndexType, Search Kit offers four categories of index, each optimized for one or more types of searching.

Search Kit is thread-safe. You can use separate indexing and searching threads. Your application is responsible for ensuring that no more than one process is open at a time for writing to an index.

Availability
Declared In
SKIndex.h

SKIndexGetMaximumBytesBeforeFlush

Not recommended. Gets the memory size limit for updates to an index, measured in bytes.

CFIndex SKIndexGetMaximumBytesBeforeFlush (
   SKIndexRef      inIndex
);

Special Considerations

This function is rarely needed and is likely to be deprecated. Apple recommends using the SKIndexFlush function along with the default memory size limit for index updates. Refer to the SKIndexSetMaximumBytesBeforeFlush function for more information.

Availability
Declared In
SKIndex.h

SKIndexGetMaximumDocumentID

Gets the highest-numbered document ID in an index.

SKDocumentID SKIndexGetMaximumDocumentID (
   SKIndexRef  inIndex
);

Parameters
inIndex

An index.

Return Value

A document ID object containing the highest-numbered document ID in the index.

Discussion

Use this function with SKIndexGetDocumentCount to determine whether an index is fragmented and in need of compaction. See SKIndexCompact.

Search Kit is thread-safe. You can use separate indexing and searching threads. Your application is responsible for ensuring that no more than one process is open at a time for writing to an index.

Version Notes

In versions of Mac OS X prior to Mac OS X v10.4, the return type for SKIndexGetMaximumDocumentID was CFIndex. The return type in Mac OS X v10.4 and later is SKDocumentID.

Availability
Declared In
SKIndex.h

SKIndexGetMaximumTermID

Gets the highest-numbered term ID in an index.

CFIndex SKIndexGetMaximumTermID (
   SKIndexRef  inIndex
);

Parameters
inIndex

An index.

Return Value

A CFIndex object containing the highest-numbered term ID in an index.

Discussion

A new Search Kit index does not have term IDs until it is flushed.

Search Kit is thread-safe. You can use separate indexing and searching threads. Your application is responsible for ensuring that no more than one process is open at a time for writing to an index.

Availability
Declared In
SKIndex.h

SKIndexGetTermDocumentCount

Gets the number of documents containing a given term represented in an index.

CFIndex SKIndexGetTermDocumentCount (
   SKIndexRef      inIndex,
   CFIndex         inTermID
);

Parameters
inIndex

The index containing the text of the documents you want to examine.

inTermID

The terms whose occurrences you want to know.

Return Value

A CFIndex object containing the number of documents represented in an index that contain a given term.

Discussion

If you want to know in which documents a term appears across multiple indexes, call this function separately on each index. Before querying each index, get the index-specific term ID using SKIndexGetTermIDForTermString.

To ensure that this function takes into account document URL objects (SKDocumentRefs) recently added to indexes, call SKIndexFlush on each index before calling this function.

Availability
Declared In
SKIndex.h