EB ライブラリ

[前へ] [次へ] [目次]

## テキストデータ

テキストデータの取得は、検索と並ぶ重要な機能です。

ここで言う テキストデータ (text data) は、 本文 (text body) という意味ではありません。 CD-ROM 書籍には確かに本文も存在しますが、本文と同じデータ形式を用いて 書かれたデータが数種類あります。 本書では、これらのデータをまとめてテキストデータと呼んでいます。 EB ライブラリが扱えるテキストデータの種類には、次のものがあります。

- 見出し
- 本文
- メニュー
- 著作権表示
- 複合検索の入力語の候補一覧

本章では、これらのテキストデータの取得と加工方法について説明します。

### テキストデータのシークと読み込み

UNIX でプログラムを組んだ経験のある方には、ファイルからデータを読み込む 際に用いる `lseek()`, `read()` というシステムコール をご存じの方も多いでしょう。

EB ライブラリでも、テキストデータの取得には、シーク (seek) と 読み込み (read) という 2 つの操作で行います。 ただし、EB ライブラリではファイルポインタやディスクリプタはなく、 `EB_Book` オブジェクトを通じてシークや読み込みの操作を行います。

また、シーク時に指定する位置も `off_t` 型ではなく、 `EB_Position` 型 (「[検索] データ型の詳細」 を参照のこと) のオブジェクトを用います。 たとえば、本文の先頭位置は、`eb_text()` という関数を使って 次のように取得できますが、このときも位置データは `EB_Position` 型オブジェクトに書き込まれます。

>     EB_Position position;

>     /* 関数の処理が成功すると、position に本文の開始位置が
>      * 書き込まれます。 */
>     if (eb_text(&book, &position) != EB_SUCCESS) {
>         fprintf(stderr, "an error occurs.\n");
>         return;
>     }

参考までに、`EB_Position` 型の内部構造は、次のようになっています。

>     typedef struct EB_Position_Struct EB_Position;

>     struct EB_Position_Struct {
>         int page;     /* ページ番号 */
>         int offset;   /* ページ内のオフセット */
>     };

検索して見つかった一致エントリの見出しや本文を読み込む際にも、位置情報 の指定には `EB_Position` 型が使われます。 一致したエントリの情報は、関数 `eb_hit_list()` によって `EB_Hit` という型のオブジェクトに書き込まれますが、 `EB_Hit` 型は次のように定義されています。 (詳しくは 「[検索] データ型の詳細」 を参照のこと。)

>     typedef struct {
>         EB_Position heading;   /* 見出しの位置 */
>         EB_Position text;      /* 本文の位置   */
>     } EB_Hit;

つまり、このときの見出しと本文の位置も、`EB_Position` 型で 表現されているのです。

では、実際のプログラムを例にして、シークと読み込みを行ってみます。 まずは、シークからです。 これには関数 `eb_seek_text()` を用います。 ここでもやはり、位置は `EB_Position` 型で渡します。

>     if (eb_seek_text(&book, &position) != EB_SUCCESS) {
>         fprintf(stderr, "an error occurs.\n");
>         return;
>     }

データの種類 (見出し、本文 ...) によらず、テキストデータのシークは すべて `eb_seek_text()` で行います。

ただし、`EB_Book` オブジェクトは、テキストデータの種類別に 読み込み位置を覚えているわけではなく、全種類のテキストデータで共有する 位置情報を一つ覚えているだけです。 たとえば、本文を読み込んだ後で、別の位置にシークして見出しを読み込むと、 `EB_Book` は本文の読み込み位置のことは忘れてしまいます。

さて、シークが終わったら、データを読み込みます。 読み込もうとするテキストデータの種類によって、使用する関数が異なります。 見出しだけは `eb_read_heading()` を使いますが、それ以外では `eb_read_text()` を使います。

以下は、`eb_read_text()` の使用例です。

>     #define MAX_LENGTH 1000
>     char buffer[MAX_LENGTH + 1];
>     ssize_t text_length;

>     if (eb_read_text(&book, NULL, NULL, NULL, MAX_LENGTH,
>         text, &text_length) != EB_SUCCESS) {
>         fprintf(stderr, "an error occurs.\n");
>         return;
>     }

成功すると、`text` にはテキストデータが、 `text_length` には実際に読み込んだバイト数が書き込まれます。 テキストは最大で `MAX_LENGTH` バイト書き込まれます。 テキストデータはさらにナル文字で終端されますので、`buffer` には もう 1 バイト分の領域が必要になります。

`eb_read_heading()` の呼び出し方も、`eb_read_text()` とまったく変わりません。

>     if (eb_read_heading(&book, NULL, NULL, NULL, MAX_LENGTH,
>         text, &text_length) != EB_SUCCESS) {
>         fprintf(stderr, "an error occurs.\n");
>         return;
>     }

`eb_read_text()` や `eb_read_heading()` で読み込んだ テキストデータは平文のテキストになっていて、ナル文字で終端されています。

>     printf("%s\n", text);   /* 出力してみる */

読み込みたいテキストデータが長すぎて、`eb_read_text()` あるいは `eb_read_heading()` を一回呼び出しただけでは全部 読み込めなかった場合は、再度呼び出すことで続きのデータを読み込むことが できます。

### テキストデータの内部形式

前節の例では、読み込んだテキストデータは、平文テキストになっていました。 けれども、CD-ROM 書籍内に平文テキストのデータが、そのまま収録されている わけではありません。

実際のテキストデータの例を、以下に示します。 左側のブロックは 16 進数でダンプした様子で、右側はそれを基に JIS X 0208 (日本語のかな漢字) の文字を表している部分を `[　]` という形に 直したものです。

>          (16進数によるダンプ)            (可能な部分をかな漢字に変換)
>     1f0900011f41010026321f611f042121   1f0900011f410100[Σ]1f611f04[　]
>     212721211f053e704a734a541f0a1f04   [：][　]1f05[情][報][編]1f0a1f04
>     214e1f0525372530255e1f04214f2121   [［]1f05[シ][グ][マ]1f04[］][　]
>     214a237323692367236d236121212370   [（][ｓ][ｉ][ｇ][ｍ][ａ][　][ｐ]
>     2372236f236a236523632374214b1f05   [ｒ][ｏ][ｊ][ｅ][ｃ][ｔ][）]1f05

右側のブロックを見ると、おおよそ平文に近い形でテキストデータが収められて いることが分かりますが、ところどころに「文字」ではないデータも含まれて います。

文字ではない部分は、すべて「エスケープシーケンス」と呼ばれるものです。 エスケープシーケンスとは、テキストデータを出力する際に、改行の禁止や 強調修飾といった制御情報を伝えるための仕組みです。 16 進数の `1f` が、エスケープシーケンスの開始を意味します。

参考までに、上のテキストデータで使われているエスケープシーケンスを すべて列挙すると、次のようになります。

`1f09 0001`
  字下げ (インデント) の量を指定。 (引数が 0001 なので、字下げ量は 1。)
`1f41 0100`
  検索キーの開始。 (引数 0100 の意味については、JIS X 4081 に記述がないため不明。)
`1f61`
  検索キーの終了。
`1f04`
  半角表示の開始。
`1f05`
  半角表示の終了。
`1f0a`
  改行

前節のプログラムで、読み込んだデータが平文テキストになっていたのは、 実は EB ライブラリが加工処理をしたからです。 つまり、「改行」のように平文テキストでも表現可能なエスケープシーケンス については処理し、「検索キーの開始」のように表現できないものについては 無視するようにして、平文テキストになるように加工していたのです。

しかし、平文テキストは表現力が乏しいので、元のデータには含まれている エスケープシーケンスの多くを無視することになってしまいます。 HTML のように、もっと表現力のある形式で出力するなら、無視せずに済む シーケンスを増やせそうです。 では、HTML 形式でテキストデータを取得する関数が EB ライブラリに用意されて いるかというと、残念ながらありません。

その代わりに、かなり手間はかかりますが、自由にテキストデータを加工できる ための仕組みが用意されています。 それが、次の節で説明する フック (hook) です。 フックを使うことで、テキストデータを柔軟に加工することができます。

### フック

特に何も指定しなければ、`eb_read_text()`, `eb_read_heading()` が返すテキストデータの加工は、あらかじめ 決められた通りの方法で行われます。 たとえば、「改行」のエスケープシーケンスに対しては、`\n` を 書き込むようになっています。

フック (hook) を使うと、こうした加工方法を変えることができます。 フックは、あらかじめ決められたフック設定位置に対して、フック関数を登録 することで有効になります。 フック関数が登録されていると、`eb_read_text()` や `eb_read_heading()` は、あらかじめ決まったやり方でデータを 書き込む代わりに、フック関数を呼び出します。 呼び出されたフック関数がデータの書き込み処理を行うことで、 `eb_read_text()` や `eb_read_heading()` から返る テキストデータが変化するというわけです。

EB ライブラリには、多数のフック設定位置が用意されています。 各エスケープシーケンスには、それぞれ専用にフックが用意されており、 それ以外にも文字のためのフックが存在します。 (どのようなフック設定位置があるか、詳しくは 「フックコードの一覧」 を参照のこと。)

それぞれのフック設定位置は、フックコード (hook code) と 呼ばれるコード値で識別されます。 たとえば、前述の「改行」のエスケープシーケンスに対応するフックコード は `EB_HOOK_NEWLINE` になります。

アプリケーションプログラムがフックを扱うには、フックの集合である フックセット (hook set) を用意します。 これは、EB ライブラリで利用可能なすべてのフック設定位置に対して、どの フック関数を使うのかを記録するためのオブジェクトです。

では、実際にどうやってフックセットを扱うのか、説明していきましょう。 フックセットは `EB_Hookset` 型のオブジェクトで表しますので、 まず `EB_Hookset` オブジェクトを用意します。

>     EB_Hookset hookset;

`EB_Hookset` オブジェクトは、`EB_Book` オブジェクト と同様に、使用前に必ず初期化する必要があります。

>     eb_initialize_hookset(&hookset);

実際のフック関数は、次のようなものになります。 この例では、フック関数の中で `eb_write_text_string()` という 関数を呼び出して、`<br>` という文字列をテキストデータ として書き込んでいます。

>     EB_Error_Code
>     hook_newline(EB_Book *book, EB_Appendix *appendix, void *container,
>         EB_Hook_Code code, int argc, const unsigned int *argv) {
>         eb_write_text_string(book, "<br>");
>         return 0;
>     }

関数 `eb_set_hook()` を用いることで、このフック関数を フックセットに登録することができます。 ただし、まず `EB_Hook` という型のオブジェクトにいったん フックコードとフック関数を設定し、それを `eb_set_hook()` を 渡してやる必要があります。 ここでは、「改行」を表すエスケープシーケンスに対して、上記のフック関数 を登録してみます。

>     EB_Hook hook;

>     hook.code = EB_HOOK_NEWLINE;   # フックコードをセット
>     hook.function = hook_newline;  # フック関数をセット
>     eb_set_hook(&hookset, &hook);

なお、同じフック設定位置 (フックコード) に複数回フック関数を登録しても、 有効になるのは最後に登録したものだけですので、注意して下さい。 フック関数として `NULL` を指定すると、登録されているフックが 解除されます。

関数 `eb_set_hooks()` (最後に `s` が付く) を使えば、 複数のフック関数を一度に登録できます。

>     static const EB_Hook hooks[] = {
>         {EB_HOOK_NEWLINE,        hook_newline},
>         {EB_HOOK_SET_INDENT,     hook_set_indent},
>         {EB_HOOK_WIDE_JISX0208,  hook_set_jisx0208},
>         {EB_HOOK_NULL,           NULL}
>     };

>     eb_set_hooks(&hookset, &hooks);

配列の末尾を明示するために、`EB_HOOK_NULL` という特殊な フックコードを置きます。 この点も注意して下さい。

こうしてフック関数を登録したフックセットを、`eb_raed_text()`, `eb_raed_heading()` への引数として渡します。 前節までの例では、`NULL` を渡していましたが、代わりに `&hookset` を渡してみます。

>     if (eb_read_text(&book, NULL, &hookset, NULL, MAX_LENGTH,
>         text, &text_length) != EB_SUCCESS) {
>         fprintf(stderr, "an error occurs.\n");
>         return;
>     }

これによって、テキストデータ中に改行を表すエスケープシーケンスがあると、 `\n` の代わりに `<br>` という文字列が 書き込まれるようになります。

`EB_Hookset` オブジェクトを使い終わったら、 `eb_finalize_hookset()` を呼んで後始末をします。

>     eb_finalize_hookset(&hookset);

### フックと文字コードの関係

前節では、エスケープシーケンスに対するフックを例にとりましたが、この他 にも、EB ライブラリには文字に対するフックが用意されています。

`EB_HOOK_ISO8859_1`
  ISO 8859-1 (ラテン文字 1) 文字へのフック。ただし制御文字を除きます。 引数として、ISO 8859-1 の文字番号がフック関数に渡されます。
`EB_HOOK_NARROW_JISX0208`
  半角の JIS X 0208 (日本語のかな漢字) 文字へのフック。 引数として、日本語 EUC で表現した場合の文字番号が、フック関数に渡されます。
`EB_HOOK_WIDE_JISX0208`
  全角の JIS X 0208 (日本語のかな漢字) 文字へのフック。 引数として、日本語 EUC で表現した場合の文字番号が、フック関数に渡されます。
`EB_HOOK_GB2312`
  GB 2312 (中国語の簡体字) 文字へのフック。 引数として、中国語 EUC で表現した場合の文字番号が、フック関数に渡されます。
`EB_HOOK_NARROW_FONT`
  半角の外字へのフック。 引数として、外字の文字番号が、フック関数に渡されます。
`EB_HOOK_WIDE_FONT`
  半角の外字へのフック。 引数として、外字の文字番号が、フック関数に渡されます。

いずれも、その文字がテキストデータ中に現れる度に、フック関数が呼び出され ます。

上の記述を見ても分かるように、フック関数に渡される文字番号は、書籍の文字 コードに応じて、ISO 8859-1, 日本語 EUC、中国語 EUC のいずれかの文字コード で表現されたものになります。

フック関数を登録しなければ、その文字番号がテキストデータとしてそのまま 書き込まれます。

もし、アプリケーションプログラムが、EB ライブラリの内部コードとは異なる 文字コードを使用したい場合は、これらのフックのフック関数を登録して、 コード変換処理をするのも手です。 ただし、一文字毎にフック関数が呼び出されるので、相応の負荷がかかります。

また、EBXA-C を扱うには、特別な処理が必要です。 EBXA-C では、文字コードとして GB 2312 と JIS X 0208 が使われますが (「文字コード」 を参照のこと)、EB ライブラリによる標準の処理 では、どちらも 0xa1a1 〜 0xfefe にマッピングされて衝突するため、最低 でもどちらか一方をフックして文字の表現方法を変えないと、正しく出力 できません。

### クロス検索の検索結果

すでに 「検索」 の章で述べたように、CD-ROM 書籍 には前方一致検索、後方一致検索といった複数の検索メソッドがあります。 EB ライブラリで検索を行うと、どの検索メソッドでも、一致したエントリの 情報は、以下のような `EB_Hit` 型のオブジェクトとして 受け取ります。

>     typedef struct {
>         EB_Position heading;   /* 見出しの位置 */
>         EB_Position text;      /* 本文の位置   */
>     } EB_Hit;

しかしクロス検索では、`EB_Hit` の見出しと本文の位置は まったく同じになります。 したがって、見出しと本文のテキストデータを読み込むには、他の検索メソッド のようにそれぞれの位置にシークして読み込むというやり方ではうまく いきません。

以下に、クロス検索の見出しと本文を読み込むプログラム例を示します。

>     /* 見出し位置へのシークを行う */
>     if (eb_seek_text(&book, &hits[0].heading) != EB_SUCCESS) {
>         fprintf(stderr, "an error occurs.\n");
>         return;
>     }
>     /* 見出しの読み込みを行う */
>     if (eb_read_heading(&book, NULL, NULL, NULL, MAX_LENGTH,
>         heading, &heading_length) != EB_SUCCESS) {
>         fprintf(stderr, "an error occurs.\n");
>         return;
>     }
>     /* 先ほど読み込んだ見出しの、次の部分へ飛ぶ */
>     if (eb_forward_heading(&book) != EB_SUCCESS) {
>         fprintf(stderr, "an error occurs.\n");
>         return;
>     }
>     /* 本文の読み込みを行う */
>     if (eb_read_heading(&book, NULL, NULL, NULL, MAX_LENGTH,
>         text, &text_length) != EB_SUCCESS) {
>         fprintf(stderr, "an error occurs.\n");
>         return;
>     }

クロス検索でも、見出しの内容を読み込む方法は他の検索メソッドと変わり はなく、`eb_read_heading()` を使います。 変わっているのは、本文の読み込みです。 `eb_read_text()` ではなく、`eb_read_heading()` を使います。 見出しを読み込むための関数 `eb_read_heading()` を、本文を 読み込むために呼ぶというのは奇妙な話ですが、これはクロス検索の本文が 見出しと同じ形式になっているためです。 通常、見出しは一行程度しか書かれていませんが、実際のところクロス検索 の本文も一行程度しかありません。

また、本文は見出しのすぐ後に書かれているため、上記のように見出しを 読み込んだ後で `eb_forward_heading()` という関数を呼び、 その後で本文を読み込むためにもう一度 `eb_read_heading()` を 呼ぶという変わった手順を踏みます。

本文だけが必要で見出しが要らなければ、シーク直後に `eb_forward_heading()` を呼ぶようにします。 その後で `eb_read_heading()` を呼ぶと、本文を読み込みます。

### 著作権表示

先に記したように、テキストデータには何種類かあり、その中に 著作権表示 (copyright notice) というものがあります。 名前の通り、著作権表示に関するテキストデータを収めたものです。

一般に、著作権表示は本文とはまったく独立したデータとして用意されます。 したがって、本文を先頭から末尾まで読んでみても、著作権表示はどこにも 見つかりません。

選択中の副本について、著作権表示の開始位置を知るには `eb_copyright()` を使います。 この関数は、副本が著作権表示を持っていなければ `EB_ERR_NO_SUCH_SEARCH` を返しますので、著作権表示の有無も 同時に分かります。 (開始位置は取得せずに、有無だけを調べたいときは、 `eb_have_copyright()` という関数が使えます。)

>     EB_Position position;
>     EB_Error_Code err;

>     err = eb_copyright(&book, &position);
>     if (err == EB_ERR_NO_SUCH_SEARCH) {
>         /* 著作権表示はない */
>     } else if (err != EB_SUCCESS) {
>         /* それ以外のエラー */
>        return;
>     }

後は、得られた位置 (`position`) にシークして、 `eb_read_text()` でテキストデータを読み込みます。

### メニュー

本文とは独立したテキストデータとしては、著作権表示の他に メニュー (menu) というものがあります。 メニューは、主に本文の補助となるデータを収録しています。 代表的なものでは、「前書き (序)」「凡例」といったものが挙げられます。

メニューでは「別項目参照」というエスケープシーケンスを多用して、階層的 な構造になっているのが一般的です。 このエスケープシーケンスには、参照先のテキストの位置が記録されています。

たとえば、ある CD-ROM 書籍のメニューが次のようになっていたとします。 この例では、メニューには 3 つの項目があります。

>      * 序文
>      * 表記について
>      * 奥付

メニューのそれぞれの項目には、参照先があります。 テキストデータの内部表現では、「序文」「表記について」「奥付」の それぞれの文字列の前後に別項目参照開始および終了エスケープシーケンスが 付いた形になっています。 視覚的に分かるように記すと、次のような形になっています。

>      * <別項目参照開始シーケンス> "序文" <別項目参照終了シーケンス>
>      * <別項目参照開始シーケンス> "表記" <別項目参照終了シーケンス>
>      * <別項目参照開始シーケンス> "奥付" <別項目参照終了シーケンス>

HTML の書き方を知っているなら、`a` タグと言えば分かるのでは ないかと思います。

>     <a href="./index.html">EB ライブラリのホームページ</a>

ただし、参照先の位置情報は終了シーケンス側に記載されますので、この点は HTML とは逆になります。 蛇足ですが、別位置参照はメニューだけでなく、本文でも一般的に使用されます。

別項目参照開始および終了シーケンスに対して、それぞれフック `EB_HOOK_BEGIN_REFERENCE` と `EB_HOOK_END_REFERENCE` が用意されています。 参照先の位置情報は、終了シーケンスへのフック関数に対して、引数として 渡されます。 たとえば、`EB_HOOK_END_REFERENCE` へのフック関数の冒頭では、 次のようにすると良いかも知れません。

>     EB_Error_Code
>     hook_end_ref(EB_Book *book, EB_Appendix *appendix, void *container,
>         EB_Hook_Code code, int argc, const unsigned int *argv)
>     {
>         EB_Position position;

>         position.page = argv[1];    # 参照先のページ番号
>         position.offset = argv[2];  # 参照先のオフセット

参照先は、メニューの第 2 層となります。 この書籍の「奥付」の参照先を辿ったら、次のような表記になっていました。

>     ○○堂出版社 新国語辞典 第 2 版 (EPWING 版)
>     第 1 版 発行 1988年 2月
>     第 2 版 発行 1999年 11月
>     第 2 版 (EPWING 版) 発行 2000年 2月

同様に「序文」「表記に付いて」の参照先についても、こうした文章データ が用意されていました。 図示すると、メニューの階層は次のようになります。

>     　　　　　　　　　　　　┌─────┐
>     第１層　　　　　　　　　│メニュー　│
>     　　　　　　　　　　　　└──┰──┘
>     　　　　　　　　　　　　　　　┃
>     　　　　　　　┏━━━━━━━╋━━━━━━━┓
>     　　　　　　　┃　　　　　　　┃　　　　　　　┃
>     　　　　┌──┸──┐　┌──┸──┐　┌──┸──┐
>     第２層　│メニュー　│　│メニュー　│　│メニュー　│
>     　　　　└─────┘　└─────┘　└─────┘

この辞書の例では、メニューはここで終わりになっていますが、書籍によっては さらに第 3 層、第 4 層と続く場合もあります。 また、メニュー全体が均一の階層数になっているとは限りません。 メニューの参照先が本文や著作権表示になっていることもあります。

選択中の副本について、(第 1 層の) メニューの開始位置 を知るには `eb_menu()` を使います。 この関数は、副本がメニューを持っていなければ `EB_ERR_NO_SUCH_SEARCH` を返しますので、メニューの有無も同時に 分かります。 (開始位置は取得せずに、有無だけを調べたいときは、 `eb_have_menu()` という関数が使えます。)

>     EB_Position position;
>     EB_Error_Code err;

>     err = eb_menu(&book, &position);
>     if (err == EB_ERR_NO_SUCH_SEARCH) {
>         /* メニューはない */
>     } else if (err != EB_SUCCESS) {
>         /* それ以外のエラー */
>        return;
>     }

後は、得られた位置 (`position`) にシークして、 `eb_read_text()` でテキストデータを読み込みます。

### 複合検索の候補一覧

「複合検索」(「複合検索」 を参照のこと) のところで述べたように、 複合検索では、入力語に 候補一覧 (candidates) が用意されている ことがあります。 これは、入力語として有効な語をあらかじめ列挙しておき、 アプリケーションプログラムのユーザに選択させる仕組みです。

たとえば、人名を検索するのために、次のような複合検索があったとします。

>     入力語 0: 国・地域
>     入力語 1: 時代
>     入力語 2: 性別
>     入力語 3: キーワード
>     入力語 4: キーワード

このうち、入力語 3 の「性別」には、入力語として有効な語は「男」と「女」 の 2 つしかないでしょう。 このように、入力語として有効な語が限られている場合に、候補一覧が用意 されていることがあります。

候補一覧は検索のためのデータではありますが、内部構造はテキストデータ そのものです。 ユーザに対して候補を列記した示したテキストを示し、その中の一つを選択 してもらうようになっています。

しかも、候補一覧のデータ構造はメニューと非常に似ており、メニューの ような階層構造を持っています (「メニュー」 を参照のこと)。 たとえば、上の複合検索の入力語 2 「国・地域」にも候補の一覧を設けると したら、最初の階層は次のようになるかも知れません。

>     * 日本 (→選択)
>     * 日本以外のアジア (→詳細)
>     * ヨーロッパ (→詳細)
>     * 北アメリカ (→詳細)
>     * その他 (→詳細)

「日本」を選ぶと、そこで入力語が決定されたことになります。しかし、 それ以外の項目についてはさらに細かく分類された選択肢が用意されて います。 ここでは、「北アメリカ」を選んでみましょう。 すると、さらに次のような候補一覧のデータが提示されます。

>     * アメリカ (→選択)
>     * カナダ (→選択)

ここで、「アメリカ」「カナダ」を選ぶと、入力語が決定されます。

次に実際に、EB ライブラリを使ってこうした候補一覧を扱う方法について 説明します。 まず、アプリケーションプログラムは、複合検索の入力語が候補一覧を持って いるかどうかを、確認する必要があるでしょう。 `eb_multi_entry_candidates()` を使うと、候補一覧データの開始位置 を取得することができます。 この関数は、候補一覧を持っていなければ `EB_ERR_NO_CANDIDATES` を 返しますので、候補一覧の有無も分かります。 (開始位置は取得せずに、有無だけを調べたいときは、 `eb_multi_entry_have_candidates()` という関数が使えます。)

>     EB_Position position;
>     EB_Error_Code err;

>     /* mulit_id, entry_id で、どの複合検索の
>      * 何番目の入力語について確認するのかを指定します。*/
>     err = eb_multi_entry_candidates(&book, multi_id, entry_id, &position);
>     if (err == EB_ERR_NO_CANDIDATES) {
>         /* この入力語には、候補一覧が用意されていない */
>        return;
>     } else if (err != EB_SUCCESS) {
>         /* それ以外のエラー */
>        return;
>     }

後は、得られた位置 (`position`) にシークして、 `eb_read_text()` でテキストデータを読み込みます。 読み込んだテキストでは、候補となる語のそれぞれが候補開始と終了を表す エスケープシーケンスに挟まれた形になっています。

>     * <候補開始シーケンス> "日本" <候補終了シーケンス>
>     * <候補開始シーケンス> "日本以外のアジア" <候補終了シーケンス>
>     * <候補開始シーケンス> "ヨーロッパ" <候補終了シーケンス>
>     * <候補開始シーケンス> "北アメリカ" <候補終了シーケンス>
>     * <候補開始シーケンス> "その他" <候補終了シーケンス>

候補開始シーケンスに対しては、フックとして `EB_HOOK_BEGIN_CANDIDATE` が用意されています。 終了シーケンスに対するフックは 2 種類あって、さらに次の階層へ続く場合 に呼ばれる `EB_HOOK_END_CANDIDATE_GROUP` と、その語がそのまま 入力語の候補となる場合に呼ばれる `EB_HOOK_END_GROUP_LEAF` に 分かれています。

次の階層のデータの開始位置は、終了シーケンスのフック関数に、引数として 渡ってきます。 (この点もメニューと同様なので、メニューの解説を参考にして下さい。)

終了シーケンスに対するフック関数の中では、`eb_current_candidate()` という関数が使えます。 この関数は、開始シーケンスと終了シーケンスの間に挟まれた「候補」の文字列 (ポインタ) を返します。

>     const char *candidate;

>     candidate = eb_current_candidate(book);

### 区切りコードの問題

本文は、先頭から末尾まで一本の繋がったデータ列になっています。 英語辞典なら、最初の単語 `A' から最後の `zzz' までの説明が、すべて一つの 「本文」の中に書かれることになります。

一般に、アプリケーションプログラムがある単語を検索した際は、本文の中から その単語を説明した部分だけを抜き出して出力することになるでしょう。 たとえば、`dictionary' という単語を引いた場合、次のような文章が出力される 事が期待されます。 その次や、次の次の単語の説明まで延々と表示されることを、おそらく大半の ユーザは望まない筈です。

>     dictionary [名] (複: dictionaries)
>     辞典、事典
>     [類義] lexicon, glossary (用語辞典), encyclopedia (百科事典)

しかし、困ったことに CD-ROM 書籍には、単語の説明の終わりを示す印 (エスケープシーケンス) が定義されていません。 つまり、ある語の説明部分を正確に抜き出すことは、電子ブックや EPWING では 不可能なのです。

しかしながら、幸いにも市販の書籍の多くには、単語の説明の終了位置にだけ 出現する、特有のエスケープシーケンスが存在します。 もちろん、このエスケープシーケンスは本来「単語の説明の終了」を示すもの ではなく別の用途として用いるのですが、「終了位置」として代用できる という意味です。

EB ライブラリでは、この「終了位置」の印に使えるエスケープシーケンスの ことを、区切りコード (stop code) と呼んでいます。 EB ライブラリは区切りコードを自動判定する機能を持っていますが、判定は 完璧ではないので外れることもあります。 外れると本文が途中で途切れたり、本文の続きが延々と出力されたりします。

その場合は、明示的に appendix (詳しくは ebappendix コマンドのマニュアル の「appendix (付録) とは」を参照のこと) で区切りコードを指定することによって回避できる書籍もありますが、 残念ながら区切りコードがまったく存在しない書籍も少数ながら存在します。 区切りコードを持たない書籍に対して、有効な対処方法は今のところありません。

`eb_read_text()` による本文の取得では、区切りコードが検出された 時点で読み込みを止めます。 さらに繰り返し `eb_read_text()` を呼んでも、区切りコードより先の 本文は読み込めません。

区切りコードを検出したかどうかの判定には、`eb_is_text_stopped()` を使います。 この関数は、最後に読み込みを行ったテキストデータの中に、区切りコードを 検出していれば 1 を返します。

本文以外のテキストデータにも区切りコードの概念は存在しますので、 `eb_is_text_stopped()` を使って区切りコードを検出できます。 しかし、本文以外では EB ライブラリが確実に区切りを判別できますので、 誤判定の問題は起きません。

見出しにおける区切りは、それぞれの単語の見出しの終了位置となります。 メニューおよび複合検索の候補一覧では、階層化された個々のメニューデータ の終了位置で区切りと判定されます。 (同一階層に複数個のメニューデータがあっても、個々のメニューデータで 区切られます。) 著作権表示では、全文の終了位置で区切りと判定されます。

### サンプルプログラム

>     /*                                                            -*- C -*-
>      * Copyright (c) 1999-2006  Motoyuki Kasahara
>      *
>      * Redistribution and use in source and binary forms, with or without
>      * modification, are permitted provided that the following conditions
>      * are met:
>      * 1. Redistributions of source code must retain the above copyright
>      *    notice, this list of conditions and the following disclaimer.
>      * 2. Redistributions in binary form must reproduce the above copyright
>      *    notice, this list of conditions and the following disclaimer in the
>      *    documentation and/or other materials provided with the distribution.
>      * 3. Neither the name of the project nor the names of its contributors
>      *    may be used to endorse or promote products derived from this software
>      *    without specific prior written permission.
>      *
>      * THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
>      * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
>      * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
>      * ARE DISCLAIMED.  IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
>      * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
>      * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
>      * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
>      * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
>      * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
>      * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
>      * SUCH DAMAGE.
>      */

>     /*
>      * 使用方法:
>      *     text <book-path> <subbook-index> <number>
>      * 例:
>      *     text /cdrom 0 10
>      * 説明:
>      *     <book-path> で指定した CD-ROM 書籍から特定の副本を選び、本文
>      *     の先頭から <number> 個分の単語の説明を出力します。
>      *
>      *     <subbook-index> には、検索対象の副本のインデックスを指定しま
>      *     す。インデックスは、書籍の最初の副本から順に 0、1、2 ... に
>      *     なります。
>      */
>     #include <stdio.h>
>     #include <stdlib.h>

>     #include <eb/eb.h>
>     #include <eb/error.h>
>     #include <eb/text.h>

>     #define MAXLEN_TEXT 1023

>     int
>     main(int argc, char *argv[])
>     {
>         EB_Error_Code error_code;
>         EB_Book book;
>         EB_Subbook_Code subbook_list[EB_MAX_SUBBOOKS];
>         int subbook_count;
>         int subbook_index;
>         EB_Position text_position;
>         char text[MAXLEN_TEXT + 1];
>         ssize_t text_length;
>         int text_count;
>         int i;

>         /* コマンド行引数をチェック。*/
>         if (argc != 4) {
>             fprintf(stderr, "Usage: %s book-path subbook-index number\n",
>                 argv[0]);
>             exit(1);
>         }
>         text_count = atoi(argv[3]);

>         /* EB ライブラリと `book' を初期化。*/
>         eb_initialize_library();
>         eb_initialize_book(&book);

>         /* 書籍を `book' に結び付ける。*/
>         error_code = eb_bind(&book, argv[1]);
>         if (error_code != EB_SUCCESS) {
>             fprintf(stderr, "%s: failed to bind the book, %s: %s\n",
>                 argv[0], eb_error_message(error_code), argv[1]);
>             goto die;
>         }

>         /* 副本の一覧を取得。*/
>         error_code = eb_subbook_list(&book, subbook_list, &subbook_count);
>         if (error_code != EB_SUCCESS) {
>             fprintf(stderr, "%s: failed to get the subbbook list, %s\n",
>                 argv[0], eb_error_message(error_code));
>             goto die;
>         }

>         /* 副本のインデックスを取得。*/
>         subbook_index = atoi(argv[2]);

>         /*「現在の副本 (current subbook)」を設定。*/
>         error_code = eb_set_subbook(&book, subbook_list[subbook_index]);
>         if (error_code != EB_SUCCESS) {
>             fprintf(stderr, "%s: failed to set the current subbook, %s\n",
>                 argv[0], eb_error_message(error_code));
>             goto die;
>         }

>         /* テキストの開始位置を取得。*/
>         error_code = eb_text(&book, &text_position);
>         if (error_code != EB_SUCCESS) {
>             fprintf(stderr, "%s: failed to get text information, %s\n",
>                 argv[0], eb_error_message(error_code));
>             goto die;
>         }

>         /* テキストをシーク。*/
>         error_code = eb_seek_text(&book, &text_position);
>         if (error_code != EB_SUCCESS) {
>             fprintf(stderr, "%s: failed to seek text, %s\n",
>                 argv[0], eb_error_message(error_code));
>             goto die;
>         }

>         i = 0;
>         while (i < text_count) {
>             /* テキストを取得。*/
>             error_code = eb_read_text(&book, NULL, NULL, NULL, MAXLEN_TEXT,
>                 text, &text_length);
>             if (error_code != EB_SUCCESS) {
>                 fprintf(stderr, "%s: failed to read text, %s\n",
>                     argv[0], eb_error_message(error_code));
>                 goto die;
>             }
>             fputs(text, stdout);

>             if (!eb_is_text_stopped(&book))
>                 continue;

>             fputs("\n----------------------------------------\n", stdout);

>             /* 次の単語の説明へ移動。*/
>             error_code = eb_forward_text(&book, NULL);
>             if (error_code == EB_ERR_END_OF_CONTENT)
>                 fputs("\n[END]\n", stdout);
>             else if (error_code != EB_SUCCESS) {
>                 fprintf(stderr, "%s: failed to read text, %s\n",
>                     argv[0], eb_error_message(error_code));
>                 goto die;
>             }
>             i++;
>         }

>         /* 書籍と EB ライブラリの利用を終了。*/
>         eb_finalize_book(&book);
>         eb_finalize_library();
>         exit(0);

>         /* エラー発生で終了するときの処理。*/
>       die:
>         eb_finalize_book(&book);
>         eb_finalize_library();
>         exit(1);
>     }

### データ型の詳細

この節で説明しているデータ型を使うには、次のようにヘッダファイルを 読み込んで下さい。

>     #include <eb/eb.h>

#### `EB_Hook_Code` 型

データ型 `EB_Hook_Hook` は、フックの設定位置コードを表します。

この型は符合付き整数型の別名として定義されていますので、2 つのコードを 2 項演算子 `==` と `!=` で一致比較することができます。

EB ライブラリでは、全部で `EB_NUMBER_OF_HOOKS` 個のフックコード を定義しています。 定義されている設定位置コードの一覧については、 次の節 (「フックコードの一覧」 を参照のこと) を参照して下さい。

#### `EB_Hook` 型

データ型 `EB_Hook` は、フックコードとそれに対応するフック関数 の組を表します。 内部構造は、次のように定義されています。

>     typedef struct EB_Hook_Struct EB_Hook;

>     struct EB_Hook_Struct {
>         EB_Hook_Code code;
>         EB_Error_Code (*FUNC)(EB_Book *, EB_Appendix *, void *,
>             EB_Hook_Code, int, const unsigned int *);
>     };

アプリケーションプログラムは、直接 `EB_Hook` オブジェクトの メンバを参照したり、セットしたりしても構いません。

#### `EB_Hookset` 型

データ型 `EB_Hookset` は、フック一式を表します。 EB ライブラリで利用可能なすべてのフック設定位置に対して、どのような フック関数を指定するのかを記録するための型です。

`EB_Hookiset` オブジェクトの操作は、すべて EB ライブラリが用意 している関数で行います。 アプリケーションプログラムは、直接 `EB_Hookset` オブジェクトの メンバを参照したり、セットしたりすべきではありません。

`EB_Hookset` オブジェクトを使用する際は、まずそのオブジェクトに 対して `eb_initialize_hookset()` を呼んで初期化しなくては なりません。

### フック関数の詳細

この節では、フック関数の仕様について記します。

まず、フック関数を呼び出す `eb_read_text()` および `eb_read_heading()` のプロトタイプは次のようになっています。

>     EB_Error_Code
>     eb_read_text(EB_Book *book, EB_Appendix *appendix,
>         EB_Hookset *hookset, void *container, size_t text_max_length,
>         char *text, ssize_t *text_length)

一方、フック関数のプロトタイプは、次のようになっています。

>     EB_Error_Code
>     hook_function(EB_Book *book, EB_Appendix *appendix, void *container,
>         EB_Hook_Code code, int argc, const unsigned int *argv);

引数 book, appendix, container は、 `eb_read_text()` あるいは `eb_read_heading()` に 渡された値がそのままフック関数にも渡ってきます。

appendix というのは、書籍に対する補助データを提供するオブジェクト です (appendix (付録) について詳しくは ebappendix コマンドのマニュアル の「appendix (付録) とは」を参照のこと)。

引数 container は、アプリケーションプログラムからフック関数に 何かデータを渡したいときに使います。

最後の argc と argv には、加工前のテキストデータが 渡されます。 文字に対するフックでは、文字コード番号が渡ってきます。 エスケープシーケンスに対するフックでは、そのシーケンス自体のコード (`1f` で始まるコード) と、もしあればエスケープシーケンスへの 引数をが渡ってきます。 個々のフックにおいて、argc と argv にどうような値が 渡ってくるのか、詳しくは 「フックコードの一覧」 を参照のこと。

フック関数の中から次に挙げる関数を呼び出すことで、テキストデータへの 書き込みを行うことができます。

- `eb_write_text()`
- `eb_write_text_string()`
- `eb_write_text_byte1()`
- `eb_write_text_byte2()`

これらの関数の仕様に関して詳しくは 「[テキストデータ] 関数の詳細」 を参照のこと。

フック関数が `EB_SUCCESS` 以外の値を返すと、フック関数を 呼び出した `eb_read_text()`, `eb_read_heading()` はエラーが発生したものと見なし、そのエラーコードをそのまま アプリケーションプログラムに返します。

フック関数の中では、book に対して以下の関数を呼び出しては いけません。 呼び出したときの動作は、未定義です。

- `eb_seek_text()`
- `eb_read_text()`
- `eb_read_heading()`
- `eb_read_rawtext()`
- `eb_forward_text()`
- `eb_backward_text()`
- `eb_set_subbook()`
- `eb_unset_subbook()`
- `eb_load_all_subbook()`
- `eb_bind()`
- `eb_finalize_book()`
- `eb_finalize_library()`

### フックコードの一覧

この節で説明しているフックコードを使うには、次のようにヘッダファイルを 読み込んで下さい。

>     #include <eb/text.h>

#### 定数 `EB_HOOK_NULL`

`EB_HOOK_NULL` は厳密にはフックではなく、 `eb_set_hooks()` で複数のフック関数を登録する際に、 `EB_Hook` 配列の末尾の要素を示すために用います。 このフックコードに対して、フック関数は登録できません。

詳しくは、「[テキストデータ] フック関数の詳細」 を参照のこと。

#### 定数 `EB_HOOK_INITIALIZE`

`EB_HOOK_INITIALIZE` は、`eb_seek_text()` を 呼び出した直後の最初の `eb_read_text()`, `eb_read_heading()` の呼び出し時に処理されます。 何か初期化処理をしたいときに、使うと良いでしょう。

このフックが、フック関数に渡す `argc` は 0 です。 フック関数を登録していない状態では、このフックはテキストデータに何も 書き込みません。

#### 定数 `EB_HOOK_BEGIN_NARROW`

#### 定数 `EB_HOOK_END_NARROW`

`EB_HOOK_BEGIN_NARROW` および `EB_HOOK_END_NARROW` は、半角表示の開始と終了を表すエスケープシーケンスに対するフックです。

どちらのフックも、フック関数に渡す `argc` は 1 です。 `argv[0]` はエスケープシーケンスのコードそのもので、 `EB_HOOK_BEGIN_NARROW` なら `0x1f04`、 `EB_HOOK_END_NARROW` なら `0x1f05` になります。

フック関数を登録していない状態では、これらのフックはテキストデータに何も 書き込みません。

#### 定数 `EB_HOOK_BEGIN_SUBSCRIPT`

#### 定数 `EB_HOOK_END_SUBSCRIPT`

`EB_HOOK_BEGIN_SUBSCRIPT` および `EB_HOOK_END_SUBSCRIPT` は、下付き表示の開始と終了を表す エスケープシーケンスに対するフックです。

どちらのフックも、フック関数に渡す `argc` は 1 です。 `argv[0]` の値はエスケープシーケンスのコードそのもので、 `EB_HOOK_BEGIN_SUBSCRIPT` なら `0x1f06`、 `EB_HOOK_END_SUBSCRIPT` なら `0x1f07` になります。

フック関数を登録していない状態では、これらのフックはテキストデータに 何も書き込みません。

#### 定数 `EB_HOOK_SET_INDENT`

`EB_HOOK_SET_INDENT` は、テキストデータの行頭の字下げ指定を 表すエスケープシーケンスに対するフックです。

このフックが、フック関数に渡す `argc` は 2 です。 `argv[0]` はエスケープシーケンスのコードそのもので、 `0x1f09` になります。 `argv[1]` が、字下げの量を表します。

字下げの量の単位が、何であるのかは不明です。 また、字下げ量の最小値は、0 の場合と 1 の場合の二通りがあります。 いずれにしろ、字下げは 1 ずつ増えたり減ったりします。

フック関数を登録していない状態では、このフックはテキストデータに何も 書き込みません。

#### 定数 `EB_HOOK_NEWLINE`

`EB_HOOK_SET_NEWLINE` は、改行を表すエスケープシーケンスに 対するフックです。

ただし、`eb_read_heading()` (見出しの読み込み) による処理では、 改行を表すエスケープシーケンスは区切りコードとしても扱われます。 そのため、エスケープシーケンスが見つかってもこのフックの処理は行われず、 ただちに読み込み処理は終了します。

このフックが、フック関数に渡す `argc` は 1 です。 `argv[0]` はエスケープシーケンスのコードそのもので、 `0x1f0a` になります。

フック関数を登録していない状態では、このフックはテキストデータに何も 書き込みませんが、`eb_initialize_hookset()` で `EB_Hook` オブジェクトを初期化すると、フック関数として `eb_hook_newline()` が自動的に登録されます。

#### 定数 `EB_HOOK_BEGIN_SUPERSCRIPT`

#### 定数 `EB_HOOK_END_SUPERSCRIPT`

`EB_HOOK_BEGIN_SUPERSCRIPT` および `EB_HOOK_END_SUPERSCRIPT` は、上付き表示の開始と終了を表す エスケープシーケンスに対するフックです。

どちらのフックも、フック関数に渡す `argc` は 1 です。 `argv[0]` はエスケープシーケンスのコードそのもので、 `EB_HOOK_BEGIN_SUPERSCRIPT` なら `0x1f0e`、 `EB_HOOK_END_SUPERSCRIPT` なら `0x1f0f` になります。

フック関数を登録していない状態では、これらのフックはテキストデータに何も 書き込みません。

#### 定数 `EB_HOOK_BEGIN_NO_NEWLINE`

#### 定数 `EB_HOOK_END_NO_NEWLINE`

`EB_HOOK_BEGIN_NO_NEWLINE` および `EB_HOOK_END_NO_NEWLINE` は、改行禁止の開始と終了を表す エスケープシーケンスに対するフックです。

どちらのフックも、フック関数に渡す `argc` は 1 です。 `argv[0]` はエスケープシーケンスのコードそのもので、 `EB_HOOK_BEGIN_NO_NEWLINE` なら `0x1f10`、 `EB_HOOK_END_NO_NEWLINE` なら `0x1f11` になります。

フック関数を登録していない状態では、これらのフックはテキストデータに何も 書き込みません。

#### 定数 `EB_HOOK_BEGIN_EMPHASIS`

#### 定数 `EB_HOOK_END_EMPHASIS`

`EB_HOOK_BEGIN_EMPHASIS` および `EB_HOOK_END_EMPHASIS` は、強調表示の開始と終了を表すエスケープシーケンスに対するフックです。

どちらのフックも、フック関数に渡す `argc` は 1 です。 `argv[0]` はエスケープシーケンスのコードそのもので、 `EB_HOOK_BEGIN_EMPHASIS` なら `0x1f12`、 `EB_HOOK_END_EMPHASIS` なら `0x1f13` になります。

フック関数を登録していない状態では、これらのフックはテキストデータに何も 書き込みません。

#### 定数 `EB_HOOK_BEGIN_CANDIDATE`

#### 定数 `EB_HOOK_END_CANDIDATE_LEAF`

#### 定数 `EB_HOOK_END_CANDIDATE_GROUP`

`EB_HOOK_BEGIN_CANDIDATE` は、複合検索の候補となる語の開始を 表すエスケープシーケンスに対するフックです。

それに対して、終了を表すエスケープシーケンスに対するフックは 2 種類 あります。 一つは `EB_HOOK_END_CANDIDATE_LEAF` で、候補となる語が実際に 検索の入力語として使えるものであることを示します。 もう一つは `EB_HOOK_END_CANDIDATE_GROUP` で、候補となる語は さらに細かい選択肢に分かれていることを示します。 (したがって、候補となる語を検索の入力語として使うことはできません。)

フック `EB_HOOK_BEGIN_CANDIDATES` が、フック関数に渡す `argc` は 1 です。 `argv[0]` はエスケープシーケンスのコードそのもので、 `0x1f43` になります。

フック `EB_HOOK_END_CANDIDATE_LEAF` および `EB_HOOK_END_CANDIDATE_GROUP` が、フック関数に渡す `argc` は 3 です。 どちらのフックも、`argv[0]` はエスケープシーケンスのコード そのもので、`0x1f63` になります。 フック `EB_HOOK_END_CANDIDATE_GROUP` の `argv[1]` と `argv[2]` は、次の階層の候補一覧データの開始ページ番号と オフセットです。 これは、`EB_Position` オブジェクト (「[検索] データ型の詳細」 を参照のこと) の `page` および `offset` メンバの値に相当します。 フック `EB_HOOK_END_CANDIDATE_LEAF` では、`argv[1]`, `argv[2]` は 2 つとも 0 になっています。

フック関数を登録していない状態では、これらのフックはテキストデータに何も 書き込みません。

#### 定数 `EB_HOOK_BEGIN_REFERENCE`

#### 定数 `EB_HOOK_END_REFERENCE`

`EB_HOOK_BEGIN_REFERENCE` および `EB_HOOK_END_REFERENCE` は、別位置のテキストデータの参照開始と 終了を表すエスケープシーケンスに対するフックです。

フック `EB_HOOK_BEGIN_REFERENCE` が、フック関数に渡す `argc` は 2 です。 `argv[0]` はエスケープシーケンスのコードそのもので、 `0x1f42` になります。 `argv[1]` の意味は不明です。

`EB_HOOK_END_REFERENCE` が、フック関数に渡す `argc` は 3 です。 `argv[0]` はエスケープシーケンスのコードそのもので、 `0x1f62` になります。 `argv[1]` と `argv[2]` は、参照先のページ番号と オフセットです。 これは、`EB_Position` オブジェクト (「[検索] データ型の詳細」 を参照のこと) の `page` および `offset` メンバの値に相当します。

フック関数を登録していない状態では、これらのフックはテキストデータに何も 書き込みません。

#### 定数 `EB_HOOK_BEGIN_KEYWORD`

#### 定数 `EB_HOOK_END_KEYWORD`

`EB_HOOK_BEGIN_KEYWORD` および `EB_HOOK_END_KEYWORD` は、 検索キーの開始と終了を表すエスケープシーケンスに対するフックです。

フック `EB_HOOK_BEGIN_KEYWORD` が、フック関数に渡す `argc` は 2 です。 `argv[0]` はエスケープシーケンスのコードそのもので、 `0x1f41` になります。 `argv[1]` の意味は不明です。

`EB_HOOK_END_KEYWORD` は、フック関数に 1 個の引数を渡します。 `argv[0]` はエスケープシーケンスのコードそのもので、 `0x1f61` になります。

フック関数を登録していない状態では、これらのフックはテキストデータに何も 書き込みません。

#### 定数 `EB_HOOK_BEGIN_DECORATION`

#### 定数 `EB_HOOK_END_DECORATION`

`EB_HOOK_BEGIN_DECORATION` および `EB_HOOK_END_DECORATION` は、文字修飾の開始と終了を表す エスケープシーケンスに対するフックです。

フック `EB_HOOK_BEGIN_DECORATION` が、フック関数に渡す `argc` は 2 です。 `argv[0]` はエスケープシーケンスのコードそのもので、 `0x1fe0` になります。 `argv[1]` の意味は不明です。

`EB_HOOK_END_KEYWORD` は、フック関数に 1 個の引数を渡します。 `argv[0]` はエスケープシーケンスのコードそのもので、 `0x1fe1` になります。

フック関数を登録していない状態では、これらのフックはテキストデータに何も 書き込みません。

#### 定数 `EB_HOOK_NARROW_FONT`

#### 定数 `EB_HOOK_WIDE_FONT`

`EB_HOOK_NARROW_FONT` および `EB_HOOK_WIDE_FONT` は、 それぞれ半角外字と全角外字に対するフックです。

どちらのフックも、フック関数に渡す `argc` は 1 です。 `argv[0]` は、外字の文字番号を表します。

フック関数を登録していない状態では、このフックはテキストデータに何も 書き込みませんが、`eb_initialize_hookset()` で `EB_Hook` オブジェクトを初期化すると、フック関数として `eb_hook_narrow_character_text()` および `eb_hook_wide_character_text()` が自動的に登録されます。

#### 定数 `EB_HOOK_ISO8859_1`

`EB_HOOK_ISO8859_1` は、ISO 8859-1 (ラテン文字 1) 文字に対する フックです。

このフックが、フック関数に渡す `argc` は 1 です。 `argv[0]` は、ISO 8859-1 の文字番号を表します。

フック関数を登録していない状態では、`argv[0]` の値をそのまま テキストデータに書き込みます。 つまり、文字はそのまま ISO 8859-1 として、1 バイト書き込まれます。

このフックが利用されるのは、処理中の書籍の文字コードが `EB_CHARCODE_ISO8859_1` の場合だけです。

#### 定数 `EB_HOOK_NARROW_JISX0208`

#### 定数 `EB_HOOK_WIDE_JISX0208`

`EB_HOOK_NARROW_JISX0208` と `EB_HOOK_WIDE_JISX0208` は、半角および全角の JIS X 0208 (日本語のかな漢字) 文字に対するフックです。

どちらのフックも、フック関数に渡す `argc` は 1 です。 `argv[0]` は、JIS X 0208 の文字を日本語 EUC で表現したときの 文字番号を表します。

フック関数を登録していない状態では、`argv[0]` の値をそのまま テキストデータに書き込みます。 つまり、文字はそのまま日本語 EUC として、2 バイト書き込まれます。

このフックが利用されるのは、 処理中の書籍の文字コードが `EB_CHARCODE_JISX0208` か `EB_CHARCODE_JISX0208_GB2312` の場合だけです。

#### 定数 `EB_HOOK_GB2312`

`EB_HOOK_GB2312` は、GB 2312 (中国語の簡体字) 文字に対する フックです。

このフックが、フック関数に渡す `argc` は 1 です。 `argv[0]` は、GB 2312 の文字を中国語 EUC で表現したときの 文字番号を表します。

フック関数を登録していない状態では、`argv[0]` の値をそのまま テキストデータに書き込みます。 つまり、文字はそのまま中国語 EUC として、2 バイト書き込まれます。

このフックが利用されるのは、処理中の書籍の文字コードが `EB_CHARCODE_JISX0208_GB2312` の場合だけです。

#### 定数 `EB_HOOK_BEGIN_MONO_GRAPHIC`

#### 定数 `EB_HOOK_END_MONO_GRAPHIC`

`EB_HOOK_BEGIN_MONO_GRAPHIC` および `EB_HOOK_END_MONO_GRAPIHC` は、モノクロ図版の開始と終了を 表すエスケープシーケンスに対するフックです。

フック `EB_HOOK_BEGIN_MONO_GRAPHIC` が、フック関数に渡す `argc` は 4 です。 `argv[0]` はエスケープシーケンスのコードそのもので、 `0x1f32` か `0x1f44` のいずれかになります。 `argv[2]` と `argv[3]` は、図版の高さと幅 (ピクセル数) を意味します。 ただし、電子ブックのモノクロ図版 (最初の引数が `0x1f32` の 場合) には、図版の高さと幅の情報が欠けているので、値はどちらも 0 に なります。 `argv[1]` の意味は不明です。

`EB_HOOK_END_MONO_GRAPHIC` が、フック関数に渡す `argc` は 3 です。 `argv[0]` は、エスケープシーケンスのコードそのものです。 `EB_HOOK_BEGIN_MONO_GRAPHIC` の `argv[0]` が `0x1f32` なら、`EB_HOOK_END_MONO_GRAPHIC` の `argv[0]` は `0x1f52` になり、`0x1f44` なら `0x1f64` になります。 `argv[1]` と `argv[2]` は、図版データのページ番号 とオフセットです。 これは、`EB_Position` オブジェクト (「[検索] データ型の詳細」 を参照のこと) の `page` および `offset` メンバの値に相当します。

図版データの取り出し方については、「モノクロ図版」 を参照してください。

フック関数を登録していない状態では、これらのフックはテキストデータに何も 書き込みません。

#### 定数 `EB_HOOK_BEGIN_GRAY_GRAPHIC`

#### 定数 `EB_HOOK_END_GRAY_GRAPHIC`

これらのフック名称は、グレースケール図版のために予約されていますが、 本バージョンの EB ライブラリではまだ対応していません。

#### 定数 `EB_HOOK_BEGIN_COLOR_BMP`

#### 定数 `EB_HOOK_BEGIN_COLOR_JPEG`

#### 定数 `EB_HOOK_END_COLOR_GRAPHIC`

`EB_HOOK_BEGIN_COLOR_BMP` と `EB_HOOK_COLOR_JPEG` は、それぞれ BMP 形式と JPEG 形式のカラー図版の開始を表す エスケープシーケンスに対するフックです。 開始のフックは BMP と JPEG とでフックが分かれていますが、終了の フックは共通で、`EB_HOOK_END_COLOR_GRAPIHC` になります。

フック `EB_HOOK_BEGIN_COLOR_BMP` と `EB_HOOK_COLOR_JPEG` が、フック関数に渡す `argc` は 4 です。 `argv[0]` はエスケープシーケンスのコードそのもので、 `0x1f4d` になります。 `argv[2]` と `argv[3]` は、図版の幅と高さ (ピクセル数) を意味します。 `argv[1]` の意味は不明です。

フック `EB_HOOK_END_COLOR_BMP` が、フック関数に渡す `argc` は 3 です。 `argv[0]` はエスケープシーケンスのコードそのもので、 `0x1f6d` になります。 `argv[1]` と `argv[2]` は、図版データのページ番号 とオフセットです。 これは、`EB_Position` オブジェクト (「[検索] データ型の詳細」 を参照のこと) の `page` および `offset` メンバの値に相当します。

図版データの取り出し方については、「カラー図版」 を参照してください。

フック関数を登録していない状態では、これらのフックはテキストデータに何も 書き込みません。

#### 定数 `EB_HOOK_BEGIN_IN_COLOR_BMP`

#### 定数 `EB_HOOK_BEGIN_IN_COLOR_JPEG`

#### 定数 `EB_HOOK_END_IN_COLOR_GRAPHIC`

`EB_HOOK_BEGIN_IN_COLOR_BMP` と `EB_HOOK_IN_COLOR_JPEG` は、 それぞれ BMP 形式と JPEG 形式のインラインカラー図版の開始を表す エスケープシーケンスに対するフックです。 開始のフックは BMP と JPEG とでフックが分かれていますが、終了の フックは共通で、`EB_HOOK_END_IN_COLOR_GRAPIHC` になります。

フック `EB_HOOK_BEGIN_IN_COLOR_BMP` と `EB_HOOK_IN_COLOR_JPEG` が、フック関数に渡す `argc` は 4 です。 `argv[0]` はエスケープシーケンスのコードそのもので、 `0x1f3c` になります。 `argv[2]` と `argv[3]` は、図版の幅と高さ (ピクセル数) を意味します。 `argv[1]` の意味は不明です。

フック `EB_HOOK_END_IN_COLOR_BMP` が、フック関数に渡す `argc` は 3 です。 `argv[0]` はエスケープシーケンスのコードそのもので、 `0x1f5c` になります。 `argv[1]` と `argv[2]` は、図版データのページ番号と オフセットです。 これは、`EB_Position` オブジェクト (「[検索] データ型の詳細」 を参照のこと) の `page` および `offset` メンバの値に相当します。

図版データの取り出し方については、「カラー図版」 を参照してください。

フック関数を登録していない状態では、これらのフックはテキストデータに何も 書き込みません。

#### 定数 `EB_HOOK_BEGIN_CLICKABLE_AREA`

#### 定数 `EB_HOOK_END_CLICKABLE_AREA`

`EB_HOOK_BEGIN_CLICKABLE_AREA` は、カラー図版およびインラインカラー図版内の特定矩形領域に対して、参照先情報を表現した開始エスケープシーケンスに対するフックです。 同様に、`EB_HOOK_END_CLICKABLE_AREA` は終了エスケープシーケンスに対するフックです。

フック `EB_HOOK_BEGIN_CLICKABLE_AREA` が、フック関数に渡す `argc` は 7 です。 `argv[0]` はエスケープシーケンスのコードそのもので、 `0x1f4f` になります。 `argv[1]` と `argv[2]` は、それぞれ矩形領域の開始 x, y 座標を表します。 それぞれ矩形領域の開始 x, y 座標を表します。 カラー図版の左上の座標が (0, 0) です。 同様に、`argv[3]` と `argv[4]` が図版の右方向への 幅と、下方向への高さを表します。 最後の `argv[5]` と `argv[6]` が参照先のページ番号 とオフセットとなります。

>     　　　　　　　　　参照先付きカラー図版
>     （０，０）
>     　　┌─────────────────────┐
>     　　│　　　　　　　　　　　　　　　　　　　　　│
>     　　│（ｘ，ｙ）　　　　　　　　　　　　　　　　│
>     　　│　　┌　─　─　─　─　─　─　┐　　　　│
>     　　│　　│　　　　　　　　　高さ↑　│　　　　│
>     　　│　　　　　　　　　　　　　　│　　　　　　│
>     　　│　　│　　矩形領域　　　　　│　│　　　　│
>     　　│　　　　　　　　　　　　　　│　　　　　　│
>     　　│　　│　　　　　　　　　　　│　│　　　　│
>     　　│　　　　　　　幅　　　　　　│　　　　　　│
>     　　│　　│←──────────┼→│　　　　│
>     　　│　　　　　　　　　　　　　　↓　　　　　　│
>     　　│　　└　─　─　─　─　─　─　┘　　　　│
>     　　│　　　　　　　　　　　　　　　　　　　　　│
>     　　└─────────────────────┘

`EB_HOOK_END_CLICKABLE_AREA` が、フック関数に渡す `argc` は 1 です。 `argv[0]` はエスケープシーケンスのコードそのもので、 `0x1f6f` になります。

参照先情報の取り出し方については、 「参照先付きカラー図版」 を参照して下さい。

フック関数を登録していない状態では、これらのフックはテキストデータに何も 書き込みません。

#### 定数 `EB_HOOK_BEGIN_WAVE`

#### 定数 `EB_HOOK_END_WAVE`

`EB_HOOK_BEGIN_WAVE` および `EB_HOOK_END_WAVE` は、 WAVE (PCM) 形式の音声データの開始と終了を表すエスケープシーケンスに対する フックです。

フック `EB_HOOK_BEGIN_WAVE` が、フック関数に渡す `argc` は 6 です。 `argv[0]` はエスケープシーケンスのコードそのもので、 `0x1f4a` になります。 `argv[2]` と `argv[3]` は音声データの開始位置の ページ番号とオフセット、`argv[4]` と `argv[5]` は 終了位置のページ番号とオフセットをそれぞれ表します。 `argv[1]` の意味は不明です。

`EB_HOOK_END_WAVE` が、フック関数に渡す `argc` は 1 です。 `argv[0]` はエスケープシーケンスのコードそのもので、 `0x1f6a` になります。

音声データの取り出し方については、「WAVE 音声」 を参照して下さい。

フック関数を登録していない状態では、これらのフックはテキストデータに何も 書き込みません。

#### 定数 `EB_HOOK_BEGIN_MPEG`

#### 定数 `EB_HOOK_END_MPEG`

`EB_HOOK_BEGIN_MPEG` および `EB_HOOK_END_MPEG` は、 MPEG 形式の動画データの開始と終了を表すエスケープシーケンスに対するフック です。

フック `EB_HOOK_BEGIN_MPEG` が、フック関数に渡す `argc` は 6 です。 `argv[0]` はエスケープシーケンスのコードそのもので、 `0x1f39` になります。 `argv[2]` 〜 `argv[5]` は、動画データのファイル名を エンコードした数値列になります。 `argv[1]` の意味は不明です。

`EB_HOOK_END_MPEG` が、フック関数に渡す `argc` は 1 です。 `argv[0]` はエスケープシーケンスのコードそのもので、 `0x1f59` になります。

動画データの取り出し方については、「MPEG 動画」 を参照して下さい。

フック関数を登録していない状態では、これらのフックはテキストデータに何も 書き込みません。

### フックセット操作関数の詳細

この節で説明している関数を使うには、次のようにヘッダファイルを読み込んで 下さい。

>     #include <eb/text.h>

#### `void eb_initialize_hookset (EB_Hookset *hookset)`

関数 `initialize_hookset()` は、hookset の指す `EB_Hookset` オブジェクトを初期化します。 `EB_Hookiset` オブジェクトに対して EB ライブラリの他の関数を 呼ぶ前に、 必ずそのオブジェクトを初期化しなくてはなりません。 初期化していないオブジェクトに対して、EB ライブラリの他の関数を呼んだ 場合の動作は未定義です。 また、すでに初期化したオブジェクトに対して、再度 `eb_initialize_hookset()` を呼んではいけません。 呼んだ場合の動作は未定義です。

この関数は、各フックの初期値を次のようにセットします。

フック | フック関数
`EB_HOOK_NARROW_JISX0208` | `eb_hook_euc_to_ascii()`
`EB_HOOK_NARROW_FONT` | `eb_hook_narrow_character_text()`
`EB_HOOK_WIDE_FONT` | `eb_hook_wide_character_text()`
`EB_HOOK_NEWLINE` | `eb_hook_newline()`
上記以外のフック | `NULL` (フック関数なし)

#### `EB_Error_Code eb_finalize_hookset (EB_Hookset *hookset)`

関数 `eb_finalize_hookset()` は、hookset が指す `EB_Hooksest` オブジェクトの後始末を行います。

オブジェクトが割り当てて管理していたメモリは、すべて解放されます。 すべてのフックには、フック関数として `NULL` がセットされます。

後始末をしたオブジェクトに対して `eb_set_hook()`, `eb_set_hooks()` を呼ぶことで、オブジェクトを再利用することができます。

#### `EB_Error_Code eb_set_hook (EB_Hookset *hookset, const EB_Hook *hook)`

関数 `eb_set_hook()` は、hookset が指す `EB_Hooksest` オブジェクトに、フック関数を一つ登録します。 登録するフックの種類とフック関数は、hook で指定します。

同じフックコードに複数回フック関数を登録しても、有効になるのは最後に 登録したものだけですので、注意して下さい。 フック関数として `NULL` を指定すると、登録されているフックが 解除されます。

成功すると、この関数は `EB_SUCCESS` を返します。 失敗すると、原因を示すエラーコードを返します。

#### `EB_Error_Code eb_set_hooks (EB_Hookset *hookset, const EB_Hook *hooks)`

この関数は `eb_set_hook()` に似ていますが、任意の個数の フック関数を一度に登録できる点が異なります。

登録するフックの種類とフック関数は、hooks で指定します。 hooks は `EB_Hook` オブジェクトの配列 (の先頭) を 指していなければなりません。 また、この配列の末尾には、フックコード `EB_HOOK_NULL` をセット した `EB_Hook` オブジェクトを配列要素として置く必要があります。

`eb_set_hooks()` は、配列の先頭から順番に、指定されたフックコード に対してフック関数を登録していきます。 エラーが発生すると、残りのフックの登録はせずに、原因を示すエラーコード をただちに返します。 すべてのフック関数の登録に成功すると、`EB_SUCCESS` を返します。

### 組み込みフック関数の詳細

EB ライブラリは、基本的なフック関数をいくつか用意しています。 本節では、これらのフック関数についての仕様を解説します。

この節で説明している関数を使うには、次のようにヘッダファイルを読み込んで 下さい。

>     #include <eb/text.h>

いずれのフック関数も、引数 appendix と container に `NULL` を渡されても、動作に支障はないようになっています。

#### `EB_Error_Code eb_hook_euc_to_ascii (EB_Book *book, EB_Appendix *appendix, void *container, EB_Hook_Code code, int argc, const unsigned int *argv)`

`eb_hook_euc_to_ascii()` は、フックコード `EB_HOOK_NARROW_JISX0208` (半角 JIS X 0208 文字) のための フック関数です。

`EB_Hookset` オブジェクトを関数 `eb_initialiez_hookset()` で初期化すると、この関数が自動的に 登録されます。

このフック関数は、`argv[0]` として渡された JIS X 0208 の文字 (エンコーディングは日本語 EUC) を調べ、対応する ASCII 文字が存在すれば その ASCII 文字をテキストデータとして書き込み、なければ JIS X 0208 の 文字をそのまま書き込みます。

常に `EB_SUCCESS` を返します。

#### `EB_Error_Code eb_hook_narrow_character_text (EB_Book *book, EB_Appendix *appendix, void *container, EB_Hook_Code code, int argc, const unsigned int *argv)`

#### `EB_Error_Code eb_hook_wide_character_text (EB_Book *book, EB_Appendix *appendix, void *container, EB_Hook_Code code, int argc, const unsigned int *argv)`

`eb_hook_narrow_character_text()` は、フックコード `EB_HOOK_NARROW_FONT` (半角外字) のためのフック関数です。 同様に `eb_hook_wide_character_text()` は、フックコード `EB_HOOK_WIDE_FONT` (全角外字) のためのフック関数です。

`EB_Hookset` オブジェクトを関数 `eb_initialiez_hookset()` で初期化すると、これらの関数が自動的 に登録されます。

この関数は、appendix の選択中している副本が、 `argv[0]` として渡された外字の代替文字列を持っているかどうか 調べます。 持っていればその文字列をテキストデータとして書き込み、持っていなければ `<?>` という文字列を書き込みます。

appendix が `NULL` の場合や、付録が副本を選択中で ない場合も、代替文字列を持っていないものとして扱います。

この関数は、常に `EB_SUCCESS` を返します。

#### `EB_Error_Code eb_hook_newline (EB_Book *book, EB_Appendix *appendix, void *container, EB_Hook_Code code, int argc, const unsigned int *argv)`

`eb_hook_narrow_newline()` は、フックコード `EB_HOOK_NEWLINE` (改行) のためのフック関数です。

`EB_Hookset` オブジェクトを関数 `eb_initialiez_hookset()` で初期化すると、これらの関数が自動的 に登録されます。

この関数は、テキストデータに `\n` を書き込みます。 常に `EB_SUCCESS` を返します。

#### `EB_Error_Code eb_hook_empty (EB_Book *book, EB_Appendix *appendix, void *container, EB_Hook_Code code, int argc, const unsigned int *argv)`

`eb_hook_empty()` は、何もしないフック関数です。 常に `EB_SUCCESS` を返します。

### テキストデータ操作関数の詳細

この節で説明している関数を使うには、次のようにヘッダファイルを読み込んで 下さい。

>     #include <eb/text.h>

#### `int eb_have_text (EB_Book *book)`

#### `int eb_have_menu (EB_Book *book)`

#### `int eb_have_copyright (EB_Book *book)`

関数 `eb_have_text()` は、book の選択している副本が、 本文を持っているかどうかを調べます。 同様に、`eb_have_menu()` はメニューを持っているかどうか、 `eb_have_copyright()` は著作権表示を持っているかどうか調べます。

いずれの関数も、持っていれば 1 を返し、持っていなければ 0 を返します。 book が副本を選択していない場合も 0 を返します。

#### `EB_Error_Code eb_text (EB_Book *book, EB_Position *position)`

#### `EB_Error_Code eb_menu (EB_Book *book, EB_Position *position)`

#### `EB_Error_Code eb_copyright (EB_Book *book, EB_Position *position)`

関数 `eb_text()` は、book が選択している副本の本文 の開始位置を position の指す領域に書き込みます。 同様に、`eb_menu()` はメニューの開始位置を、 `eb_have_copyright()` は著作権表示の開始位置を書き込みます。

成功すると、これらの関数は `EB_SUCCESS` を返します。 失敗すると、position に必ずシークが失敗する位置を書き込んで、 原因を示すエラーコードを返します。

あらかじめ、book 内のいずれかの副本が選択されていなくては なりません。 book が副本を選択していなければ、`EB_ERR_NO_CUR_SUB` を返します。 選択中の副本が、対象となるテキストデータを持っていなければ、 `EB_ERR_NO_SUCH_SEARCH` を返します。

#### `EB_Error_Code eb_seek_text (EB_Book *book, const EB_Position *position)`

関数 `eb_seek_text()` は、book が選択している副本の テキストデータファイルをシークします。 シーク位置は position で指定します。 このとき、position は常にファイルの先頭からの位置として解釈 されます。 (相対位置へのシーク機能は、EB ライブラリにはありません。)

シークを行うと、それまでに行った読み込みの状態記録がリセットされます。 `eb_read_text()`, `eb_read_heading()`, `eb_read_rawtext()` を用いてテキストデータを読み込むには、 前もってこの関数を呼び出しておく必要があります。

成功すると、この関数は `EB_SUCCESS` を返します。 失敗すると、原因を示すエラーコードを返します。

あらかじめ、book 内のいずれかの副本が選択されていなくては なりません。 book が副本を選択していなければ、`EB_ERR_NO_CUR_SUB` を返します。 選択中の副本にテキストデータが存在しないときは、`EB_ERR_NO_TEXT` を返します。

なお、書籍によっては、テキストデータを収めたファイルには他のデータも 一緒に格納されていることがありますが、テキスト以外のデータにアクセス しても、テキストデータの現在位置、読み込みに関する状態記録は変化しません。

#### `EB_Error_Code eb_tell_text (EB_Book *book, EB_Position *position)`

関数 `eb_seek_text()` は、book が選択している副本の テキストデータファイルの現在のアクセス位置を返します。

成功すると、position の指す領域に現在のアクセス位置を書き込み、 `EB_SUCCESS` を返します。 失敗すると、シークが必ず失敗する位置を書き込み、原因を示すエラーコード を返します。

あらかじめ、book 内のいずれかの副本が選択されていなくては なりません。 book が副本を選択していなければ、`EB_ERR_NO_CUR_SUB` を返します。 選択中の副本にテキストデータが存在しないときは、`EB_ERR_NO_TEXT` を返します。

#### `EB_Error_Code eb_read_text (EB_Book *book, EB_Appendix *appendix, EB_Hookset *hookset, void *container, size_t text_max_length, char *text, ssize_t *text_length)`

#### `EB_Error_Code eb_read_heading (EB_Book *book, EB_Appendix *appendix, EB_Hookset *hookset, void *container, size_t text_max_length, char *text, ssize_t *text_length)`

関数 `eb_read_text()` と `eb_read_heading()` は、 book が選択している副本のテキストデータファイルの現在のアクセス位置からデータ を読み込みます。 `eb_read_heading()` は見出しの読み込みに用い、 `eb_read_text()` はそれ以外のテキストデータの読み込みに用います。

読み込まれたテキストデータは、必要に応じて文字コードの変換 (「文字コード」 を参照のこと) が行われた後に、hookset の指すフックセットにしたがって加工されます。 hookset が `NULL` のときは、代わりに EB ライブラリ側 で用意している 標準のフックセット (default hookset) が 用いられます。 このフックセットは、`eb_initialize_hookset()` によって 初期化しただけのフックセットと等価です。

フックセットによって加工された後に、テキストデータは text の 指す領域に書き込まれ、書き込んだバイト数が text_length の指す 領域に書き込まれます。 text はナル文字で終端されますが、text_length には ナル文字の分は勘定に入れません。 テキストデータは、text_max_length で指定されたバイト数を超えて 書き込むことはありません。 ただし、text_max_length にもナル文字の分は勘定に入っていません ので、text は text_max_length + 1 バイト分のデータ を格納できる大きさが必要です。

どちらの関数も、成功すれば `EB_SUCCESS` を返し、失敗すれば text_length の指す領域に 0 を書き込んで原因を示すエラーコード を返します。

あらかじめ、book 内のいずれかの副本が選択されていなくては なりません。 book が副本を選択していなければ、`EB_ERR_NO_CUR_SUB` を返します。

また、`eb_read_text()` と `eb_read_heading()` を 呼び出すには、 あらかじめ `eb_seek_text()` の呼び出しを成功させ、テキストデータ のアクセス位置がセットされた状態にしておかなくてはなりません。 シークをせずに呼び出すと、`EB_ERR_NO_PREV_SEEK` を返します。

逆に一度シークすれば、区切りコードが検出されるまでの間なら、関数を 繰り返し呼ぶことでテキストデータの続きを読み込むことができます。 区切りコードが検出されると、関数を呼び出しても読み込みは行われません。 その場合でも、他にエラーが発生しなければ `EB_SUCCESS` が返り、 text には空文字列が書き込まれます。

ただし、一度 `eb_read_text()` を呼び出してテキストデータを 読み込み始めたら、繰り返し呼び出す際も、`eb_read_text()` を 使わなければなりません。 途中から `eb_read_heading()` および後述の `eb_read_rawtext()` に切り替えて呼び出すと `EB_ERR_DIFF_CONTENT` エラーが返ります。 関数 `eb_read_heading()` についても同様です。 この制限は、再度 `eb_seek_text()` を呼び出すか、 `eb_set_subbook()` で副本を選択し直すまで続きます。

渡された appendix が区切りコードの情報を持った副本を選択中 であれば、本文の区切りコードとしてその値を使用します。 それ以外の場合は、`eb_read_text()` が区切りコードを自動判別を 試みます。 ただし、この判定は完璧なものではないので、書籍によっては変な位置で本文 が切れてしまうかも知れません。 (本文以外のテキストデータに関しては、このような問題は起きません。)

引数 container は、アプリケーションプログラムからフック関数に データを渡すためのものです。 `eb_read_text()`, `eb_read_heading()` では、直接 この引数の値を参照することはありません。

引数 appendix, container は、そのままフック関数に 渡されます。 これらの引数は `NULL` でも構いません。 (呼び出されるフック関数で支障がなければ。)

なお、フック関数や `eb_read_text()`, `eb_read_heading()` 自身が文字ないしエスケープシーケンス一個分に対するデータを書き込もうと したときに、text に十分な空き領域がないということが起こり 得ます。 その場合、関数は途中まで text に書き込むことはせずに、 いったん処理を終えて戻ります。 したがって、マルチバイト文字のデータが途中で切れたりすることはありません。

書き込めなかった分は、当然ながら text_length の勘定には 入りません。 書き込めなかったデータは book 内部に保存されているので、 もう一度 `eb_read_text()`, `eb_read_heading()` を 呼び出すと、前回の呼び出しで書き込めなかったデータがまず text の先頭に書き込まれます。 書き込んだデータは text_length の勘定に入ります。

ただし、`book` が保存しているデータの長さが text_max_length を超えていると、何も書き込まずに関数は終了 します。 このとき、書き込めなかったデータは引き続き保存されます。 つまり、`text_max_length` があまりに小さく、かつ保持している データのほうが長いと、何度呼び出しても `text` への書き込みが 進みませんので、注意が必要です。

`eb_seek_text()` を呼び出すか、`eb_set_subbook()` で副本を選択し直すと、保存していたデータは破棄されます。

#### `EB_Error_Code eb_read_rawtext (EB_Book *book, size_t text_max_length, char *text, ssize_t *text_length)`

関数 `eb_read_rawtext()` は、book が選択している 副本のテキストデータファイルの現在のアクセス位置からデータを読み込みます。

`eb_read_text()` と似ていますが、この関数はフックセットによる データの加工や文字コードの変換を一切行わず、データを内部表現のまま返します。 読み込むテキストデータの種類は、何であっても構いません。

読み込んだテキストデータは text の指す領域に書き込まれ、 書き込んだバイト数が text_length の指す領域に書き込まれます。 テキストデータは、text_max_length で指定されたバイト数を超えて 書き込むことはありません。 ただし、`eb_read_text()` と異なり、text はナル文字 で終端されません。 マルチバイト文字やエスケープシーケンスの途中で text の残り領域 が足りなくなった場合も、途中までは書き込みます。

処理が成功すれば `EB_SUCCESS` を返し、失敗すれば text_length の指す領域に 0 を書き込んで原因を示すエラーコード を返します。

あらかじめ、book 内のいずれかの副本が選択されていなくては なりません。 book が副本を選択していなければ、`EB_ERR_NO_CUR_SUB` を返します。

また、この関数を呼び出すには、あらかじめ `eb_seek_text()` の 呼び出しを成功させ、テキストデータのアクセス位置がセットされた状態にして おかなくてはなりません。 シークをせずに呼び出すと、`EB_ERR_NO_PREV_SEEK` を返します。

この関数は、繰り返し呼び出すことで、前回読み込んだテキストデータの続き を読み込むことができます。 ただし、区切りコードの検出を行いませんので、ひたすら呼び出しを続けると、 テキストデータファイルの末尾まで行ってしまいます。

一度 `eb_read_rawtext()` を呼び出してテキストデータを読み込み 始めたら、繰り返し呼び出す際も、`eb_read_rawtext()` を 使わなければなりません。 途中から、`eb_read_text()` や `eb_read_heading()` に 切り替えると、 `EB_ERR_DIFF_CONTENT` エラーが返ります。 この制限は、再度 `eb_seek_text()` を呼び出すか、 `eb_set_subbook()` で副本を選択し直すまで続きます。

#### `int eb_is_text_stopped (EB_Book *book)`

関数 `eb_is_text_stopped()` は、最後に読み込んだテキストデータ が末尾に達したかどうかを判定します。

book が選択中の副本で、最後に `eb_read_text()` または `eb_read_heading()` でテキストデータを読み込んだ際に、 区切りコードを検出したか、テキストデータ全体の一番後ろの位置に達して 読み込みを終えていれば、この関数は 1 を返します。 それ以外のときは、0 を返します。

book が副本を選択していない場合や、選択中の副本にテキストデータ が存在しない場合も 0 が返ります。

`eb_read_text()` または `eb_read_heading()` で テキストデータを読み込んでいない場合も、同様に 0 が返ります。 テキストデータを読み込んだ後であっても、テキストデータの読み込みに関する 状態記録をリセットする関数 (eb_read_text() の項を参照) を呼んでしまうと、 読み込んでいないと見なされますので、注意して下さい。

通常はこの関数を使わなくても、`eb_read_text()` や `eb_read_heading()` が 0 を返したら、テキストデータの末尾に 達したとみなして差し支えないでしょう。 ただしその際は、引数 `text_max_length` の値を十分大きく取って 下さい。

#### `EB_Error_Code eb_write_text_byte1 (EB_Book *book, int byte1)`

#### `EB_Error_Code eb_write_text_byte2 (EB_Book *book, int byte1, int byte2)`

#### `EB_Error_Code eb_write_text_string (EB_Book *book, const char *string)`

#### `EB_Error_Code eb_write_text (EB_Book *book, const char *stream, size_t stream_length)`

これらの関数は、いずれもフック関数の中から、テキストデータを書き込む ために用います。 書き込むデータの種類によって、使い分けて下さい。

`eb_write_text_byte1()` は、byte1 で指定した 1 バイトの値を書き込みます。 `eb_write_text_byte2()` は、byte1, byte2 で指定した 2 バイトを書き込みます。 `eb_write_text_string()` は、string で指定した 文字列を書き込みます。 `eb_write_text()` は、stream から始まる長さ stream_length バイトのバイト列を書き込みます。

どの関数も、成功すると `EB_SUCCESS` を返し、失敗すると原因を 示すエラーコードを返します。

最終的に、書き込んだテキストデータは、フック関数の呼び出し元である `eb_read_text()`, `eb_read_heading()` から アプリケーションプログラムに渡されます。

フック関数として呼び出されていないときに、これらの関数を呼び出した場合 の動作は未定義です。

#### `const char *eb_current_candidate (EB_Book *book)`

関数 `eb_current_candidate()` は、アクセス中のテキストデータの 現在位置に書かれている、複合検索の候補となる語を返します。

返す文字列の長さは、最長で `EB_MAX_WORD_LENGTH` バイトになります。 ただし、この長さにナル文字は含みません。

この関数は非常に特殊で、複合検索の候補となる語の終了を意味する エスケープシーケンスへのフックである `EB_HOOK_END_CANDIDATE_LEAF` および `EB_HOOK_END_CANDIDATE_GROUP` に対するフック関数の中で のみ呼び出すことができます。 それ以外の場所で呼び出したときの動作は、未定義です。

この関数の呼び出し方ですが、フック関数に渡ってきた `EB_Book` オブジェクト (へのポインタ) を、そのままこの関数に引数として渡して やります。

book の文字コード (「[CD-ROM 書籍と `EB_Book` オブジェクト] データ型の詳細」 を参照のこと) が `EB_CHARCODE_ISO8859_1` なら、関数の返す文字列は ISO 8859-1 になり、それ以外の文字コードの場合は日本語 EUC になります。 関数の返す文字列は、他のフックによる加工処理の影響を受けません。 文字コードの変換を行う以外は、内部データをそのまま返します。

なお、この関数が返した文字列を参照できるのは、フック関数から戻るまでの 間だけですので、注意して下さい。

#### `EB_Error_Code eb_forward_text (EB_Book *book, EB_Appendix *appendix)`

#### `EB_Error_Code eb_backward_text (EB_Book *book, EB_Appendix *appendix)`

関数 `eb_forward_text()` と `eb_backward_text()` は、 book が選択している副本の本文のアクセス位置を前後に移動させ、 本文の区切りコードを単位とした頭出しを行います。 ちょうど、音楽 CD の曲の頭出しと同じです。

`eb_forward_text()` は本文の末尾方向に向かってアクセス位置を 進め、`eb_backward_text()` は先頭方向に向かってアクセス位置を 戻します。

`eb_forward_text()` の呼び出しでは、アクセス位置は必ず次の語の 説明の開始位置まで移動します。 それに対して `eb_backward_text()` の呼び出しでは、移動先が状態 によって異なります。 もし、現在のアクセス位置がその単語の説明の先頭にあるときは、 `eb_backward_text()` の呼び出しによって、一つ前の単語の説明の 先頭にアクセス位置が移動します。 アクセス位置が単語の説明の途中や末尾にあるときは、その単語の説明の 先頭に移動します。

この関数は、成功すると `EB_SUCCESS` を返し、失敗すると原因を示す エラーコードを返します。

あらかじめ、book 内のいずれかの副本が選択されていなくては なりません。 book が副本を選択していなければ、`EB_ERR_NO_CUR_SUB` を返します。

加えて、これらの関数を呼び出すには、あらかじめ `eb_seek_text()` か `eb_read_text()` を呼び出しが成功していないといけません。 (`eb_read_text()` の呼び出しを成功させるには、さらに前もって `eb_seek_text()` の呼び出しを成功させることが条件となります。)

`eb_read_text()` ではなく、`eb_read_heading()` や `eb_read_rawtext()` の呼び出しに成功した後でこの関数を 呼び出すと、`EB_ERR_DIFF_CONTENT` を返します。 また、前もって `eb_seek_text()` でシークせずにこの関数を 呼び出すと、`EB_ERR_NO_PREV_SEEK` を返します。

本文データの末尾や先頭に達してしまって、その方向にもう本文がないときは、 `EB_ERR_END_OF_CONTENT` を返します。

appendix が `NULL` ではなく、区切りコードの情報を 持った副本を選択中であれば、本文の区切りコードとしてその値を使用します。 それ以外の場合は、`eb_read_text()` と同じ方法で区切りコードの 自動判別を試みます。

アクセス位置上にあるのがメニューや著作権表示のように、本文以外の テキストデータであっても構いません。 ただし、本文以外のテキストデータの内部には、頭出し位置がデータの 先頭位置にしかありませんので、この関数が役に立つ状況はほとんど ありません。

(メニューでは、個々の階層のメニューデータが、それぞれ独立した テキストデータになっているため、頭出しを行っても前後のメニューデータへは 移動できません。 複合検索の候補一覧も同様です。)

#### `EB_Error_Code eb_forward_heading (EB_Book *book)`

関数 `eb_forward_heading()` は、book が選択している 副本の見出しのアクセス位置を後に移動させ、見出しの区切りを単位とした頭出し を行います。

本文の頭出しを行う関数 `eb_forward_text()` の見出し版です。 ただし、見出しで頭出しを行う機会は、クロス検索の本文取得に限られるため、 `eb_backward_heading()` という関数は用意していません。

この関数を呼ぶと、アクセス位置が次の見出しの開始位置まで移動します。 (クロス検索では、見出し領域の中に「見出し」と「本文」が交互に書かれて いますが、データ構造上「本文」と「見出し」は区別が付きません。 アクセス位置がクロス検索の見出し領域内の場合、この関数を呼ぶと最も近い 「見出し」もしくは「本文」の開始位置まで移動します。)

`eb_read_heading()` ではなく、`eb_read_text()` や `eb_read_rawtext()` の呼び出しに成功した後でこの関数を 呼び出すと、`EB_ERR_DIFF_CONTENT` を返します。 また、前もって `eb_seek_text()` でシークせずにこの関数を 呼び出すと、`EB_ERR_NO_PREV_SEEK` を返します。

この関数は、成功すると `EB_SUCCESS` を返し、失敗すると原因を示す エラーコードを返します。

クロス検索以外の検索メソッドの見出しの格納位置に対して、この関数を 呼ぶことも可能ですが、そのような必要に迫られる機会はないでしょう。

[前へ] [次へ] [目次]