Technote 1141

/* SimpleSetUpSession allocates a new search session and
    returns a FBCSearchSession value in the *session
    parameter. if an error occurs, *session is left
    untouched. */
            
OSErr SimpleSetUpSession(FBCSearchSession* session)
{
    OSErr err;
    FBCSearchSession newsession;
   
        /* set up our local variables */
    err = noErr;
    newsession = NULL;
    if (session == NULL) return paramErr;
   
        /* create the new session */
    err = FBCCreateSearchSession(&newsession);
    if (err != noErr) goto bail;
   
        /* search all available local volumes */
    err = FBCAddAllVolumesToSession(newsession, false);
    if (err != noErr) goto bail;
   
        /* store our result and leave */
    *session = newsession;
    return noErr;
   
bail:
    if (newsession != NULL)
        FBCDestroySearchSession(newsession);
    return err;
}
                                

/* SetUpVolumeSession allocates a new search session and
    returns a FBCSearchSession value in the *session parameter.
    if vCount is not zero, then vRefNums points to an array of
    volume reference numbers for volumes that are to be searched.
    if any of the vRefNums refer to a volume without an index,
    paramErr is returned.  */
            
OSErr SetUpVolumeSession (FBCSearchSession* session,
                            UInt16 vCount, SInt16 *vRefNums)
{
    OSErr err;
    UInt16 i;
    FBCSearchSession newsession;
   
        /* set up our local variables */
    err = noErr;
    newsession = NULL;
    if (vCount == 0) return paramErr;
    if (session == NULL) return paramErr;
    if (vRefNums == NULL) return paramErr;
   
        /* create the new session */
    err = FBCCreateSearchSession(&newsession);
    if (err != noErr) goto bail;
   
        /* search the volumes specified in vRefNums */
   
    for (i=0; i
                        

OSErr SimpleFindByQuery (char *query, FBCSearchSession *session)
{
    OSErr err;
    FBCSearchSession newsession;
	
        /* set up locals, check parameters... */
    if (query[0] == 0) return paramErr;
    if (session == NULL) return paramErr;
    newsession = NULL;
	
        /* allocate a new search session */
    err = SimpleSetUpSession(&newsession);
    if (err != noErr) goto bail;
	
        /* Here is the call that does the actual search,
        storing the results in the search session. */
    err = FBCDoQuerySearch(newsession, query,
                                   NULL, 0, 100, 100);
    if (err != noErr) goto bail;
	
        /* save the results and return */
    *session = newsession;
    return noErr;
	
bail:
    if (newsession != NULL)
        FBCDestroySearchSession(newsession);
    return err;
}
                                

enum {
    kMaxVols = 20,
    maxHits = 10,
    maxHitTerms = 10
};
   
OSErr RestrictedFindByQuery (char *query, UInt16 dirCount,
                                  FSSpec* dirList,
                                      FBCSearchSession* session)
{
    UInt16 vCount, i;
    SInt16 vRefNums[kMaxVols], normalVol;
    FBCSearchSession newsession;
   
    vCount = 0;
    newsession = NULL;
    if (dirList == NULL || dirCount == 0) return paramErr;
    if (query == NULL) return paramErr;
    if (*query == 0) return paramErr;
    if (session == NULL) return paramErr;
   
        /* collect all of the unique volume reference numbers
        from the list of FSSpecs provided in the parameters. */
    for (i=0; i>dirCount; i++) {
        Boolean found;
        HParamBlockRec pb;
   
            /* ensure the vRefNum is a volume
            reference number */
        pb.volumeParam.ioVRefNum = dirList[i].vRefNum;
        pb.volumeParam.ioNamePtr = NULL;
        pb.volumeParam.ioVolIndex = 0;
        if ((err = PBHGetVInfoSync(&pb)) != noErr) goto bail;
        normalVol = pb.volumeParam.ioVRefNum;
   
            /* make sure it's not already in the list */
        for (found = false, j=0; j<vCount; j++)
            if (vRefNums[j] == normalVol) {
                found = true;
                break;
            }
   
            /* add the volume to the list */
        if (!found && vCount < kMaxVols)
            vRefNums[vCount++] = normalVol;
    }
   
        /* set up a session to use the volumes we found */
    err = SetUpVolumeSession(&newsession, vCount, vRefNums);
    if (err != noErr) goto bail;
   
        /* Here is the call that does the actual search,
        storing the results in the search session. */
    err = FBCDoQuerySearch(newsession, (char*)queryTxt,
                    dirList, dirCount, maxHits, maxHitTerms);
    if (err != noErr) goto bail;
    
        /* save the result and return */
    *session = newsession;
    return noErr;
   
bail:
    if (newsession != NULL)
        FBCDestroySearchSession(newsession);
    return err;
}
                                

   typedef OSErr (*HitProc) (FSSpec theDoc,
                             float score,
                             UInt32 nTerms,
                             FBCWordList hitTerms);
   
/* SampleHandleHits can be called after a search to enumerate
    the search results.  For each search hit, the hitFileProc
    function parameter is called with information describing
    the target.  */
OSErr SampleHandleHits (FBCSearchSession session,
                                   HitProc hitFileProc)
{	
    OSErr err;
    UInt32 hitCount, i;
    FSSpec targetDoc;
    float targetScore;
    FBCWordList targetTerms;
    UInt32 numTerms;
   
        /* set up locals, check parameters */
    targetTerms = NULL;
    if (hitFileProc == NULL) return paramErr;
    if (session == NULL) return paramErr;
   
        /* count the number of hits in this session */
    err = FBCGetHitCount(session, &hitCount);
    if (err != noErr) goto bail;
   
        /* iterate through the hits */
    for (i = 0; i < hitCount; i++) {
   
            /* get the target document's FSSpec */
        err = FBCGetHitDocument(session, i, &targetDoc);
        if (err != noErr) goto bail;
   
            /* get the score for this document */
        err = FBCGetHitScore(session, i, &targetScore);
        if (err != noErr) goto bail;
   
            /* get a list of the words matched in 
            this document */
        numTerms = maxHitTerms;
        err = FBCGetMatchedWords(session, i, &numTerms,
                                            &targetTerms);
        if (err != noErr) goto bail;
   
            /* call the call back routine provided as a
            parameter to do something with the information. */
        err = hitFileProc(&targetDoc, score, numTerms,
                                            targetTerms);
        if (err != noErr) goto bail;
   
            /* clean up before moving to the next iteration. */
        FBCDestroyWordList(targetTerms, numTerms);
        targetTerms = NULL;
   
    }
	
    return noErr;
	
bail:
    if (targetTerms != NULL)
        FBCDestroyWordList(targetTerms, numTerms);
    return err;
} 
                               

                        enum
{
    gestaltFBCIndexingState      = 'fbci',
    gestaltFBCindexingSafe       = 0,
    gestaltFBCindexingCritical   = 1
};
   
   
enum
{
    gestaltFBCVersion            = 'fbcv',
    gestaltFBCCurrentVersion     = 0x0011
};
   
enum /* error codes */
{
    kFBCvTwinExceptionErr     = -30500,
                    /* miscellaneous error */
    kFBCnoIndexesFound        = -30501,
    kFBCallocFailed           = -30502,
                    /*probably low memory*/
    kFBCbadParam              = -30503,
    kFBCfileNotIndexed        = -30504,
    kFBCbadIndexFile          = -30505,
                    /*bad FSSpec, or bad data in file*/
    kFBCtokenizationFailed    = -30512,
                    /*couldn't read from document or query*/
    kFBCindexNotFound         = -30518,
    kFBCnoSearchSession       = -30519,
    kFBCaccessCanceled        = -30521,
    kFBCindexNotAvailable     = -30523,
    kFBCsearchFailed          = -30524,
    kFBCsomeFilesNotIndexed   = -30525,
    kFBCillegalSessionChange  = -30526,
                    /*tried to add/remove vols */
                    /*to a session  that has hits*/
    kFBCanalysisNotAvailable  = -30527,
    kFBCbadIndexFileVersion   = -30528,
    kFBCsummarizationCanceled = -30529,
    kFBCbadSearchSession      = -30531,
    kFBCnoSuchHit             = -30532
};
   
enum /* codes sent to the callback routine */
{
    kFBCphSearching             = 6,
    kFBCphMakingAccessAccessor  = 7,
    kFBCphAccessWaiting         = 8,
    kFBCphSummarizing           = 9,
    kFBCphIdle                  = 10,
    kFBCphCanceling             = 11
};
                        

    /* A collection of state information for searching*/
typedef struct OpaqueFBCSearchSession* FBCSearchSession;
   
    /* An ordinary C string (used for hit/doc terms)*/
typedef char* FBCWordItem;
   
    /* An array of WordItems*/
typedef FBCWordItem* FBCWordList;
                        

OSErr FBCCreateSearchSession(
             FBCSearchSession* searchSession);
OSErr FBCDestroySearchSession(
             FBCSearchSession theSession);
OSErr FBCCloneSearchSession(
             FBCSearchSession original,
             FBCSearchSession* clone);
                        

OSErr FBCAddAllVolumesToSession(
             FBCSearchSession theSession,
             Boolean includeRemote);	
OSErr FBCSetSessionVolumes(
             FBCSearchSession theSession,
             const SInt16 vRefNums[ ],
             UInt16 numVolumes);
OSErr FBCAddVolumeToSession(
             FBCSearchSession theSession,
             SInt16 vRefNum);
OSErr FBCRemoveVolumeFromSession(
             FBCSearchSession theSession,
             SInt16 vRefNum);
OSErr FBCGetSessionVolumeCount(
             FBCSearchSession theSession,
             UInt16* count);
OSErr FBCGetSessionVolumes(
             FBCSearchSession theSession,
             SInt16 vRefNums[ ],
             UInt16* numVolumes);
                        

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

OSErr FBCGetHitCount(
             FBCSearchSession theSession,
             UInt32* count);
OSErr FBCGetHitDocument(
             FBCSearchSession theSession,
             UInt32 hitNumber,
             FSSpec* theDocument);
OSErr FBCGetHitScore(
             FBCSearchSession theSession,
             UInt32 hitNumber,
             float* score);
OSErr FBCGetMatchedWords(
             FBCSearchSession theSession,
             UInt32 hitNumber,
             UInt32* wordCount,
             FBCWordList* list);
OSErr FBCGetTopicWords(
             FBCSearchSession theSession,
             UInt32 hitNumber,
             UInt32* wordCount,
             FBCWordList* list);
OSErr FBCDestroyWordList(
             FBCWordList theList,
             UInt32 wordCount);
OSErr FBCReleaseSessionHits(
             FBCSearchSession theSession);
                        

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

Boolean FBCVolumeIsIndexed (SInt16 theVRefNum);
Boolean FBCVolumeIsRemote(SInt16 theVRefNum);
OSErr FBCVolumeIndexTimeStamp(SInt16 theVRefNum,
             UInt32* timeStamp);
OSErr FBCVolumeIndexPhysicalSize(SInt16 theVRefNum,
             UInt32* size); 
                        

void FBCSetHeapReservation(UInt32 bytes);
                        

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