Search Kit Reference

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.

• SKIndexCreateWithURL
• SKIndexCreateWithMutableData
• SKIndexOpenWithData
• SKIndexOpenWithMutableData
• SKIndexOpenWithURL
• SKIndexClose
• SKIndexGetIndexType
• SKIndexGetTypeID

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.

• SKIndexAddDocumentWithText
• SKIndexAddDocument
• SKIndexFlush
• SKIndexCompact
• SKIndexGetDocumentCount
• SKIndexGetMaximumDocumentID
• SKIndexGetMaximumTermID
• SKIndexDocumentIteratorCreate
• SKIndexDocumentIteratorCopyNext
• SKIndexDocumentIteratorGetTypeID
• SKIndexGetAnalysisProperties
• SKIndexMoveDocument
• SKIndexRemoveDocument
• SKIndexRenameDocument
• SKIndexSetMaximumBytesBeforeFlush
• SKIndexGetMaximumBytesBeforeFlush

Working With Text Importers

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

• SKLoadDefaultExtractorPlugIns

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.

• SKDocumentCreateWithURL
• SKDocumentCreate
• SKDocumentCopyURL
• SKDocumentGetName
• SKDocumentGetParent
• SKDocumentGetSchemeName
• SKDocumentGetTypeID
• SKIndexCopyDocumentForDocumentID
• SKIndexCopyInfoForDocumentIDs
• SKIndexCopyDocumentRefsForDocumentIDs
• SKIndexCopyDocumentURLsForDocumentIDs
• SKIndexCopyDocumentIDArrayForTermID
• SKIndexCopyTermIDArrayForDocumentID
• SKIndexCopyTermStringForTermID
• SKIndexGetTermIDForTermString
• SKIndexSetDocumentProperties
• SKIndexCopyDocumentProperties
• SKIndexGetDocumentState
• SKIndexGetDocumentTermCount
• SKIndexGetDocumentTermFrequency
• SKIndexGetTermDocumentCount
• SKIndexGetDocumentID

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.

• SKSearchCreate
• SKSearchFindMatches
• SKSearchCancel
• SKSearchGetTypeID

Working With Summarization

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

• SKSummaryCreateWithString
• SKSummaryGetSentenceSummaryInfo
• SKSummaryGetParagraphSummaryInfo
• SKSummaryGetSentenceCount
• SKSummaryGetParagraphCount
• SKSummaryCopySentenceAtIndex
• SKSummaryCopyParagraphAtIndex
• SKSummaryCopySentenceSummaryString
• SKSummaryCopyParagraphSummaryString
• SKSummaryGetTypeID

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.

• SKSearchGroupCopyIndexes Deprecated in Mac OS X v10.4
• SKSearchGroupCreate Deprecated in Mac OS X v10.4
• SKSearchGroupGetTypeID Deprecated in Mac OS X v10.4
• SKSearchResultsCopyMatchingTerms Deprecated in Mac OS X v10.4
• SKSearchResultsCreateWithDocuments Deprecated in Mac OS X v10.4
• SKSearchResultsCreateWithQuery Deprecated in Mac OS X v10.4
• SKSearchResultsGetCount Deprecated in Mac OS X v10.4
• SKSearchResultsGetInfoInRange Deprecated in Mac OS X v10.4
• SKSearchResultsGetTypeID Deprecated in Mac OS X v10.4

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 CFURLRef object for.

Discussion

You can use this function to create a CFURL Reference 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.

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.

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.

Related Sample Code

• SeeMyFriends

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.

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.

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.

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.

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.

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.

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

SKDocumentGetTypeID

Gets the type identifier for Search Kit document URL objects.

CFTypeID SKDocumentGetTypeID (void);

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.

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).

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.

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).

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.

Related Sample Code

• SeeMyFriends

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.

Related Sample Code

• SeeMyFriends

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Related Sample Code

• SeeMyFriends

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.

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.

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.

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.

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.

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.

Special Considerations

You cannot use CFMakeCollectable with SKIndex objects.

Related Sample Code

• SeeMyFriends

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.

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.

Special Considerations

You cannot use CFMakeCollectable with SKIndex objects.

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.

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.

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.

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.

SKIndexDocumentIteratorGetTypeID

Gets the type identifier for Search Kit document iterators.

CFTypeID SKIndexDocumentIteratorGetTypeID (void);

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.

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.

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.

Related Sample Code

• SeeMyFriends

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

SKIndexGetIndexType

Gets the category of an index.

SKIndexType SKIndexGetIndexType (
   SKIndexRef      inIndex
);

Parameters

inIndex

The index whose category you want to know.

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.

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.

SKIndexGetMaximumDocumentID

Gets the highest-numbered document ID in an index.

SKDocumentID SKIndexGetMaximumDocumentID (
   SKIndexRef  inIndex
);

Parameters

inIndex

An 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.

SKIndexGetMaximumTermID

Gets the highest-numbered term ID in an index.

CFIndex SKIndexGetMaximumTermID (
   SKIndexRef  inIndex
);

Parameters

inIndex

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.

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.

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.

SKIndexGetTermIDForTermString

Gets the ID for a term in an index.

CFIndex SKIndexGetTermIDForTermString (
   SKIndexRef      inIndex,
   CFStringRef     inTermString
);

Parameters

inIndex

The index you want to examine.

inTermString

The term string whose corresponding ID you want.

SKIndexGetTypeID

Gets the type identifier for Search Kit indexes.

CFTypeID SKIndexGetTypeID (void);

Discussion

Search Kit represents indexes with the SKIndexRef opaque type. If your code needs to determine whether a particular data type is an index, you can use this function along with the CFGetTypeID function and perform a comparison.

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

SKIndexMoveDocument

Changes the parent of a document URL object in an index.

Boolean SKIndexMoveDocument (
   SKIndexRef      inIndex,
   SKDocumentRef   inDocument,
   SKDocumentRef   inNewParent
);

Parameters

inIndex

The index containing the document URL object (SKDocumentRef) you want to move.

inDocument

The document URL object you want to move.

inNewParent

The new parent document URL object for the document URL object you want to move.

Discussion

When your application moves a document, use this function to update the index to reflect the change.

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.

SKIndexOpenWithData

Opens an existing, named index for searching only.

SKIndexRef SKIndexOpenWithData (
   CFDataRef       inData,
   CFStringRef     inIndexName
);

Parameters

inData

The index to open.

inIndexName

The name of the index. Can be NULL, in which case this function attempts to open the index with the default name of IADefaultIndex.

Discussion

An index opened by SKIndexOpenWithData can be searched but not updated. To open an index for updating, use SKIndexOpenWithMutableData.

If inIndexName is NULL and inData does not contain an index with the default name, this function returns 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.

A call to SKIndexOpenWithData retains the opened index. When your application no longer needs the index, dispose of it by calling SKIndexClose.

Special Considerations

You cannot use CFMakeCollectable with SKIndex objects.

SKIndexOpenWithMutableData

Opens an existing, named index for searching and updating.

SKIndexRef SKIndexOpenWithMutableData (
   CFMutableDataRef    inData,
   CFStringRef         inIndexName
);

Parameters

inData

The index to open.

inIndexName

The name of the index. Can be NULL, in which case this function attempts to open the index with the default name of IADefaultIndex.

Discussion

An index opened by SKIndexOpenWithMutableData may be searched or updated. To open an index for search only, use the SKIndexOpenWithData function.

If inIndexName is NULL and inData does not contain an index with the default name, this function returns 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.

A call to SKIndexOpenWithMutableData retains the opened index. When your application no longer needs the index, dispose of it by calling SKIndexClose.

Special Considerations

You cannot use CFMakeCollectable with SKIndex objects.

SKIndexOpenWithURL

Opens an existing, named index stored in a file whose location is specified with a CFURL object.

SKIndexRef SKIndexOpenWithURL (
   CFURLRef        inURL,
   CFStringRef     inIndexName,
   Boolean         inWriteAccess
);

Parameters

inURL

The location of the index.

inIndexName

The name of the index. Can be NULL.

inWriteAccess

A Boolean value indicating whether the index is open for updating. To open an index for searching only, pass false (0 or kCFBoolenFalse). To open it for searching and updating, pass true (1 or kCFBooleanTrue).

Discussion

A call to SKIndexOpenWithURL retains the opened index. When your application no longer needs the index, dispose of it by calling SKIndexClose.

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

You cannot use CFMakeCollectable with SKIndex objects.

SKIndexRemoveDocument

Removes a document URL object and its children, if any, from an index.

Boolean SKIndexRemoveDocument (
   SKIndexRef      inIndex,
   SKDocumentRef   inDocument
);

Parameters

inIndex

The index from which you want to remove the document URL object (SKDocumentRef).

inDocument

The document URL object to remove.

Discussion

When your application deletes a document, use this function to update the index to reflect the change.

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.

Related Sample Code

• SeeMyFriends

SKIndexRenameDocument

Changes the name of a document URL object in an index.

Boolean SKIndexRenameDocument (
   SKIndexRef      inIndex,
   SKDocumentRef   inDocument,
   CFStringRef     inNewName
);

Parameters

inIndex

The index containing the document URL object (SKDocumentRef) whose name you want to change.

inDocument

The document URL object whose name you want to change.

inNewName

The new name for the document URL object.

Discussion

When your application changes the name of a document, use this function to update the index to reflect the change.

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.

SKIndexSetDocumentProperties

Sets the application-defined properties of a document URL object.

void SKIndexSetDocumentProperties (
   SKIndexRef          inIndex,
   SKDocumentRef       inDocument,
   CFDictionaryRef     inProperties
);

Parameters

inIndex

An index containing the document URL object (SKDocumentRef) whose properties you want to set.

inDocument

The document URL object whose properties you want to set.

inProperties

A CFDictionary object containing the properties to apply to the document URL object.

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 persistently set application-defined properties for a document URL object in an index. This function replaces a document URL object’s existing properties dictionary with the new one. To obtain a copy of a document URL object’s properties dictionary, use SKIndexCopyDocumentProperties.

SKIndexSetMaximumBytesBeforeFlush

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

void SKIndexSetMaximumBytesBeforeFlush (
   SKIndexRef  inIndex
   CFIndex     inBytesForUpdate
);

Discussion

This function is rarely needed and is likely to be deprecated. Search Kit keeps track of index updates that are not yet committed to disk. Apple recommends using the default memory size limit for index updates, which is currently 2 million bytes.

Special Considerations

Apple recommends use of the SKIndexFlush function instead of SKIndexSetMaximumBytesBeforeFlush.

Version Notes

In Mac OS X v10.3, the default memory size limit for index updates was 1 million bytes.

SKLoadDefaultExtractorPlugIns

Tells Search Kit to use the Spotlight metadata importers.

void SKLoadDefaultExtractorPlugIns (void);

Discussion

The Spotlight metadata importers determine the kMDItemTextContent property for each document passed to the SKIndexAddDocument function. See http://developer.apple.com/macosx/tiger/spotlight.html.

Call the SKLoadDefaultExtractorPlugIns function once at application launch to tell Search Kit to use the Spotlight metadata importers. The function SKIndexAddDocument will then use Spotlight’s importers to extract the text from supported files and place that text into an index, leaving the markup behind.

Version Notes

In versions of Mac OS X prior to Mac OS X v10.4, Search Kit used its own set of default text extractor plug-ins. The file types supported by Search Kit’s default text extractor plug-ins were:

• plaintext

• PDF

• HTML

• RTF

• Microsoft Word (.doc)

SKSearchCancel

Cancels an asynchronous search request.

void SKSearchCancel (
   SKSearchRef                 inSearch
);

Parameters

inSearch

The search object whose associated asynchronous search you want to cancel.

Discussion

Call this function when you want to cancel an asynchronous search that you initiated with SKSearchCreate. This function stops the search process if it is still in progress at the time. It does not dispose of the search object (SKSearchRef).

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.

SKSearchCreate

Creates an asynchronous search object for querying an index, and initiates search.

SKSearchRef SKSearchCreate (
   SKIndexRef              inIndex,
   CFStringRef             inQuery,
   SKSearchOptions         inSearchOptions
);

Parameters

inIndex

The index to query.

inQuery

The query string to search for.

inSearchOptions

The search options. May be NULL. See the “SKSearchOptions” enumeration for a description of the available options.

Discussion

This function creates an asynchronous search object for querying the document contents in an index. It also initiates the search on a separate thread.

After you create the search object, call SKSearchFindMatches to retrieve results. You can call SKSearchFindMatches immediately. To cancel a search, call SKSearchCancel.

For normal (non-similarity-based) queries, Search Kit discerns the type of query—Boolean, prefix, phrase, and so on—from the syntax of the query itself. Moreover, Search Kit supports multiple query types within a single search. For example, the following query includes Boolean, prefix, and suffix searching:

appl* OR *ing

This query will return documents containing words that begin with “appl” as well as documents that contain words that end with “ing”.

For similarity searches, specified with the kSKSearchOptionFindSimilar flag in the inSearchOptions parameter, SKSearchCreate ignores all query operators.

The query operators that SKSearchCreate recognizes for non-similarity searching are:

The operators AND, OR, and NOT are case sensitive.

Search Kit performs Unicode normalization on query strings and on the text placed into indexes. It uses Unicode Normalization Form KC (NFKC, compatibility decomposition followed by canonical composition) as documented in Unicode Standard Annex #15. For example, the a-grave character, ‘à’, can be written as the two Unicode characters (0x0061, 0x0300) or as the single Unicode character 0x00E0. Search Kit will normalize (0x0061, 0x0300) to 0x00E0. For more information on Unicode normalization, see http://unicode.org/reports/tr15.

Search Kit further normalizes query strings and indexes by stripping diacritical marks and by forcing characters to lowercase. For example, Search Kit normalizes each of the following characters to ‘a’: ‘a’, ‘à’, ‘A’, and ‘À’.

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 search object, dispose of it by calling CFRelease.

Special Considerations

Search Kit supports logical exclusion. The NOT and ! operators behave as though they were EXCLUDE operators. For example, a search for ‘red NOT blue’ returns all documents that contain the word ‘red’ and do not contain the word ‘blue’.

Unary Boolean operators, however, are not currently implemented in Search Kit. A search, for example, for ‘NOT blue’, returns zero documents no matter what their content.

You cannot use CFMakeCollectable with SKSearch objects. In a garbage-collected environment, you must use CFRelease to dispose of an SKSearch object.

Version Notes

Mac OS X version 10.4 uses a completely revised, and far more powerful, query approach than did earlier versions of Mac OS X. Refer to the Discussion in this function for details. Refer to SKSearchResultsCreateWithQuery (deprecated) for a description of Search Kit’s behavior in earlier versions of Mac OS X.

In versions of Mac OS X prior to version 10.4, Search Kit did not perform Unicode normalization, and did not remove diacritical marks.

Related Sample Code

• SeeMyFriends

SKSearchFindMatches

Extracts search result information from a search object.

Boolean SKSearchFindMatches (
   SKSearchRef         inSearch,
   CFIndex             inMaximumCount,
   SKDocumentID        *outDocumentIDsArray,
   float               *outScoresArray,
   CFTimeInterval      maximumTime
   CFIndex             *outFoundCount
);

Parameters

inSearch

A reference to a search object (SKSearchRef) previously created with SKSearchCreate.

inMaximumCount

The maximum number of items to find. For each item found, SKSearchFindMatches places the associated document ID into the outDocumentIDsArray array. Specify an inMaximumCount of 0 to find as many items as possible within maximumTime.

outDocumentIDsArray

On input, a pointer to an array for document IDs. On output, points to points to the previously allocated array, which now contains the found document IDs. The size of this array must be equal to inMaximumCount.

outScoresArray

On input, a pointer to an array for scores. On output, points to the previously allocated array, which now contains relevance scores for the found items. The size of this array, if not NULL, must be equal to inMaximumCount. Can be NULL on input, provided that your application doesn’t need this information. Search Kit does not normalize relevance scores, so they can be very large.

maximumTime

The maximum number of seconds before this function returns, whether or not inMaximumCount items have been found. Setting maximumTime to 0 tells the search to return quickly

outFoundCount

On input, a pointer to a CFIndex object that will hold the number of items found. On output, points to the CFIndex object that now contains the actual number of items found.

Discussion

The SKSearchFindMatches extracts results from a find operation initiated by a search object (SKSearchRef).

This function provides results to its output parameters simply in the order in which they are found. This reduces latency to support search-as-you-type functionality. Larger scores mean greater relevance.

You can call this function on a search object repeatedly to get additional sets of search results. For example, if you call this function twice with an inMaximumCount value of 10, the first call will put the first 10 items found into the output arrays and the second call will put the second 10 items found into the output arrays.

Applications are free to display relevance scores in any appropriate manner. One simple way is to divide each relevance score by the largest number returned to get relevance numbers scaled linearly from 0.0 to 1.0. Search Kit does not scale the relevance scores for you, because you may want to combine the scores from several calls on a search object or the scores from calls to more than one search object.

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.

Before invoking a search, call SKIndexFlush on all indexes you will query to ensure that updates to the indexes have been flushed to disk.

Related Sample Code

• SeeMyFriends

SKSearchGetTypeID

Gets the type identifier for Search Kit search objects.

CFTypeID SKSearchGetTypeID (void);

Discussion

Search Kit represents searches with search objects (SKSearchRef opaque types). If your code needs to determine whether a particular data type is a search object, you can use this function along with the CFGetTypeID function and perform a comparison.

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

SKSummaryCopyParagraphAtIndex

Gets a specified paragraph from the text in a summarization object.

CFStringRef SKSummaryCopyParagraphAtIndex (
   SKSummaryRef        summary,
   CFIndex             i,
);

Parameters

summary

The summarization object containing the text from which you want a paragraph.

i

The ordinal number of the paragraph in the original text, with the first paragraph designated by zero (this function uses zero-based indexing).

SKSummaryCopyParagraphSummaryString

Gets a text string consisting of a summary with, at most, the requested number of paragraphs.

CFStringRef SKSummaryCopyParagraphSummaryString (
   SKSummaryRef        summary,
   CFIndex             numParagraphs
);

Parameters

summary

The summarization object containing the text from which you want a summarization.

numParagraphs

The maximum number of paragraphs you want in the summary.

SKSummaryCopySentenceAtIndex

Gets a specified sentence from the text in a summarization object.

CFStringRef SKSummaryCopySentenceAtIndex (
   SKSummaryRef        summary,
   CFIndex             i,
);

Parameters

summary

The summarization object containing the text from which you want a sentence.

i

The ordinal number of the sentence in the original text, with the first sentence designated by zero (this function uses zero-based indexing).

SKSummaryCopySentenceSummaryString

Gets a text string consisting of a summary with, at most, the requested number of sentences.

CFStringRef SKSummaryCopySentenceSummaryString (
   SKSummaryRef        summary,
   CFIndex             numSentences
);

Parameters

summary

The summarization object containing the text from which you want a summarization.

numSentences

The maximum number of sentences you want in the summary.

SKSummaryCreateWithString

Creates a summary object based on a text string.

SKSummaryRef SKSummaryCreateWithString (
   CFStringRef     inString
);

Parameters

inString

The text string that you want to summarize.

Discussion

The SKSummaryCreateWithString function creates a summarization object that pre-analyzes a text string to support fast summarization. When your application no longer needs the summarization object, dispose of it by calling CFRelease.

SKSummaryGetParagraphCount

Gets the number of paragraphs in a summarization object.

CFIndex SKSummaryGetParagraphCount (
   SKSummaryRef    summary
);

Parameters

summary

The summarization object whose paragraphs you want to count.

SKSummaryGetParagraphSummaryInfo

Gets detailed information about a body of text for constructing a custom paragraph-based summary string.

CFIndex SKSummaryGetParagraphSummaryInfo (
   SKSummaryRef            summary,
   CFIndex                 numParagraphsInSummary,
   CFIndex                 *outRankOrderOfParagraphs,
   CFIndex                 *outParagraphIndexOfParagraphs
);

Parameters

summary

The summarization object containing the text from which you want to build a summary.

numParagraphsInSummary

The maximum number of paragraphs you want in the summary.

outRankOrderOfParagraphs

On input, a pointer to an array of CFIndex objects. On output, points to the previously allocated array, which now lists the summarization relevance rank of each paragraph in the original text. The most important paragraph gets a rank of 1. The array size must equal numParagraphsInSummary, or else be NULL if you don’t want to get the relevance ranks.

outParagraphIndexOfParagraphs

On output, points to an array containing the ordinal number for each paragraph in the original text. Use the SKSummaryCopyParagraphAtIndex function with one of these numbers to get the corresponding paragraph. The array size must equal numParagraphsInSummary, or else be NULL if you don’t want to get the ordinal numbers of the paragraphs.

SKSummaryGetSentenceCount

Gets the number of sentences in a summarization object.

CFIndex SKSummaryGetSentenceCount (
   SKSummaryRef    summary
);

Parameters

summary

The summarization object whose sentences you want to count.

SKSummaryGetSentenceSummaryInfo

Gets detailed information about a body of text for constructing a custom sentence-based summary string.

CFIndex SKSummaryGetSentenceSummaryInfo (
   SKSummaryRef            summary,
   CFIndex                 numSentencesInSummary,
   CFIndex                 *outRankOrderOfSentences,
   CFIndex                 *outSentenceIndexOfSentences,
   CFIndex                 *outParagraphIndexOfSentences
);

Parameters

summary

The summarization object containing the text from which you want to build a summary.

numSentencesInSummary

The maximum number of sentences you want in the summary.

outRankOrderOfSentences

On input, a pointer to an array of CFIndex objects. On output, points to the previously allocated array, which now lists the summarization relevance rank of each sentence in the original text. The most important sentence gets a rank of 1. The array size must equal numSentencesInSummary, or else be NULL if you don’t want to get the rank orders.

outSentenceIndexOfSentences

On input, a pointer to an array of CFIndex objects. On output, points to the previously allocated array, which now contains the ordinal number for each sentence in the original text. Use the SKSummaryCopySentenceAtIndex function with one of these numbers to get the corresponding sentence. The array size must equal numSentencesInSummary, or else be NULL if you don’t want to get the ordinal numbers of the sentences.

outParagraphIndexOfSentences

On input, a pointer to an array of CFIndex objects. On output, points to the previously allocated array, which now contains the ordinal number for the paragraph that each corresponding sentence, referenced in outSentenceIndexOfSentences, appears in. The array size must equal numSentencesInSummary, or else be NULL if you don’t want to get the ordinal numbers of the sentences.

SKSummaryGetTypeID

Gets the type identifier for Search Kit summarization objects.

CFTypeID SKSummaryGetTypeID (void);

Discussion

Search Kit represents summarization results with summarization objects (SKSummaryRef opaque types). If your code needs to determine whether a particular data type is a summary, you can use this function along with the CFGetTypeID function and perform a comparison.

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

Callbacks

Developers should avoid using the callbacks listed in this section; instead, use SKSearchCreate and SKSearchFindMatches.

SKSearchResultsFilterCallBack

Deprecated. Use SKSearchCreate and SKSearchFindMatches instead, which do not use a callback.

typedef Boolean (SKSearchResultsFilterCallBack) (
   SKIndexRef     inIndex,
   SKDocumentRef     inDocument,
   void      *inContext

If you name your function MySearchResultsFilter, you would declare it like this:

Boolean MySearchResultsFilter (
   SKIndexRef     inIndex,
   SKDocumentRef     inDocument,
   void      *inContext
);

Parameters

inIndex

The index you are searching.

inDocument

The document URL object within the index you are searching.

inContext

An application-specified context which you set when calling SKSearchResultsCreateWithQuery or SKSearchResultsCreateWithDocuments.

Discussion

Deprecated. Defines a pointer to a search-results filtering callback function for hit testing and processing during a search. Use this callback function to perform custom filtering on the search hits returned by the SKSearchResultsCreateWithQuery and SKSearchResultsCreateWithDocuments functions. Return true to keep this document URL object (SKDocumentRef) in the results, false to filter it out.

Data Types

SKDocumentRef

Defines an opaque data type representing a document’s URL.

typedef struct __SKDocument *SKDocumentRef;

Discussion

A document URL object is a generic location specification for a document. It is built from a document scheme, a parent document, and a document name. You can convert back and forth between document URL objects and CFURL objects using Search Kit’s SKDocumentCreateWithURL and SKDocumentCopyURL functions.

To create a Search Kit document URL object, use SKDocumentCreateWithURL when you can provide a complete URL, or use SKDocumentCreate when you want to specify document location indirectly using a parent document URL object. For other operations on documents, see “Working with Documents and Terms.”

If you create document URL objects with indirect locations using the SKDocumentCreate function, you can resolve the locations by assembling them piece by piece, starting with a document URL object and going up step by step, parent to parent.

SKIndexDocumentIteratorRef

Defines an opaque data type representing an index-based document iterator.

typedef struct __SKIndexDocumentIterator *SKIndexDocumentIteratorRef;

Discussion

A Search Kit document iterator lets your application loop through all the document URL objects owned by a given parent document URL object. To create an iterator, use SKIndexDocumentIteratorCreate. To get a copy of the next document in the set owned by the iterator, use SKIndexDocumentIteratorCopyNext.

SKIndexRef

Defines an opaque data type representing an index.

typedef struct __SKIndex *SKIndexRef;

Discussion

A Search Kit index object contains the textual contents of one or more documents, as well as document URL objects (SKDocumentRefs) representing those documents’ locations.

To create a new disk-based Search Kit index object, use SKIndexCreateWithURL. To create a memory-based index, use SKIndexCreateWithMutableData. For other operations on indexes, see “Creating, Opening, and Closing Indexes” and “Managing Indexes.” Also see“Fast Asynchronous Searching.”

Special Considerations

You cannot use CFMakeCollectable with SKIndex objects. In a garbage-collected environment, you must use SKIndexClose to dispose of an SKIndex object.

SKSearchRef

Defines an opaque data type representing a an asynchronous search.

typedef struct __SKSearch *SKSearchRef;

Discussion

A search object is created when you call the SKSearchCreate function.

Special Considerations

You cannot use CFMakeCollectable with SKSearch objects. In a garbage-collected environment, you must use CFRelease to dispose of an SKSearch object.

SKSummaryRef

Defines an opaque data type representing summarization information.

typedef struct __SKSummary *SKSummaryRef;

Discussion

A summarization object contains summarization information, including summary text.

SKDocumentID

Defines an opaque data type representing a lightweight document identifier.

typedef CFIndex SKDocumentID;

Discussion

Use document IDs rather than document URL objects (SKDocumentRefs) whenever possible. Using document IDs results in faster searching.

You can work with document IDs using a variety of Search Kit functions. See SKIndexGetMaximumDocumentID, SKIndexCopyDocumentForDocumentID, SKIndexCopyInfoForDocumentIDs, SKIndexCopyDocumentRefsForDocumentIDs, SKIndexCopyDocumentURLsForDocumentIDs, SKIndexCopyDocumentIDArrayForTermID, and SKIndexCopyTermIDArrayForDocumentID.

SKSearchResultsRef

Deprecated. Use asynchronous searching with SKSearchCreate instead, which does not employ search groups.

typedef struct __SKSearchResults *SKSearchResultsRef;

Discussion

Defines an opaque data type representing the result of a search. To perform a query and generate search results, use SKSearchResultsCreateWithQuery or SKSearchResultsCreateWithDocuments. To examine the result of a search, use SKSearchResultsGetInfoInRange. For other operations on search results, see “Legacy Support for Synchronous Searching.”

SKSearchGroupRef

Deprecated. Use asynchronous searching with SKSearchCreate instead, which does not employ search groups.

typedef struct __SKSearchGroup *SKSearchGroupRef;

Discussion

Defines an opaque data type representing a search group.

A search group is a group of one or more indexes to be searched. To create a search group, use SKSearchGroupCreate. For other operations with search groups, see “Fast Asynchronous Searching.”

Constants

Text Analysis Keys

Each of these constants is an optional key in a Search Kit index’s text analysis properties dictionary. The constant descriptions describe the corresponding values for each of these keys. These keys are declared in the Analysis.h header file.

   
const CFStringRef kSKMinTermLength;
const CFStringRef kSKStopWords;
const CFStringRef kSKSubstitutions;
const CFStringRef kSKMaximumTerms;
const CFStringRef kSKProximityIndexing;
const CFStringRef kSKTermChars;
const CFStringRef kSKStartTermChars;
const CFStringRef kSKEndTermChars;

Constants

kSKMinTermLength

The minimum term length to index. Specified as a CFNumber object. If this optional key is not present, Search Kit indexing defaults to a minimum term length of 1.

Available in Mac OS X v10.3 and later.

Declared in SKAnalysis.h.

kSKStopWords

A set of stopwords—words not to index. Specified as a CFSet object. There is no default stopword list. You must supply your own.

Available in Mac OS X v10.3 and later.

Declared in SKAnalysis.h.

kSKSubstitutions

A dictionary of term substitutions—terms that differ in their character strings but that match during a search. Specified as a CFDictionary object.

Available in Mac OS X v10.3 and later.

Declared in SKAnalysis.h.

kSKMaximumTerms

The maximum number of number unique terms to index in each document. Specified as a CFNumber object.

Search Kit indexes from the beginning of a document. When it has indexed the first n unique terms, it stops.

The default number of maximum terms, which applies if you do not provide a number, is 2000.

To tell Search Kit to index all the terms in each document without limit, specify a value of 0.

Available in Mac OS X v10.4 and later.

Declared in SKAnalysis.h.

kSKProximityIndexing

A Boolean flag indicating whether or not Search Kit should use proximity indexing. The flag can be a 0 or kCFBoolenFalse value (for false) or a 1 or kCFBooleanTrue value for true.

Proximity indexing supports phrase searching. If this key is not present in an index’s text analysis properties dictionary, Search Kit defaults to not adding proximity information to the index.

Available in Mac OS X v10.4 and later.

Declared in SKAnalysis.h.

kSKTermChars

Additional valid starting-position “word” characters for indexing and querying. The corresponding value, a CFString object, specifies the additional valid “word” characters that you want to be considered as valid starting characters of terms for indexing and querying. “Word” characters are contrasted with nonword characters, such as spaces.

The value of kSKStartTermChars, if this key is present, overrides the value of kSKTermChars for the first character of a term.

By default, Search Kit considers alphanumeric characters as valid starting characters for terms, and considers all others (including the underscore character) to be nonword characters.

Available in Mac OS X v10.4 and later.

Declared in SKAnalysis.h.

kSKStartTermChars

Additional valid starting-position “word” characters for indexing and querying. The corresponding value, a CFString object, specifies the additional valid “word” characters that you want to be considered as valid starting characters of terms for indexing and querying. “Word” characters are contrasted with nonword characters, such as spaces.

The value of kSKStartTermChars, if this key is present, overrides the value of kSKTermChars for the first character of a term.

By default, Search Kit considers alphanumeric characters as valid starting characters for terms, and considers all others (including the underscore character) to be nonword characters.

Available in Mac OS X v10.4 and later.

Declared in SKAnalysis.h.

kSKEndTermChars

Additional valid last-position “word” characters for indexing and querying. The corresponding value, a CFString object, specifies the additional valid “word” characters that you want to be considered as valid ending characters of terms for indexing and querying. “Word” characters are contrasted with nonword characters, such as spaces.

The value of kSKEndTermChars, if this key is present, overrides the value of kSKTermChars for the last character of a term.

By default, Search Kit considers alphanumeric characters as valid ending characters for terms, and considers all others (including the underscore character) to be nonword characters.

Available in Mac OS X v10.4 and later.

Declared in SKAnalysis.h.

SKDocumentIndexState

The indexing state of a document.

enum SKDocumentIndexState {
   kSKDocumentStateNotIndexed  = 0,
   kSKDocumentStateIndexed     = 1,
   kSKDocumentStateAddPending  = 2,
   kSKDocumentStateDeletePending= 3
};

Constants

kSKDocumentStateNotIndexed

Specifies that the document is not indexed.

Available in Mac OS X v10.3 and later.

Declared in SKIndex.h.

kSKDocumentStateIndexed

Specifies that the document is indexed.

Available in Mac OS X v10.3 and later.

Declared in SKIndex.h.

kSKDocumentStateAddPending

Specifies that the document is not in the index but will be added after the index is flushed or closed.

Available in Mac OS X v10.3 and later.

Declared in SKIndex.h.

kSKDocumentStateDeletePending

Specifies that the document is in the index but will be deleted after the index is flushed or closed.

Available in Mac OS X v10.3 and later.

Declared in SKIndex.h.

SKSearchOptions

Specifies the search options available for the SKSearchCreate function.

typedef UInt32 SKSearchOptions;
enum SKSearchType {
   kSKSearchOptionDefault = 0,
   kSKSearchOptionNoRelevanceScores = 1L << 0,
   kSKSearchOptionSpaceMeansOR = 1L << 1
   kSKSearchOptionFindSimilar = 1L << 2
};

Constants

kSKSearchOptionDefault

Default search options include:

• Relevance scores will be computed

• Spaces in a query are interpreted as Boolean AND operators.

• Do not use similarity searching.

Available in Mac OS X v10.4 and later.

Declared in SKSearch.h.

kSKSearchOptionNoRelevanceScores

This option saves time during a search by suppressing the computation of relevance scores.

Available in Mac OS X v10.4 and later.

Declared in SKSearch.h.

kSKSearchOptionSpaceMeansOR

This option alters query behavior so that spaces are interpreted as Boolean OR operators.

Available in Mac OS X v10.4 and later.

Declared in SKSearch.h.

kSKSearchOptionFindSimilar

This option alters query behavior so that Search Kit returns references to documents that are similar to an example text string. When this option is specified, Search Kit ignores all query operators.

Available in Mac OS X v10.4 and later.

Declared in SKSearch.h.

SKIndexType

Specifies the category of an index.

enum SKIndexType {
   kSKIndexUnknown         = 0,
   kSKIndexInverted        = 1,
   kSKIndexVector          = 2,
   kSKIndexInvertedVector  = 3
};

Constants

kSKIndexUnknown

Specifies an unknown index type.

Available in Mac OS X v10.3 and later.

Declared in SKIndex.h.

kSKIndexInverted

Specifies an inverted index, mapping terms to documents.

Available in Mac OS X v10.3 and later.

Declared in SKIndex.h.

kSKIndexVector

Specifies a vector index, mapping documents to terms.

Available in Mac OS X v10.3 and later.

Declared in SKIndex.h.

kSKIndexInvertedVector

Specifies an index type with all the capabilities of an inverted and a vector index.

Available in Mac OS X v10.3 and later.

Declared in SKIndex.h.

Deprecated Text Analysis Keys

Search Kit ignores the kSKLanguageTypes constant. It determines language directly by document content.

   
const CFStringRef kSKLanguageTypes;

Constants

kSKLanguageTypes

Deprecated—Search Kit ignores this constant.

In releases of Mac OS X previous to version 10.4, each string in this key’s corresponding value specifies a language to use for indexing. Each such string is a two character ISO 639-1 code. For example, 'en' for English, 'ja' for Japanese, and so on. If this key is not present, Search Kit uses the Mac OS X preferences system to determine the primary language from the user’s locale.

Available in Mac OS X v10.3 and later.

Deprecated in Mac OS X v10.4.

Declared in SKAnalysis.h.

Version Notes

In releases of Mac OS X prior to version 10.4, the kSKLanguageTypes constant was an optional key in an index’s text analysis properties dictionary. Starting in Mac OS X v10.4, Search Kit ignores this constant and determines language directly by the document content. A document may use multiple languages.

Deprecated Search Keys

Search Kit ignores the constants in this group. Use asynchronous searching with SKSearchCreate instead, which uses query syntax to determine search type.

enum SKSearchType {
   kSKSearchRanked         = 0,
   kSKSearchBooleanRanked  = 1,
   kSKSearchRequiredRanked = 2,
   kSKSearchPrefixRanked   = 3
};

Constants

kSKSearchRanked

Deprecated. Specifies a basic ranked search.

Available in Mac OS X v10.3 and later.

Declared in SKSearch.h.

kSKSearchBooleanRanked

Deprecated. Specifies a query that can include Boolean operators including '|', '&', '!', '(', and ')'.

Available in Mac OS X v10.3 and later.

Declared in SKSearch.h.

kSKSearchRequiredRanked

Deprecated. Specifies a query that can include required ('+') or excluded ('-') terms.

Available in Mac OS X v10.3 and later.

Declared in SKSearch.h.

kSKSearchPrefixRanked

Deprecated. Specifies a prefix-based search, which matches terms that begin with the query string.

Available in Mac OS X v10.3 and later.

Declared in SKSearch.h.

Version Notes

In releases of Mac OS X prior to version 10.4, these constants specify the category of search to perform. Starting with Mac OS X v10.4, use asynchronous searching with SKSearchCreate instead, which uses query syntax to determine search type.

In older versions of Mac OS X, these constants specify the various search types you can use with SKSearchResultsCreateWithQuery. Each of these specifies a set of ranked search hits. The kSKSearchRanked and kSKSearchPrefixRanked constants can be used for all index types. The kSKSearchBooleanRanked and kSKSearchRequiredRanked constants cannot be used for vector indexes.