Technote 1180

ページの先頭に戻る

コンテンツ検索が使用可能であるかどうかの判断 FBC では 2 つの Gestalt セレクタを定義しています。FBC のクライアントは、呼び出しを行う前に適切なバージョンのインプリメンテーションが使用可能であることを検証する必要があり、実際の検索を実行する前に FBC の索引作成ステータスをチェックしなければなりません。 enum { gestaltFBCVersion = 'fbcv', gestaltFBCCurrentVersion = 0x0011 }; gestaltFBCVersion セレクタは、コンピュータ上にインストールされている FBC のバージョンを返します。デベロッパは、このバージョンと、プログラムのコンパイルに使用したインタフェースのバージョン (gestaltFBCCurrentVersion を使って取得できる) を比較して、FBC への呼び出しを行うことが安全であるかどうかを判断することができます。gestaltFBCVersion のバージョンがアプリケーションのコンパイルに使用したインタフェースのバージョンと異なる場合、アプリケーションでは FBC への呼び出しを行わないようにしてください。 enum { gestaltFBCIndexingState = 'fbci', gestaltFBCindexingSafe = 0, gestaltFBCindexingCritical = 1 }; gestaltFBCIndexingState セレクタは、FBC の現在の索引作成ステータスに関する情報を返します。任意の時点で、索引作成ステータスは、gestaltFBCindexingSafe または gestaltFBCindexingCritical のいずれかになります。ステータスが gestaltFBCindexingCritical の場合、ステータスが gestaltFBCindexingSafe に戻るまで、実行した検索は同期遅延に陥ってしまいます。一方、返された FBC 索引作成ステータスが gestaltFBCindexingSafe であると、すべての検索が即座に実行されます。同期遅延を回避するには、デベロッパは gestaltFBCIndexingState セレクタをチェックして、返された索引作成ステータスが gestaltFBCindexingSafe のときだけ FBC への呼び出しを行うようにしてください。

ページの先頭に戻る

検索セッションを使った作業 FBC は、クライアントアプリケーションが「検索セッション」のオープンとクローズを行うことを許可します。検索セッションには、検索の結果、見つかった条件に一致するファイルのリストを含めて、検索に関するすべての情報が含まれます。FBC のクライアントは、このセクションで定義されているルーチンを使って、検索セッションへの参照の取得、検索セッションの変更、および検索セッションのステータスに対するクエリーを実行することができます。検索セッションへの参照は、FBC ライブラリによって所有されている opaque ポインタ型として定義されます。 typedef struct OpaqueFBCSearchSession* FBCSearchSession; 検索セッション構造体にアクセスするときは、ここで定義されているルーチンのみを使用してください。この中には、検索セッションの複製や破棄を行うために適切な FBC ルーチンを使用することも含まれます。検索セッションは複雑なメモリ構造体で、その中には、検索セッションを複製するときにコピーしたり、検索セッションの割り当てを解除するときに破棄する必要のあるその他のデータへのポインタが含まれます。 FBC ライブラリを使用するときに実行する通常の処理の流れは、検索セッションの作成、ターゲットとなる特定のボリュームに合わせた検索セッションの設定、検索の実行、検索結果のクエリー、そして検索の破棄という順序になります。このほかにも可能な検索方法として、検索セッションを再初期化して、それを別の検索でも繰り返し使用する機能、検索セッションのクローニングを行い、クローンを使ってさらに検索を実行する機能、また検索結果を特定のディレクトリに保存されているファイルに制限する機能などが用意されています。

ページの先頭に戻る

検索セッションのセットアップ 「リスト 6」に示すように、新しいセッションを作成して検索の順序を整えるには、FBC ライブラリへの少なくとも 2 つの呼び出しが必要になります。このサンプルでは、新しい検索セッションが作成され、それが索引ファイルを含むすべてのローカルボリュームを検索するように設定されます。FBCAddAllVolumesToSession を呼び出すことで、索引が作成されているローカルボリュームをすべて検索する検索セッションが自動的に設定されます。

/* SimpleSetUpSession は新しい検索セッションを割り当て、 FBCSearchSession 値を *session パラメータに返す。エラーが発生 すると、*session は手つかずのまま残される */ OSErr SimpleSetUpSession(FBCSearchSession* session) { OSErr err; FBCSearchSession newsession; /* ローカル変数をセットアップする */ err = noErr; newsession = NULL; if (session == NULL) return paramErr; /* 新しいセッションを作成する */ err = FBCCreateSearchSession(&newsession); if (err != noErr) goto bail; /* 使用可能なローカルボリュームをすべて検索する */ err = FBCAddAllVolumesToSession(newsession, false); if (err != noErr) goto bail; /* 結果を格納して処理を終了する */ *session = newsession; return noErr; bail: if (newsession != NULL) FBCDestroySearchSession(newsession); return err; }

リスト 6 索引が作成されているローカルボリュームをすべて検索する検索セッションのセットアップ

検索セッションによって検索されるボリュームをデベロッパがより詳細に制御できるように、FBC にはさまざまなルーチンのセットが用意されています。「リスト 7」は、新しい検索セッションを設定して、特定のボリュームのセットを検索する方法を具体的に示しています。

/* SetUpVolumeSession は新しい検索セッションを割り当て、 FBCSearchSession 値を *session パラメータに返す。vCount がゼ ロの場合、vRefNums は検索対象のボリュームに対するボリューム参 照番号の配列をポイントする。vRefNums のいずれかが索引を含まな いボリュームを参照していると、paramErr が返される */ OSErr SetUpVolumeSession (FBCSearchSession* session, UInt16 vCount, SInt16 *vRefNums) { OSErr err; UInt16 i; FBCSearchSession newsession; /* ローカル変数をセットアップする */ err = noErr; newsession = NULL; if (vCount == 0) return paramErr; if (session == NULL) return paramErr; if (vRefNums == NULL) return paramErr; /* 新しいセッションを作成する */ err = FBCCreateSearchSession(&newsession); if (err != noErr) goto bail; /* vRefNums で指定されているボリュームを検索する */ for (i=0; i<vCount; i++) { if (!FBCVolumeIsIndexed(vRefNums[i])) { err = paramErr; goto bail; } else { err = FBCAddVolumeToSession(newsession, vRefNums[i]); if (err != noErr) goto bail; } } /* 結果を格納して処理を終了する */ *session = newsession; return noErr; bail: if (newsession != NULL) FBCDestroySearchSession(newsession); return err; }

リスト 7 特定のボリュームのセットを検索するセッションのセットアップ

このサンプルの FBCAddVolumeToSession ルーチンは、検索セッションにボリュームを追加するために使用されています。また、検索セッションによって現在ターゲットとなっているボリュームについてクエリーを行ったり、提供されているリストからボリュームを削除するためにその他のルーチンが使用されています。 いくつかのボリュームを検索するように検索セッションを設定すると、その検索セッションは、1 度検索を行った後でも、ターゲットボリュームを再設定することなく繰り返し使用することができます。検索を実行して検索結果を検証した後、FBCReleaseSessionHits ルーチンを呼び出すことで、検索セッションは次の検索を行う準備を整えます。このルーチンは、直前に実行した検索の結果をすべて破棄しますが、ターゲットボリュームのリストはそのまま保持します。 FBCCloneSearchSession ルーチンを使って検索セッションのコピーを作成すると、ターゲットボリュームのリストが複製された検索セッションにコピーされます。

ページの先頭に戻る

検索の実行 FBC が検索を実行すると、条件に一致するファイルのリストが生成されます。このリストは「ヒット」と呼ばれ、検索セッションの内部に格納されます。FBC では、単語のリストを含むクエリー文字列を使用した内容に基づく検索、以前の検索で取得した 1 つまたは複数のヒットに基づく類似検索、またはサンプルファイルのリストに基づく類似検索の実行を要求できます。「リスト 8」は、クエリーに基づく検索を実行する方法を具体的に示しています。このサンプルのクエリーは、索引が作成されているすべてのボリュームで条件に一致するファイルを検索するために使用されています。

OSErr SimpleFindByQuery (char *query, FBCSearchSession *session) { OSErr err; FBCSearchSession newsession; /* ローカル変数をセットアップし、パラメータをチェックする */ if (query[0] == 0) return paramErr; if (session == NULL) return paramErr; newsession = NULL; /* 新しい検索セッションを割り当てる */ err = SimpleSetUpSession(&newsession); if (err != noErr) goto bail; /* これは、実際に検索して、 その結果を検索セッションに格納する呼び出し */ err = FBCDoQuerySearch(newsession, query, NULL, 0, 100, 100); if (err != noErr) goto bail; /* 結果を保存して処理を終了する */ *session = newsession; return noErr; bail: if (newsession != NULL) FBCDestroySearchSession(newsession); return err; }

リスト 8 索引が作成されているすべてのボリュームを対象とするクエリーに基づいた検索

FBCDoExampleSearch または FBCBlindExampleSearch ルーチンを使って実行される検索は、他のファイルに類似したファイルを検出するために使用できます。類似検索を実行すると、サンプルとして指定したファイルと類似した内容を持つファイルが検索されます。サンプルは、以前の検索で取得したヒットを参照する索引として指定するか、ディスク上のファイルを参照する FSSpec レコードのリストとして指定することができます。 FBCDoExampleSearch、FBCBlindExampleSearch、および FBCDoQuerySearch という 3 つの検索ルーチンでは、検索結果を 1 つまたは複数のディレクトリに格納されているファイルに限定することができます。このように限定するには、クライアントではターゲットディレクトリを参照する FSSpec レコードのリストを提供する必要があります。「リスト 9」のサンプルは、検索の結果を特定のディレクトリのセットに制限する方法について具体的に説明しています。

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; /* パラメータで指定されている FSSpec のリストから ユニークなボリューム参照番号をすべて収集 */ for (i=0; i<dirCount; i++) { Boolean found; HParamBlockRec pb; /* vRefNum がボリューム参照番号であることを確認 */ 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; /* それがすでにリスト内にないことを確認 */ for (found = false, j=0; j<vCount; j++) if (vRefNums[j] == normalVol) { found = true; break; } /* ボリュームをリストに追加 */ if (!found && vCount < kMaxVols) vRefNums[vCount++] = normalVol; } /* 検出したボリュームを使用するようにセッションを設定 */ err = SetUpVolumeSession(&newsession, vCount, vRefNums); if (err != noErr) goto bail; /* 実際の検索を行い、その結果を検索セッションに格納 */ err = FBCDoQuerySearch(newsession, (char*)queryTxt, dirList, dirCount, maxHits, maxHitTerms); if (err != noErr) goto bail; /* 結果を保存して処理を終了 */ *session = newsession; return noErr; bail: if (newsession != NULL) FBCDestroySearchSession(newsession); return err; }

リスト 9 特定のディレクトリのセットを対象とする検索

このサンプルでは、パラメータとして指定されたターゲットディレクトリを参照する FSSpec レコードの配列から抽出したボリューム参照番号は、検索セッションによって検索されるボリュームを設定するために使用されています。この後、ターゲットディレクトリのリストは FBCDoQuerySearch に渡されます。

ページの先頭に戻る

検索セッションからの情報の取得 検索セッションを使用して検索を行った後、その検索セッションには条件に一致する 1 つまたは複数のファイルに関する情報が含まれます。クライアントでは、ファイルの FSSpec レコード、ファイルに含まれる条件に一致した単語、直前の検索操作でファイルに割り当てられた「スコア」、ファイルに関するその他の情報など、個別のヒットに関する情報にアクセスすることができます。「リスト 10」は、検索によって返された各ヒットの情報を取得する方法を具体的に示しています。

typedef OSErr (*HitProc) (FSSpec theDoc, float score, UInt32 nTerms, FBCWordList hitTerms); /* SampleHandleHits は、検索結果を列挙するために検索終了後に 呼び出すことができる。それぞれの検索ヒットに対して、 hitFileProc 関数パラメータは、ターゲットを記述する情報を使っ て呼び出される */ OSErr SampleHandleHits (FBCSearchSession session, HitProc hitFileProc) { OSErr err; UInt32 hitCount, i; FSSpec targetDoc; float targetScore; FBCWordList targetTerms; UInt32 numTerms; /* ローカル変数をセットアップし、パラメータをチェック */ targetTerms = NULL; if (hitFileProc == NULL) return paramErr; if (session == NULL) return paramErr; /* このセッションに含まれるヒットの数をカウント */ err = FBCGetHitCount(session, &hitCount); if (err != noErr) goto bail; /* ヒット全体について反復処理を実行 */ for (i = 0; i < hitCount; i++) { /* ターゲットになる書類の FSSpec を取得 */ err = FBCGetHitDocument(session, i, &targetDoc); if (err != noErr) goto bail; /* この書類のスコアを取得 */ err = FBCGetHitScore(session, i, &targetScore); if (err != noErr) goto bail; /* この書類に含まれる条件に一致した単語のリストを取得 */ numTerms = maxHitTerms; err = FBCGetMatchedWords(session, i, &numTerms, &targetTerms); if (err != noErr) goto bail; /* パラメータとして指定されているコールバックルーチンを 呼び出し、情報に関する何らかの処理を実行 */ err = hitFileProc(&targetDoc, score, numTerms, targetTerms); if (err != noErr) goto bail; /* 次の反復処理に遷移する前にクリーンアップ */ FBCDestroyWordList(targetTerms, numTerms); targetTerms = NULL; } return noErr; bail: if (targetTerms != NULL) FBCDestroyWordList(targetTerms, numTerms); return err; }

リスト 10 検索セッションで検出されたすべてのファイルの列挙

ページの先頭に戻る

ページの先頭に戻る

コンテンツ検索リファレンス このセクションでは、PowerPC FBC ライブラリへの CFM ベースのインタフェースについて説明します。これらのルーチンを使用する PowerPC アプリケーションでは、「Find By Content」という名前のライブラリに対するリンクを行う必要があります。

ページの先頭に戻る

データ型 FBC には、以下のデータ型が用意されています。これらのデータ型に対する記憶領域管理は FBC ライブラリによって提供されます。クライアントでは、Memory Manager の呼び出しを使って、これらの構造体の割り当てまたは割り当て解除を行わないでください。 FBCSearchSession typedef struct OpaqueFBCSearchSession* FBCSearchSession; FBC によって作成された検索セッションは、このデータ型のポインタ変数を介して参照されます。このポインタによって参照されるデータのフォーマットは、FBC ライブラリ固有の内部的なものです。クライアントでは、このデータへの直接的なアクセスや変更をしようとしないででください。 FBCWordItem typedef char* FBCWordItem; 通常の C 文字列。このデータ型は、検索セッションからヒットに関する情報を取得するときに使用します。 FBCWordList typedef FBCWordItem* FBCWordList; WordItems の配列。このデータ型は、検索セッションからヒットに関する情報を取得するときに使用します。

ページの先頭に戻る

検索セッションの割り当てと初期化 次のルーチンは、検索セッションの割り当てと破棄を行うために使用できます。検索セッションによって占有される記憶領域は FBC によって所有されており、検索セッションの割り当て、コピー、および破棄に使用できるのは、これらのルーチンのみです。 FBCCreateSearchSession OSErr FBCCreateSearchSession( FBCSearchSession* searchSession); searchSession は FBCSearchSession 型の変数をポイントします。 FBCCreateSearchSession は新しい検索セッションを割り当て、searchSession によってポイントされる変数にその検索セッションへの参照を返します。 FBCDestroySearchSession OSErr FBCDestroySearchSession( FBCSearchSession theSession); theSession は検索セッションへのポインタです。 FBCDestroySearchSession は、検索セッションによって占有されている記憶領域を解放します。この中には、検索セッションと関連づけられているボリューム設定情報とヒットが含まれます。 FBCCloneSearchSession OSErr FBCCloneSearchSession( FBCSearchSession original, FBCSearchSession* clone); original は検索セッションへのポインタです。 clone は FBCSearchSession 型の変数をポイントします。 FBCCloneSearchSession は新しい検索セッションを作成し、clone パラメータによってポイントされる変数にその検索セッションへのポインタを格納します。新しい検索セッションにコピーされる元の検索セッションの情報の中には、検索セッションのターゲットとなるボリュームと、以前の検索で検出されたすべてのヒットが含まれます。

ページの先頭に戻る

検索セッションの設定 検索セッションを設定して、検索対象を特定のボリュームのセットに制限することができます。次のルーチンを使用すると、クライアントは、FBC によって検索されるボリュームのセットにアクセスできるようになります。 FBCAddAllVolumesToSession OSErr FBCAddAllVolumesToSession( FBCSearchSession theSession, Boolean includeRemote); theSession は検索セッションへのポインタです。 includeRemote はブール値です。 FBCAddAllVolumesToSession は、索引が作成されているマウントボリュームをすべて検索するように検索セッションを設定します。includeRemote が true の場合は、リモートボリュームが検索セッションのターゲットボリュームリストに組み込まれます。索引が作成されていないボリュームは、検索セッションのターゲットボリュームリストに追加されません。 FBCSetSessionVolumes OSErr FBCSetSessionVolumes( FBCSearchSession theSession, const SInt16 *vRefNums, UInt16 numVolumes); theSession は検索セッションへのポインタです。 vRefNums はボリューム参照番号 (16 ビット整数) の配列へのポインタです。 numVolumes は、vRefNums 配列に含まれるボリューム参照番号の数を含んだ整数値です。 FBCSetSessionVolumes により、クライアントは 1 度の呼び出しで、検索セッションのターゲットとなるボリュームのリストに複数のボリュームを追加することができます。 FBCAddVolumeToSession OSErr FBCAddVolumeToSession( FBCSearchSession theSession, SInt16 vRefNum); theSession は検索セッションへのポインタです。 vRefNum は 1 つのボリューム参照番号です。 FBCAddVolumeToSession は、検索セッションによって検索されるボリュームのリストに 1 つのボリュームを追加します。索引が作成されていないボリュームはリストに追加されません。 FBCRemoveVolumeFromSession OSErr FBCRemoveVolumeFromSession( FBCSearchSession theSession, SInt16 vRefNum); theSession は検索セッションへのポインタです。 vRefNum は 1 つのボリューム参照番号です。 FBCRemoveVolumeFromSession は、検索セッションによって検索されるボリュームのリストから指定されたボリュームを削除します。 FBCGetSessionVolumeCount OSErr FBCGetSessionVolumeCount( FBCSearchSession theSession, UInt16* count); theSession は検索セッションへのポインタです。 count は、結果が格納される 16 ビット整数へのポインタです。 FBCGetSessionVolumeCount は、検索セッションによって検索されるボリュームのリストに含まれるボリュームの数を *count に返します。 FBCGetSessionVolumes OSErr FBCGetSessionVolumes( FBCSearchSession theSession, SInt16 *vRefNums, UInt16* numVolumes); theSession は検索セッションへのポインタです。 vRefNums は、ボリューム参照番号 (16 ビット整数) の配列へのポインタです。 *numVolumes は 16 ビット整数へのポインタです。入力時、この値は vRefNums に格納できる要素の数です。また出力時には、この値には vRefNums に実際に格納されている要素の数が設定されます。 FBCGetSessionVolumes は、検索セッションによって検索されるボリュームのリストを vRefNums によってポイントされる配列に返します。*numVolumes には配列に返されたボリューム参照番号の数が設定されます。

ページの先頭に戻る

検索の実行 FBC には、このセクションに記載されている検索を実行するため、3 つの異なるルーチンが用意されています。 FBCGetSessionVolumeCount OSErr FBCDoQuerySearch( FBCSearchSession theSession, char* queryText, const FSSpec targetDirs[ ], UInt32 numTargets, UInt32 maxHits, UInt32 maxHitWords); theSession は検索セッションへのポインタです。 queryText は、検索する項目を含む C 形式の文字列を参照します。 targetDirs は、ディレクトリを参照する FSSpec レコードの配列をポイントします。numTargets がゼロの場合、このパラメータには NULL を設定できます。 numTargets には、targetDirs によってポイントされる配列内の FSSpec レコードの数が含まれます。 maxHits は返されるヒットの最大数です。 maxHitWords はレポートされるヒットした単語の最大数です。 FBCDoQuerySearch は、queryText で検出される検索項目に基づいた検索を実行します。targetDirs パラメータが存在すると (numTargets がゼロでないと)、targetDirs で指定されるディレクトリに格納されているファイルだけが、検索によって検出されるヒットの中に組み込まれます。 FBCDoExampleSearch OSErr FBCDoExampleSearch( FBCSearchSession theSession, const UInt32* exampleHitNums, UInt32 numExamples, const FSSpec targetDirs[ ], UInt32 numTargets, UInt32 maxHits, UInt32 maxHitWords); theSession には検索セッションへのポインタが含まれます。このセッションには、以前の検索で生成されたヒットリストが含まれていなければなりません。 exampleHitNums は 32 ビット整数の配列をポイントします。 numExamples には、exampleHitNums によってポイントされる配列内の整数の数が含まれます。 targetDirs は、ディレクトリを参照する FSSpec レコードの配列をポイントします。numTargets がゼロの場合、このパラメータには NULL を設定できます。 numTargets には、targetDirs によってポイントされる配列内の FSSpec レコードの数が含まれます。 maxHits は返されるヒットの最大数です。 maxHitWords はレポートされるヒットした単語の最大数です。 FBCDoExampleSearch は、前の検索で検出されたヒットをサンプルとして使用し、サンプルベースの検索または「類似」検索を実行します。exampleHitNums は、サンプルファイルとして使用されることになる 1 つまたは複数のヒットの索引を含む長整数の配列をポイントします。targetDirs パラメータが存在すると (numTargets がゼロでないと)、targetDirs で指定されるディレクトリに格納されているファイルだけが、検索によって検出されるヒットの中に組み込まれます。 FBCBlindExampleSearch OSErr FBCBlindExampleSearch( FSSpec examples[ ], UInt32 numExamples, const FSSpec targetDirs[ ], UInt32 numTargets, UInt32 maxHits, UInt32 maxHitWords, Boolean allIndexes, Boolean includeRemote, FBCSearchSession* theSession); examples は、ファイルを参照する FSSpec レコードの配列をポイントします。FBC は、これらのファイルに類似したファイルを検索することになります。 numExamples には、examples によってポイントされる配列内の FSSpec レコードの数が含まれます。 targetDirs は、ディレクトリを参照する FSSpec レコードの配列をポイントします。numTargets がゼロの場合、このパラメータには NULL を設定できます。targetDirs が NULL でなく、numTargets もゼロでない場合は、これらのディレクトリに格納されているファイルだけが検索によって返されるヒットリストの中に組み込まれます。 numTargets には、targetDirs によってポイントされる配列内の FSSpec レコードの数が含まれます。 maxHits は返されるヒットの最大数です。 maxHitWords はレポートされるヒットした単語の最大数です。 includeRemote はブール値です。 theSession は、このルーチンによって作成される FBCSearchSession 型の変数をポイントします。 FBCBlindExampleSearch は新しい検索セッションを作成し、examples パラメータで指定された FSSpec レコードの配列で参照されているファイルを使って検索を実行します。targetDirs パラメータが存在すると (numTargets がゼロでないと)、targetDirs で指定されるディレクトリに格納されているファイルだけが、検索によって検出されるヒットの中に組み込まれます。includeRemote が true の場合は、リモートボリュームが検索セッションのターゲットボリュームリストに組み込まれます。 サンプルファイルの一部に索引が作成されていない場合は、索引が作成されているファイルを使って検索が実行され、検索終了後、エラーコード kFBCsomeFilesNotIndexed が返されます。この場合、検索セッションが作成され、その検索セッションへの参照が *theSession に返されます。

ページの先頭に戻る

ヒットに関する情報の取得 検索終了後の検索セッションには、検索時に検出されたヒットのリストが含まれます。このセクションに記載されているるルーチンを使って、クライアントは検索セッション内に格納されているヒットに関する情報にアクセスできるようになります。ヒットレコードには 0 から count-1 までのインデックスが付けられます。 FBCGetHitCount OSErr FBCGetHitCount( FBCSearchSession theSession, UInt32* count); theSession は検索セッションへのポインタです。 count は 32 ビット整数へのポインタです。 FBCGetHitCount は、count によってポイントされる変数に検索セッションに含まれるヒットの数を設定します。ヒットレコードには 0 から count-1 までのインデックスが付けられます。 　 FBCGetHitDocument OSErr FBCGetHitDocument( FBCSearchSession theSession, UInt32 hitNumber, FSSpec* theDocument); theSession は検索セッションへのポインタです。 hitNumber は、検索セッションに含まれるヒットレコードを参照するインデックス値です。 theDocument は FSSpec レコードへのポインタです。 FBCGetHitDocument は、検索セッションに含まれるヒットのうち、インデックスが hitNumber であるヒットに対応する FSSpec レコードを返します。 FBCGetHitScore OSErr FBCGetHitScore( FBCSearchSession theSession, UInt32 hitNumber, float* score); theSession は検索セッションへのポインタです。 hitNumber は、検索セッションに含まれるヒットレコードを参照するインデックス値です。 score は浮動小数点型の変数へのポインタです。 FBCGetHitScore は、検索セッションに含まれるヒットのうち、インデックスが hitNumber であるヒットに割り当てられている妥当性スコアを返します。このスコアは、直前に実行した特定の検索コンテキストでの検索条件に対する書類の妥当性を表す尺度です。スコアは 0.0 - 1.0 の範囲に標準化され、対象となる検索の中で最も妥当性の高いヒットは常に 1.0 というスコアを持ちます。 FBCGetMatchedWords OSErr FBCGetMatchedWords( FBCSearchSession theSession, UInt32 hitNumber, UInt32* wordCount, FBCWordList* list); theSession は検索セッションへのポインタです。 hitNumber は、検索セッションに含まれるヒットレコードを参照するインデックス値です。 wordCount は 32 ビット整数へのポインタです。 list は FBCWordList 型の変数へのポインタです。 FBCGetMatchedWords は、検索セッションに含まれるヒットのうち、インデックスが hitNumber であるヒットに対応する条件に一致した単語のリストを返します。この単語のリストは、そのヒットが返された理由を具体的に示します。値が返されるとき、*list には単語リスト構造体へのポインタが含まれ、*wordCount にはその構造体に含まれるエントリの数が設定されます。なお、処理が終了したときには、FBCDestroyWordList を呼び出して、この構造体を確実に破棄してください。 ヒットに対応する条件に一致した単語はヒットそのものの中に格納されるため、それらの検索は高速に実行されます。 FBCGetTopicWords OSErr FBCGetTopicWords( FBCSearchSession theSession, UInt32 hitNumber, UInt32* wordCount, FBCWordList* list); theSession は検索セッションへのポインタです。 hitNumber は、検索セッションに含まれるヒットレコードを参照するインデックス値です。 wordCount は 32 ビット整数へのポインタです。 list は FBCWordList 型の変数へのポインタです。 FBCGetTopicWords は、検索セッションに含まれるヒットのうち、インデックスが hitNumber であるヒットに対応するトピックを表す単語のリストを返します。この単語のリストは、「何に関する書類なのか」という問いに対する手がかりを与えます。値が返されるとき、*list には単語リスト構造体へのポインタが含まれ、*wordCount にはその構造体に含まれるエントリの数が設定されます。なお、処理が終了したときには、FBCDestroyWordList を呼び出して、この構造体を確実に破棄してください。 特定のヒットに対応するトピックを表す単語のリストは索引ファイルを介して生成される必要があるため、この呼び出しの実行は FBCGetMatchedWords の実行よりもかなり遅くなります。 FBCDestroyWordList OSErr FBCDestroyWordList( FBCWordList theList, UInt32 wordCount); theList は単語リストへのポインタです。 wordCount はリストに含まれる単語の数です。 FBCDestroyWordList は、FBCGetMatchedWords または FBCGetTopicWords によって割り当てられた単語リストを破棄します。 FBCReleaseSessionHits OSErr FBCReleaseSessionHits( FBCSearchSession theSession); theSession は検索セッションへのポインタです。このセッションには検索によって生成されたヒットが含まれることがあります。 FBCReleaseSessionHits は、直前の検索で取得したヒットに関連する格納情報を検索セッションから削除します。ただし、ボリューム設定情報はそのまま保持されるため、この呼び出しの実行後、検索セッションは次の検索を実行する準備を整えます。

ページの先頭に戻る

テキストの要約 この呼び出しは、入力テキストの中で検出された「最も妥当性の高い」センテンスを含む要約を生成します。 FBCSummarize OSErr FBCSummarize( void* inBuf, UInt32 inLength, void* outBuf, UInt32* outLength, UInt32* numSentences); inBuf は要約されるテキストへのポインタです。 inLength は inBuf によってポイントされるテキストの長さです。 outBuf は要約が格納されるバッファをポイントします。 outLength は 32 ビット整数へのポインタです。入力時、この値には outBuf によってポイントされるバッファのサイズが設定されます。また出力時には、outBuf によってポイントされるバッファに格納されているデータの実際の長さが設定されます。 numSentences は 32 ビット整数へのポインタです。入力時、この値は要約として望ましいセンテンスの最大数です。また出力時には、この値には生成されたセンテンスの実際の数が設定されます。入力時に numSentences が 0 であると、FBC は入力バッファに含まれているセンテンスの数を取り出し、それを 10 で除算します。その計算結果が 0 の場合は、最大数の値として 1 が使用されます。また、その計算結果が 10 を超える場合は、最大数の値として 10 が使用されます。

ページの先頭に戻る

ボリュームに関する情報の取得 FBC には、ボリュームに関する情報にアクセスする以下のようなユーティリティルーチンが用意されています。 FBCVolumeIsIndexed Boolean FBCVolumeIsIndexed (SInt16 theVRefNum); theVRefNum はボリューム参照番号です。 FBCVolumeIsIndexed は、指定されたボリュームに索引が作成されている場合に true を返します。 FBCVolumeIsRemote Boolean FBCVolumeIsRemote(SInt16 theVRefNum); theVRefNum はボリューム参照番号です。 FBCVolumeIsRemote は、指定されたボリュームがリモートサーバ上にある場合に true を返します。クライアントでは、ネットワークボリュームを検索対象から除外して、ネットワークの遅延を回避できます。 FBCVolumeIndexTimeStamp OSErr FBCVolumeIndexTimeStamp(SInt16 theVRefNum, UInt32* timeStamp); theVRefNum はボリューム参照番号です。 timeStamp は符号なし 32 ビット整数へのポインタです。 FBCVolumeIndexTimeStamp は、ボリュームの索引が最後に更新された日時を返します。timeStamp に返される値は、GetDateTime によって返される値と同じフォーマットです。 FBCVolumeIndexPhysicalSize OSErr FBCVolumeIndexPhysicalSize(SInt16 theVRefNum, UInt32* size); theVRefNum はボリューム参照番号です。 size は符号なし 32 ビット整数へのポインタです。

FBCVolumeIndexPhysicalSize はボリュームの索引ファイルのサイズをバイト単位で返します。

ページの先頭に戻る

ボリューム、フォルダ、およびファイルの索引作成 コンテンツ検索には新しい API が追加され、新規ファイルまたは変更されたファイルの索引を即座に作成できるようになりました。新しいルーチンは次のように宣言されます。 FBCIndexItems OSErr FBCIndexItems( FSSpecArrayPtr theItems, UInt32 itemCount); theItems は、索引を作成するファイルを参照する FSSpec レコードの配列へのポインタです。 itemCount は FSSpec レコードの配列に含まれる項目の数です。 FBCIndexItems は、先頭のパラメータにポインタとして渡された FSSpec レコードの配列の中で参照されているファイルの索引を作成します (または索引を作成し直します)。ファイルを含むボリュームがすでに索引を持っている場合、その書類は既存の索引に追加され、索引が再度作成されます。また、ボリュームに索引が含まれていない場合は、新しい索引が作成されます。 通常、FBCIndexItems は、索引を含むボリュームでファイルを保存 (またはファイルを更新) した後に呼び出します。これにより、ユーザは特に何らかの操作を行うことなく、索引を常に最新の状態に保つことができます。ボリュームに索引が含まれているかどうかを判断する方法については、Sherlock のテクニカルノートを参照してください。 互換性に関する注意 FBCIndexItems というシンボルは、「コンテンツ検索」共有ライブラリのオリジナルバージョンからエクスポートされていません。このルーチンを使用する必要のあるアプリケーションでは、このシンボルへの弱いリンクを行い、さらに実際に呼び出してみる前に、このルーチンが存在するかどうかをテストしてください。これを行うためのテクニックについては、テクニカルノート「TN1083 Code Fragment Manager ベースの共有ライブラリへの弱いリンク」を参照してください。

ページの先頭に戻る

ヒープスペースの予約 FBC のクライアントは、検索を実行する前に、ヒープゾーンの中にコールバックルーチンで使用するスペースを予約することができます。 FBCSetHeapReservation void FBCSetHeapReservation(UInt32 bytes); bytes は予約するバイト数を含む整数値です。 FBCSetHeapReservation は、検索中にクライアントのコールバックルーチンが呼び出されるたびに、FBC が保証するクライアントアプリケーションのヒープで使用可能なバイト数を設定します。このルーチンを呼び出してヒープスペースを明示的に予約しないと、200K のスペースが自動的に予約されます。

ページの先頭に戻る

アプリケーション定義のルーチン クライアントは検索中に定期的に呼び出されるルーチンを指定することができます。このルーチンは、検索のステータスに関する情報と、検索が完了する前に検索をキャンセルするオプションの両方をクライアントに提供します。 コールバックルーチンは次のように定義されます。 FBCCallbackProcPtr typedef Boolean (*FBCCallbackProcPtr)( UInt16 phase, float percentDone, void *data); phase は、検索の現在のステータスを示す、以下の定数のいずれかを含んだ 16 ビット整数です enum { kFBCphSearching = 6, kFBCphMakingAccessAccessor = 7, kFBCphAccessWaiting = 8, kFBCphSummarizing = 9, kFBCphIdle = 10, kFBCphCanceling = 11 }; percentDone は 0.0 - 1.0 の範囲の進捗状況を示す値です。 data には、FBCSetCallback の data パラメータに指定した値と同じ値が含まれます 検索が進行している間にシステムのロックアップが発生するのを防ぐため、コールバックが直接的または間接的に WaitNextEvent を呼び出すようにしてください。 コールバック関数が true を返すと、進行中の検索はキャンセルされます。 FBCSetCallback void FBCSetCallback(FBCCallbackProcPtr fn, void* data); fn は使用するコールバック関数へのポインタです。 data は使用するコールバック関数に渡される値です。 FBCSetCallback は、検索中に呼び出されるコールバック関数を設定します。クライアントがコールバック関数を定義していない場合は、デフォルトのコールバック関数が使用されます。デフォルトのコールバック関数は WaitNextEvent を呼び出して、false を返します。

ページの先頭に戻る

ページの先頭に戻る

参考文献

Technote TN1141 Sherlock - 拡張と制御 そして Find by Content Library Technote TN1181 Sherlock のコンテンツ検索 Text Extractor プラグイン

ページの先頭に戻る

更新日: 1999 年 10 月 5 日