/*
     File:       FindByContent.h
 
     Contains:   Public search interface for the Find by Content shared library
 
     Version:    Technology: 2.0
                 Release:    QuickTime 6.0.2
 
     Copyright:  (c) 1997-2001 by Apple Computer, Inc., all rights reserved.
 
     Bugs?:      For bug reports, consult the following page on
                 the World Wide Web:
 
                     http://developer.apple.com/bugreporter/
 
*/
#ifndef __FINDBYCONTENT__
#define __FINDBYCONTENT__

#ifndef __MACTYPES__
#include <MacTypes.h>
#endif

#ifndef __FILES__
#include <Files.h>
#endif

#ifndef __MACERRORS__
#include <MacErrors.h>
#endif




#if PRAGMA_ONCE
#pragma once
#endif

#ifdef __cplusplus
extern "C" {
#endif

#if PRAGMA_IMPORT
#pragma import on
#endif

#if PRAGMA_STRUCT_ALIGN
    #pragma options align=mac68k
#elif PRAGMA_STRUCT_PACKPUSH
    #pragma pack(push, 2)
#elif PRAGMA_STRUCT_PACK
    #pragma pack(2)
#endif

/*
   ***************************************************************************
   Phase values
   These values are passed to the client's callback function to indicate what
   the FBC code is doing.
   ***************************************************************************
*/
enum {
                                                                /* indexing phases*/
    kFBCphIndexing              = 0,
    kFBCphFlushing              = 1,
    kFBCphMerging               = 2,
    kFBCphMakingIndexAccessor   = 3,
    kFBCphCompacting            = 4,
    kFBCphIndexWaiting          = 5,                            /* access phases*/
    kFBCphSearching             = 6,
    kFBCphMakingAccessAccessor  = 7,
    kFBCphAccessWaiting         = 8,                            /* summarization*/
    kFBCphSummarizing           = 9,                            /* indexing or access*/
    kFBCphIdle                  = 10,
    kFBCphCanceling             = 11
};



/*
   ***************************************************************************
   Pointer types
   These point to memory allocated by the FBC shared library, and must be deallocated
   by calls that are defined below.
   ***************************************************************************
*/

/* 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;
/*
   ***************************************************************************
   Callback function type for progress reporting and cancelation during
   searching and indexing.  The client's callback function should call
   WaitNextEvent; a "sleep" value of 1 is suggested.  If the callback function
   wants to cancel the current operation (indexing, search, or doc-terms
   retrieval) it should return true.
   ***************************************************************************
*/

typedef CALLBACK_API_C( Boolean , FBCCallbackProcPtr )(UInt16 phase, float percentDone, void *data);
/*
   ***************************************************************************
   Set the callback function for progress reporting and cancelation during
   searching and indexing, and set the amount of heap space to reserve for
   the client's use when FBC allocates memory.
   ***************************************************************************
*/
EXTERN_API_C( void )
FBCSetCallback                  (FBCCallbackProcPtr     fn,
                                 void *                 data);

EXTERN_API_C( void )
FBCSetHeapReservation           (UInt32                 bytes);

/*
   ***************************************************************************
   Find out whether a volume is indexed, the date & time of its last
   completed  update, and its physical size.
   ***************************************************************************
*/

EXTERN_API_C( Boolean )
FBCVolumeIsIndexed              (SInt16                 theVRefNum);

EXTERN_API_C( Boolean )
FBCVolumeIsRemote               (SInt16                 theVRefNum);

EXTERN_API_C( OSErr )
FBCVolumeIndexTimeStamp         (SInt16                 theVRefNum,
                                 UInt32 *               timeStamp);

EXTERN_API_C( OSErr )
FBCVolumeIndexPhysicalSize      (SInt16                 theVRefNum,
                                 UInt32 *               size);

/*
   ***************************************************************************
   Create & configure a search session
   ***************************************************************************
*/

EXTERN_API_C( OSErr )
FBCCreateSearchSession          (FBCSearchSession *     searchSession);

EXTERN_API_C( OSErr )
FBCAddAllVolumesToSession       (FBCSearchSession       theSession,
                                 Boolean                includeRemote);

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

EXTERN_API_C( OSErr )
FBCAddVolumeToSession           (FBCSearchSession       theSession,
                                 SInt16                 vRefNum);

EXTERN_API_C( OSErr )
FBCRemoveVolumeFromSession      (FBCSearchSession       theSession,
                                 SInt16                 vRefNum);

EXTERN_API_C( OSErr )
FBCGetSessionVolumeCount        (FBCSearchSession       theSession,
                                 UInt16 *               count);

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

EXTERN_API_C( OSErr )
FBCCloneSearchSession           (FBCSearchSession       original,
                                 FBCSearchSession *     clone);

/*
   ***************************************************************************
   Execute a search
   ***************************************************************************
*/

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

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

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


/*
   ***************************************************************************
   Get information about hits [wrapper for THitItem C++ API]
   ***************************************************************************
*/

EXTERN_API_C( OSErr )
FBCGetHitCount                  (FBCSearchSession       theSession,
                                 UInt32 *               count);

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

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

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

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


/*
   ***************************************************************************
   Summarize a buffer of text
   ***************************************************************************
*/

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

/*
   ***************************************************************************
   Deallocate hit lists, word arrays, and search sessions
   ***************************************************************************
*/

EXTERN_API_C( OSErr )
FBCReleaseSessionHits           (FBCSearchSession       theSession);

EXTERN_API_C( OSErr )
FBCDestroyWordList              (FBCWordList            theList,
                                 UInt32                 wordCount);

EXTERN_API_C( OSErr )
FBCDestroySearchSession         (FBCSearchSession       theSession);

/*
   ***************************************************************************
   Index one or more files and/or folders
   ***************************************************************************
*/

#if CALL_NOT_IN_CARBON
EXTERN_API_C( OSErr )
FBCIndexItems                   (FSSpecArrayPtr         theItems,
                                 UInt32                 itemCount);

#endif  /* CALL_NOT_IN_CARBON */


#if PRAGMA_STRUCT_ALIGN
    #pragma options align=reset
#elif PRAGMA_STRUCT_PACKPUSH
    #pragma pack(pop)
#elif PRAGMA_STRUCT_PACK
    #pragma pack()
#endif

#ifdef PRAGMA_IMPORT_OFF
#pragma import off
#elif PRAGMA_IMPORT
#pragma import reset
#endif

#ifdef __cplusplus
}
#endif

#endif /* __FINDBYCONTENT__ */