ADC Home > Reference Library > Reference > Carbon > Data Management > Find By Content Reference (Not Recommended) >

< Previous PageNext Page > Hide TOC

Legacy Documentclose button

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.

Deprecated Find By Content Reference (Not Recommended) Functions

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

Deprecated in Mac OS X v10.4

DisposeFBCCallbackUPP

Disposes of universal procedure pointer (UPP) to a search cancellation callback. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

void DisposeFBCCallbackUPP (
   FBCCallbackUPP userUPP
);

Parameters
userUPP

The universal procedure pointer.

Discussion

See the callback FBCCallbackProcPtr for more information.

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Availability
Declared In
FindByContent.h

DisposeFBCHitTestUPP

Disposes of universal procedure pointer (UPP) to a search-hit testing callback. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

void DisposeFBCHitTestUPP (
   FBCHitTestUPP userUPP
);

Parameters
userUPP

The universal procedure pointer.

Discussion

See the callback FBCHitTestProcPtr for more information.

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Availability
Declared In
FindByContent.h

FBCAddAllVolumesToSession

Adds all volumes to a search session. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

Not recommended

OSErr FBCAddAllVolumesToSession (
   FBCSearchSession theSession,
   Boolean includeRemote
);

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Carbon Porting Notes

This function does nothing in Mac OS X.

Availability
Declared In
FindByContent.h

FBCAddVolumeToSession

Adds one volume to a session. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

Not recommended

OSErr FBCAddVolumeToSession (
   FBCSearchSession theSession,
   SInt16 vRefNum
);

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Carbon Porting Notes

This function does nothing in Mac OS X.

Availability
Declared In
FindByContent.h

FBCBlindExampleSearch

Executes a similarity search. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

Not recommended

OSErr FBCBlindExampleSearch (
   const FSSpec examples[],
   UInt32 numExamples,
   const FSSpec targetDirs[],
   UInt32 numTargets,
   UInt32 maxHits,
   UInt32 maxHitWords,
   Boolean allIndexes,
   Boolean includeRemote,
   FBCSearchSession * theSession
);

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Carbon Porting Notes

Use the function FBCBlindExampleSearchWithCallback instead.

Availability
Declared In
FindByContent.h

FBCBlindExampleSearchWithCallback

Performs a similarity search that uses example files instead of a query string, and installs callbacks for progress reporting and search hit testing. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

OSErr FBCBlindExampleSearchWithCallback (
   const FSSpec examples[],
   UInt32 numExamples,
   const FSSpec targetDirs[],
   UInt32 numTargets,
   UInt32 maxHits,
   UInt32 maxHitWords,
   Boolean allIndexes,
   Boolean includeRemote,
   FBCSearchSession * theSession,
   FBCCallbackUPP callback,
   void * callbackData,
   FBCHitTestUPP userHitTest,
   void * userHitTestData
);

Parameters
examples

An array of FSSpec data types that specify the location of one or more examples files. The hits are the files that most resemble the examples in terms of weighted word frequencies.

numExamples

The number of examples in the examples array.

targetDirs

An array of FSSpec data types that specify the directories you want to search. Any directories that are not indexed are skipped.

numTargets

A value that specifies number of directories specified by the targetDirs parameter.

maxHits

A value that specifies the maximum number of hits you want. If you pass N for this parameter, you get the N most relevant hits found in an exhaustive search of the indexes (or all the hits if there are less than N).

maxHitWords

This parameter is ignored in Mac OS X version 10.2 and later.

allIndexes

This parameter is ignored in Mac OS X version 10.2 and later.

includeRemote

This parameter is ignored in Mac OS X version 10.2 and later.

theSession

A valid search session object. You obtain a search session object by calling the function FBCCreateSearchSession.

callback

A universal procedure pointer to your callback for cancelling a search. See FBCCallbackProcPtr for more information.

callbackData

A pointer to data needed by the callback specified by the callback parameter. Pass NULL if your callback does not require any data.

userHitTest

A universal procedure pointer a your callback for testing search hits. See FBCHitTestProcPtr for more information.

callbackData

A pointer to data needed by the callback specified by the userHitTest parameter. Pass NULL if your callback does not require any data.

Return Value

A result code. See “Find By Content Result Codes.”

Discussion

You should use the function FBCBlindExampleSearchWithCallback for cases where your example files have not been indexed. If the files have been indexed, it is simpler and more efficient for you to use the function FBCDoExampleSearch.

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Availability
Declared In
FindByContent.h

FBCCloneSearchSession

Clones a search session. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

Not recommended

OSErr FBCCloneSearchSession (
   FBCSearchSession original,
   FBCSearchSession * clone
);

Parameters
original

A valid search session object. You obtain a search session object by calling the function FBCCreateSearchSession.

clone

On return, points to a newly-created search session object that is a copy of the one specified by the original parameter.

Return Value

A result code. See “Find By Content Result Codes.”

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Availability
Declared In
FindByContent.h

FBCCreateSearchSession

Creates a search session. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

OSErr FBCCreateSearchSession (
   FBCSearchSession * searchSession
);

Parameters
searchSession

On return, points to a newly-created search session object. You provide a search session object as a parameter when you call other other search functions.

Return Value

A result code. See “Find By Content Result Codes.”

Discussion

You must create a search session using the function FBCCreateSearchSession before you can use any other search function.

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Availability
Declared In
FindByContent.h

FBCDeleteIndexFileForFolder

Deletes the index file associated with a folder. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

OSErr FBCDeleteIndexFileForFolder (
   const FSRef * folder
);

Parameters
folder

An FSRef that specifies the folder whose index file you want to delete.

Return Value

A result code. See “Find By Content Result Codes.”

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Availability
Declared In
FindByContent.h

FBCDestroySearchSession

Disposes of a search session object. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

OSErr FBCDestroySearchSession (
   FBCSearchSession theSession
);

Parameters
theSession

The search session object you want to dispose of. You obtain a search session object by calling the function FBCCreateSearchSession.

Return Value

A result code. See “Find By Content Result Codes.”

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Availability
Declared In
FindByContent.h

FBCDestroyWordList

Destroys a word list. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

Not recommended

OSErr FBCDestroyWordList (
   FBCWordList theList,
   UInt32 wordCount
);

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Availability
Declared In
FindByContent.h

FBCDisposeSummary

Disposes of a summary reference object. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

OSStatus FBCDisposeSummary (
   FBCSummaryRef summary
);

Parameters
summary

The summary reference object you want to dispose of. You obtain a summary reference object when you call the function FBCGetSummaryOfCFString.

Return Value

A result code. See “Find By Content Result Codes.”

Discussion

You must dispose of a summary reference object when you no longer need it.

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Availability
Declared In
FindByContent.h

FBCDoCFStringSearch

Initiates a search using a CFString as the query string. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

OSErr FBCDoCFStringSearch (
   FBCSearchSession theSession,
   CFStringRef queryString,
   const FSSpec targetDirs[],
   UInt32 numTargets,
   UInt32 maxHits,
   UInt32 maxHitWords
);

Parameters
theSession

A valid search session object. You obtain a search session object by calling the function FBCCreateSearchSession.

queryString

The query string specified as a CFString.

targetDirs

An array of FSSpec data types that specify the directories you want to search. Any directories that are not indexed are skipped.

numTargets

A value that specifies number of directories specified by the targetDirs parameter.

maxHits

A value that specifies the maximum number of hits you want. If you pass N for this parameter, you get the N most relevant hits found in an exhaustive search of the indexes (or all the hits if there are less than N).

maxHitWords

This parameter is ignored in Mac OS X version 10.2 and later.

Return Value

A result code. See “Find By Content Result Codes.”

Discussion

When the function FBCDoCFStringSearch returns, you must retrieve hit information by calling the functions FBCGetHitCount, FBCGetHitDocumentRef, and FBCGetHitScore. You call FBCGetHitCount to obtain the number of hits found. Then you can iterate through each hit to get the associated FSRef and score by calling FBCGetHitDocumentRef and FBCGetHitScore.

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Availability
Declared In
FindByContent.h

FBCDoExampleSearch

Performs a similarity search that uses example files instead of a query string. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

OSErr FBCDoExampleSearch (
   FBCSearchSession theSession,
   const UInt32 * exampleHitNums,
   UInt32 numExamples,
   const FSSpec targetDirs[],
   UInt32 numTargets,
   UInt32 maxHits,
   UInt32 maxHitWords
);

Parameters
theSession

A valid search session object. You must provide the search session object you provided to the search function FBCDoCFStringSearch.

exampleHitNums

A pointer to the hits obtained from a previous search using theSession search session object.

numExamples

The number of examples pointed to by the exampleHitNums parameter.

targetDirs

An array of FSSpec data types that specify the directories you want to search. Any directories that are not indexed are skipped.

numTargets

A value that specifies number of directories specified by the targetDirs parameter.

maxHits

A value that specifies the maximum number of hits you want. If you pass N for this parameter, you get the N most relevant hits found in an exhaustive search of the indexes (or all the hits if there are less than N).

maxHitWords

This parameter is ignored in Mac OS X version 10.2 and later.

Return Value

A result code. See “Find By Content Result Codes.”

Discussion

You should use the function FBCDoExampleSearch for cases where you example files have been indexed. If you example files have not been indexed, us the function FBCBlindExampleSearchWithCallback.

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Availability
Declared In
FindByContent.h

FBCDoQuerySearch

Initiates a search using a C string as the query string. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

OSErr FBCDoQuerySearch (
   FBCSearchSession theSession,
   char * queryText,
   const FSSpec targetDirs[],
   UInt32 numTargets,
   UInt32 maxHits,
   UInt32 maxHitWords
);

Parameters
theSession

A valid search session object. You obtain a search session object by calling the function FBCCreateSearchSession.

queryText

The query string specified as a C string.

numTargets

A value that specifies number of directories specified by the targetDirs parameter.

maxHits

A value that specifies the maximum number of hits you want. If you pass N for this parameter, you get the N most relevant hits found in an exhaustive search of the indexes (or all the hits if there are less than N).

maxHitWords

This parameter is ignored in Mac OS X version 10.2 and later.

Return Value

A result code. See “Find By Content Result Codes.”

Discussion

You should use the function FBCDoCFStringSearch instead of this one.

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Availability
Declared In
FindByContent.h

FBCFindIndexFileFolderForFolder

Gets the location of the index file associated with a directory. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

Not recommended

OSErr FBCFindIndexFileFolderForFolder (
   const FSRef * inFolder,
   FSRef * outFolder
);

Parameters
inFolder

A pointer to an FSRef that specifies the location of the folder that contains the index file for a directory.

outFolder

On output, points to the FSRef that specifies the directory that contains he index file.

Return Value

A result code. See “Find By Content Result Codes.”

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Availability
Declared In
FindByContent.h

FBCGetHitCount

Obtains the number of hits returned for a search session. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

OSErr FBCGetHitCount (
   FBCSearchSession theSession,
   UInt32 * count
);

Parameters
theSession

A valid search session object. You must provide the search session object you provided to the search function FBCDoCFStringSearch.

count

On return, points to the number of hits returned for the search on the object specified by theSession.

Return Value

A result code. See “Find By Content Result Codes.”

Discussion

You can iterate through each hit to get the associated FSRef and score by calling the functions FBCGetHitDocumentRef and FBCGetHitScore.

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Availability
Declared In
FindByContent.h

FBCGetHitDocument

Retrieves the FSSpec associated with a specific hit and search. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

OSErr FBCGetHitDocument (
   FBCSearchSession theSession,
   UInt32 hitNumber,
   FSSpec * theDocument
);

Parameters
theSession

A valid search session object. You must provide the search session object you provided to the search function FBCDoCFStringSearch.

hitNumber

A value that specifies the hit whose document you want to retrieve.

theDocument

A pointer to an FSSpec that specifies the location of the document associated with hitNumber for the search previously carried out on theSession.

Return Value

A result code. See “Find By Content Result Codes.”

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Availability
Declared In
FindByContent.h

FBCGetHitDocumentRef

Retrieves the FSRef associated with a specific hit and search. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

OSErr FBCGetHitDocumentRef (
   FBCSearchSession theSession,
   UInt32 hitNumber,
   FSRef * theDocument
);

Parameters
theSession

A valid search session object. You must provide the search session object you provided to the search function FBCDoCFStringSearch.

hitNumber

A value that specifies the hit whose document you want to retrieve.

theDocument

A pointer to an FSRef that specifies the location of the document associated with hitNumber for the search previously carried out on theSession.

Return Value

A result code. See “Find By Content Result Codes.”

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Availability
Declared In
FindByContent.h

FBCGetHitScore

Obtains the hit score associated with a specific hit. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

OSErr FBCGetHitScore (
   FBCSearchSession theSession,
   UInt32 hitNumber,
   float * score
);

Parameters
theSession

A valid search session object. You must provide the search session object you provided to the search function FBCDoCFStringSearch.

hitNumber

A value that specifies the hit whose document you want to retrieve.

float

A pointer to a value that specifies the hit score. Scores are normalized to range from 1.0 (most significant) to 0 (least significant).

Return Value

A result code. See “Find By Content Result Codes.”

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Availability
Declared In
FindByContent.h

FBCGetMatchedWords

Gets a list of matched words for a search session. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

Not recommended

OSErr FBCGetMatchedWords (
   FBCSearchSession theSession,
   UInt32 hitNumber,
   UInt32 * wordCount,
   FBCWordList * list
);

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Carbon Porting Notes

This function does nothing in Mac OS X.

Availability
Declared In
FindByContent.h

FBCGetSessionVolumeCount

Gets a volume count for a search session. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

Not recommended

OSErr FBCGetSessionVolumeCount (
   FBCSearchSession theSession,
   UInt16 * count
);

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Carbon Porting Notes

This function does nothing in Mac OS X.

Availability
Declared In
FindByContent.h

FBCGetSessionVolumes

Gets the volumes associated with a search session. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

Not recommended

OSErr FBCGetSessionVolumes (
   FBCSearchSession theSession,
   SInt16 vRefNums[],
   UInt16 * numVolumes
);

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Carbon Porting Notes

This function does nothing in Mac OS X.

Availability
Declared In
FindByContent.h

FBCGetSummaryOfCFString

Creates a summary reference object for CFString. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

OSStatus FBCGetSummaryOfCFString (
   CFStringRef inString,
   FBCSummaryRef * summary
);

Parameters
inString

A CFStringRef representing the text you want summarized. Summarization works with all languages that use white space to separate words, plus Japanese. It works best with text that is not broken into lines using CR and/or LF characters.

summary

On output, a newly-created summary reference object that contains summary information for the string specified by the inString parameter. A summary reference object is an opaque object. To access the information in this object, you can use the functions FBCGetSummarySentenceCount and FBCGetSummarySentences. You should call the function FBCDisposeSummary when you no longer need the summary reference object.

Return Value

A result code. See “Find By Content Result Codes.”

Discussion

A summary reference object is an opaque object that can very quickly give you a summary containing any desired number of sentences from 1 up to the total number of sentences found in the original text.

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Availability
Declared In
FindByContent.h

FBCGetSummarySentenceCount

Obtains the number of sentences in a summary reference object. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

OSStatus FBCGetSummarySentenceCount (
   FBCSummaryRef summary,
   UInt32 * numSentences
);

Parameters
summary

A valid summary reference object. You obtain a summary reference object when you call the function FBCGetSummaryOfCFString.

numSentences

On output, a pointer to the number of sentences contained in the summary.

Return Value

A result code. See “Find By Content Result Codes.”

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Availability
Declared In
FindByContent.h

FBCGetSummarySentences

Obtains a summary that contains a specified number of sentences. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

OSStatus FBCGetSummarySentences (
   FBCSummaryRef summary,
   CFStringRef * outString,
   UInt32 * numSentences,
   Boolean paragraphs
);

Parameters
summary

A valid summary reference object. You obtain a summary reference object when you call the function FBCGetSummaryOfCFString.

outString

On output, a pointer to a CFStringRef that contains the summary. You are responsible for releasing the CFStringRef when you no longer need it.

numSentences

On input, the number of sentences you want in the summary. On output, the number of sentences actually written into the summary. If you pass 0, Find by Content uses a logarithmic function to determine the number of sentences.

paragraphs

A Boolean value that specifies the content of the summary. If you pass true the summary is made up of whole paragraphs that contain the relevant sentences. If it is false, only the relevant sentences are included.

Return Value

A result code. See “Find By Content Result Codes.”

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Availability
Declared In
FindByContent.h

FBCGetTopicWords

Gets a list of topic words for a search session. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

Not recommended

OSErr FBCGetTopicWords (
   FBCSearchSession theSession,
   UInt32 hitNumber,
   UInt32 * wordCount,
   FBCWordList * list
);

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Carbon Porting Notes

This function does nothing in Mac OS X.

Availability
Declared In
FindByContent.h

FBCIndexItems

Indexes one or more files or folders. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

Not recommended

OSErr FBCIndexItems (
   FSSpecArrayPtr theItems,
   UInt32 itemCount
);

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Availability
Declared In
FindByContent.h

FBCIndexItemsInLanguages

Indexes one or more directories. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

OSErr FBCIndexItemsInLanguages (
   FSSpecArrayPtr theItems,
   UInt32 itemCount,
   UInt32 languageHighBits,
   UInt32 languageLowBits
);

Parameters
theItems

An FSPecArrayPtr that specifies the directory or directories to be indexed; subdirectories are included automatically.

itemCount

The number of items pointed to by theItems parameter.

languageHighBits

A value that specifies the languages to be used. The high bits are obtained by summing the desired constants defined in Language Constants.

languageLowBits

A value that specifies the languages to be used. The low bits should always be 0.

Return Value

A result code. See “Find By Content Result Codes.”

Discussion

Your application must first call the function FBCIndexItemsInLanguages to make an index of the files to be searched. Find by Content looks at the contents of each file (including the file's name) to make the index. For PDF and HTML files, the textual content is separated out from formatting information; for all other file types, the entire data of the file is used. The index is an invisible file.

Some file types do not contain words that are useful for searching, such as graphics files and application software. Find by Content has lists of Mac OS file types and filename extensions for such files, and any file that has one of the listed types or one of the listed extensions is treated specially when it is indexed. That is, the name of the file is indexed, but the contents are not. In addition, folder names are indexed. The lists of types and extensions are text files named StopTypes and StopExts. You can edit these lists using an editor (such as BBEdit or TextEdit). The files are located in the /System/Library/Find/ directory.

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Availability
Declared In
FindByContent.h

FBCReleaseSessionHits

Releases the hits associated with a search session object. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

OSErr FBCReleaseSessionHits (
   FBCSearchSession theSession
);

Parameters
theSession

A valid search session object. You obtain a search session object by calling the function FBCCreateSearchSession.

Return Value

A result code. See “Find By Content Result Codes.”

Discussion

The function FBCReleaseSessionHits releases the hits associated with a specific search session object, resetting the object so it can be used in another search. You are responsible for releasing a search session object when you no longer need it by calling the function FBCDestroySearchSession.

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Availability
Declared In
FindByContent.h

FBCRemoveVolumeFromSession

Removes a volume from a search session. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

Not recommended

OSErr FBCRemoveVolumeFromSession (
   FBCSearchSession theSession,
   SInt16 vRefNum
);

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Carbon Porting Notes

This function does nothing in Mac OS X.

Availability
Declared In
FindByContent.h

FBCSetCallback

Sets a callback. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

Not Recommended.

void FBCSetCallback (
   FBCCallbackUPP fn,
   void * data
);

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Carbon Porting Notes

Use the function FBCSetSessionCallback instead.

Availability
Declared In
FindByContent.h

FBCSetHeapReservation

Sets the amount of heap space to reserve for application use when Find by Content allocates memory. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

Not recommended

void FBCSetHeapReservation (
   UInt32 bytes
);

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Carbon Porting Notes

This function does nothing in Mac OS X.

Availability
Declared In
FindByContent.h

FBCSetSessionCallback

Sets a callback function that allows your application to cancel a search operation. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

void FBCSetSessionCallback (
   FBCSearchSession searchSession,
   FBCCallbackUPP fn,
   void * data
);

Parameters
searchSession

A valid search session object. You obtain a search session object by calling the function FBCCreateSearchSession.

fn

A universal procedure pointer to your callback for cancelling a search. See FBCCallbackProcPtr for more information.

data

A pointer to data needed by your callback. Pass NULL if your callback does not require any data.

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Availability
Declared In
FindByContent.h

FBCSetSessionHitTest

Sets a callback function that allows your application to perform search-hit testing. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

void FBCSetSessionHitTest (
   FBCSearchSession theSession,
   FBCHitTestUPP fn,
   void * data
);

Parameters
theSession

A valid search session object. You obtain a search session object by calling the function FBCCreateSearchSession.

fn

A universal procedure pointer a your callback for testing search-hits. See FBCHitTestProcPtr for more information.

data

A pointer to data needed by your callback. Pass NULL if your callback does not require any data.

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Availability
Declared In
FindByContent.h

FBCSetSessionVolumes

Sets the volumes for a search session. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

Not recommended

OSErr FBCSetSessionVolumes (
   FBCSearchSession theSession,
   const SInt16 vRefNums[],
   UInt16 numVolumes
);

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Carbon Porting Notes

This function does nothing in Mac OS X.

Availability
Declared In
FindByContent.h

FBCSummarize

Summarizes text that is specified as an ASCII buffer. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

OSErr FBCSummarize (
   const void * inBuf,
   UInt32 inLength,
   void * outBuf,
   UInt32 * outLength,
   UInt32 * numSentences
);

Parameters
inBuf

A pointer to the ASCII text you want summarized.

inLength

The length of the text buffer pointed to by inBuf.

outBuf

On output, points to the summarized text.

outLength

On output, points to a value that specifies the length of the summarized text.

numSentences

On input, points to a value that specifies the number of sentences desired in the summary. On output, points to the number of sentences actually written into the summary. If you pass 0, Find by Content uses a logarithmic function to determine the number of sentences.

Return Value

A result code. See “Find By Content Result Codes.”

Discussion

You should use the function FBCSummarizeCFString instead of FBCSummarize because the CFString version is more reliable and accurate.

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Availability
Declared In
FindByContent.h

FBCSummarizeCFString

Summarizes text that is specified as a CFString. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

OSStatus FBCSummarizeCFString (
   CFStringRef inString,
   CFStringRef * outString,
   UInt32 * numSentences
);

Parameters
inString

A CFStringRef representing the text you want summarized. Summarization works with all languages that use white space to separate words, plus Japanese. It works best with text that is not broken into lines using CR and/or LF characters.

outString

On output, points to the summarization. You are responsible for releasing this string.

numSentences

On input, points to a value that specifies the number of sentences you want in the summary. On output, points to the number of sentences actually written into the summary. If you pass 0, Find by Content uses a logarithmic function to determine the number of sentences.

Return Value

A result code. See “Find By Content Result Codes.”

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Availability
Declared In
FindByContent.h

FBCVolumeIndexPhysicalSize

Obtains the physical size of an index. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

Not recommended

OSErr FBCVolumeIndexPhysicalSize (
   SInt16 theVRefNum,
   UInt32 * size
);

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Carbon Porting Notes

This function does nothing in Mac OS X.

Availability
Declared In
FindByContent.h

FBCVolumeIndexTimeStamp

Obtains the date and time when an index was last updated. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

Not recommended

OSErr FBCVolumeIndexTimeStamp (
   SInt16 theVRefNum,
   UInt32 * timeStamp
);

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Carbon Porting Notes

This function does nothing in Mac OS X.

Availability
Declared In
FindByContent.h

FBCVolumeIsIndexed

Determines whether a volume is indexed. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

Not recommended

Boolean FBCVolumeIsIndexed (
   SInt16 theVRefNum
);

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Carbon Porting Notes

This function does nothing in Mac OS X.

Availability
Declared In
FindByContent.h

FBCVolumeIsRemote

Determines whether a volume is remote. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

Not recommended

Boolean FBCVolumeIsRemote (
   SInt16 theVRefNum
);

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Carbon Porting Notes

This function does nothing in Mac OS X.

Availability
Declared In
FindByContent.h

InvokeFBCCallbackUPP

Invokes a universal procedure pointer (UPP) to a search cancellation callback. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

Boolean InvokeFBCCallbackUPP (
   UInt16 phase,
   float percentDone,
   void * data,
   FBCCallbackUPP userUPP
);

Discussion

You should not need to call this function as Find by Content invokes your callback for you.

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Availability
Declared In
FindByContent.h

InvokeFBCHitTestUPP

Invokes a universal procedure pointer (UPP) to a search-hit testing callback. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

Boolean InvokeFBCHitTestUPP (
   const FSRef * theFile,
   void * data,
   FBCHitTestUPP userUPP
);

Discussion

You should not need to call this function as Find by Content invokes your callback for you.

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Availability
Declared In
FindByContent.h

NewFBCCallbackUPP

Creates a new universal procedure pointer (UPP) to a search cancellation callback. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

FBCCallbackUPP NewFBCCallbackUPP (
   FBCCallbackProcPtr userRoutine
);

Parameters
userRoutine

A pointer to your progress callback.

Return Value

See the description of the FBCCallbackUPP data type.

Discussion

See the callback FBCCallbackProcPtr for more information.

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Availability
Declared In
FindByContent.h

NewFBCHitTestUPP

Creates a new universal procedure pointer (UPP) to a search-hit testing callback. (Deprecated in Mac OS X v10.4. Use Search Kit instead; see Search Kit Programming Guide.)

FBCHitTestUPP NewFBCHitTestUPP (
   FBCHitTestProcPtr userRoutine
);

Parameters
userRoutine

A pointer to your search-hit-testing callback.

Return Value

See the description of the FBCHitTestUPP data type.

Discussion

See the callback FBCHitTestProcPtr for more information.

Special Considerations

Because the Search Kit takes a different approach to finding and displaying information from that used by the Find by Content API, you cannot make a one-to-one substitution of Search 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.

Availability
Declared In
FindByContent.h

< Previous PageNext Page > Hide TOC

© 2006 Apple Computer, Inc. All Rights Reserved. (Last updated: 2006-07-13)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.