| Framework | CoreServices/CoreServices.h |
| Declared in | SKDocument.h SKIndex.h SKSearch.h SKSummary.h |
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 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.
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
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
Search Kit can import the textual content of file-based documents into indexes using the Spotlight metadata importers.
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
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.
Search Kit’s Summarization functions supplant those in Apple’s Find by Content API.
SKSummaryCreateWithString
SKSummaryGetSentenceSummaryInfo
SKSummaryGetParagraphSummaryInfo
SKSummaryGetSentenceCount
SKSummaryGetParagraphCount
SKSummaryCopySentenceAtIndex
SKSummaryCopyParagraphAtIndex
SKSummaryCopySentenceSummaryString
SKSummaryCopyParagraphSummaryString
SKSummaryGetTypeID
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.
SKSearchGroupGetTypeID
SKSearchResultsGetTypeID
SKSearchGroupCopyIndexes Deprecated in Mac OS X v10.4
SKSearchGroupCreate 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
Builds a CFURL object from a document URL object.
CFURLRef SKDocumentCopyURL ( SKDocumentRef inDocument );
The document URL object (SKDocumentRef) that you want a CFURL object for.
A CFURL object representing a document location, or NULL on failure.
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.
SKDocument.h
Creates a document URL object based on a scheme, parent, and name.
SKDocumentRef SKDocumentCreate ( CFStringRef inScheme, SKDocumentRef inParent, CFStringRef inName );
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.
The document URL object one step up in the document hierarchy. Can be NULL.
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.
The new document URL object, or NULL on failure.
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.
SKDocument.h
Creates a document URL object from a CFURL object.
SKDocumentRef SKDocumentCreateWithURL ( CFURLRef 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.
The new document URL object (SKDocumentRef), or NULL if the document URL object could not be created.
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.
SKDocument.hGets the name of a document URL object.
CFStringRef SKDocumentGetName ( SKDocumentRef inDocument );
The document URL object (SKDocumentRef) whose name you want to get.
A CFString object containing the document URL object’s name, or NULL on failure.
SKDocument.hGets a document URL object’s parent.
SKDocumentRef SKDocumentGetParent ( SKDocumentRef inDocument );
The document URL object (SKDocumentRef) whose parent you want to get.
The parent document URL object, or NULL on failure.
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.
SKDocument.hGets the scheme name for a document URL object.
CFStringRef SKDocumentGetSchemeName ( SKDocumentRef inDocument );
The document URL object (SKDocumentRef) whose scheme you want to get.
A CFString object containing the document URL object’s scheme name, or NULL on failure.
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
SKDocument.hGets the type identifier for Search Kit document URL objects.
CFTypeID SKDocumentGetTypeID (void);
A CFTypeID object containing the type identifier for the document URL object (SKDocumentRef).
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.
SKDocument.h
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 );
The index you are adding the document URL object to.
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.
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.
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).
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.
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.
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.
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.
SKIndex.h
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 );
The index to which you are adding the document URL object (SKDocumentRef).
The document URL object to add.
The document text. Can be NULL.
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).
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.
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.
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.
SKIndex.h
Closes an index.
void SKIndexClose ( SKIndexRef inIndex );
The index to close.
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.
SKIndex.h
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 );
The index you want to compact.
A Boolean value of true on success, or false on failure.
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.
SKIndex.h
Obtains a document URL object from an index.
SKDocumentRef SKIndexCopyDocumentForDocumentID ( SKIndexRef inIndex, SKDocumentID inDocumentID );
The index containing the document URL object (SKDocumentRef).
The ID of the document URL object you want to copy.
A Search Kit document URL object.
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.
SKIndex.h
Obtains document IDs for documents that contain a given term.
CFArrayRef SKIndexCopyDocumentIDArrayForTermID ( SKIndexRef inIndex, CFIndex inTermID );
The index to search.
The ID of the term to search for.
An array of CFNumbers, each the ID for a document URL object that points to a document containing the search term.
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.
SKIndex.h
Obtains the application-defined properties of an indexed document.
CFDictionaryRef SKIndexCopyDocumentProperties ( SKIndexRef inIndex, SKDocumentRef inDocument );
The index containing the document URL object (SKDocumentRef) whose properties you want to copy.
The document URL object whose properties you want to copy.
A CFDictionary object containing the document URL object’s (SKDocumentRef’s) properties, or NULL on failure.
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.
SKIndex.h
Gets document URL objects based on document IDs.
void SKIndexCopyDocumentRefsForDocumentIDs ( SKIndexRef inIndex, CFIndex inCount, SKDocumentID *inDocumentIDsArray, SKDocumentRef *outDocumentRefsArray );
The index containing the document information.
The number of document IDs in inDocumentIDsArray.
Points to an array of document IDs corresponding to the document URL objects (SKDocumentRefs) you want.
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.
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.
SKSearch.h
Gets document URLs based on document IDs.
void SKIndexCopyDocumentURLsForDocumentIDs ( SKIndexRef inIndex, CFIndex inCount, SKDocumentID *inDocumentIDsArray, CFURLRef *outDocumentURLsArray );
The index containing the document information.
The number of document IDs in inDocumentIDsArray.
Points to an array of document IDs corresponding to the document URLs (CFURL objects) you want.
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.
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.
SKSearch.h
Gets document names and parent IDs based on document IDs.
void SKIndexCopyInfoForDocumentIDs ( SKIndexRef inIndex, CFIndex inCount, SKDocumentID *inDocumentIDsArray, CFStringRef *outNamesArray, SKDocumentID *outParentIDsArray );
The index containing the document information.
The number of document IDs in inDocumentIDsArray.
Points to an array of document IDs representing the documents whose names and parent IDs you want.
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.
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.
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.
SKSearch.h
Obtains the IDs for the terms of an indexed document.
CFArrayRef SKIndexCopyTermIDArrayForDocumentID ( SKIndexRef inIndex, SKDocumentID inDocumentID );
The index containing the document URL object (SKDocumentRef) and associated textual content.
The ID of the document whose term IDs you are copying.
A CFArray containing CFNumbers, each of which represents the ID for a term in a document.
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.
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.
SKIndex.h
Obtains a term, specified by ID, from an index.
CFStringRef SKIndexCopyTermStringForTermID ( SKIndexRef inIndex, CFIndex inTermID );
The index whose terms you are searching.
The ID of the term whose string you want.
A CFString containing the term specified by inTermID.
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.
SKIndex.h
Creates a named index stored in a CFMutableData object.
SKIndexRef SKIndexCreateWithMutableData ( CFMutableDataRef inData, CFStringRef inIndexName, SKIndexType inIndexType, CFDictionaryRef inAnalysisProperties );
An empty CFMutableData object to contain the index being created.
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.
The index type. See SKIndexType.
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.
The newly created index.
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.
SKIndex.h
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 );
The location of the index.
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.
The index type. See SKIndexType.
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.
A unique reference to the newly created index.
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.
SKIndex.h
Obtains the next document URL object from an index using a document iterator.
SKDocumentRef SKIndexDocumentIteratorCopyNext ( SKIndexDocumentIteratorRef inIterator );
The index-based document iterator. See SKIndexDocumentIteratorCreate for information on creating an document iterator, and SKIndexDocumentIteratorRef for more about iterators.
The next document URL object (SKDocumentRef) in the index.
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.
SKIndex.h
Creates an index-based iterator for document URL objects owned by a parent document URL object.
SKIndexDocumentIteratorRef SKIndexDocumentIteratorCreate ( SKIndexRef inIndex, SKDocumentRef inParentDocument );
The index you want to iterate across.
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.
An index-based document iterator.
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.
SKIndex.hGets the type identifier for Search Kit document iterators.
CFTypeID SKIndexDocumentIteratorGetTypeID (void);
A CFTypeID object containing the type identifier for the SKIndexDocumentIterator opaque type.
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.
SKIndex.h
Invokes all pending updates associated with an index and commits them to backing store.
Boolean SKIndexFlush ( SKIndexRef inIndex );
The index you want to update and commit to backing store.
A Boolean value of true on success, or false on failure.
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.
SKIndex.h
Gets the text analysis properties of an index.
CFDictionaryRef SKIndexGetAnalysisProperties ( SKIndexRef inIndex );
The index whose text-analysis properties you want to get.
A CFDictionary object containing the index’s text-analysis properties. On failure, returns NULL.
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.
SKIndex.h
Gets the total number of documents represented in an index.
CFIndex SKIndexGetDocumentCount ( SKIndexRef inIndex );
The index whose document URL objects (SKDocumentRefs) you want to count.
A CFIndex object containing the number of document URL objects in the index. On failure, returns 0.
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.
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.
SKIndex.h
Gets the ID of a document URL object in an index.
SKDocumentID SKIndexGetDocumentID ( SKIndexRef inIndex, SKDocumentRef inDocument );
The index containing the text of the document whose document URL object (SKDocumentRef) ID you want.
The document URL object whose ID you want.
A document ID object.
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.
SKIndex.hGets the current indexing state of a document URL object in an index.
SKDocumentIndexState SKIndexGetDocumentState ( SKIndexRef inIndex, SKDocumentRef inDocument );
The index containing the document URL object (SKDocumentRef) whose indexing state you want.
The document URL object whose indexing state you want.
A value indicating the document URL object’s indexing state.
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.
SKIndex.h
Gets the number of terms for a document in an index.
CFIndex SKIndexGetDocumentTermCount ( SKIndexRef inIndex, SKDocumentID inDocumentID );
The index containing the text of the document whose term count you want.
The ID of the document URL object (SKDocumentRef) whose term count you want. Obtain a document ID by calling SKIndexGetDocumentID.
A CFIndex object containing the number of terms in a document.
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.
SKIndex.h
Gets the number of occurrences of a term in a document.
CFIndex SKIndexGetDocumentTermFrequency ( SKIndexRef inIndex, SKDocumentID inDocumentID, CFIndex inTermID );
The index containing the text of the document whose term count you are interested in.
The ID of the document URL object whose associated term count you are interested in. Obtain a document ID by calling SKIndexGetDocumentID.
The ID of the term whose number of occurrences you want.
A CFIndex object containing the number of occurrences of a term in a document.
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.
SKIndex.hGets the category of an index.
SKIndexType SKIndexGetIndexType ( SKIndexRef inIndex );
The index whose category you want to know.
The category of the index. See the SKIndexType enumeration for a list of the various index categories. On failure, returns a value of kSKIndexUnknown.
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.
SKIndex.h
Not recommended. Gets the memory size limit for updates to an index, measured in bytes.
CFIndex SKIndexGetMaximumBytesBeforeFlush ( SKIndexRef inIndex );
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.
SKIndex.h
Gets the highest-numbered document ID in an index.
SKDocumentID SKIndexGetMaximumDocumentID ( SKIndexRef inIndex );
An index.
A document ID object containing the highest-numbered document ID in the index.
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.
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.
SKIndex.h
Gets the highest-numbered term ID in an index.
CFIndex SKIndexGetMaximumTermID ( SKIndexRef inIndex );
An index.
A CFIndex object containing the highest-numbered term ID in an index.
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.
SKIndex.h
Gets the number of documents containing a given term represented in an index.
CFIndex SKIndexGetTermDocumentCount ( SKIndexRef inIndex, CFIndex inTermID );
The index containing the text of the documents you want to examine.
The terms whose occurrences you want to know.
A CFIndex object containing the number of documents represented in an index that contain a given term.
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.
SKIndex.h