Next Page >

Hide TOC

Legacy Document

Important: The Find by Content API is deprecated as of Mac OS X v10.4. A much more complete solution for finding and displaying information is provided by the Search Kit. See Search Kit Programming Guide for guidelines on using the Search Kit.

Find By Content Reference (Not Recommended)

Framework	ApplicationServices/ApplicationServices.h
Declared in	FindByContent.h

Overview

Whereas the Find by Content API searches specified volumes or folders for words typed in by a user, Search Kit uses a much faster fully indexed search to return relevant content of all sorts. Because the Search Kit takes a different approach to searching for and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Seach Kit functions for Find by Content functions. However, the basic features of the Search Kit can be implemented very quickly, and Search Kit offers much greater capability than the Find by Content API.

Previous to Mac OS X version 10.2, the main client for Find by Content was Sherlock; in versions 10.2 and 10.3 it was the Finder. In version 10.4 and later, Search Kit is used instead by the Finder, Mail, and Spotlight.

Carbon supports Find By Content, but note that it is not contained within the Carbon framework.

Functions by Task

Working With Indexes

Setting Up a Search Session Object

Executing a Search

Getting Information About Search Session Hits

Deallocating Hit Lists and Search Sessions

Summarizing Text

Working with Universal Procedure Pointers

Deprecated Functions

Callbacks

FBCCallbackProcPtr

Defines a pointer to a function that can cancel a search operation.

typedef Boolean (*FBCCallbackProcPtr)
(
   UInt16 phase,
   float percentDone,
   void * data
);

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

Boolean MyFBCCallbackProcPtr (
   UInt16 phase,
   float percentDone,
   void * data
);

Parameters

phase
percentDone
data: A pointer to data needed by your callback. This is the same data you provided to the function FBCSetSessionCallback in the data parameter.

Return Value

Return true if you wants to cancel the current operation. Otherwise return false.

Discussion

Find by Content invoke your callback periodically (approximately every 5 ticks) while searching. Your callback can cancel a search operation by returning a value of true.

Availability

Available in Mac OS X v10.0 through Mac OS X v10.4.

Declared In

FindByContent.h

FBCHitTestProcPtr

Defines a pointer to a function that performs search-hit testing.

typedef Boolean (*FBCHitTestProcPtr)
(
   const FSRef * theFile,
   void * data
);

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

Boolean MyFBCHitTestProcPtr (
   const FSRef * theFile,
   void * data
);

Parameters

theFile: A pointer to an FSRef that specifies the location of file that matches the search query.
data: A pointer to data needed by your callback. This is the same data you provided to the function FBCSetSessionHitTest in the data parameter.

Return Value

Return true if your callback wants to accept the file as a valid match or false to reject it.

Discussion

You can use this callback to impose additional matching criteria in addition to that provided to Find by Content. For example, you could accept a hit only if the file has a creation date later than a specified date.

Availability

Available in Mac OS X v10.2 through Mac OS X v10.4.

Declared In

FindByContent.h

Data Types

FBCCallbackUPP

Defines a universal procedure pointer to a search cancellation callback.

typedef FBCCallbackProcPtr FBCCallbackUPP;

Discussion

For more information, see the description of the FBCCallbackProcPtr callback function.

Availability

Available in Mac OS X v10.0 through Mac OS X v10.4.

Declared In

FindByContent.h

FBCHitTestUPP

Defines a universal procedure pointer to a search-hit testing callback.

typedef FBCHitTestProcPtr FBCHitTestUPP;

Discussion

For more information, see the description of the FBCHitTestProcPtr callback function.

Availability

Available in Mac OS X v10.2 through Mac OS X v10.4.

Declared In

FindByContent.h

FBCSearchSession

Defines pointer to an opaque data type (referred to as a search session object) that contains a collection of state information used in a search session.

typedef struct OpaqueFBCSearchSession * FBCSearchSession;

Discussion

You call the function FBCCreateSearchSessionto create a new search session object. When no longer need the search session object, you must dispose of it by calling the function FBCDestroySearchSession.

Availability

Available in Mac OS X v10.0 through Mac OS X v10.4.

Declared In

FindByContent.h

FBCSummaryRef

A pointer to an opaque data type (referred to as a summary reference object) that contains summary information, from which summary text can be obtained.

typedef struct OpaqueFBCSummaryRef * FBCSummaryRef;

Discussion

You call the function FBCGetSummaryOfCFStringto create a new summary reference object. When no longer need the summary reference object, you must dispose of it by calling the function FBCDisposeSummary.

Availability

Available in Mac OS X v10.2 through Mac OS X v10.4.

Declared In

FindByContent.h

FBCWordItem

Defines a data type for an ordinary C string used for searching.

typedef char* FBCWordItem;

Availability

Available in Mac OS X v10.0 through Mac OS X v10.4.

Declared In

FindByContent.h

FBCWordList

Defines an array of word items.

typedef FBCWordItem * FBCWordList;

Availability

Available in Mac OS X v10.0 through Mac OS X v10.4.

Declared In

FindByContent.h

Constants

Language Constants

Define values for language constants.

enum {
   kFBCenglishHighWord = 0x80000000,
   kFBCdutchHighWord = 0x40000000,
   kFBCgermanHighWord = 0x20000000,
   kFBCswedishHighWord = 0x10000000,
   kFBCdanishHighWord = 0x08000000,
   kFBCspanishHighWord = 0x04000000,
   kFBCportugueseHighWord = 0x02000000,
   kFBCitalianHighWord = 0x01000000,
   kFBCfrenchHighWord = 0x00800000,
   kFBCromanHighWord = 0x00400000,
   kFBCicelandicHighWord = 0x00200000,
   kFBChebrewHighWord = 0x00100000,
   kFBCarabicHighWord = 0x00080000,
   kFBCcenteuroHighWord = 0x00040000,
   kFBCcroatianHighWord = 0x00020000,
   kFBCturkishHighWord = 0x00010000,
   kFBCromanianHighWord = 0x00008000,
   kFBCgreekHighWord = 0x00004000,
   kFBCcyrillicHighWord = 0x00002000,
   kFBCdevanagariHighWord = 0x00001000,
   kFBCgujuratiHighWord = 0x00000800,
   kFBCgurmukhiHighWord = 0x00000400,
   kFBCjapaneseHighWord = 0x00000200,
   kFBCkoreanHighWord = 0x00000100,
   kFBCdefaultLanguagesHighWord = 0xFF800000
};

Discussion

Language constants are passed as parameters to the function FBCIndexItemsInLanguages. The purpose of these constants is to tell Find by Content what languages the user expects the files to contain. From this, Find by Content infer the character encodings to look for, and for some languages, what lists of words to exclude from the index and what rules to use in reducing words to their stems.

These constants are bits in a 64-bit array that consists of two UInt32 words. In the current implementation the low word is always 0, so values for the high word are given. If both UInt32 words are 0, the default value of kDefaultLanguagesHighWord is used.

Phase Values

Define values that are passed to a progress callback function to indicate what phase of an operation Find By Content is currently performing; most of these values are not used in Mac OS X.

enum {
   kFBCphIndexing = 0,
   kFBCphFlushing = 1,
   kFBCphMerging = 2,
   kFBCphMakingIndexAccessor = 3,
   kFBCphCompacting = 4,
   kFBCphIndexWaiting = 5,
   kFBCphSearching = 6,
   kFBCphMakingAccessAccessor = 7,
   kFBCphAccessWaiting = 8,
   kFBCphSummarizing = 9,
   kFBCphIdle = 10,
   kFBCphCanceling = 11
};