EB ライブラリ

この文書は、EB ライブラリバージョンに対応しています。

はじめに

EB ライブラリは CD-ROM 書籍にアクセスするための C のライブラリです。 UNIX 系 OS および Windows (2000以降) のシステム上で動作させることができます。

EB ライブラリは EB, EBG, EBXA, EBXA-C, S-EBXA および EPWING 形式の CD-ROM 書籍に対応しています。これらは、主に日本で販売されている辞書に使われています。 CD-ROM 書籍自体は ISO 9660 形式になっていますので、他の ISO 9660 形式と同じ要領でマウントすることができます。

本書は、EB ライブラリを使ってアプリケーションプログラムを作成する開発者向けに、ライブラリの仕様を解説した文書です。そして、ライブラリの公式な参照マニュアルでもあります。読み進めるにあたって、読者は EB ライブラリおよび CD-ROM 書籍の内部構造について知っている必要はありませんが、電子ブックか EPWING を利用して、実際に CD-ROM 書籍がどのようなものかを理解しておくことをお薦めします。また、C 言語によるプログラミングについては、十分に理解していることを前提とします。

本書の内容に沿って EB ライブラリを使ったアプリケーションプログラムを作成するには、お使用いのシステムに EB ライブラリと C コンパイラをインストールしておいて下さい。なお、本書では主に UNIX 系 OS を使用した場合について、記述しています。

EB ライブラリはフリーソフトウェアです。ソースコードおよびバイナリを、いわゆる Modified BSD ライセンスの下で使用することが可能です。 (バージョン 4.1 よりも前のものは、GPL を採用していました。) 詳しくは、ソースコードに付属している COPYING という英文のファイルを参照して下さい。

電子ブックと EPWING について

電子ブックと EPWING は、いずれも主に日本で使われている電子書籍のデータ形式の名称で、CD-ROM に収めた形で数々の書籍が市販されています。 CD-ROM は ISO 9660 形式なので、CD-ROM ドライブが扱えるシステムであれば、容易にアクセスすることができます。電子書籍のデータ形式とはいっても、実際は辞書向けに特化した構造となっており、市販されている書籍も辞書の類が圧倒的に多いようです。

電子ブック、EPWING ともに、データ形式に関する規格の全容は一般公開されていませんが、EPWING ついては規格の一部が日本工業規格 JIS X 4081 「電子出版検索データ構造」として公開されています。さらに、EPWING と電子ブックのデータ形式は、酷似していることが知られています。

EB ライブラリの開発者も、電子ブック、EPWING 規格の全容は知りません。 EB ライブラリでは JIS X 4081 の記述をもとに、電子ブック、EPWING を読めるようにしてあります。しかしながら、規格の全容が分からない状態で開発しているため、残念ながら一部に正しく読めない書籍が存在します。

本書の構成について

次章「EB ライブラリの特徴」では、EB ライブラリが対応している機能、対応していない機能について、簡単に説明します。また、ライブラリの概略に関して、最初に知っておいたほうが良いと思われる事柄をいくつか説明しています。

さらに次の章「プログラムのコンパイル方法」では、EB ライブラリを利用したプログラムのコンパイル方法を説明します。本書のサンプルプログラムをコンパイルするために必要な情報も、この章に記してあります。

そして、その次の章「ライブラリの初期化と後始末」からが、実際の EB ライブラリのプログラミングの解説となります。それぞれの章は、次のような節から構成されています。ただし、章によっては一部の節がない場合もあります。

解説: その章で解説する機能や概念についての基礎知識、EB ライブラリの仕様の概要について解説しています。
サンプルプログラム: 「解説」ではプログラムの断片だけを示すことが多いので、動作可能なプログラムのサンプルをここで示します。
データ型の詳細: データ型や関数、定数値などについての参照マニュアルです。

EB ライブラリの特徴

前に述べたように、EB ライブラリは、電子ブック (EB, EBG, EBXA, EBXA-C, S-EBXA) と EPWING 形式の CD-ROM 書籍に対応しています。

EB ライブラリは、これらの CD-ROM 書籍に対して、次の処理を行うことができます。

前方一致検索
後方一致検索
完全一致検索
条件検索
複合検索
見出しデータの取得
本文データの取得
メニューの取得
著作権表示の取得
カラー図版データの取得 (ただし EPWING のみ)
モノクロ図版データの取得
外字データの取得
動画データの取得

この章では、EB ライブラリの概要に関して、あらかじめ知っておいて頂いたほうが良いと思われるその他の事柄について、何点か説明します。

ヘッダファイル

EB ライブラリには、いくつかのヘッダファイルが用意されています。

appendix.h: appendix (付録) に関連した宣言、定義を行う。
binary.h: バイナリデータに関連した宣言、定義を行う。
eb.h: EB ライブラリの基本ヘッダファイル。
error.h: エラーコードに関連した宣言、定義を行う。
font.h: 外字に関連した宣言、定義を行う。
text.h: テキストデータ (本文、見出しなど) に関連した宣言、定義を行う。

これ以外にもいくつかのファイルがインストールされますが、上に挙げたヘッダファイルから読み込まれるもので、アプリケーションプログラムが直接読み込む必要はありません。

アプリケーションプログラムは、EB ライブラリを使う際にこのヘッダファイルをファイルの先頭付近で読み込みます。

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

eb.h ではなく、eb/eb.h を読み込むようにして下さい。

文字コード

EB ライブラリでは、CD-ROM 書籍内のデータを文字列にしてアプリケーションに渡す際の文字コードを規定しています。

EBG (海外の電子ブック) については、データが ISO 8859-1 (ラテン文字 1、ただし制御文字を除く) で書かれているため、データのやり取りも ISO 8859-1 で行います。ただし、外字だけは 2 バイトで表現し、0x0101 ～ 0x1efe の領域を使用します。 (外字領域の下位 16 ビットは 0x01 ～ 0xfe の範囲を使用します。)

EBG, EBXA-C を除いた電子ブック、および EPWING については、データが JIS X 0208 (日本語のかな漢字) で書かれており、JIS X 0208 を 0x2121 ～ 0x7e7e にマッピングし、0xa121 ～ 0xfe7e を外字領域にしています (下図)。

　　　　　　　　　　　　　　　　上位８ビット

　　　　　　　　　００　２１　　　　７ｅ　ａ１　　　　ｆｅ
　　　　　　　００┌──┬─────┬──┬─────┬┐
　　　　　　　　　│　　│　　　　　│　　│　　　　　││
　　　　　　　２１├──┼─────┼──┼─────┼┤
　　　　　　　　　│　　│　　　　　│　　│　　　　　││
　　　　　　　　　│　　│ＪＩＳ　Ｘ│　　│　外字　　││
　　　　　　　　　│　　│０２０８　│　　│　　　　　││
　　　　　　　　　│　　│　　　　　│　　│　　　　　││
　　　　　　　７ｅ├──┼─────┼──┼─────┼┤
下位８ビット　　　│　　│　　　　　│　　│　　　　　││
　　　　　　　ａ１├──┼─────┼──┼─────┼┤
　　　　　　　　　│　　│　　　　　│　　│　　　　　││
　　　　　　　　　│　　│　　　　　│　　│　　　　　││
　　　　　　　　　│　　│　　　　　│　　│　　　　　││
　　　　　　　　　│　　│　　　　　│　　│　　　　　││
　　　　　　　ｆｅ├──┼─────┼──┼─────┼┤
　　　　　　　　　└──┴─────┴──┴─────┴┘

EB ライブラリでは JIS X 0208 部分を日本語 EUC (EUC-JP) にエンコードして、アプリケーションとのやり取りも日本語 EUC で行います。したがって、JIS X 0208 部分は 0xa1a1 ～ 0xfefe にマッピングされます。

EBXA-C (中日・日中辞書の電子ブック) については、データが JIS X 0208 (日本語のかな漢字) と GB 2312 (中国語の簡体字) で書かれており、 JIS X 0208 を 0x2121 ～ 0x7e7e にマッピング、 GB 2312 を 0x21a1 ～ 0x7efe にマッピングし、 0xa121 ～ 0xfe7e を外字領域にしています (下図)。

　　　　　　　　　　　　　　　　上位８ビット

　　　　　　　　　００　２１　　　　７ｅ　ａ１　　　　ｆｅ
　　　　　　　００┌──┬─────┬──┬─────┬┐
　　　　　　　　　│　　│　　　　　│　　│　　　　　││
　　　　　　　２１├──┼─────┼──┼─────┼┤
　　　　　　　　　│　　│　　　　　│　　│　　　　　││
　　　　　　　　　│　　│ＪＩＳ　Ｘ│　　│　外字　　││
　　　　　　　　　│　　│０２０８　│　　│　　　　　││
　　　　　　　　　│　　│　　　　　│　　│　　　　　││
　　　　　　　７ｅ├──┼─────┼──┼─────┼┤
下位８ビット　　　│　　│　　　　　│　　│　　　　　││
　　　　　　　ａ１├──┼─────┼──┼─────┼┤
　　　　　　　　　│　　│　　　　　│　　│　　　　　││
　　　　　　　　　│　　│ＧＢ　　　│　　│　　　　　││
　　　　　　　　　│　　│２３１２　│　　│　　　　　││
　　　　　　　　　│　　│　　　　　│　　│　　　　　││
　　　　　　　ｆｅ├──┼─────┼──┼─────┼┤
　　　　　　　　　└──┴─────┴──┴─────┴┘

EB ライブラリでは、アプリケーションとのやり取りに使う文字コードは、日本語 EUC および中国語 EUC (EUC-ZH) です。したがって、そのままでは JIS X 0208 と GB 2312 が 0xa1a1 ～ 0xfefe にマッピングされ、衝突してしまいます。この問題をどう回避するのかは、アプリケーション側で決める必要があります (詳しくは、「フックと文字コードの関係」を参照のこと)。

電子ブック、EPWING ともに、外字については、アプリケーション側でどう扱うかを決める必要があります。外字について詳しくは「外字」を参照のこと。

圧縮された書籍について

EB ライブラは、データを圧縮して収録した書籍を扱うことができます。今のところ、次の 4 種類の圧縮方法に対応しています。

ebzip 圧縮形式: EB ライブラリ独自の圧縮形式です。付属の ebzip コマンドを使うと、この形式で圧縮した書籍を作れます。
EPWING V4, V5 形式: 市販の EPWING V4, V5 の書籍の一部に、この形式で圧縮したものがあります。
EPWING V6 形式: 市販の EPWING V6 の書籍の一部に、この形式で圧縮したものがあります。 EPWING V4, V5 形式の改良型です。
S-EBXA 形式: 市販の S-EBXA の書籍の一部に、この形式で圧縮したものがあります。

データの伸長は EB ライブラリ側で自動的に行われるため、アプリケーションプログラムからは、アクセスしている書籍が圧縮されているかどうか分かりません。アプリケーションプログラムは、書籍が圧縮されているかどうかで処理を変える必要はありません。

遠隔ホスト上の書籍について

バージョン 4.0 から、EB ライブラリは他のホストの書籍にアクセスできるようになりました。

遠隔アクセスの処理はすべて EB ライブラリ側で行われますので、アプリケーションプログラムは、書籍が自分のホスト上にあるかどうかで、 EB ライブラリの呼び出し手順を変える必要はありません。

ただし、他のホストからアクセスすると、処理速度は非常に遅くなります。そのため、効率良く処理できるよう、アプリケーションの処理方法を工夫すべき状況が生じることはあるかも知れません。

システムの要件

アプリケーションプログラムのコンパイルに用いるコンパイラには、 ANSI (ANSI X3.159-1989, ISO/IEC 9899-1990) 対応のものを対象としています。また、システムには POSIX.1 (IEEE Std. 1003.2-1990, ISO/IEC 9945-1:1990) 準拠ないし互換のものを対象としています。

永らく EB ライブラリでは、古いコンパイラや UNIX 系システムへの対応もそれなりに行われていましたが、バージョン 4.1 からは対応を打ち切っています。特に ANSI 対応のコンパイラは必須ですので、ご注意ください。

プログラムのコンパイル方法

本章では、EB ライブラリを利用したプログラムのコンパイルの仕方について、 2 通りの方法を説明します。

一つ目は、ごく私的な、小規模のプログラムをコンパイルする際に向いているてっとり早くコンパイルするための方法です。 EB ライブラリの使い方を覚える目的で簡単なプログラムを組む際は、こちらが良いでしょう。

二つ目は、EB ライブラリを組み込んだアプリケーションをフリーソフトウェアとしてリリースする際に向いている方法です。 EB ライブラリには、GNU Autoconf, Automake, Libtool を併用する仕組みを用意してありますので、これらを使ったコンパイル方法について説明します。

てっとり早いコンパイル方法

アプリケーションプログラムをコンパイルする際は、ヘッダファイルのディレクトリ位置を C コンパイラに教えてやる必要があるかも知れません。一般に UNIX の C コンパイラでは、-I オプションで位置を指定します。

cc -I/usr/local/include -c sample.c

/usr/local/include/eb ではなく、その一つ上を指定します (「ヘッダファイル」を参照のこと)。

次に、リンクして実行バイナリを生成する工程ですが、以下に記したライブラリの一部、もしくは全部をリンクします。括弧内は、ライブラリのファイル名です (ただし、.a や .so といった接尾子は省略)。

EB ライブラリ (libeb): EB ライブラリの本体です。このライブラリは必須です。
zlib (libz): 圧縮と伸長を行うライブラリです (詳しくは @url{http://www.gzip.org/zlib/})。 ebzip コマンドで圧縮した辞書を扱うために使います。このライブラリは必須です。 EB ライブラリのソースコードには zlib も収録されています。システムに zlib がインストールされていなければ、EB ライブラリをインストールする際に、zlib も自動的にインストールされます。
gettext ライブラリ (libintl): メッセージの国際化機能 (NLS) を提供するライブラリですメッセージの国際化機能を有効にして EB ライブラリをコンパイルしている場合は、必要になるかも知れません。 gettext の実装は何種類かありますが、EB ライブラリで使用できるのはメッセージカタログの形式が GNU gettext 互換のものだけです。メッセージの国際化機能を有効にしている場合でも、OS の標準 C ライブラリとして glibc を採用しているシステムでは、指定する必要はありません。
iconv ライブラリ: 文字コード変換のライブラリです。 gettext ライブラリをリンクする場合、一緒に必要となるかも知れません。 iconv の実装も何種類かあり、OS によっては最初から添付されています。

必要なライブラリファイルの名称を、C コンパイラに指定してやります。加えて、ファイルの置かれているディレクトリ位置を、C コンパイラに教える必要があるかも知れません。一般に UNIX の C コンパイラでは、-L オプションでディレクトリ位置を指定し、-l オプションでライブラリのファイル名を指定します。

cc sample.o -L/usr/local/lib -leb -lz -lintl -liconv

ただし、共有ライブラリをリンクする場合は、実行時におけるライブラリの検索パスも合わせて指定する必要があるかも知れません。

cc sample.o -R/usr/local/lib -L/usr/local/lib -leb -lz -lintl -liconv

C コンパイラの使い方に関しての詳細は、C コンパイラのマニュアルを参照して下さい。

Autoconf を併用したコンパイル方法

作業の前に、Autoconf, Automake, Libtool は、あらかじめインストールしておいて下さい。 Autoconf はバージョン 2.50 以降が必要です。

まず、アプリケーションプログラムの configure.ac (もしくは configure.in) に、次の行を加えます。

eb_LIB_EB4

マクロ eb_LIB_EB4 は、EB ライブラリの使用に必要な一切のチェックを行い、さらに configure に次のオプションを追加します。

  --with-eb-conf=FILE     eb.conf file is FILE [SYSCONFDIR/eb.conf]

eb.conf は、EB ライブラリをインストールしたときの情報を記録したファイルで、ライブラリと一緒にインストールされます。 eb_LIB_EB4 はこのファイルを読み込んで、C コンパイラに渡さなければいけないオプションなどの情報を得ます。 --eb-conf-file は、eb.conf のファイル名を明示的に指定するオプションです。

マクロ eb_LIB_EB4 は、eb4.m4 というファイルで提供されています。 EB ライブラリを /usr/local にインストールし、個々のファイルのインストール先を変更していなければ、/usr/local/share/aclocal にインストールされます。この eb4.m4 をソースコードの適当なディレクトリの下 (たとえば m4) にコピーして下さい。

aclocal コマンドで aclocal.m4 を再生成する際は、 -I オプションでマクロファイルのディレクトリを指定します。

aclocal -I m4

加えて、トップディレクトリの Makefile.am の中にも aclocal へ渡すオプションを書いておきます。

ACLOCAL_AMFLAGS = -I m4

また、ソースコードのディレクトリに Libtool パッケージがまだ用意されていなければ、用意します。 libtoolize コマンドを実行して下さい。 Libtool パッケージが、ソースコードのディレクトリにコピーされます。

libtoolize

最後に、コンパイルを行うディレクトリの Makefile.am ファイルの _LDFLAGS と INCLUDES に、次のような値を追加します。

program_LDFLAGS = $(EBCONF_EBLIBS) $(EBCONF_ZLIBLIBS) $(EBCONF_INTLLIBS)
INCLUDES = $(EBCONF_EBINCS)

(program_LDFLAGS の program のところは、アプリケーションプログラムの実際のコマンド名にします。)

EB ライブラリ本体のデバッグ

「自分が作ったアプリケーションが正しく動かないのは、ひょっとすると EB ライブラリのバグが原因ではないか?」という疑問を抱き、EB ライブラリの挙動を確認したいと思うことがあるかも知れません。

そのような場合は、環境変数 EB_DEBUG をセットした状態でアプリケーションを実行してみて下さい。 EB ライブラリは標準エラー出力に、次のようなログを (かなり大量ですが) 出力するようになります。

[EB] in: eb_set_font(book=0, font_code=0)
[EB] in: eb_load_narrow_font(book=0)
[EB] out: eb_load_narrow_font()
[EB] in: eb_load_wide_font(book=0)
[EB] out: eb_load_wide_font()
[EB] out: eb_set_font() = EB_SUCCESS

これらのログは、関数の呼び出し時の引数列、および関数からの戻り値を示しています。 ebfixlog という Perl5 スクリプトを使うと、ログを整形することができます。このスクリプトは、EB ライブラリのソースコードの misc ディレクトリに収められています。

ebfixlog は、コマンド行の引数として与えられたファイル (引数が指定されなければ標準入力) からメッセージデータを読み込み、次のように字下げして出力します。

[EB] in: eb_set_font(book=0, font_code=0)
[EB]   in: eb_load_narrow_font(book=0)
[EB]   out: eb_load_narrow_font()
[EB]   in: eb_load_wide_font(book=0)
[EB]   out: eb_load_wide_font()
[EB] out: eb_set_font() = EB_SUCCESS

通常 ebfixlog スクリプトは、zio および ebnet と呼ばれる、 EB ライブラリでファイル入出力を受け持つ処理部のログは読み捨てるようになっています。これにより、ログの量がかなり減ります。

zio は EB ライブラリの低レベル入出力の処理部で、頻繁に呼び出されます。問題の原因を調べる際も、まずは読み捨てた方がライブラリの内部動作を追跡しやすいでしょう。

ebfixlog の -z オプションを使うと、zio のメッセージを読み捨てずに出力するようになります。

ebnet は遠隔アクセスの入出力を処理する部分で、zio よりもさらに下位レベルに位置します。遠隔アクセスの挙動を追跡するとき以外は、読み捨てた方が良いと思います。

ebfixlog の -n オプションを使うと、ebnet, zio 両方のメッセージを読み捨てずに出力するようになります。

ライブラリの初期化と後始末

この章からは、EB ライブラリのプログラミングについての解説になります。

まず、アプリケーションプログラムから EB ライブラリを利用するには、最初にライブラリを初期化する必要があります。

ライブラリの初期化を行うには、eb_initialize_library() という関数を呼び出します。

if (eb_initialize_library() != EB_SUCCESS) {
    printf("eb_initialize_library() failed\n");
    exit(1);
}

同様に、ライブラリを使い終わったら、eb_finalize_library() という関数を呼び出して後始末をします。

eb_finalize_library();

サンプルプログラム

関数の詳細

この項で説明している関数を使うには、eb/eb.h を読み込んで下さい。

#include <eb/eb.h>

`EB_Error_Code eb_initialize_library ()`

関数 eb_initialize_library() は、EB ライブラリを初期化します。アプリケーションプログラムは、EB ライブラリの他の関数を呼ぶ前に、必ず一回だけこの関数を呼ぶ必要があります。

メッセージの国際化機能 (NLS) を有効にして EB ライブラリをコンパイルした場合、eb_initialize_library() は bindtextdomain() を呼び出します。したがって、アプリケーションプログラムが setlocale() を呼び出すのは、この関数を呼び出す前である必要があります。

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

ライブラリを初期化せずに、EB ライブラリの他の関数を呼んだ場合の動作は未定義です。また、すでに初期化を済ませた状態で、再度 eb_initialize_library() を呼んでもいけません。呼んだ場合の動作は未定義です。

`void eb_finalize_library ()`

関数 eb_finalize_library() は、EB ライブラリを使い終わった際の後始末を行います。ただし、アプリケーションプログラム側で使用した EB_Book、EB_Hookset、EB_Appendix オブジェクトの後始末は行いません。オブジェクトを後始末するには、それぞれ専用の関数 eb_finalize_book()、eb_finalize_hookset()、 eb_finalize_appendix() を各オブジェクトに対して別途呼んでやる必要があります。

ライブラリの後始末をした後は、EB ライブラリのいかなる関数も呼んではいけません。呼んだ場合の動作は未定義です。

CD-ROM 書籍と `EB_Book` オブジェクト

EB ライブラリでは、CD-ROM 書籍へのアクセスは、すべて EB_Book 型のオブジェクトを介して行います。したがって、ほとんどのアプリケーションプログラムは、本章で記述している処理を必要とするはずです。

本章では EB_Book オブジェクトの初期化、後始末といった基本的な取り扱い方について説明します。

`EB_Book` オブジェクト

CD-ROM 書籍へアクセスするには、まず EB_Book 型のオブジェクトを用意します。同時に複数の CD-ROM 書籍にアクセスするなら、書籍一冊毎にオブジェクトを作る必要があります。

EB_Book book;

もちろん、オブジェクトの領域は、malloc() で確保しても構いません。

EB_Book *book_pointer;

book_pointer = (EB_Book *) malloc(sizeof(EB_Book));

EB_Book オブジェクトの中身 (変数 book の中身および book_pointer の指す領域) はまだ初期化されていませんので、次の要領でオブジェクトを初期化します。

eb_initialize_book(&book);
eb_initialize_book(book_pointer);

eb_initialize() へ渡す引数は EB_Book オブジェクトへのポインタであって、EB_Book オブジェクトそのものではないことに注意して下さい。 (EB ライブラリの他の関数も、すべてオブジェクトをポインタで渡します。)

CD-ROM 書籍を使うには、続いて EB_Book オブジェクトを CD-ROM 書籍の実体に結び付けます。これは、関数 eb_bind() によって行います。

ＥＢ＿Ｂｏｏｋ　　　　　　　　　　　　ＣＤ－ＲＯＭ書籍
オブジェクト　　　　　　　　　　┌────────────┐
┌───┐　　　　　　　　　　　│　　　　　　　　　　　　│
│　　　┝━━━━━━━━━━━┥　／ｍｎｔ／ｃｄｒｏｍ　│
└───┘　ｅｂ＿ｂｉｎｄ（）　│　　　　　　　　　　　　│
　　　　　　　　　　　　　　　　└────────────┘

実際のプログラムでは、次のようにします。

if (eb_bind(&book, "/mnt/cdrom") != EB_SUCCESS) {
    printf("eb_bind() failed\n");
    return;
}

eb_bind() に渡す書籍のパス (この例では /mnt/cdrom) は書籍のトップディレクトリ、つまり catalog または catalogs ファイルのあるディレクトリを指定します。

EB_Book オブジェクトを使い終わったら、 eb_finalize_book() を呼んで後始末をします。オブジェクトは書籍との結び付きを解かれた状態に戻り、内部で割り当てられたメモリは解放され、開いていたファイルもすべて閉じられます。

eb_finalize_book(&book);
eb_finalize_book(book_pointer);

オブジェクトの領域を malloc() で確保した場合は、 eb_finalize_book() を呼んだ後ならば、オブジェクトの領域を安全に解放することができます。

free(book_pointer);

遠隔ホストへの `eb_bind()`

前節で説明した eb_bind() を用いて、EB_Book オブジェクトを遠隔ホストの書籍に結びつけることができます。これには、書籍のパスの代わりに、遠隔アクセス用の識別子を指定します。識別子は、次のような形式をとります。

ebnet://ホスト:ポート/書籍名

ホスト は遠隔ホストの IP アドレスもしくはホスト名です。ただし、IPv6 アドレスを指定する場合は、アドレスを [ と ] で囲む必要があります。 ポート は、そのホストが待ち受けているポートの番号です。ホストが待ち受けているポートが標準の 22010 番であれば、:ポート の部分は省略可能です。

以下に eb_bind() のコード例を記します。

if (eb_bind(&book, "ebnet://localhost/cdrom") != EB_SUCCESS) {
    printf("eb_bind() failed\n");
    return;
}

サンプルプログラム

このサンプルプログラムでは、CD-ROM 書籍の種類を調べるために、 eb_disc_code() という関数を使用しています。この関数については、「関数の詳細」を参照のこと。

データ型の詳細

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

#include <eb/eb.h>

`EB_Book` 型

EB_Book 型は、一冊の CD-ROM 書籍を表します。 CD-ROM 書籍へのアクセスは、すべてこの型のオブジェクトを介して行います。同時に複数の CD-ROM 書籍にアクセスする際は、書籍一冊毎にオブジェクトを作る必要があります。

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

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

`EB_Disc_Code` 型

データ型 EB_Disc_Code は、CD-ROM 書籍の形式コードを表します。現在のところ、次の値が定義されています。

EB_DISC_EB: 電子ブック (EB, EBG, EBXA, EBXA-C, S-EBXA) であることを表します。
EB_DISC_EPWING: EPWING であることを表します。
EB_DISC_INVALID: 不正な形式コード値を表します。

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

`EB_Character_Code` 型

データ型 EB_Character_Code は、CD-ROM 書籍で使用される文字コードを表します。現在のところ、次の値が定義されています。

EB_CHARCODE_ISO8859_1: ISO 8859-1 (ラテン文字 1) を使用していることを表します。電子ブックの EBG はこれです。
EB_CHARCODE_JISX0208: JIS X 0208 (日本語のかな漢字) を使用していることを表します。 EBG, EBXA-C 以外の電子ブック、および EPWING はすべてこれです。
EB_CHARCODE_JISX0208_GB2312: JIS X 0208 (日本語のかな漢字) と GB 2312 (中国語の簡体字) を併用していることを表します。電子ブックの EBXA-C はこれです。
EB_CHARCODE_INVALID: 不正な文字コード値を表します。

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

関数の詳細

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

#include <eb/eb.h>

`void eb_initialize_book (EB_Book *book)`

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

`EB_Error_Code eb_bind (EB_Book book, const char path)`

関数 eb_bind() は、book の指す EB_Book オブジェクトを、パス path にある CD-ROM 書籍に結び付けます。パスには、書籍のトップディレクトリか遠隔アクセス識別子を指定します。書籍のトップディレクトリとは、catalog あるいは catalogs ファイルの存在するディレクトリを指します。

オブジェクトがすでに書籍に結び付いていた場合、その書籍との結び付きを解いてから、path にある書籍に結び付けます。

成功すると、関数は EB_SUCCESS を返します。このとき、副本は未選択の状態になります。失敗すると、オブジェクトを書籍との結び付きを解かれた状態にして、原因を示すエラーコードを返します。

path は、EB_MAX_PATH_LENGTH バイトに収まていなくてはなりません。さらに、path が相対パスのときは、絶対パスに変換した結果がこの長さに収まっていなくてはなりません。これを超えると、EB_ERR_TOO_LONG_FILE_NAME を返します。

`void eb_finalize_book (EB_Book *book)`

関数 eb_finalize_book() は、book が指す EB_Book オブジェクトの後始末を行います。

オブジェクトが割り当てて管理していたメモリはすべて解放され、ファイルディスクリプタもすべて閉じられます。オブジェクトが書籍と結び付いていた場合は、結び付きが解かれます。

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

`int eb_is_bound (EB_Book *book)`

関数 eb_is_bound() は、book が書籍に結び付いているかどうかを調べます。結び付いていれば 1 を返し、そうでなければ 0 を返します。

`EB_Error_Code eb_path (EB_Book book const char path)`

関数 eb_path() は、book に結び付いている書籍のパスもしくは遠隔アクセス識別子を、path の指す領域に書き込みます。

成功すると、関数は EB_SUCCESS を返します。失敗すると、path の指す領域に空文字列を書き込み、原因を示すエラーコードを返します。

book は、あらかじめ書籍に結び付いている必要があります。結びついていない場合は、EB_ERR_UNBOUND_BOOK を返します。

path に書き込むパス名のバイト数は、最長で EB_MAX_PATH_LENGTH になります。この長さは、末尾のナル文字を含みません。関数が返すパスは正規化された形になっているので、eb_bind() に渡したときのものと同じとは限りません。たとえば、相対パスだった場合は、絶対パスに変換されます。

`EB_Error_Code eb_disc_type (EB_Book book, EB_Disc_Code disc_code)`

関数 eb_disc_type() は、book のディスクの形式を disc_code の指す領域に書き込みます。書き込むディスクの形式の値は、EB_Disc_Code 型 (「[CD-ROM 書籍と EB_Book オブジェクト] データ型の詳細」を参照のこと) のいずれかの定数値です。

成功すると、関数は EB_SUCCESS を返します。失敗すると、disc_code の指す領域に EB_DISC_INVALID を書き込み、原因を示すエラーコードを返します。

book は、あらかじめ書籍に結び付いていなければなりません。結びついていない場合は、EB_ERR_UNBOUND_BOOK を返します。

`EB_Error_Code eb_character_code (EB_Book book, EB_Character_Code character_code)`

関数 eb_character_code() は、book が書かれている文字コードを character_code の指す領域に書き込みます。書き込む文字コードの値は、EB_Character_Code 型 (「[CD-ROM 書籍と EB_Book オブジェクト] データ型の詳細」を参照のこと) のいずれかの定数値です。

成功すると、関数は EB_SUCCESS を返します。失敗すると、character_code の指す領域に EB_CHARCODE_INVALID を書き込み、原因を示すエラーコードを返します。

book は、あらかじめ書籍に結び付いていなければなりません。結びついていない場合は、EB_ERR_UNBOUND_BOOK を返します。

エラー処理

EB ライブラリの関数の呼び出しは、常に成功するとは限りません。たとえば、EB_Book オブジェクトを書籍に結びつける関数 eb_bind() には、引数として書籍のトップディレクトリを渡しますが、存在しないディレクトリを指定した場合、処理は失敗に終わります。

一般にこうした事象は、ユーザが誤ったパスを指定したときに起こりますが、メモリ不足のように、ユーザのミスが原因ではない失敗も起こりえます。

本章では、関数の呼び出しが失敗した場合の処理について説明します。

エラーコードとエラーメッセージ

EB ライブラリの関数の多くは、戻り値として EB_Error_Code 型の値を返します。処理が成功したときに返す値は EB_SUCCESS ですが、失敗したときはエラーの原因に応じて様々な値を返します。このため、EB ライブラリでは次のような EB_SUCCESS との比較処理がよく行われます。

EB_Error_Code error_code;

error_code = eb_bind(&book, "/mnt/cdrom");
if (error_code != EB_SUCCESS) {
    printf("eb_bind() failed\n");
    return;
}

エラーコードの値は、関数 eb_error_message() によってエラーメッセージに変換することもできます。こうすることで、エラーの原因をアプリケーションプログラムのユーザにもう少し分かりやすく伝えることができます。

error_code = eb_bind(&book, "/mnt/cdrom");
if (error_code != EB_SUCCESS) {
    printf("eb_bind() failed, %s\n",
        eb_error_message(error_code));
    return;
}

error_code が EB_ERR_TOO_LONG_FILENAME にセットされていれば、次のようなエラーメッセージが出力されます。

too long filename

あるいは、次のように日本語のメッセージかも知れません。

ファイル名が長すぎます

メッセージの国際化機能 (NLS) を無効にして EB ライブラリをコンパイルした場合は、常に英語のメッセージが返ります。有効にした場合は、ロケールの設定によってどちらの言語のメッセージが返るかが決まります。

本書ではプログラムを簡潔にするために、エラー処理は最低限しか行っていません。けれども一般のアプリケーションプログラムでは、関数の呼び出しが成功したかどうかを常にチェックし、処理が失敗した際はエラーメッセージを出力して、ユーザにエラーの原因を伝えるのが望ましいといえます。

エラーに対する寛容さ

EB_Book オブジェクトは、状態に関するパラメタをいくつか持っています。オブジェクトが CD-ROM 書籍に結び付いているかどうかも、こうしたパラメタのうちの一つです。

引数に EB_Book オブジェクトへのポインタを取る関数には、あらかじめオブジェクトの特定のパラメタがセットされていることを前提としているものもあります。たとえば、eb_path() は、オブジェクトが書籍に結び付いていることを前提としています。では、もしも書籍に結び付いていないオブジェクトを eb_path() に渡したらどうなるでしょうか。

EB_Book book;
EB_Error_Code error_code;
char path[EB_MAX_PATH_LENGTH + 1];

eb_initialize_library();
eb_initialize(&book);
error_code = eb_path(&book, path);    /* どうなる? */

この場合、eb_path() は EB_ERR_UNBOUND_BOOK を返します。 EB ライブラリの関数は、必要なパラメタがセットされていないオブジェクトを検知して拒絶します。

しかしながら、参照マニュアルで明示されている場合を除いて、EB ライブラリの関数は、与えられたポインタが NULL かどうかまでは調べません。次のようなことをすると、プログラムを異常終了させてしまいます。

eb_bind(NULL, "/mnt/cdrom");    /* 異常終了! */
eb_bind(&book, NULL);           /* これも異常終了! */

データ型の詳細

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

#include <eb/error.h>

`EB_Error_Code` 型

データ型 EB_Error_Code は、EB ライブラリのエラーコードを表します。この型は符合付き整数型の別名として定義されていますので、2 つのコードを 2 項演算子 == と != で一致比較することができます。

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

エラーコードの一覧

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

#include <eb/error.h>

定数 `EB_SUCCESS`

成功。エラーは起きていない。

定数 `EB_ERR_MEMORY_EXHAUSTED`

EB ライブラリが malloc() を呼び出したが、NULL が返ってきた。

定数 `EB_ERR_TOO_LONG_FILE_NAME`

与えられた書籍のパス名が長すぎる。

定数 `EB_ERR_BAD_FILE_NAME`

書籍のパス名が不正である。

定数 `EB_ERR_BAD_DIR_NAME`

ディレクトリ名が不正である。 (EB ライブラリの内部処理用なので、このエラーコードがアプリケーションプログラムに返ることはありません。)

定数 `EB_ERR_TOO_LONG_WORD`

与えられた検索語は長すぎる。

定数 `EB_ERR_BAD_WORD`

与えられた検索語に不正な文字が含まれている。

定数 `EB_ERR_EMPTY_WORD`

与えられた検索語は空である。

定数 `EB_ERR_FAIL_GETCWD`

getcwd() もしくは getwd() が失敗した。

定数 `EB_ERR_FAIL_OPEN_CAT`

EB ライブラリが、書籍のカタログファイルを開くことに失敗した。

定数 `EB_ERR_FAIL_OPEN_CATAPP`

EB ライブラリが、appendix のカタログファイルを開くことに失敗した。

定数 `EB_ERR_FAIL_OPEN_TEXT`

EB ライブラリが、書籍の本文ファイルを開くことに失敗した。

定数 `EB_ERR_FAIL_OPEN_FONT`

EB ライブラリが、書籍の外字ファイルを開くことに失敗した。

定数 `EB_ERR_FAIL_OPEN_APP`

EB ライブラリが、appendix ファイルを開くことに失敗した。

定数 `EB_ERR_FAIL_OPEN_BINARY`

EB ライブラリが、バイナリデータファイルを開くことに失敗した。

定数 `EB_ERR_FAIL_READ_CAT`

EB ライブラリが、書籍のカタログファイルを読み込むことに失敗した。

定数 `EB_ERR_FAIL_READ_CATAPP`

EB ライブラリが、appendix のカタログファイルを読み込むことに失敗した。

定数 `EB_ERR_FAIL_READ_TEXT`

EB ライブラリが、書籍の本文ファイルを読むことに失敗した。

定数 `EB_ERR_FAIL_READ_FONT`

EB ライブラリが、書籍の外字ファイルを読み込むことに失敗した。

定数 `EB_ERR_FAIL_READ_APP`

EB ライブラリが、appendix のメインファイルを読み込むことに失敗した。

定数 `EB_ERR_FAIL_READ_BINARY`

EB ライブラリが、書籍のバイナリデータファイルを読み込むことに失敗した。

定数 `EB_ERR_FAIL_SEEK_CAT`

EB ライブラリが、書籍のカタログファイルのシークに失敗した。

定数 `EB_ERR_FAIL_SEEK_CATAPP`

EB ライブラリが、appendix のカタログファイルのシークに失敗した。

定数 `EB_ERR_FAIL_SEEK_TEXT`

EB ライブラリが、書籍の本文ファイルのシークに失敗した。

定数 `EB_ERR_FAIL_SEEK_FONT`

EB ライブラリが、書籍の外字ファイルのシークに失敗した。

定数 `EB_ERR_FAIL_SEEK_APP`

EB ライブラリが、appendix のメインファイルのシークに失敗した。

定数 `EB_ERR_FAIL_SEEK_BINARY`

EB ライブラリが、書籍のバイナリデータファイルのシークに失敗した。

定数 `EB_ERR_UNEXP_CAT`

EB ライブラリが、書籍のカタログファイル内で、期待とは異なるデータ列を見つけた。

定数 `EB_ERR_UNEXP_CATAPP`

EB ライブラリが、appendix のカタログファイル内で、想定外のデータ列を見つけた。

定数 `EB_ERR_UNEXP_TEXT`

EB ライブラリが、書籍の本文ファイル内で、想定外のデータ列を見つけた。

定数 `EB_ERR_UNEXP_FONT`

EB ライブラリが、書籍の外字ファイル内で、想定外のデータ列を見つけた。

定数 `EB_ERR_UNEXP_APP`

EB ライブラリが、appendix のメインファイル内で、想定外のデータ列を見つけた。

定数 `EB_ERR_UNEXP_BINARY`

EB ライブラリが、書籍のバイナリデータファイル内で、想定外のデータ列を見つけた。

定数 `EB_ERR_UNBOUND_BOOK`

呼び出された EB ライブラリの関数は、書籍に結び付けられた EB_Book オブジェクトを引数にとるが、与えられたオブジェクトは書籍に結び付けられていなかった。

定数 `EB_ERR_UNBOUND_APP`

呼び出された EB ライブラリの関数は、appendix に結び付けられた EB_Appendix オブジェクトを引数にとるが、与えられたオブジェクトは appendix に結び付けられていなかった。

定数 `EB_ERR_NO_SUB`

書籍は副本を一つも持っていない。

定数 `EB_ERR_NO_APPSUB`

appendix は副本を一つも持っていない。

定数 `EB_ERR_NO_FONT`

選択中の副本は、外字を一種類も持っていない。

定数 `EB_ERR_NO_TEXT`

選択中の副本は、本文データを持っていない。

定数 `EB_ERR_NO_CUR_SUB`

呼び出された関数は、副本が選択されている EB_Book オブジェクトを引数としてとるが、与えられたオブジェクトでは選択されていなかった。

定数 `EB_ERR_NO_CUR_APPSUB`

呼び出された関数は、副本が選択されている EB_Appendix オブジェクトを引数にとるが、与えられたオブジェクトでは選択されていなかった。

定数 `EB_ERR_NO_CUR_FONT`

呼び出された関数は、外字が選択されている EB_Book オブジェクトを引数にとるが、与えられたオブジェクトでは選択されていなかった。

定数 `EB_ERR_NO_CUR_BINARY`

呼び出された関数は、バイナリデータの読み込み要求をセットしている EB_Book オブジェクトを引数にとるが、与えられたオブジェクトではセットされていなかった。

定数 `EB_ERR_NO_SUCH_SUB`

EB_Book オブジェクトと副本コードが関数に与えられたが、 EB_Book オブジェクトに結び付けられている書籍は、その副本コードに一致する副本を持っていない。

定数 `EB_ERR_NO_SUCH_APPSUB`

EB_Appendix オブジェクトと副本コードが関数に与えられたが、 EB_Appendix オブジェクトに結び付けられている appendix は、その副本コードに一致する副本を持っていない。

定数 `EB_ERR_NO_SUCH_FONT`

EB_Book オブジェクトと外字の縦のサイズが関数に与えられたが、 EB_Book オブジェクトに結びつけられていた書籍で選択中の副本は、そのサイズの外字を持っていない。

定数 `EB_ERR_NO_SUCH_CHAR_BMP`

EB_Book オブジェクトと文字番号が関数に与えられたが、 EB_Book オブジェクトに結び付けられていた書籍で選択中の副本は、その番号の外字のビットマップデータを持っていない。

定数 `EB_ERR_NO_SUCH_CHAR_TEXT`

EB_Appendix オブジェクトと文字番号が関数に与えられたが、 EB_Appendix オブジェクトに結び付けられている appendix で選択中の副本は、その番号の外字の代替文字列を持っていない。

定数 `EB_ERR_NO_SUCH_SEARCH`

選択中の副本は、指定された検索メソッドを持っていないので、検索は行えない。

定数 `EB_ERR_NO_SUCH_HOOK`

不正なフックコードが関数に渡された。

定数 `EB_ERR_NO_SUCH_BINARY`

指定された位置に、指定された形式のバイナリデータは存在しない。

定数 `EB_ERR_DIFF_CONTENT`

アプリケーションプログラムからテキストデータの取得を要求されたが、指定されたテキストデータの種類が、前回リクエストされたときと一致していない。

定数 `EB_ERR_NO_PREV_SEARCH`

eb_hit_list() が呼び出されたが、アプリケーションプログラムから前もって検索のリクエストがなされていない。

定数 `EB_ERR_NO_SUCH_MULTI_ID`

EB_Book オブジェクトと複合検索コードが関数に渡されたが、結び付けられた書籍で選択中の副本は、そのコードに一致する複合検索を持っていない。

定数 `EB_ERR_NO_SUCH_ENTRY_ID`

EB_Book オブジェクトと複合検索エントリコードが関数に渡されたが、結び付けられた書籍で選択中の副本は、そのエントリコードに一致する複合検索エントリを持っていない。

定数 `EB_ERR_TOO_MANY_WORDS`

アプリケーションプログラムから条件検索もしくは複合検索の検索をリクエストされたが、検索語の個数が多すぎる。

定数 `EB_ERR_NO_WORD`

アプリケーションプログラムから条件検索もしくは複合検索の検索をリクエストされたが、検索語がすべて空である。

定数 `EB_ERR_NO_CANDIDATES`

eb_multi_entry_candidates() が呼び出されたが、指定された複合検索エントリは、検索語の候補一覧データを持っていない。

定数 `EB_ERR_END_OF_CONTENT`

eb_forward_text() あるいは eb_backward_text() で本文の頭出しを行おうとしたが、すでに本文の末尾ないし先頭に達していて、それ以上先に進むことができなかった。

定数 `EB_ERR_NO_PREV_SEEK`

あらかじめ eb_seek_text() でシークを行っていない状態で、テキストデータの読み込みや頭出しを行おうとした。

定数 `EB_ERR_EBNET_UNSUPPORTED`

この EB ライブラリは、遠隔ホストへのアクセスには対応していない。

定数 `EB_ERR_EBNET_FAIL_CONNECT`

遠隔ホストへのアクセスを試みたが、サーバ (EBNETD) に接続できなかった。

定数 `EB_ERR_EBNET_SERVER_BUSY`

遠隔ホストへの接続を行ったが、書籍にアクセスしているクライアントの数がすでに上限に達しているため、その書籍を利用できなかった。

定数 `EB_ERR_EBNET_NO_PERMISSION`

遠隔ホストへの接続を行ったが、その書籍への利用権限がないため、サーバからアクセスを拒否された。

定数 `EB_ERR_UNBOUND_BOOKLIST`

呼び出された EB ライブラリの関数は、遠隔ホストに結び付けられた EB_BookList オブジェクトを引数にとるが、与えられたオブジェクトは遠隔ホストに結び付けられていなかった。

定数 `EB_ERR_NO_SUCH_BOOK`

EB_BookList オブジェクトと書籍の要素番号を関数に渡されたが、 EB_BookList に結び付けられた遠隔ホスト上には、その要素番号に該当する書籍は存在しない。

関数の詳細

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

#include <eb/error.h>

`const char *eb_error_string (EB_Error_Code error_code)`

関数 eb_error_string() は、エラーコード error_code を文字列に変換したものを返します。文字列の文字コードは、ASCII になります。たとえば、エラーコード値 EB_SUCCESS を渡すと文字列 "EB_SUCCESS" を返します。未知のエラーコードを渡したときは、"EB_ERR_UNKNOWN" を返します。

`const char *eb_error_message (EB_Error_Code error_code)`

関数 eb_error_message() は、エラーコード error_code に対応したメッセージを文字列にして返します。関数の返すメッセージは、英語か日本語になります。

国際化機能を有効にして EB ライブラリをコンパイルしていない場合は、常に英語のメッセージを返します。このときのメッセージの文字コードは、ASCII になります。

メッセージの国際化機能 (NLS) を有効にして EB ライブラリをコンパイルした場合は、ロケールの設定に応じてどちらの言語のメッセージを返すのかが決まります。また、GNU gettext バージョン 0.36 以降では iconv() と連携することにより、メッセージの文字コードもロケールに応じて変化します。 gettext が iconv() との連携を行わなければ、英語のメッセージは ASCII、日本語のメッセージは日本語 EUC になります。この関数の呼び出しによって、gettext のテキストドメインの設定は変化しません。

未知のエラーコードを渡したときに返すメッセージは、英語では "unknown error"、日本語では "未知のエラーです" になります。

副本

紙に印刷された本では別々の書籍になっているものでも、電子ブックや EPWING では 1 枚の CD-ROM にまとめることができます。

たとえば、ある CD-ROM 書籍は、国語辞書、英々辞典、百科事典という 3 つの (印刷された本で言うところの) 「書籍」を持っていることもあり得ます。紛らわしさを避けるために、EB ライブラリではここで言う「書籍」のことを副本 (subbook) と呼んでいます。

　　　ＣＤ－ＲＯＭ書籍
┌─────────────┐
│　副本０：　［国語辞典］　│
│　副本１：　［英々辞典］　│
│　副本２：　［百科事典］　│
└─────────────┘

CD-ROM 書籍では、それぞれの副本はそれ自体が独立した書籍になっています。また、副本のデータも、副本毎に別々のファイルに収められています。したがって、EB ライブラリでも、アプリケーションプログラムの主要な処理である単語の検索や本文データの取得などは、すべて副本単位で行うようになっています。

本章では、EB ライブラリでの副本の扱い方について説明します。

副本コード

EB ライブラリでは、それぞれの副本に対して副本コード (subbook code) を割り当てます。このコードは EB ライブラリが副本を識別するために用いますので、個々の副本コードは、書籍内で同じものがないようになっています。

以下のソースコードは、eb_subbook_list() という関数の使用例です。この関数は、書籍内のすべての副本の副本コードを取得することができます。

/* book が EB_Book のオブジェクトで、すでに
 * 書籍に結び付けられていると仮定しています。*/
EB_Subbook_Code sub_codes[EB_MAX_SUBBOOKS];
int sub_count;

if (eb_subbook_list(&book, sub_codes, &sub_count)
    != EB_SUCCESS) {
    printf("eb_subbook_list() failed\n");
    return;
}

eb_subbook_list() が成功すると、書籍内のすべての副本コードが配列 sub_codes[] に格納されます。配列の先頭の副本コードは sub_codes[0] と表され、次のコードは sub_codes[1]、という具合になります。副本の個数は、sub_count に格納されます。

個々の副本には、必ず題名が付けられています。先頭の副本 (sub_codes[0]) の題名は、次のようにして得ることができます。

char title[EB_MAX_TITLE_LENGTH + 1];

if (eb_subbook_title2(&book, sub_codes[0], title)
    != EB_SUCCESS) {
    printf("eb_subbook_title2() failed\n");
    return;
}

eb_subbook_title2() の呼び出しが成功すると、 title に題名を表す文字列が格納されます。

蛇足ですが、(副本ではなく) CD-ROM の題名を取得する関数はありません。なぜなら、題名を示すデータが CD-ROM の中には何処にもないからです。

選択中の副本

EB_Book オブジェクトは、結びつけられた CD-ROM 書籍の中の任意の副本から一つ選んで、選択中の副本 (current subbook) として指定することができます。複数の副本を、同時に選択することはできません。単語の検索や、本文データの取得など、ほとんどの操作は、選択中の副本に対してだけ行えます。

eb_bind() で EB_Book オブジェクトを書籍に結び付けた直後は、いずれの副本も選択されていない状態になっています。

ＥＢ＿Ｂｏｏｋ　　　　　　　　　ＣＤ－ＲＯＭ書籍
オブジェクト
┌────┐　　　　　　　┌─────────────┐
│選択中　│　　　　　　　│　副本０：　［国語辞典］　│
│の副本　│　　　　　　　│　副本１：　［英々辞典］　│
│＜なし＞│　　　　　　　│　副本２：　［百科事典］　│
└────┘　　　　　　　└─────────────┘

副本の選択を行うには、関数 eb_set_subbook() を使用します。 eb_set_subbook() は、引数として渡された副本コードにしたがって副本を選択します。以下は、先頭の副本 (sub_codes[0]) を選択する場合の例です。

/* book が EB_Book のオブジェクトで、すでに
 * 書籍に結び付けられていると仮定しています。*/
EB_Subbook_Code sub_codes[EB_MAX_SUBBOOKS];
int sub_count;

if (eb_subbook_list(&book, sub_codes, &sub_count)
    != EB_SUCCESS) {
    printf("eb_subbook_list() failed\n");
    return;
}
if (eb_set_subbook(&book, sub_codes[0]) != EB_SUCCESS) {
    printf("eb_subbook_list() failed\n");
    return;
}

成功すると、次のように副本が選択された状態になります。

ＥＢ＿Ｂｏｏｋ　　　　　　　　　ＣＤ－ＲＯＭ書籍
オブジェクト
┌────┐　　　　　　　┌─────────────┐
│選択中　│　　┏━━━━┿━副本０：　［国語辞典］　│
│の副本　│　　┃　　　　│　副本１：　［英々辞典］　│
│　＊━━┿━━┛　　　　│　副本２：　［百科事典］　│
└────┘　　　　　　　└─────────────┘

サンプルプログラム

データ型の詳細

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

#include <eb/eb.h>

`EB_Subbook_Code` 型

データ型 EB_Subbook_Code は副本コードを表します。一冊の書籍の中の副本は、それぞれ一意の副本コードを持っています。この型は符合付き整数型の別名として定義されていますので、2 つのコードを 2 項演算子 == と != で一致比較することができます。

また、不正な副本コード値を表す EB_SUBBOOK_INVALID という特別な副本コードが定義されています。利用可能な副本に対して、この副本コードが割り当てられることはありません。

関数の詳細

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

#include <eb/eb.h>

`EB_Error_Code eb_load_all_subbooks (EB_Book *book)`

関数 eb_load_all_subbooks() は、book 内のすべての副本を初期化します。通常、副本の初期化は、その副本が初めて選択されたときに自動的に行われますが、この関数は初期化を前倒しで行います。初期化の対象となるのは、この関数を呼び出した時点でまだ初期化していないすべての副本です。この関数は、スタンドアロンで動作するサーバアプリケーションなどで有効です。クライアントからの接続を受ける前にこの関数を呼ぶことで、副本の初期化のためにクライアントを待たせなくて済みます。

初期化の対象となったすべての副本の初期化に成功すれば、関数は EB_SUCCESS を返します。一冊でも初期化に失敗した場合は、残りの副本の初期化を諦め、原因を示すエラーコードを返します。

book は、あらかじめ書籍に結び付けられていなくてはなりません。結びついていない場合は、EB_ERR_UNBOUND_BOOK を返します。

この関数を呼び出すと、book は、副本を選択していない状態になります。

`EB_Error_Code eb_subbook_list (EB_Book book, EB_Subbook_Code subbook_list, int *subbook_count)`

関数 eb_subbook_list() は、book 内のすべて副本の副本コードを EB_Subbook_Code 型の配列にして、 subbook_list の指す領域に書き込みます。配列は、最大で EB_MAX_SUBBOOKS 個の要素を持ちます。加えて、書籍が収録している副本の個数を subbook_count の指す領域に書き込みます。

成功すると、関数は EB_SUCCESS を返します。失敗すると、subbook_count の指す領域に 0 を書き込み、原因を示すエラーコードを返します。

book は、あらかじめ書籍に結び付けられていなくてはなりません。結びついていない場合は、EB_ERR_UNBOUND_BOOK を返します。

`EB_Error_Code eb_subbook (EB_Book book, EB_Subbook_Code subbook_code)`

関数 eb_subbook() は、book が選択中の副本の副本コードを subbook_code の指す領域に書き込みます。

成功すると、関数は EB_SUCCESS を返します。失敗すると、subbook_code の指す領域に EB_SUBBOOK_INVALID を書き込み、原因を示すエラーコードを返します。

あらかじめ、book はいずれかの副本を選択していなくてはなりません。選択していない場合は、EB_ERR_NO_CUR_SUB を返します。

`EB_Error_Code eb_subbook_title (EB_Book book, char title)`

関数 eb_subbook_title() は、book が選択中の副本の題名を title の指す領域に文字列として書き込みます。題名の文字列の長さは、最長で EB_MAX_TITLE_LENGTH バイトです。この長さは、末尾のナル文字を含みません。

書籍の文字コード (「[CD-ROM 書籍と EB_Book オブジェクト] データ型の詳細」を参照のこと) が EB_CHARCODE_ISO8859_1 なら、題名を表す文字列は ISO 8859-1 になり、それ以外の文字コードなら日本語 EUC になります。

成功すると、関数は EB_SUCCESS を返します。失敗すると、title の指す領域に空文字列を書き込み、原因を示すエラーコードを返します。

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

`EB_Error_Code eb_subbook_title2 (EB_Book book, EB_Subbook_Code subbook_code, char title)`

eb_subbook_title() と似ていますが、選択中の副本ではなく、引数 subbook_code で指定された副本の題名を書き込む点が異なります。

book は副本を選択していなくても構いませんが、あらかじめ書籍に結び付けられていなければなりません。結びついていない場合は、EB_ERR_UNBOUND_BOOK を返します。

`EB_Error_Code eb_subbook_directory (EB_Book book, char directory)`

関数 eb_subbook_directory() は、book 内で現在選択中の副本のデータファイルを収めたディレクトリ名を、directory の指す領域に書き込みます。

ディレクトリ名の文字列の長さは、最長で EB_MAX_DIRECTORY_NAME_LENGTH バイトです。この長さに、末尾のナル文字は含みません。ディレクトリ名は ASCII の数字、英小文字、アンダースコアで構成されます。

成功すると、関数は EB_SUCCESS を返します。失敗すると、directory の指す領域に空文字列を書き込み、原因にを示すエラーコードを返します。

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

`EB_Error_Code eb_subbook_directory2 (EB_Book book, EB_Subbook_Code subbook_code, char directory)`

eb_subbook_directory() と似ていますが、選択中の副本ではなく、引数 subbook_code で指定された副本のディレクトリ名を書き込む点が異なります。

`EB_Error_Code eb_set_subbook (EB_Book *book, EB_Subbook_Code code)`

関数 eb_set_subbook() は、book の副本 code を選択します。すでに副本を選択していた場合は、いったん未選択の状態にしてから副本 subbook_code を選択します。

成功すると、関数は EB_SUCCESS を返します。このとき、外字は未選択の状態となり、検索、テキストデータの読み込み、バイナリデータの読み込みについての状態記録は、すべてリセットされます。失敗すると、副本を未選択の状態にして、原因を示すエラーコードを返します。

あらかじめ、book は書籍に結び付けられていなければなりません。結びついていない場合は、EB_ERR_UNBOUND_BOOK を返します。

`void eb_unset_subbook (EB_Book *book)`

関数 eb_unset_subbook() は、book が選択している副本を未選択の状態にします。 book が書籍に結び付いていないか、副本が選択されていない場合は、何もしません。

検索

CD-ROM 書籍において、検索は非常に重要な機能です。 EB ライブラリでは、次のような検索メソッドが利用できます。

前方一致検索 (word search)
後方一致検索 (end-word search)
完全一致検索 (exact-word search)
条件検索 (keyword search)
クロス検索 (cross search)
複合検索 (multi search)

ただし、すべての CD-ROM 書籍、すべての副本で、ここに挙げたすべての検索メソッドが利用可能なわけではありません。副本の中には、いずれの検索メソッドも提供しないものも存在します。

EB ライブラリでは、検索を行うことができるのは、選択中の副本に対してだけです。

この章では、それぞれの検索メソッドの簡単な説明と、EB ライブラリでの扱い方について説明します。

前方一致、後方一致、完全一致検索

前方一致、後方一致、完全一致検索は、いずれも一個の入力語に一致するエントリを探し出す検索メソッドです。

前方一致検索は、入力語と先頭部分が一致するエントリを検索します。たとえば、「江戸」という語は、「江戸」「江戸時代」「江戸っ子」といったエントリに一致します。

後方一致検索は、入力語と末尾が一致するエントリを検索します。たとえば、`bye' という語は、`bye'、`good bye'、`bye bye' といったエントリに一致します。

完全一致検索は、一個の検索語と完全に一致するエントリだけを検索します。

以下は、前方一致検索のプログラムの例です。選択中の副本の中から、先頭が librar で始まるエントリを探しています。

/* book が EB_Book のオブジェクトで、すでに
 * 書籍に結び付けられ、副本を選択中だと仮定しています。*/
#define MAX_HITS 50
EB_Hit hits[MAX_HITS];
int hit_count;

if (eb_search_word(&book, "librar") != EB_SUCCESS) {
    printf("eb_search_word() failed\n");
    return;
}
if (eb_hit_list(&book, MAX_HITS, hits, &hit_count)
    != EB_SUCCESS) {
    printf("eb_hit_list() failed\n");
    return;
}

eb_search_word() は前方一致検索をリクエストする関数です。この例では、librar という検索文字列を与えています。ただし、この関数は一致したエントリを返すことはしません。

一致したエントリの取得は、続く eb_hit_list() 関数を呼び出した際に行われます。 eb_hit_list() は一致したエントリの一覧を配列 hits[] の指す領域に書き込み、見つかった一致エントリの個数を &hit_count の指す領域に書き込みます。この例では、eb_hit_list() は最大で MAX_HITS (= 50) 個のエントリを探します。 (つまり、50 個見つかったら検索を止めます。)

もし、選択中の副本が英々辞典だとすると、少なくとも library と librarian という 2 つのエントリに関する情報が得られるでしょう。このとき、配列 hits[] は次のようになっています。 (ただし、library と librarian エントリの順序は、下の絵とは異なっているかも知れません。)

┌───────────┬───────────┬─
│　ｌｉｂｒａｒｉａｎ　│　　ｌｉｂｒａｒｙ　　│
└───────────┴───────────┴─
　　　ｈｉｔｓ［０］　　　　　ｈｉｔｓ［１］

hits[] の中身については、本章の後ろの節でもう少し詳しく説明します。

ここまでは前方一致検索を例にとりましたが、後方一致の場合は eb_search_word() の代わりに eb_search_endword() を呼ぶようにします。他はすべて同じです。

if (eb_search_endword(&book, "nalization") != EB_SUCCESS) {
    printf("eb_search_endword() failed\n");
    return;
}

完全一致の場合も同様です。 eb_search_exactword() を呼ぶようにする以外は、すべて同じです。

if (eb_search_exactword(&book, "library") != EB_SUCCESS) {
    printf("eb_search_exactword() failed\n");
    return;
}

条件検索

条件検索は、複数個の入力語にすべて一致するエントリを検索します。たとえば、英々辞典の条件検索では、入力語をすべて含んだ例文を検索するようになっているかも知れません。

以下は、条件検索で make, with という語の双方と一致するエントリを、選択中の副本の中から探し出すプログラムの断片です。

/* book が EB_Book のオブジェクトで、すでに
 * 書籍に結び付けられ、副本を選択中だと仮定しています。*/
static const char *keywords[3] = {"make", "with", NULL};

if (eb_search_word(&book, keywords) != EB_SUCCESS) {
    printf("eb_search_word() failed\n");
    return;
}

条件検索を行う関数は、eb_search_keyword() です。前方一致、後方一致、完全一致検索の関数と基本的に扱い方は一緒ですが、複数の入力語を受け付けるようになっています。関数には、入力語の文字列 (へのポインタ) を配列にしたものを渡します。配列の最後には NULL を置き、配列の終端を明示する必要がある点に注意して下さい。

前方一致、後方一致、完全一致検索と同様に、eb_search_keyword() も検索のリクエストを行うだけで、一致したエントリの取得は行いません。エントリの取得には、やはり同様に eb_hit_list() 関数を使います。

EB_Hit hits[MAX_HITS];
int hit_count;

if (eb_hit_list(&book, MAX_HITS, hits, &hit_count)
    != EB_SUCCESS) {
    printf("eb_hit_list() failed\n");
    return;
}

クロス検索

クロス検索は、条件検索の亜種とも言うべき検索メソッドです。 EPWING や電子ブックをみても、どういうルールで使い分けがなされているのか分からない程、両者は実によく似ています。

EB ライブラリでクロス検索を行う関数は eb_search_cross() ですが、使い方は条件検索の関数 eb_search_keyword() とまったく同じです。使い方の詳細は、「条件検索」をご覧下さい。

複合検索

複合検索は、条件検索と同じく、複数個の入力語にすべて一致するエントリを検索しますが、個々の入力語にあらかじめ題目が付けられています。

また、前方一致、後方一致、完全一致、条件検索はすべて、各副本につき一種類しかありませんが、複合検索だけは一つの副本の中で複数の種類が用意されていることがあります。たとえば、ある世界人名事典には、次のように人名検索用と頻出用語の検索用の 2 種類の複合検索が用意されているかも知れません。

(複合検索その 1: 人名を検索する)
    入力語 0: 国・地域
    入力語 1: 時代
    入力語 2: 性別
    入力語 3: キーワード
    入力語 4: キーワード

(複合検索その 2: 頻出用語を検索する)
    入力語 0: 用語
    入力語 1: キーワード
    入力語 2: キーワード

この例のように、個々の複合検索は、入力語の題目だけでなく、入力語の数もまちまちです。また、検索する際はすべての入力語を埋める必要はなく、少なくとも一個の入力語が空でなければ、検索は成功します。

副本内の複合検索は、種類毎に複合検索コード (multi search code) によって識別されます。関数 eb_multi_search_list() を使うと、選択中の副本で利用可能な複合検索の一覧が得られます。

/* book が EB_Book のオブジェクトで、すでに
 * 書籍に結び付けられ、副本を選択中だと仮定しています。*/
EB_Multi_Search_Code multi_codes[EB_MAX_MULTI_SEARCHES];
int multi_count;

if (eb_multi_search_list(&book, multi_codes, &multi_count)
    != EB_SUCCESS) {
    printf("eb_multi_search_list() failed\n");
    return;
}

この複合検索コードは、複合検索のための関数で必要となります。たとえば、eb_multi_title() は、指定した複合検索の題名 (例:「人名検索」「頻出用語検索」) を取得する関数ですが、このときの複合検索の指定には、複合検索コードを用います。以下の例では、一覧の先頭に載っている複合検索 (multi_codes[0]) を指定しています。

char title[EB_MAX_MULTI_TITLE_LENGTH + 1];

if (eb_multi_title(&book, multi_codes[0], title)
    != EB_SUCCESS) {
    printf("eb_multi_title() failed\n");
    return;
}

さらに関数によっては、複合検索コードに加えて、何番目の入力語かも指定してやる必要があります。たとえば、特定の入力語の題目を得る関数 eb_multi_entry_label() が、これに該当します。 0 番目の入力語 (つまり先頭の入力語) の題目を取得するには、次のようにします。

char label[EB_MAX_MULTI_LABEL_LENGTH + 1];

if (eb_multi_entry_label(&book, multi_code[0], 0, label)
    != EB_SUCCESS) {
    printf("eb_multi_entry_label() failed\n");
    return;
}

複合検索を行う関数は、eb_search_multi() です。使い方は条件検索とほぼ同じで、入力語の文字列を配列にしたものを引数として渡し、配列の最後には NULL を置いて下さい。埋められていない入力語のところには、空文字列を置きます。

eb_search_multi() も検索のリクエストを行うだけで、一致したエントリの取得は行いません。取得するには eb_hit_list() を使います。

EB_Hit hits[MAX_HITS];
int hit_count;

if (eb_hit_list(&book, MAX_HITS, hits, &hit_count)
    != EB_SUCCESS) {
    fprintf(stderr, "an error occurs.\n");
    return;
}

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

一致エントリの情報

eb_hit_list() は、リクエストされた検索 (前方一致、後方一致、完全一致、条件、複合) に一致したエントリの情報と見つかったエントリの個数を、それぞれ EB_Hit 型の配列領域および int 型の領域に書き込みます。

/* book が EB_Book のオブジェクトで、すでに書籍に結び付け
 * られ、副本を選択中だと仮定しています。*/
EB_Hit hits[MAX_HITS];
int hit_count;

if (eb_hit_list(&book, MAX_HITS, hits, &hit_count)
    != EB_SUCCESS) {
    fprintf(stderr, "an error occurs.\n");
    return;
}

EB_Hit 配列の個々の要素には、一致したエントリの見出し (heading) と本文 (text) の開始位置が書き込まれています。

　　　　　　　　　　　　　見出し
　　　　　　　　　　　　┌────────────┐
　ＥＢ＿Ｈｉｔ　　　┏━┿ｌｉｂｒａｒｉａｎ　ｎ．│
┌───────┐　┃　└────────────┘
│ｈｅａｄｉｎｇ┿━┛　　本文
│　　　　　　　│　　　┌────────────────────┐
│　　　ｔｅｘｔ┿━━━┿ｌｉｂｒａｒｉａｎ　　　　　　　　　　　│
└───────┘　　　│ｎ．（１）Ａ　ｐｅｒｓｏｎ　ｗｈｏ　ｉｓ│
　　　　　　　　　　　　│ａ　ｓｐｅｃｉａｌｉｓｔ　ｉｎ　　　　　│
　　　　　　　　　　　　│ｌｉｂｒａｒｙ　ｗｏｒｋ．（２）．．．　│
　　　　　　　　　　　　└────────────────────┘

見出しと本文についてのより詳しい解説と取得方法については、「テキストデータ」を参照のこと。

残っているエントリの取得

前に述べたように、eb_hit_list() を呼び出すときは、一致するエントリを最大で何個まで探すのかを引数で指定します。また、eb_hit_list() は処理が成功すると、実際に見つかったエントリの数をアプリケーションプログラムに教えます。

error_code = eb_hit_list(&book, MAX_HITS, hits, &hit_count);
if (error_code == EB_SUCCESS)
    printf("%d entries found\n", hit_count);

指定した最大個数よりも多くの一致エントリが副本に存在している場合は、 eb_hit_list() を繰り返し呼び出すことで、残りのエントリを取得することができます。

for (;;) {
    if (eb_hit_list(&book, MAX_HITS, hits, &hit_count)
        != EB_SUCCESS) {
        fprintf(stderr, "an error occurs.\n");
        return;
    }
    if (hit_count == 0)
        break;
    /* 取得した一致エントリの処理 */
}

一致エントリがもう残っていなければ、eb_hit_list() は &hit_count の指す領域に 0 を書き込んで、 EB_SUCCESS を返します。

ただし、途中で eb_hit_list() が失敗すると (EB_SUCCESS 以外の値を返すと)、検索リクエストに関する状態記録はリセットされるため、一致エントリの取得をそれ以上続けることはできません。

重複エントリの削除

eb_hit_list() を用いて一致したエントリを取得すると、中身が実質的に変わらないエントリが複数含まれていることがあります。 EB ライブラリは、こうした重複エントリの削除は行いません。必要なら、アプリケーション側で行うことになります。

重複を完璧に取り除くなら、以下のすべての条件に一致するエントリを重複エントリとみなし、二度目以降に出現したエントリを削除します。

エントリの指す本文の位置が同じ
エントリの指す見出しの文字列 (位置ではなく文字列そのもの) が同じ

(見出し文字列の取得方法については、「テキストデータ」を参照のこと。)

重複は、直前のエントリに対してのみ起こるとは限りません。たとえば、eb_hit_list() で一致エントリが 50 個得られた場合、最後の 50 個目は前方の 49 個と重複検査を行う必要があります。したがって、全体ではエントリ同士の比較を 1 + 2 + ... + 49 = 1225 回行うことになります。

書籍によっては重複エントリが取りきれない可能性もありますが、もう少し簡単な方法もいくつかあります。処理を簡単にする第一の方法は、重複エントリの判定条件を次のように変えることです。

エントリの指す本文の位置が同じ
エントリの指す見出しの文字列の位置が同じ

さらに処理を簡単にするには、直前の 1個のエントリに対してだけ重複検査を行うという方法もあります。これなら、50 個の一致エントリに対して、比較は 49 回で済みます。ただしこの方法は、書籍によってはまったく効果がありません。

サンプルプログラム

データ型の詳細

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

#include <eb/eb.h>

`EB_Hit` 型

EB_Hit は、検索に一致したエントリの情報を格納するためのデータ型です。内部構造は、次のように定義されています。

typedef struct EB_Hit_Struct EB_Hit;

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

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

`EB_Position` 型

データ型 EB_Position は、副本のデータの位置を表します。内部構造は、次のように定義されています。

typedef struct EB_Position_Struct EB_Position;

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

ページ番号は 1 から始まり、ページ内のオフセットは 0 ～ 2047 の範囲となります。ただし、アプリケーションプログラムを作成する上で、このことを覚えておく必要はありません。

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

`EB_Multi_Search_Code` 型

データ型 EB_Multi_Search_Code は複合検索コードを表します。副本に用意されている複合検索は、それぞれ一意の複合検索コードを持っています。この型は符合付き整数型の別名として定義されていますので、2 つのコードを 2 項演算子 == と != で一致比較することができます。

また、不正な複合検索コード値を表す EB_MULTI_INVALID という特別な副本コードが定義されています。利用可能な複合検索に対して、この複合検索コードが割り当てられることはありません。

関数の詳細

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

#include <eb/eb.h>

`int eb_have_word_search (EB_Book *book)`

`int eb_have_endword_search (EB_Book *book)`

`int eb_have_exactword_search (EB_Book *book)`

関数 eb_have_word_search() は、book が選択中の副本で前方一致検索メソッドが利用可能どうかを調べます。同様に eb_have_endword_search() は後方一致検索メソッドについて、eb_have_exactword_search() は完全一致検索メソッドについて利用可能どうかを調べます。

利用可能なら 1 を返します。メソッドを持っていないか、そもそも副本が選択されていない場合は 0 を返します。

`int eb_have_keyword_search (EB_Book *book)`

関数 eb_have_keyword_search() は、book が選択中の副本で条件検索メソッドが利用可能どうかを調べます。

利用可能なら 1 を返します。メソッドを持っていないか、そもそも副本が選択されていない場合は 0 を返します。

`int eb_have_multi_search (EB_Book *book)`

関数 eb_have_multi_search() は、book が選択中の副本で複合検索メソッドが利用可能どうかを調べます。

最低 1 種類でも利用可能なら 1 を返します。メソッドを持っていないか、そもそも副本が選択されていない場合は 0 を返します。

`EB_Error_Code eb_multi_search_list (EB_Book book, EB_Multi_Search_Code multi_list, int *multi_count)`

関数 eb_multi_search_list() は、book が選択中の副本に用意されている複合検索を調べ、複合検索コードの一覧を EB_Multi_Search_Code 型の配列にして、multi_list の指す領域に書き込みます。配列は、最大で EB_MAX_MULTI_SEARCHES 個の要素を持ちます。加えて、複合検索の種類数を multi_count の指す領域に書き込みます。

成功すると、関数は EB_SUCCESS を返します。失敗すると、subbook_count の指す領域に 0 を書き込み、原因を示すエラーコードを返します。

あらかじめ、book はいずれかの副本を選択していなくてはなりません。選択していない場合は、EB_ERR_NO_CUR_SUB を返します。

`EB_Error_Code eb_multi_entry_count (EB_Book book, EB_Multi_Search_Code multi_id, int entry_count)`

関数 eb_multi_search_list() は、book が選択中の副本に用意されている複合検索 multi_id について調べ、入力語の個数を entry_count の指す領域に書き込みます。

成功すると、関数は EB_SUCCESS を返します。このとき書き込まれる入力語の個数は、1 以上 EB_MAX_MULTI_ENTRIES 以下になります。失敗すると、entry_count の指す領域には 0 を書き込み、原因を示すエラーコードを返します。

あらかじめ、book はいずれかの副本を選択していなくてはなりません。選択していない場合は、EB_ERR_NO_CUR_SUB を返します。

`EB_Error_Code eb_multi_title (EB_Book book, EB_Multi_Search_Code multi_id, char title)`

関数 eb_multi_search_list() は、book が選択中の副本に用意されている複合検索 multi_id の題名を title の指す領域に書き込みます。題目は最長で EB_MAX_MULTI_TITLE_LENGTH バイトになります。この長さに、ナル文字は含みません。

書籍の文字コード (「[CD-ROM 書籍と EB_Book オブジェクト] データ型の詳細」を参照のこと) が EB_CHARCODE_ISO8859_1 なら、題目を表す文字列は ISO 8859-1 になり、それ以外の文字コードなら日本語 EUC になります。

書籍によっては、複合検索は用意していても、複合検索の題名データを持っていないことがあります。その場合、EB ライブラリが代わりに付けた題名が title に書き込まれます。

書籍の文字コードが EB_CHARCODE_ISO8859_1 なら、 EB ライブラリが付ける題名は、"Multi Search 1", "Multi Search 2", ... になります。それ以外の文字コードであれば、題名は日本語 EUC で書かれた「複合検索 1」「複合検索 2」... という文字列になります。

成功すると、関数は EB_SUCCESS を返します。失敗すると、label の指す領域には空文字列を書き込み、原因を示すエラーコードを返します。

あらかじめ、book はいずれかの副本を選択していなくてはなりません。選択していない場合は、EB_ERR_NO_CUR_SUB を返します。

`EB_Error_Code eb_multi_entry_label (EB_Book book, EB_Multi_Search_Code multi_id, int entry_index, char label)`

関数 eb_multi_search_list() は、book が選択中の副本に用意されている複合検索 multi_id について調べ、 entry_index 番目の検索語の題目を label の指す領域に書き込みます。 entry_index は、先頭の検索語を 0 番目と数えます。題目は最長で EB_MAX_MULTI_LABEL_LENGTH バイトになります。この長さに、ナル文字は含みません。

成功すると、関数は EB_SUCCESS を返します。失敗すると、label の指す領域には空文字列を書き込み、原因を示すエラーコードを返します。

あらかじめ、book はいずれかの副本を選択していなくてはなりません。選択していない場合は、EB_ERR_NO_CUR_SUB を返します。

`int eb_multi_entry_have_candidates (EB_Book *book, EB_Multi_Search_Code multi_id, int entry_index)`

関数 eb_multi_search_list() は、book が選択中の副本に用意されている複合検索 multi_id について調べ、 entry_index 番目の検索語が候補一覧を持っているかどうか調べます。 entry_index は、先頭の検索語を 0 番目と数えます。

持っていれば 1 を返します。持っていないか、そもそも副本が選択されていない場合、あるいは multi_id, や entry_index が不正な値だった場合は 0 を返します。

`EB_Error_Code eb_multi_entry_candidates (EB_Book book, EB_Multi_Search_Code multi_id, int entry_index, EB_Position position)`

関数 eb_multi_search_list() は、book が選択中の副本に用意されている複合検索 multi_id について調べ、 entry_index 番目の検索語の候補一覧の位置を position の指す領域に書き込みます。先頭の検索語が 0 番目になります。

成功すると、関数は EB_SUCCESS を返します。失敗すると、positin の指す領域には eb_seek_text() が必ず失敗する位置情報を書き込み、原因を示すエラーコードを返します。

あらかじめ、book はいずれかの副本を選択していなくてはなりません。選択していない場合は、EB_ERR_NO_CUR_SUB を返します。

`EB_Error_Code eb_search_word (EB_Book book, const char input_word)`

`EB_Error_Code eb_search_endword (EB_Book book, const char input_word)`

`EB_Error_Code eb_search_exactword (EB_Book book, const char input_word)`

関数 eb_search_word() は、book が選択中の副本に対する前方一致検索をリクエストします。同様に eb_search_endword() は後方一致検索を、 eb_search_exactword() は完全一致検索をリクエストします。

検索する語は、引数 input_word で指定します。ただし、これらの関数は検索をリクエストするだけで、一致したエントリの情報を返すことはしません。一致したエントリの取得には eb_hit_list() を使います。関数は、成功すると EB_SUCCESS を返します。失敗すると、原因を示すエラーコードを返します。失敗すると、関数を呼び出す前にリクエストしていた検索の状態記録はリセットされますので、その状態のまま eb_hit_list() を呼び出しても、やはり失敗に終わります。

書籍の文字コード (「[CD-ROM 書籍と EB_Book オブジェクト] データ型の詳細」を参照のこと) が EB_CHARCODE_ISO8859_1 なら、関数に渡す検索語は ISO 8859-1 で書かれていなければなりません。それ以外の文字コードの場合は、日本語 EUC で書かれていなければなりません。不正な文字番号を含んでいた場合、関数は EB_ERR_BAD_WORD を返します。

加えて、検索語は 1 バイト以上、EB_MAX_WORD_LENGTH (= 255) バイト以下でなければなりません。この長さに、ナル文字は含みません。長すぎる場合は、EB_ERR_TOO_LONG_WORD を、長さが 0 (空文字列) の場合は EB_ERR_EMPTY_WORD を返します。

あらかじめ、book はいずれかの副本を選択していなくてはなりません。選択していない場合は、EB_ERR_NO_CUR_SUB を返します。なお、一致するエントリが最低 1 個あるかどうかは、戻り値には影響しません。

`EB_Error_Code eb_search_keyword (EB_Book book, const char const input_words[])`

`EB_Error_Code eb_search_cross (EB_Book book, const char const input_words[])`

`EB_Error_Code eb_search_multi (EB_Book book, EB_Multi_Search_Code multi_id, const char const input_words[])`

関数 eb_search_keyword() は、book が選択中の副本に対する条件検索をリクエストします。同様に eb_search_cross() はクロス検索を、 eb_search_multi() は複合検索をそれぞれリクエストします。

検索する語は、引数 input_words で指定します。条件検索と複合検索はいずれも複数個の検索語を受け付けますので、検索語を配列にして渡します。このとき、配列の末尾の要素には NULL を置き、配列の終端を明示します。

いずれの関数も検索をリクエストするだけで、一致したエントリの情報を返すことはしません。一致したエントリの取得には eb_hit_list() を使います。関数は、成功すると EB_SUCCESS を返します。失敗すると、原因を示すエラーコードを返します。失敗すると、関数を呼び出す前にリクエストしていた検索の状態記録はリセットされますので、その状態のまま eb_hit_list() を呼び出しても、やはり失敗に終わります。

加えて、個々の検索語は EB_MAX_WORD_LENGTH (= 255) バイト以下でなければなりません。この長さに、ナル文字は含みません。長すぎる場合は、EB_ERR_TOO_LONG_WORD を返します。長さが 0 バイトの検索語は無視されますが、少なくとも 1 個の検索語は長さが 1 以上ないといけません。長さが 1 以上の検索語が 1 つもないときは、EB_ERR_NO_WORD を返します。

末尾の NULL を除いた配列の要素数は、条件検索では EB_MAX_KEYWORDS 以下、クロス検索では EB_MAX_CROSS_ENTRIES 以下、複合検索では EB_MAX_MULTI_ENTRIES 以下でなくてはなりません。個数が多すぎると EB_ERRO_TOO_MANY_WORDS を返します。空文字列の要素を差し引いた個数ではなく、単純に渡された要素数が上限を超えているとエラーになりますので、注意が必要です。

`EB_Error_Code eb_hit_list (EB_Book book, int max_hit_count, EB_Hit hit_list, int *hit_count)`

関数 eb_hit_list() は、あらかじめ以下のいずれかの関数でリクエストされた検索を実行し、一致したエントリを取得します。

eb_search_word() (前方一致検索)
eb_search_endword() (後方一致検索)
eb_search_exactword() (完全一致検索)
eb_search_keyword() (条件検索)
eb_search_cross() (クロス検索)
eb_search_multi() (複合検索)

したがって、この関数を呼ぶ前に、上記のいずれかの関数の呼び出しに成功していなくてはなりません。

eb_hit_list() は最大で max_hit_count 個の一致エントリを hit_list に書き込みます。そして、書き込んだ一致エントリの数を hit_count が指す領域に書き込みます。それ以上の個数の一致エントリが存在する場合、残ったエントリの情報は、この関数を繰り返し呼び出すことで得ることができます。

ただし、以下に挙げた関数を呼び出すと、リクエストした検索に関する状態記録がリセットされますので、一致したエントリの取得は継続できなくなります。

eb_set_subbook()
eb_unset_subbook()
eb_load_all_subbooks()
eb_bind()
eb_finalize_book()
eb_search_word()
eb_search_endword()
eb_search_exactword()
eb_search_keyword()
eb_search_cross()
eb_search_multi()

繰り返し呼んだ場合も、一致したエントリの情報はその都度 hit_list の先頭から書き込み、hit_count が指す領域に書き込む値も、その回の eb_hit_list() の呼び出しで書き込んだ一致エントリの数になります。

成功すると、この関数は EB_SUCCESS を返します。たとえ一致したエントリがなくても、処理が正常に終了すれば、関数は EB_SUCCESS を返します。

失敗すると、hit_count が指す領域に 0 を書き込み、原因を示すエラーコードを返します。この場合、リクエストしていた検索の状態記録はリセットされますので、これ以上 eb_hit_list() を呼んで、残った一致エントリを取得することはできなくなります。

あらかじめ、book はいずれかの副本を選択していなくてはなりません。選択していない場合は、EB_ERR_NO_CUR_SUB を返します。また、先に挙げた検索のリクエストが成功していない状態でこの関数を呼ぶと、 EB_ERR_NO_PREV_SEARCH を返します。

テキストデータ

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

ここで言うテキストデータ (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 ライブラリが確実に区切りを判別できますので、誤判定の問題は起きません。

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

サンプルプログラム

データ型の詳細

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

#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 を返します。失敗すると、シークが必ず失敗する位置を書き込み、原因を示すエラーコードを返します。

`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 が保存しているデータの長さが max_text_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 を返し、失敗すると原因を示すエラーコードを返します。

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

外字

文字コードに収録されていない、私的に定義した文字のことを、俗に「外字」と言います。外字として定義した個々の文字を識別するために、文字コードに収録された文字とは重複しない位置に、各文字の文字番号に割り振るのが普通です。 (割り当てる文字番号の詳細については、「文字コード」を参照のこと。)

市販の電子ブック、EPWING でも、ほとんどが外字を使っています。外字の定義状況は書籍同士でバラバラで、まったく統一感はありません。つまり、同じ文字番号を使っていても、定義されている外字は書籍によって違います。外字は副本毎に定義することが可能ですが、一つの CD-ROM 書籍内でも副本によって定義が異なることも珍しくありません。副本によっては、数百から数千の外字を定義していることもあります。

CD-ROM 書籍では、定義した外字の字形データ (つまりフォント) を用意しています。フォントはビットマップデータであり、書籍によっては大きさの異なる数種類のフォントを用意しています。

逆に言えば、外字に対して提供されるデータは、フォントだけです。ある文字番号を割り当てられた外字が、漢字なのか、発音記号なのか、そういった補助的な情報は用意されていません。アプリケーションプログラムが外字をサポートするためには、外字のフォントをそのまま表示する以外に方法はないでしょう。

半角外字と全角外字

CD-ROM 書籍における外字には、「全角外字」「半角外字」の二種類があります。全角外字は用意されているフォントの横と縦の長さがおよそ 1:1 になっており、半角外字では 1:2 になっています。

　　　　　　全角外字　　　　　　　　　　半角外字　　
　　　　（１６×１６）　　　　　　　　（８×１６）
□□□□□□□□□□□□□□□□　　□□□□□□□□
□□□□□□□□□□□□□□□□　　□□■■□■□□
□□□■■■■■■□□□■□□□　　□□□□■□□□
□□□□□□□□■□■□■□□□　　□□□■■□□□
□□□□■□□■□□■□■□□□　　□□■□□■□□
□□□□■□□■■■■■■□□□　　□■□□□■□□
□□■■■■■□□□■□■□□□　　□□□■□■□□
□□□□□□□□□□■□■□□□　　□□■□■■□□
□□□■□□□□□□□□■□□□　　□■□□□■□□
□□□■□□□□□□□□■□□□　　□■□□□■□□
□□□■■■■■■■■■■□□□　　□■□□□■□□
□□□■□□□□□□□□■□□□　　□■□□□■□□
□□□■□□□□□□□□■□□□　　□■□□□■□□
□□□■■■■■■■■■■□□□　　□■□□□■□□
□□□□□□□□□□□□□□□□　　□□■■■□□□
□□□□□□□□□□□□□□□□　　□□□□□□□□

テキストデータには、半角表示の開始と終了を表すエスケープシーケンスがあり (「テキストデータの内部形式」を参照のこと)、開始と終了の間に置かれたものは半角外字、それ以外のところなら全角外字になります。

文字番号は同じでも、字形が全角と半角ではまったく異なることもありますので、外字の文字番号だけから、全角と半角のどちらかを判断することはできません。かならず、前方に半角開始のエスケープシーケンスが出現していたかどうかという情報に基づいて判断しないといけません。

ただし、全角か半角かの判定は EB ライブラリ側で行いますので、アプリケーションプログラムが文脈の解析を行う必要はありません。

CD-ROM 書籍の副本には、半角外字あるいは全角外字のどちらか一方だけを定義しているものもありますし、両方とも定義しているものもあります。

外字の大きさと外字コード

各副本には、定義している外字のフォントがビットマップ形式で収録されています。フォントの大きさは、縦のピクセル数を基準にすると 16, 24, 30, 48 の 4 種類があり、全角外字、半角外字それぞれのフォントの大きさ (横のピクセル数×縦のピクセル数) は次の通りになります。

縦のピクセル数	全角全角	半角外字
16	16x16	8x16
24	24x24	16x24
30	32x30	16x30
48	48x48	24x48

ただし、すべての副本でこれら 4 種類のフォントを用意しているわけではありません。縦が 16 ピクセルのものは必ず用意されていますが、それ以外はないことも珍しくありません。 (外字がまったく定義されていなければ、16 ピクセルのフォントも用意されません。)

EB ライブラリでは、このように縦方向のピクセル数、つまりフォントの高さ (font height) を基準に、外字フォントの大きさを区別しています。そして、それぞれのフォントの高さ (16, 24, 30, 48) に対して、外字コード (font code) というものを割り当てています。フォントの高さを指定する際は、必ずこの外字コードを使います。

縦のピクセル数	外字コード
16	`EB_FONT_16`
24	`EB_FONT_24`
30	`EB_FONT_30`
48	`EB_FONT_48`

選択中の外字フォントの高さ

EB_Book オブジェクトで選択中の副本が用意している外字フォントの高さの中から一つ選んで、選択中の外字フォントの高さ (current font height) として指定することができます。 EB ライブラリで外字のフォントデータ (ビットマップデータ) を取り出すには、外字フォントの高さをあらかじめ選択しておく必要があります。

選択するには、関数 eb_set_font() を使います。以下のプログラムは、高さ 24 ピクセルのフォントを選択する場合の例です。

/* book が EB_Book のオブジェクトで、すでに
 * 書籍に結び付けられ、副本を選択中だと仮定しています。*/
if (eb_set_font(&book, EB_FONT_24) != EB_SUCCESS) {
    printf("eb_set_font_() failed\n");
    return;
}

このプログラムでは、高さ 24 ピクセルのフォントを選択中の副本が用意しているものと仮定していますが、実際には用意していない副本も珍しくありません。もし、副本が高さ 24 ピクセルのフォントを用意していなければ、 eb_set_font() は EB_ERR_NO_SUCH_FONT を返します。

しかし、外字を選択する前に、前もってその副本が用意しているフォントを知りたいときもあります。これには、2 通りの方法があります。

まず 1 つ目は、選択中の副本が用意しているフォントの高さの一覧を eb_font_list() で取得する方法です。これは、副本コードの一覧を取得する eb_subbook_list() と使い方が良く似ています。

EB_Font_Code font_list[EB_MAX_FONTS];
int font_count;
int i;

if (eb_font_list(&book, font_list, &font_count) != EB_SUCCESS) {
    printf("eb_font_list() failed\n");
    return;
}

for (i = 0; i < font_count; i++) {
    if (font_list[i] == EB_FONT_24)
        printf("this subbook has EB_FONT_24\n");
}

2 つ目は、eb_have_font() を使うやり方です。この関数は、特定の高さのフォントを、選択中の副本が用意しているかどうか調べることができます。

if (eb_have_font(&book, EB_FONT_24)) {
    printf("this subbook has EB_FONT_24\n");
}

また、選択中の副本が半角外字、全角外字を定義しているかどうかは、それぞれ eb_have_narrow_font(), eb_have_wide_font() を使って調べることができます。

if (eb_have_narrow_font(&book))
    printf("this subbook has narrow font\n");
if (eb_have_wide_font(&book))
    printf("this subbook has wide font\n");

なお、あらかじめ副本を選択しておかないと、外字の高さは選択できないので注意して下さい。 eb_set_subbook() で選択中の副本を切り替えると、外字フォントの高さは常に未選択の状態に戻ります。

外字フォントの取り出し

外字の高さを選択した状態であれば、外字のフォントデータ (ビットマップデータ) を取り出すことができます。

フォントデータを取り出す関数は、全角外字なら eb_wide_font_character_bitmap()、半角外字なら eb_narrow_font_character_bitmap() です。

全角外字 0xa121 のフォントデータを取り出すプログラムは、次のようになります。半角外字の場合は、呼び出す関数名が変わるだけです。

/* book が EB_Book のオブジェクトで、すでに
 * 書籍に結び付けられ、副本と外字の高さを選択中だと仮定しています。*/
char bitmap[EB_SIZE_WIDE_FONT_48];

if (eb_wide_font_character_bitmap(book, 0xa121, bitmap)
    != EB_SUCCESS) {
    return;
}

ここでは、bitmap にフォントデータを格納しています。 bitmap の領域として EB_SIZE_WIDE_FONT_48 バイトを確保していますが、これは高さ 48 ピクセルの外字データを格納するために必要なサイズを表します。

フォントデータのサイズは、外字の高さに応じて一定です。高さ 48 ピクセルは外字の中でも最大のサイズなので、このサイズの領域を用意すれば、どの高さの外字でも格納できます。

外字データは、ビットマップ形式のデータになっています。背景色をビット値 0, 前景色をビット値 1 として、各ピクセルの値を並べてあります。並び方ですが、左上からまずは右に向かってピクセルを拾っていき、左端まで来たら一つ下の段に降りて、また右方向にピクセルを拾います。以下、一番下の段までこれを繰り返します。

ただし、バイト内では、128, 64, 32, ...1 の桁の順にビット値を格納しています。つまり、128 の桁は一番左のピクセル、1 の桁は一番右のピクセルに対応します。

以下に、16x16 の全角外字のビットマップの例と、そのバイト列を記します。背景色が□、前景色が■です。

□□□□□□□□□□□□□□□□　　0x00, 0x00,
□□□□□□□□□□□□□□□□　　0x00, 0x00,
□□□■■■■■■□□□■□□□　　0x1f, 0x88,
□□□□□□□□■□■□■□□□　　0x00, 0xc8,
□□□□■□□■□□■□■□□□　　0x09, 0x28,
□□□□■□□■■■■■■□□□　　0x09, 0xf8,
□□■■■■■□□□■□■□□□　　0x3e, 0x28,
□□□□□□□□□□■□■□□□　　0x00, 0x28,
□□□■□□□□□□□□■□□□　　0x10, 0x08,
□□□■□□□□□□□□■□□□　　0x10, 0x08,
□□□■■■■■■■■■■□□□　　0x1f, 0xf8,
□□□■□□□□□□□□■□□□　　0x18, 0x08,
□□□■□□□□□□□□■□□□　　0x18, 0x08,
□□□■■■■■■■■■■□□□　　0x1f, 0xf8,
□□□□□□□□□□□□□□□□　　0x00, 0x00,
□□□□□□□□□□□□□□□□　　0x00, 0x00,

外字フォントの変換

EB ライブラリには、外字のビットマップデータを XBM, XPM, GIF, BMP, PNG の各画像形式に変換する関数が用意されています。変換を行う関数は、次の 5 つです。

`eb_bitmap_to_xbm()`	XBM への変換
`eb_bitmap_to_xpm()`	XPM への変換
`eb_bitmap_to_gif()`	GIF への変換
`eb_bitmap_to_bmp()`	BMP への変換
`eb_bitmap_to_png()`	PNG への変換

どの関数も呼び出し方は同じですが、ここでは XBM への変換のプログラム例を示します。

/* bitmap に高さ 16 の全角外字のビットマップデータが格納
 * されていると仮定しています。*/
char bitmap[EB_SIZE_WIDE_FONT_16];
char xbm[EB_SIZE_WIDE_FONT_16_XBM];
size_t xbmsize;

if (eb_wide_font_character_bitmap(bitmap, EB_WIDTH_WIDE_FONT_16,
    EB_HEIGHT_FONT_16, xbm, &xbmsize) != EB_SUCCESS) {
    return;
}

XPM, GIF, PNG への変換では、前景色は黒、背景色は透明になります。 BMP への変換では、前景色は黒、背景色は白になります。 XBM はモノクロ図版用のデータ形式なので、色の設定はありません。

テキスト中の外字

外字はテキストデータ (本文、メニューなど) の中で使われています。

アプリケーションプログラムが、テキストデータ中に出現する外字を識別して処理を行うには、外字に対するフックを設定して、フック関数の中で処理することになります。

外字に対するフックは、全角外字に対する EB_HOOK_WIDE_FONT と半角外字に対する EB_HOOK_NARROW_FONT の二種類があります。いずれも、外字が一字出現する度に、設定したフック関数を呼び出します。

フックの扱い方については、「フックコードの一覧」を参照のこと。

データ型の詳細

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

#include <eb/eb.h>

`EB_Font_Code` 型

外字コードは、外字の高さ (ピクセル数) を表します。現在のところ、定義されている高さは次の通りです。

EB_FONT_16
EB_FONT_24
EB_FONT_30
EB_FONT_48
EB_FONT_INVALID

外字コードの実体は整数値ですが、EB_FONT_16 の値は 16 ではありません。他も同様ですので、注意して下さい。

EB_FONT_INVALID は特別な外字コードで、不正な外字コード値を表すために用います。

定数の詳細

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

#include <eb/eb.h>

定数 `EB_WIDTH_NARROW_FONT_16`

定数 `EB_WIDTH_NARROW_FONT_24`

定数 `EB_WIDTH_NARROW_FONT_30`

定数 `EB_WIDTH_NARROW_FONT_48`

定数 `EB_WIDTH_WIDE_FONT_16`

定数 `EB_WIDTH_WIDE_FONT_24`

定数 `EB_WIDTH_WIDE_FONT_30`

定数 `EB_WIDTH_WIDE_FONT_48`

これらの定数は、半角、全角およびそれぞれの高さ (外字コード) の外字一個分の幅 (横方向のピクセル数) を int 型で表しています。

定数 `EB_HEIGHT_NARROW_FONT_16`

定数 `EB_HEIGHT_NARROW_FONT_24`

定数 `EB_HEIGHT_NARROW_FONT_30`

定数 `EB_HEIGHT_NARROW_FONT_48`

定数 `EB_HEIGHT_WIDE_FONT_16`

定数 `EB_HEIGHT_WIDE_FONT_24`

定数 `EB_HEIGHT_WIDE_FONT_30`

定数 `EB_HEIGHT_WIDE_FONT_48`

これらの定数は、半角、全角およびそれぞれの高さ (外字コード) の外字一個分の縦方向のピクセル数を int 型で表しています。

EB_HEIGHT_NARROW_FONT_16 および EB_HEIGHT_WIDE_FONT_16 の実際の値は 16 です。 (外字コード EB_FONT_16 の実際の値は 16 ではありませんので、注意して下さい。)

定数 `EB_SIZE_NARROW_FONT_16`

定数 `EB_SIZE_NARROW_FONT_24`

定数 `EB_SIZE_NARROW_FONT_30`

定数 `EB_SIZE_NARROW_FONT_48`

定数 `EB_SIZE_WIDE_FONT_16`

定数 `EB_SIZE_WIDE_FONT_24`

定数 `EB_SIZE_WIDE_FONT_30`

定数 `EB_SIZE_WIDE_FONT_48`

これらの定数は、半角、全角およびそれぞれの高さ (外字コード) の外字一個分のビットマップデータを格納するのに必要な領域の大きさを表しています。値は int 型で、単位はバイトです。

定数 `EB_SIZE_NARROW_FONT_16_XBM`

定数 `EB_SIZE_NARROW_FONT_24_XBM`

定数 `EB_SIZE_NARROW_FONT_30_XBM`

定数 `EB_SIZE_NARROW_FONT_48_XBM`

定数 `EB_SIZE_WIDE_FONT_16_XBM`

定数 `EB_SIZE_WIDE_FONT_24_XBM`

定数 `EB_SIZE_WIDE_FONT_30_XBM`

定数 `EB_SIZE_WIDE_FONT_48_XBM`

これらの定数は、半角、全角およびそれぞれの高さ (外字コード) の外字一個分のビットマップデータを eb_bitmap_to_xbm() を用いて XBM 形式に変換する際に、変換後の XBM 形式のデータの大きさを表しています。値は int 型で、単位はバイトです。

定数 `EB_SIZE_NARROW_FONT_16_XPM`

定数 `EB_SIZE_NARROW_FONT_24_XPM`

定数 `EB_SIZE_NARROW_FONT_30_XPM`

定数 `EB_SIZE_NARROW_FONT_48_XPM`

定数 `EB_SIZE_WIDE_FONT_16_XPM`

定数 `EB_SIZE_WIDE_FONT_24_XPM`

定数 `EB_SIZE_WIDE_FONT_30_XPM`

定数 `EB_SIZE_WIDE_FONT_48_XPM`

これらの定数は、半角、全角およびそれぞれの高さ (外字コード) の外字一個分のビットマップデータを eb_bitmap_to_xpm() を用いて XPM 形式に変換する際に、変換後の XPM 形式のデータの大きさを表しています。値は int 型で、単位はバイトです。

定数 `EB_SIZE_NARROW_FONT_16_GIF`

定数 `EB_SIZE_NARROW_FONT_24_GIF`

定数 `EB_SIZE_NARROW_FONT_30_GIF`

定数 `EB_SIZE_NARROW_FONT_48_GIF`

定数 `EB_SIZE_WIDE_FONT_16_GIF`

定数 `EB_SIZE_WIDE_FONT_24_GIF`

定数 `EB_SIZE_WIDE_FONT_30_GIF`

定数 `EB_SIZE_WIDE_FONT_48_GIF`

これらの定数は、半角、全角およびそれぞれの高さ (外字コード) の外字一個分のビットマップデータを eb_bitmap_to_gif() を用いて GIF 形式に変換する際に、変換後の GIF 形式のデータの大きさを表しています。値は int 型で、単位はバイトです。

定数 `EB_SIZE_NARROW_FONT_16_BMP`

定数 `EB_SIZE_NARROW_FONT_24_BMP`

定数 `EB_SIZE_NARROW_FONT_30_BMP`

定数 `EB_SIZE_NARROW_FONT_48_BMP`

定数 `EB_SIZE_WIDE_FONT_16_BMP`

定数 `EB_SIZE_WIDE_FONT_24_BMP`

定数 `EB_SIZE_WIDE_FONT_30_BMP`

定数 `EB_SIZE_WIDE_FONT_48_BMP`

これらの定数は、半角、全角およびそれぞれの高さ (外字コード) の外字一個分のビットマップデータを eb_bitmap_to_bmp() を用いて BMP 形式に変換する際に、変換後の BMP 形式のデータの大きさを表しています。値は int 型で、単位はバイトです。

定数 `EB_SIZE_NARROW_FONT_16_PNG`

定数 `EB_SIZE_NARROW_FONT_24_PNG`

定数 `EB_SIZE_NARROW_FONT_30_PNG`

定数 `EB_SIZE_NARROW_FONT_48_PNG`

定数 `EB_SIZE_WIDE_FONT_16_PNG`

定数 `EB_SIZE_WIDE_FONT_24_PNG`

定数 `EB_SIZE_WIDE_FONT_30_PNG`

定数 `EB_SIZE_WIDE_FONT_48_PNG`

これらの定数は、半角、全角およびそれぞれの高さ (外字コード) の外字一個分のビットマップデータを eb_bitmap_to_png() を用いて PNG 形式に変換する際に、変換後の PNG 形式のデータの大きさを表しています。値は int 型で、単位はバイトです。

関数の詳細

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

#include <eb/font.h>

`EB_Error_Code eb_font (EB_Book book, EB_Font_Code font_code)`

関数 eb_font() は、選択している副本において、選択中の外字フォントの高さを表す外字コードを font_code の指す領域に書き込みます。

成功すると関数は EB_SUCCESS を返します。失敗すると font_code の指す領域に EB_FONT_INVALID を書き込み、原因を示すエラーコードを返します。

あらかじめ、外字フォントの高さが選択されていなければなりません。外字が選択されていなければ、EB_ERR_NO_CUR_FONT を返します。副本そのものを選択していない場合も、同様です。

`EB_Error_Code eb_set_font (EB_Book *book, EB_Font_Code font_code)`

関数 eb_set_font() は、選択中の副本における外字フォントの高さをセットします。セットする外字フォントの「高さ」は、対応する外字コードを引数 font_code で指定します。

この関数は、成功すると EB_SUCCESS を返し、指定した「高さ」が「選択中の外字フォントの高さ」となります。すでに外字フォントの高さを選択していた場合は、いったん未選択の状態にしてからあらためて font_code を選択します。

失敗すると原因を示すエラーコードを返し、外字フォントの高さは未選択の状態になります。

あらかじめ、book 内のいずれかの副本が選択されていなくてはなりません。 book が副本を選択していなければ、EB_ERR_NO_CUR_SUB を返します。また、その副本が持っていない外字フォントの高さが指定されると、 EB_ERR_NO_SUCH_FONT を返します。

`void eb_unset_font (EB_Book *book)`

関数 eb_unset_font() は、選択中の外字フォントの高さを未選択の状態に戻します。 book が書籍に結び付いていない場合や副本が選択されていない場合、もしくは外字フォントの高さが選択されていない場合は何もしません。

`EB_Error_Code eb_font_list (EB_Book book, EB_Font_Code font_list, int *font_count)`

関数 eb_font_list() は、選択中の副本が定義している外字の高さの一覧を EB_Font_Code 型の配列にして、font_list の指す領域に書き込みます。

配列は、最大で EB_MAX_FONTS 個の要素を持ちます。加えて、書籍が収録している副本の個数を font_count の指す領域に書き込みます。 (現在のバージョンでは、EB_MAX_FONTS の値は 4 になっています。高さ 16, 24, 30, 48 ピクセルの 4 種類です。)

成功すると、関数は EB_SUCCESS を返します。失敗すると、font_count の指す領域に 0 を書き込み、原因を示すエラーコードを返します。

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

`int eb_have_font (EB_Book *book, EB_Font_Code font_code)`

関数 eb_font() は、font_code で指定した高さの外字フォントを、選択中の副本が持っているかどうかを調べます。

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

`EB_Error_Code eb_font_height (EB_Book book, int height)`

関数 eb_font_height() は、book が選択中の外字フォントの高さ (縦方向のピクセル数) を height の指す領域に書き込みます。

成功すると、関数は EB_SUCCESS を返します。失敗すると、height の指す領域に 0 を書き込み、原因を示すエラーコードを返します。

あらかじめ、book は外字フォントの高さを選択していなくてはなりません。選択していない場合は、EB_ERR_NO_CUR_FONT を返します。

`EB_Error_Code eb_font_height2 (EB_Font_Code font_code, int *height)`

eb_font_height() と似ていますが、選択中の副本ではなく、引数 font_height で指定された外字コードの高さ (縦方向のピクセル数) を書き込む点が異なります。

`int eb_have_narrow_font (EB_Book *book)`

`int eb_have_wide_font (EB_Book *book)`

関数 eb_have_narrow_font() は、選択中の副本が半角外字を定義しているかどうかを調べます。同様に、関数 eb_have_wide_font() は、全角外字を定義しているかどうかを調べます。

定義していれば 1 を、定義していなければ 0 を返します。 book が副本を選択していない場合も 0 を返します。

`EB_Error_Code eb_narrow_font_width (EB_Book book, int width)`

`EB_Error_Code eb_wide_font_width (EB_Book book, int width)`

関数 eb_narrow_font_width() は、book が選択中の外字フォントの高さにおける半角外字の幅 (横方向のピクセル数) を、 height の指す領域に書き込みます。同様に、eb_wide_font_width() は全角外字の幅を書き込みます。

成功すると、関数は EB_SUCCESS を返します。失敗すると、width の指す領域に 0 を書き込み、原因を示すエラーコードを返します。

あらかじめ、book は外字の高さを選択していなくてはなりません。選択していない場合は、EB_ERR_NO_CUR_FONT を返します。

`EB_Error_Code eb_narrow_font_width2 (EB_Font_Code font_code, int *width)`

`EB_Error_Code eb_wide_font_width2 (EB_Font_Code font_code, int *width)`

eb_narrow_font_width(), eb_wide_font_width() と似ていますが、選択中の副本ではなく、引数font_height で指定された外字コードの幅 (横方向のピクセル数) を書き込む点が異なります。

`EB_Error_Code eb_narrow_font_size (EB_Book book, size_t size)`

`EB_Error_Code eb_wide_font_size (EB_Book book, size_t size)`

関数 eb_narrow_font_size() は、book が選択中の外字フォントの高さにおける半角外字一個分のデータサイズ (バイト数) を、 size の指す領域に書き込みます。同様に、eb_wide_font_size() は全角外字のサイズを書き込みます。

成功すると、関数は EB_SUCCESS を返します。失敗すると、size の指す領域に 0 を書き込み、原因を示すエラーコードを返します。

あらかじめ、book は外字フォントの高さを選択していなくてはなりません。選択していない場合は、EB_ERR_NO_CUR_FONT を返します。

`EB_Error_Code eb_narrow_font_size2 (EB_Font_Code font_code, size_t *size)`

`EB_Error_Code eb_wide_font_size2 (EB_Font_Code font_code, size_t *size)`

eb_narrow_font_size(), eb_wide_font_size() と似ていますが、選択中の副本ではなく、引数 font_height で指定された外字コードの外字一個分のデータサイズを書き込む点が異なります。

`EB_Error_Code eb_narrow_font_start (EB_Book book, int start)`

`EB_Error_Code eb_wide_font_start (EB_Book book, int start)`

関数 eb_narrow_font_start() は、book が選択中の副本における半角外字の先頭の文字番号 (半角外字の文字番号の中で最小のもの) を、start の指す領域に書き込みます。

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

あらかじめ、book は副本を選択していなくてはなりません。選択していない場合は、EB_ERR_NO_CUR_SUB を返します。副本が半角外字を定義していない場合は、EB_ERR_NO_CUR_FONT を返します。

関数 eb_wide_font_start() は、半角外字ではなく全角外字について調べるという点を除いて、eb_narrow_font_start() と同じです。

`EB_Error_Code eb_narrow_font_end (EB_Book book, int end)`

`EB_Error_Code eb_wide_font_end (EB_Book book, int end)`

関数 eb_narrow_font_end() は、book が選択中の副本における半角外字の最後の文字番号 (半角外字の文字番号の中で最大のもの) を、 start の指す領域に書き込みます。

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

関数 eb_wide_font_end() は、半角外字ではなく全角外字について調べるという点を除いて、eb_narrow_font_end() と同じです。

`EB_Error_Code eb_narrow_font_character_bitmap (EB_Book book, int character_number, char bitmap)`

`EB_Error_Code eb_wide_font_character_bitmap (EB_Book book, int character_number, char bitmap)`

関数 eb_narrow_font_character_bitmap() は、book が選択中の副本で定義している、半角外字のビットマップデータを取り出します。取り出す外字の文字番号を、character_number で指定します。

成功すると、関数はビットマップデータを bitmap の指す領域に書き込み、EB_SUCCESS を返します。失敗すると、bitmap の指す領域に空文字列を書き込み、原因を示すエラーコードを返します。

あらかじめ、book は外字フォントの高さを選択していなくてはなりません。選択していない場合は、EB_ERR_NO_CUR_FONT を返します。副本が半角外字を定義していない場合も、やはり EB_ERR_NO_CUR_FONT を返します。文字番号 character_number が外字の定義範囲外にある場合は、 EB_ERR_NO_SUCH_CHAR_BMP を返します。

関数 eb_wide_font_character_bitmap() は、半角外字ではなく全角外字のビットマップデータを取り出すという点を除いて、 eb_narrow_font_character_bitmap() と同じです。

ビットマップデータの形式については、「外字フォントの取り出し」を参照のこと。

`EB_Error_Code eb_forward_narrow_font_character (EB_Book book, int n, int character_number)`

`EB_Error_Code eb_forward_wide_font_character (EB_Book book, int n, int character_number)`

関数 eb_forward_narrow_font_character() は、book が選択中の副本で定義されている半角外字の文字番号 character_number のn 個後ろに位置する外字の文字番号を取得します。

まず、関数を呼び出す際に、character_number の指す領域に文字番号を書き込んでおきます。関数の処理が成功すると、戻ったときに n 個分だけ後方の文字番号に書き換わっています。

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

あらかじめ、book は副本を選択していなくてはなりません。選択していない場合は、EB_ERR_NO_CUR_SUB を返します。副本が半角外字を持っていない場合は、EB_ERR_NO_CUR_FONT を返します。

n 個後ろにもう外字がない場合や、呼び出した際に character_number の指す領域に書き込んであった文字番号が外字の定義範囲外にある場合は EB_ERR_NO_SUCH_CHAR_BMP を返します。

n には負の数を指定することもできます。この場合、次の呼び出しと等価になります。

/* n < 0 とする */
eb_backward_narrow_font_character (book, -n, character_number);

関数 eb_forward_wide_font_character() は、半角外字ではなく全角外字について操作するという点を除いて、 eb_forward_narrow_font_character() と同じです。

`EB_Error_Code eb_backward_narrow_font_character (EB_Book book, int n, int character_number)`

`EB_Error_Code eb_backward_wide_font_character (EB_Book book, int n, int character_number)`

関数 eb_backward_narrow_font_character() は eb_forward_narrow_font_character() とはちょうど逆の関数です。 book が選択中の副本で定義されている半角外字の文字番号 character_number の n 個前方に位置する外字の文字番号を取得します。

同様に、eb_backward_wide_font_character() は、全角外字について n 個前方の外字の文字番号を取得する関数で、 eb_forward_wide_font_character() と反対の関数です。

n には負の数を指定することも可能で、それぞれ次の呼び出しと等価になります。

/* 半角外字の場合 (n < 0) */
eb_forward_narrow_font_character (book, -n, character_number);

/* 全角外字の場合 (n < 0) */
eb_forward_wide_font_character (book, -n, character_number);

`EB_Error_Code eb_narrow_font_xbm_size (EB_Font_Code height, size_t *size)`

`EB_Error_Code eb_narrow_font_xpm_size (EB_Font_Code height, size_t *size)`

`EB_Error_Code eb_narrow_font_gif_size (EB_Font_Code height, size_t *size)`

`EB_Error_Code eb_narrow_font_bmp_size (EB_Font_Code height, size_t *size)`

`EB_Error_Code eb_narrow_font_png_size (EB_Font_Code height, size_t *size)`

`EB_Error_Code eb_wide_font_xbm_size (EB_Font_Code height, size_t *size)`

`EB_Error_Code eb_wide_font_xpm_size (EB_Font_Code height, size_t *size)`

`EB_Error_Code eb_wide_font_gif_size (EB_Font_Code height, size_t *size)`

`EB_Error_Code eb_wide_font_bmp_size (EB_Font_Code height, size_t *size)`

`EB_Error_Code eb_wide_font_png_size (EB_Font_Code height, size_t *size)`

最初の 5 つの関数 (eb_narrow_font_xbm_size() ～ eb_narrow_font_png_size()) は、外字コード height の半角外字一個のビットマップを XBM, XPM, GIF, BMP, PNG 形式にそれぞれ変換したときのデータサイズを size の指す領域に書き込みます。

同様に、後ろの 5 つの関数 (eb_wide_font_xbm_size() ～ eb_wide_font_png_size()) は、全角外字を変換したときのデータサイズを書き込みます。

いずれの関数も、成功すると EB_SUCCESS を返します。失敗すると、size の指す領域に 0 を書き込み、原因を示すエラーコードを返します。

`EB_Error_Code eb_bitmap_to_xbm (const char bitmap, int width, int height, char image, size_t *image_length)`

`EB_Error_Code eb_bitmap_to_xpm (const char bitmap, int width, int height, char image, size_t *image_length)`

`EB_Error_Code eb_bitmap_to_gif (const char bitmap, int width, int height, char image, size_t *image_length)`

`EB_Error_Code eb_bitmap_to_bmp (const char bitmap, int width, int height, char image, size_t *image_length)`

`EB_Error_Code eb_bitmap_to_png (const char bitmap, int width, int height, char image, size_t *image_length)`

これら 5 つの関数は、eb_narrow_font_character() または eb_wide_font_character() で取り出した外字のビットマップを XBM, XPM, GIF, BMP, PNG 形式にそれぞれ変換します。

ビットマップデータの指す領域を bitmap で指定し、ビットマップの高さと幅を width, height で渡します。

関数の呼び出しから戻ると、image の指す領域に変換後のデータが書き込まれ、image_length の指す領域に変換後のデータの大きさが書き込まれます。

サンプルプログラム

バイナリデータ

バイナリデータ (binary data) とは、図版や動画、音声といったマルチメディアデータのことを指します。バイナリデータは、必ずテキストデータ (「テキストデータ」を参照のこと) から参照される形で利用されます。

今のところ EB ライブラリでは、全種類のバイナリデータを取り扱うことができるわけではありません。電子ブックで扱えるのは、2 階調のモノクロ図版と、カラー図版 (JPEG) だけです。 EPWING では、モノクロ図版、カラー図版 (BMP および JPEG) に加えて、 WAVE (PCM) 音声、MPEG 動画を扱うことができます。

ただし、EB ライブラリが提供しているのは、こうしたバイナリデータを CD-ROM 書籍から取得する機能だけです。表示したり再生したりする機能は用意していませんので、注意して下さい。

アプリケーションは、英和辞書や国語辞書といった辞書だけを対象にするなら、バイナリデータの表示や再生には対応しなくても支障はありません。しかし一方では、図鑑や数式の表現にモノクロ図版を使っている数学辞典のように、対応しないと不便なものもあります。バイナリデータの表示や再生の機能を実装するかどうかは、アプリケーションの対象辞書をどの範囲までにするのかによって決めると良いでしょう。

以下、この章では種類別にバイナリデータの扱い方について説明します。

バイナリデータの種類毎にデータの取り出し方は微妙に異なりますが (これはデータの収録方法が微妙に異なっているからに他なりません)、おおよそ手順は、次のようなものになります。

テキストデータのフックを用いて、バイナリデータの参照情報を取得する。
eb_binary_set_...() 関数を呼び出して、指定した位置のバイナリデータをこれから読み込む旨を EB ライブラリに伝える。
eb_read_binary() で実際にデータを読み込む。

テキストデータと同様に、バイナリデータも副本に属するデータですので、副本を選択していないと取得することはできません。バイナリデータの読み込みには、テキストデータとは別のファイルディスクリプタが割り当てられます。したがって、双方を交互に読み込んでも、動作には影響はありません。

モノクロ図版

2 階調のモノクロ図版は、電子ブック、EPWING 双方に存在し、EB ライブラリではどちらも扱うことができます。 (電子ブックに存在する 16 階調のモノクロ図版は、今のところ EB ライブラリでは対応していません。)

モノクロ図版データの内部形式は外字と同じですが、EB ライブラリでは、 1 ピクセルに 1bit を割り当てた BMP 形式に変換してアプリケーションに渡すようにしています。したがって、アプリケーションからは、あたかも BMP の図版データが収録されているようにみえます。

テキストデータ内からは、バイナリデータであるモノクロ図版を参照する形をとります。モノクロ図版を取り出すには、この参照情報が必要です。参照情報の取得は、テキストデータ処理時に、モノクロ図版の開始と終了を表すエスケープシーケンスへのフック EB_HOOK_BEGIN_MONO_GRAPHIC と EB_HOOK_END_MONO_GRAPHIC を用いて行います。

フック EB_HOOK_BEGIN_MONO_GRAPHIC がフック関数に渡す引数 (argv) は 4 つあり、このうちの argv[2] と argv[3] が図版の幅と高さ (ピクセル数) を意味します。

また、フック EB_HOOK_END_MONO_GRAPHIC がフック関数に渡す引数は 3 つで、argv[1] と argv[2] が、図版データのページ番号とオフセットになります。

モノクロ図版を取得するには、上記のフックから得た図版のページ番号とオフセット、および幅と高さを記憶しておきます。

次に、eb_set_binary_mono_graphic() を呼び出して、これからモノクロ図版のデータを取得することを EB ライブラリに伝えます。 eb_set_binary_mono_graphic() への引数には、 EB_Book オブジェクトと、先ほど得た図版へのページ番号、オフセット、幅、高さを渡します。 EB_Book オブジェクトは、これから取り出そうとしている図版を収録している副本をあらかじめ選択しておく必要があります。

/* eb_set_binary_mono_graphic() の関数プロトタイプ */
EB_Error_Code
eb_set_binary_mono_graphic(EB_Book *book, EB_Position *position,
    int width, int height);

電子ブックでは、フック関数に渡される幅と高さの値は 0 になっていますが、そのまま eb_set_binary_mono_graphic() に渡します。 (EPWING では 0 を渡してはいけません。)

以上で図版データの取得準備ができたので、データを読み込みます。これには、eb_read_binary() を使います。

#define MAX_LENGTH 1000
char bitmap[MAX_LENGTH];
ssize_t bitmap_length;

if (eb_read_binary(&book, MAX_LENGTH, bitmap, &bitmap_length)
    != EB_SUCCESS) {
    fprintf(stderr, "an error occurs.\n");
    return;
}

成功すると、読み込んだ図版データが bitmap に書き込まれ、何バイト書き込んだのかが bitmap_length に書き込まれます。書き込まれるバイト数は、最大で MAX_LENGTH バイトです。

必ずしも一回の eb_read_binary() の呼び出しで図版データを終端まで読み込む必要はなく、関数を繰り返し呼び出せば、前回の続きを読み込むことができます。 eb_read_binary() は、図版データの終端まで来るとそれ以上データは読み込みませんので、eb_read_binary() が 0 を返した時点で図版データが終端したことを認識できます。

カラー図版

カラー図版は、電子ブックでは JPEG 形式、EPWING では JPEG と BMP (DIB) 形式のものが使用されています。 EB ライブラリはこれらをすべて扱うことができますが、電子ブックへの対応は限定的なものになっています。(詳しくは後述します。)

カラー図版のデータを取り出すには、モノクロ図版と同様にテキストデータからカラー図版への参照情報をフックを通じて取得し、続いて実際にカラー図版のデータを読み込むという手順になります。

eb_set_binary_color_graphic() を呼び出して、これからアプリケーションがカラー図版のデータを取得しようとしていることを EB ライブラリに伝えます。 eb_set_binary_color_graphic() への引数には、 EB_Book オブジェクトに加えて、カラー図版のページ番号とオフセットを渡します。

/* eb_set_binary_color_graphic() の関数プロトタイプ */
EB_Error_Code
eb_set_binary_color_graphic(EB_Book *book, EB_Position *position);

EB_Book オブジェクトは、これから取り出そうとしている図版を収録している副本をあらかじめ選択しておきます。カラー図版のページ番号とオフセットの情報は、カラー図版の開始と終了を表すエスケープシーケンスへのフックから得ます。フックは、インライン表示用と非インライン用の 2 種類があり、さらにそれぞれ開始フックが JPEG 用と BMP 用に分かれています。

EB_HOOK_BEGIN_COLOR_BMP
EB_HOOK_BEGIN_COLOR_JPEG: 非インライン用 BMP, JPEG の開始フック
EB_HOOK_END_COLOR_GRAPHIC: 非インライン用カラー図版 (BMP, JPEG 共通) の終了フック
EB_HOOK_BEGIN_IN_COLOR_BMP
EB_HOOK_BEGIN_IN_COLOR_JPEG: インライン用 BMP, JPEG の開始フック
EB_HOOK_END_IN_COLOR_GRAPHIC: 非インライン用カラー図版 (BMP, JPEG 共通) の終了フック

非インライン用の終了フック EB_HOOK_END_GRAPHIC では、フック関数に渡す引数の argv[1] と argv[2] が、図版データのページ番号とオフセットになりますので、これを eb_set_binary_color_graphic() に渡してやります。同様に、インライン用の終了フック EB_HOOK_END_IN_GRAPHIC では、argv[2] と argv[3] がページ番号とオフセットですので、これを渡します。

後は、実際にカラー図版のデータを取り出します。これには、モノクロ図版と同様に eb_read_binary() を用います。使い方はまったく一緒ですので、詳しくは「モノクロ図版」を参照してください。

ただし、電子ブックのカラー図版については、データの終了位置が来ても EB ライブラリは読み込みを止めないという制限事項があります。これは、データの大きさに関する情報が記されていないためで、データの終端位置は、アプリケーションが JPEG のデータをデコードして割り出すしかありません。

参照先付きカラー図版

カラー図版には、画像内の特定の矩形領域に参照先の情報を付け加えたものがあります。 HTML におけるクリッカブル・イメージ (clickable image) とほぼ同じで、その矩形領域内にマウスポインタがある間にマウスをクリックすると、あらかじめ決められたリンク先に画面が遷移するという仕掛けです。リンク先となる矩形領域は、画像一つに対して複数個登録できます。

　　　　　　　参照先付きカラー図版の例
┌────────────────────────┐
│┌　─　─　─　─　┐　　┌　─　─　─　─　┐│
│　　　　　　　　　　　　　　　　　　　　　　　　│
││　　矩形領域１　　│　　│　　矩形領域２　　││
│　　　　　　　　　　　　　　　　　　　　　　　　│
│└　─　─　─　─　┘　　└　─　─　─　─　┘│
│　　　　　　　　　　　　　　　　　　　　　　　　│
│┌　─　─　─　─　┐　　　　　　　　　　　　　│
│　　　　　　　　　　　　　　　　　　　　　　　　│
││　　矩形領域３　　│　　　　　　図版　　　　　│
│　　　　　　　　　　　　　　　　　　　　　　　　│
│└　─　─　─　─　┘　　　　　　　　　　　　　│
└────────────────────────┘

参照先付きカラー図版の取り扱い方は、通常のカラー図版を拡張した形となります。通常のカラー図版の場合では、たとえば JPEG の非インライン画像では、次のような順番でフックが呼び出されます。

EB_HOOK_BEGIN_COLOR_JPEG (非インライン用 JPEG 開始)
EB_HOOK_END_COLOR_GRAPHIC (非インライン用 JPEG 終了)

これに対して参照先付きのカラー図版では、この2つのフックの間に、矩形領域情報に関するフックが挿入されます。

EB_HOOK_BEGIN_COLOR_JPEG (非インライン用 JPEG 開始)
EB_HOOK_BEGIN_CLICKABLE_AREA (矩形領域1 開始)
EB_HOOK_END_CLICKABLE_AREA (矩形領域1 終了)
EB_HOOK_BEGIN_CLICKABLE_AREA (矩形領域2 開始)
EB_HOOK_END_CLICKABLE_AREA (矩形領域2 終了)
以下、矩形領域3、矩形領域4 ... と矩形領域の個数分だけ続く。
EB_HOOK_END_COLOR_GRAPHIC (非インライン用 JPEG 終了)

矩形領域に関する具体的な情報は、EB_HOOK_BEGIN_CLICKABLE_AREA (開始フック) のほうで取得します。フック関数に渡す引数の argv[1] と argv[2] が、それぞれ矩形領域の開始 x, y 座標を表します。カラー図版の左上の座標が (0, 0) です。同様に、argv[3] と argv[4] が矩形領域の右方向への幅と、下方向への高さを表します。最後の argv[5] と argv[6] が参照先のページ番号とオフセットとなります。

アプリケーションが参照先付きカラー図版に対応しない場合は、矩形領域の開始情報と終了情報を無視することになります。これにより、図版は通常の (参照先を持たない) カラー図版とまったく同じく扱われます。

WAVE (PCM) 音声

WAVE (PCM) 形式の音声データは EPWING にだけ存在します。 (代わりに電子ブックには CD-DA 形式の音声データがありますが、EB ライブラリでは対応していません。)

WAVE 形式の音声データを取り出すには、まずテキストデータ中から WAVE 音声の参照情報を得ます。参照開始と終了を表すエスケープシーケンスへのフック EB_HOOK_BEGIN_WAVE と EB_HOOK_END_WAVE がそれぞれありますので、これを用います。

フック EB_HOOK_BEGIN_WAVE がフック関数に渡す引数のうち、 argv[2] と argv[3] が音声データの開始位置のページ番号とオフセット、argv[4] と argv[5] が終了位置のページ番号とオフセットとなります。

この開始位置と終了位置を関数 eb_set_binary_wave() に渡して、その位置にある音声データをこれから取り出すことを EB ライブラリに伝えます。

/* eb_set_binary_wave() の関数プロトタイプ */
EB_Error_Code
eb_set_binary_wave(EB_Book *book, EB_Position *start_position,
EB_Position *end_position);

そして後は、実際に音声データを取り出します。これには、他のバイナリデータと同様に eb_read_binary() を用います。 eb_read_binary() の使い方は、「モノクロ図版」を参照のことを参照してください。

MPEG1 動画

MPEG1 形式の動画データは EPWING にだけ存在します。動画データは EPWING の CD-ROM の movie というディレクトリの下に、動画毎に一個のファイルにした形で収められています。

テキストデータ中に存在する、MPEG データの参照開始と終了を表すエスケープシーケンスへのフック EB_HOOK_BEGIN_MPEG と EB_HOOK_END_MPEG を使用することで、参照先の MPEG のファイル名を取得できます。

具体的には、フック EB_HOOK_BEGIN_MPEG がフック関数に渡す引数のうち、argv[2] ～ argv[5] が合わせて一つのファイル名を表すようになっています。

MPEG 動画のデータを得るには、このファイル名を eb_set_binary_mpeg() に渡して、そのファイルの動画データをこれから取り出す旨を EB ライブラリに伝えます。ファイル名は、次のようにして argv + 2 (&argv[2] でも同じ) を渡します。

if (eb_set_binary_mpeg(&book, argv + 2) != EB_SUCCESS) {
    fprintf(stderr, "an error occurs.\n");
    return;
}

後は、実際に動画データを取り出します。これには、やはり他のバイナリデータと同様に eb_read_binary() を用います。 eb_read_binary() の使い方については、「モノクロ図版」を参照のことを参照してください。

関数の詳細

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

#include <eb/binary.h>

`EB_Error_Code eb_set_binary_mono_graphic (EB_Book book, const EB_Position position, int width, height)`

関数 eb_set_binary_mono_graphic() は、モノクロ図版のデータをこれから取得しようとしていることを EB ライブラリに伝えます。引数 position は図版の位置、width, height には図版の幅と高さを渡します。これらの情報は、図版の参照元であるテキストデータに記載されており、通常はフック関数を通じて得るようにします。ただし、電子ブックでは幅と高さの値の情報がテキストデータに記されていないため、0 を渡すことになります。

成功すると、関数は EB_SUCCESS を返します。失敗すると、原因に応じたエラーコードを返します。

あらかじめ、図版を取り出そうとしている副本を選択しておかなければなりません。 book が副本を選択していなければ、EB_ERR_NO_CUR_SUB を返します。図版の位置、幅、高さの値が明らかにおかしいと EB ライブラリが判断したときは、EB_ERR_NO_SUCH_BINARY を返します。

この関数は、実際に図版データを読み込むことはしません。読み込みには、eb_read_binary() を用います。モノクロ図版のデータは、1 ピクセルに 1bit を割り当てた BMP 形式になっています。

`EB_Error_Code eb_set_binary_color_graphic (EB_Book book, const EB_Position position)`

関数 eb_set_binary_color_graphic() は、EPWING のカラー図版のデータをこれから取得しようとしていることを EB ライブラリに伝えます。引数 position は図版の位置を渡します。位置の情報は、図版の参照元であるテキストデータに記載されており、通常はフック関数を通じて得るようにします。

成功すると、関数は EB_SUCCESS を返します。

あらかじめ、図版を取り出そうとしている副本を選択しておかなければなりません。 book が副本を選択していなければ、EB_ERR_NO_CUR_SUB を返します。図版の位置が明らかにおかしいと EB ライブラリが判断したときは、 EB_ERR_NO_SUCH_BINARY を返します。

この関数は、実際に図版データを読み込むことはしません。読み込みには、eb_read_binary() を用います。カラー図版データは、JPEG か BMP (DIB) のいずかの形式になっています。

`EB_Error_Code eb_set_binary_wave (EB_Book book, const EB_Position start_position, EB_Position *end_position)`

関数 eb_set_binary_wave() は、WAVE (PCM) 形式の音声のデータをこれから取得しようとしていることを EB ライブラリに伝えます。引数 start_position と end_position には音声データの開始位置を渡します。位置の情報は、音声データの参照元であるテキストデータに記載されており、通常はフック関数を通じて得るようにします。

成功すると、関数は EB_SUCCESS を返します。失敗すると、原因に応じたエラーコードを返します。

あらかじめ、音声データを取り出そうとしている副本を選択しておかなければなりません。 book が副本を選択していなければ、EB_ERR_NO_CUR_SUB を返します。音声データの位置が明らかにおかしいと EB ライブラリが判断したときは、 EB_ERR_NO_SUCH_BINARY を返します。

この関数は、実際に音声データを読み込むことはしません。読み込みには、eb_read_binary() を用います。

`EB_Error_Code eb_set_binary_mpeg (EB_Book book, const unsigned int argv)`

関数 eb_set_binary_mpeg() は、MPEG1 形式の動画のデータをこれから取得しようとしていることを EB ライブラリに伝えます。引数 argv には動画データのファイル名を渡します。ただし、このファイル名は文字列ではなく、フック関数 EB_HOOK_BEGIN_MPEG に渡された引数 argv[2] ～ argv[5] の部分を渡します。つまり、フック関数の引数 argv + 2 を、 eb_set_binary_mpeg() への引数 argv として渡します。

成功すると、関数は EB_SUCCESS を返します。失敗すると、原因に応じたエラーコードを返します。

あらかじめ、動画データを取り出そうとしている副本を選択しておかなければなりません。 book が副本を選択していなければ、EB_ERR_NO_CUR_SUB を返します。存在しない動画ファイル名を EB ライブラリが判断したときは、 EB_ERR_NO_SUCH_BINARY を返します。

成功すると、関数は EB_SUCCESS を返します。

この関数は、実際に動画データを読み込むことはしません。読み込みには、eb_read_binary() を用います。

`EB_Error_Code eb_read_binary (EB_Book book, size_t binary_max_length, char binary, ssize_t *binary_length)`

関数 eb_read_binary() は、バイナリデータを読み込みます。読み込もうとしているバイナリデータは、事前に

eb_set_binary_mono_graphic()
eb_set_binary_color_graphic()
eb_set_binary_wave()
eb_set_binary_mpeg()

のいずれかの関数で、EB ライブラリに通知しておく必要があります。

読み込んだデータは引数 binary の指す先の領域に書き込まれます。また、このとき書き込まれたバイト数は、binary_length の指す先の領域にセットされます。ただし、書き込まれるバイト数は、最長でも引数 binary_max_length に指定した値までとなります。

この関数は、特に読み込んだデータの終端にナル文字を付加するような事はしません。読み込まれるデータもバイナリ形式なので、途中にナル文字が出現する事もあります。

この関数を一回呼び出しだだけで、バイナリデータ全体を一気に取得する必要はありません。繰り返し呼び出せば、前回の続きからデータが読み込まれます。

ただし、以下に挙げた関数を呼び出すと、バイナリデータの読み込みに関する状態記録がリセットされますので、それ以上の読み込みはできなくなります。

eb_set_subbook()
eb_unset_subbook()
eb_load_all_subbooks()
eb_bind()
eb_finalize_book()
eb_set_binary_mono_graphic()
eb_set_binary_color_graphic()
eb_set_binary_wave()
eb_set_binary_mpeg()

eb_read_binary() を繰り返し呼んだ場合、バイナリデータはその都度 binary の先頭から書き込まれ、*binary_length の値も、その回の eb_read_binary() の呼び出しで書き込まれたバイト数になります。

データの終端に来ると、それ以上この関数を呼んでも関数は binary には何も書き込まず、*binary_length に 0 を書き込み、 EB_SUCCESS を返します。

成功すると、この関数は EB_SUCCESS を返します。失敗すると、binary_length が指す領域に -1 を書き込み、原因を示すエラーコードを返します。この場合、バイナリデータの読み込み状態の記録がリセットされますので、データの続きを読み込むことはできなくなります。

あらかじめ、book はいずれかの副本を選択していなくてはなりません。選択していない場合は、EB_ERR_NO_CUR_SUB を返します。また、冒頭に挙げた関数の呼び出しが成功していない状態でこの関数を呼ぶと、 EB_ERR_NO_CUR_BINARY を返します。

`EB_Error_Code eb_compose_movie_file_name (const unsigned int argv, char composed_file_name)`

関数 eb_compose_movie_file_name() は、動画データのファイル名を通常の文字列に変換します。

EB ライブラリでは、動画データのファイル名はフック関数 EB_HOOK_BEGIN_MPEG に渡された 4 つの int 型引数 (argv[2] ～ argv[5]) によって表現されます。

動画データを読み込む際は、これをそのまま eb_set_binary_mpeg() に渡せば良いのですが、ファイル名を通常の文字列で得たい場合は、この関数を用います。たとえば、個々の動画に一意の ID のようなものを振りたい場合は、ファイル名を ID として使うと良いかも知れません。なお、この関数で変換して得られるファイル名にはパスが含まれていません。

フック関数の引数 argv + 2 をこの関数への引数 argv として渡すと、composed_file_name が指す先の領域に、文字列形式に変換されたファイル名が格納されます。ファイル名は最長で EB_MAX_DIRECTORY_NAME_LENGTH (= 8) バイトになります。この長さには終端のナル文字の分を含んでいませんので、格納領域にはもう 1 バイト余裕が要ります。

なお、格納されたファイル名は、実際に存在するファイル名とは若干異なっている可能性があります。たとえば、英字の大文字と小文字、接尾子の有無などの違いがこれに当たります。この関数は、あくまで文字列に機械的に変換するだけなので、ファイルが実在するかどうかのチェックはしません。

成功すると、関数は EB_SUCCESS を返します。

`EB_Error_Code eb_compose_movie_path_name (EB_Book book, const unsigned int argv, char *composed_path_name)`

関数 eb_compose_movie_path_name() は、動画データのファイル名を通常の文字列に変換します。働きは、前述の関数 eb_compose_movie_file_name() に良く似ていますが、eb_compose_movie_path_name() が返すファイル名は、絶対パスの形式になっている点が異なります。

また、eb_compose_movie_path_name() では、ファイル名が実在するかどうかのチェックを行うという点も、大きな違いです。ファイル名を文字列に変換した上で、英字の大文字と小文字の違いや接尾子の有無は、実在のファイルに合わせて調整したものを返します。したがって、パスを除いた部分で比較しても、 eb_compose_movie_file_name() が返すファイル名とは必ずしも一致しません。

引数 book は、動画ファイルを収録している副本を選択しておかなければなりません。副本を選択していなければ、EB_ERR_NO_CUR_SUB を返します。

引数 argv の意味は、eb_compose_movie_file_name() と同じです。

ファイル名の変換が成功すると、関数は composed_path_name が指す先の領域に、文字列形式に変換された動画ファイル名を格納し、 EB_SUCCESS を返します。ファイル名は最長で EB_MAX_PATH_LENGTH バイトになります。この長さには終端のナル文字の分を含んでいませんので、格納領域にはもう 1 バイト余裕が要ります。

ファイル名が実在しないと、EB_ERR_BAD_FILE_NAME を返します。

`EB_Error_Code eb_decompose_movie_file_name (unsigned int argv, const char composed_file_name)`

関数 eb_compose_movie_file_name() は、 eb_compose_movie_file_name() とちょうど逆の働きをします。つまり、通常の文字列に変換された動画データのファイル名 composed_file_name を、4 つの int 型引数 argv に戻します。したがって、argv の指す領域は、少なくとも int 型の値を 4 つ格納できる大きさが必要です。

成功すると、関数は EB_SUCCESS を返します。

appendix データ

appendix (付録) とは CD-ROM 書籍の補助データのことです。 appendix は CD-ROM 書籍の出版社から提供されているものではなく、 EB ライブラリに固有のものです。 ebappendix コマンドを用いて生成します (詳しくは ebappendix コマンドのマニュアルの「appendix (付録) とは」を参照のこと)。

appendix は以下のデータを CD-ROM 書籍に対して提供します。

本文の区切りコード
外字の代替文字列

appendix のレイアウトは CD-ROM 書籍のものとよく似ています。トップディレクトリには catalog もしくは catalogs ファイルが存在し、各副本のデータは対応するサブディレクトリに配置されています。

アプリケーションは appendix に対応し、本文の区切りコードの情報を使えるようにすることをお薦めします。外字の代替文字列については、外字のフォントをそのまま表示できるのであれば、対応する必要性はかなり乏しいですが、本文の区切りコードは、扱えないと正しく本文を表示できない書籍に対応できません (区切りコードについては、「区切りコードの問題」を参照のこと)。

`EB_Appendix` オブジェクト

CD-ROM 書籍本体を扱うには EB_Book オブジェクトを用いましたが、appendix を扱うには EB_Appendix オブジェクトを使います。 EB_Appendix オブジェクトを操作するための関数は、 EB_Book のものとは異なりますが、操作手順はよく似ています。

EB_Appendix オブジェクトは、個々の appendix に対して 1 個ずつ作る必要があります。

EB_Appendix app;

もちろん、オブジェクトの領域は、malloc() で確保しても構いません。

EB_Appendix *app_pointer;

app_pointer = (EB_Appendix *) malloc(sizeof(EB_Appendix));

オブジェクトは、使う前に必ず eb_initialize_appendix() という関数で中身を初期化しなくてはなりません。 EB_Book オブジェクトでも eb_initialize_book() で初期化する必要がありましたが、それと同じです。

eb_initialize_appendix(&app);
eb_initialize_appendix(app_pointer);

続いて、オブジェクトを appendix の実体に結び付けるために、 eb_bind_appendix() を呼び出します。これは、EB_Book オブジェクトの eb_bind() に相当します。

ＥＢ＿Ａｐｐｅｎｄｉｘ　　　　　　　　　　ａｐｐｅｎｄｉｘ
オブジェクト　　　　　　　　　　　　┌────────────┐
┌───┐　　　　　　　　　　　　　│　　　　　　　　　　　　│
│　　　┝━━━━━━━━━━━━━┥　／ｍｎｔ／ｄｉｃｔ　　│
└───┘　ｅｂ＿ｂｉｎｄ　　　　　│　　　　　　　　　　　　│
　　　　　　＿ａｐｐｅｎｄｉｘ（）　└────────────┘

実際のプログラムでは、次のようにします。

if (eb_bind_appendix(&app, "/mnt/dict") != EB_SUCCESS) {
    printf("eb_bind_appendix() failed\n");
    return;
}

eb_bind_appendix() に渡す appendix のパス (この例では /mnt/dict) は appendix のトップディレクトリ、つまり catalog または catalogs ファイルのあるディレクトリを指定します。パスには、遠隔アクセス識別子 (例: ebnet://localhost/dict.app) を指定することも可能です。

EB_Appendix オブジェクトを使い終わったら、 eb_finalize_appendix() を呼んで後始末をします。オブジェクトは appendix との結び付きを解かれた状態に戻り、内部で割り当てられたメモリは解放され、開いていたファイルもすべて閉じられます。

eb_finalize_appendix(&app);
eb_finalize_appendix(app_pointer);

オブジェクトの領域を malloc() で確保した場合は、 eb_finalize_appendix() を呼んだ後ならば、オブジェクトの領域を安全に解放することができます。

free(app_pointer);

副本

CD-ROM と同様に、appendix にも副本が存在します。 appendix の副本も、副本コードを使って識別します。個々の副本コードは、appendix 内で同じものがないようになっています。

CD-ROM 書籍内のすべての副本の副本コードを取得する関数として eb_subbook_list() がありましたが、appendix にも eb_appendix_subbook_list() という同様の関数があります。

/* app が EB_Appendix のオブジェクトで、
 * すでに書籍に結び付けられていると仮定しています。*/
EB_Subbook_Code sub_codes[EB_MAX_SUBBOOKS];
int sub_count;

if (eb_appendix_subbook_list(&app, sub_codes, &sub_count)
    != EB_SUCCESS) {
    printf("eb_appendix_subbook_list() failed\n");
    return;
}

eb_appendix_subbook_list() が成功すると、書籍内のすべての副本コードが配列 sub_codes[] に格納されます。配列の先頭の副本コードは sub_codes[0] と表され、次のコードは sub_codes[1]、という具合になります。副本の個数は、sub_count に格納されます。

EB_Book と同様に EB_Appendix オブジェクトでも、結びつけられた CD-ROM 書籍の中の任意の副本から一つ選んで、選択中の副本 (current subbook) として指定することができます。複数の副本を、同時に選択することはできません。区切りコードや外字の代替文字列といった appendix 内のデータへのアクセスは、選択中の副本に対してだけ行えます。

以下は、先頭の副本 (sub_codes[0]) を選択する場合の例です。

/* app が EB_Appendix のオブジェクトで、
 * すでに書籍に結び付けられていると仮定しています。*/
if (eb_set_appendix_subbook(&app, sub_codes[0]) != EB_SUCCESS) {
    printf("eb_subbook_list() failed\n");
    return;
}

eb_bind_appendix() で EB_Appendix オブジェクトを appendix に結び付けた直後は、いずれの副本も選択されていない状態になっています。

本文の区切りコード

CD-ROM 書籍によっては、EB ライブラリが本文の表示を正しい位置で止められないことがあります (詳しくは、「区切りコードの問題」を参照のこと)。これは、本文の区切りコードの推測を EB ライブラリが誤ったために起こるのですが、appendix データを使うことで、正しい区切りコードを EB ライブラリに教えてやることができます。

CD-ROM 書籍の本文を取得する関数 eb_read_text() は第 2 引数に EB_Appendix * をとるのですが、ここに appendix オブジェクトを渡してやるようにします。

/* book, app は、それぞれ EB_Book
 * および EB_Appendix のオブジェクトで、どちらもすでに
 * 副本を選択中と仮定しています。*/
#define MAX_LENGTH 1000
char buffer[MAX_LENGTH + 1];
ssize_t text_length;

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

eb_read_text() は、渡された appendix オブジェクトが副本を選択済みで、かつ区切りコードの情報を持っていれば、その区切りコードを使用します。

外字の代替文字列

CD-ROM 書籍は、定義している外字の情報としてフォントのデータしか用意していません。つまり、その外字がどのような文字なのかをユーザに分かるようにするには、アプリケーションがフォントを表示するしかありません。しかしこれでは、テキストインターフェースを用いたアプリケーションでは、本文中の外字の部分がまったく分かりません。外字を多用している書籍では、本文が解読不能に近い状態になるかも知れません。

そこで EB ライブラリでは、外字の代替となる文字列を appendix 内で定義できるようにしています。 appendix が用意されている場合に限り、アプリケーションは外字のフォントを描画する代わりにその代替文字列を出力することにすれば、テキストインターフェースを用いたアプリケーションでも書籍が読み易くなります。

appendix に定義されている代替文字列を取り出す関数は、2 つあります。半角外字用の eb_narrow_alt_character_text() と全角外字用の eb_wide_alt_character_text() です。どちらも、使い方は変わりません。

以下の例では、半角外字の文字番号 0xa121 に対する代替文字列を buffer に格納しています。

/* app が EB_Appendix のオブジェクトで、
 * すでに副本を選択中であると仮定しています。*/
char buffer[EB_MAX_ALTERNATION_TEXT_LENGTH + 1];

if (eb_narrow_alt_character_text(&app, buffer, 0xa121)
    != EB_SUCCESS) {
    printf("eb_narrow_alt_character_text() failed\n");
    return;
}

外字は個々の副本に対して定義されているので、代替文字列を取り出すには、あらかじめ副本を選択しておく必要があります。外字のフォントを取り出す際は、これに加えて外字の「高さ」も選択しておく必要がありましたが、代替文字列には高さの概念がないので必要ありません。

代替文字列は最長で EB_MAX_ALTERNATION_TEXT_LENGTH バイト (= 31 バイト) です。ただし、この長さにはナル文字の分は含んでいないので、buffer はもう 1 バイト分余裕を持たせています。

データ型の詳細

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

#include <eb/appendix.h>

`EB_Appendix` 型

EB_Appendix 型は、一冊の CD-ROM 書籍を表します。 CD-ROM 書籍へのアクセスは、すべてこの型のオブジェクトを介して行います。同時に複数の CD-ROM 書籍にアクセスする際は、書籍一冊毎にオブジェクトを作る必要があります。

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

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

関数の詳細

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

#include <eb/appendix.h>

`void eb_initialize_appendix (EB_Appendix *app)`

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

`void eb_finalize_appendix (EB_Appendix *app)`

関数 eb_finalize_appendix() は、app が指す EB_Appendix オブジェクトの後始末を行います。

オブジェクトが割り当てて管理していたメモリはすべて解放され、ファイルディスクリプタもすべて閉じられます。オブジェクトが appendix と結び付いていた場合は、結び付きが解かれます。

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

`EB_Error_Code eb_bind_appendix (EB_Appendix app, const char path)`

関数 eb_bind_appendix() は、app の指す EB_Appendix オブジェクトを、パス path にある appendix に結び付けます。パスには、appendix のトップディレクトリか遠隔アクセス識別子を指定します。 appendix のトップディレクトリとは、catalog あるいは catalogs ファイルの存在するディレクトリを指します。

オブジェクトがすでにappendix に結び付いていた場合、その appendix との結び付きを解いてから、path にある appendix に結び付けます。

成功すると、関数は EB_SUCCESS を返します。このとき、副本は未選択の状態になります。失敗すると、オブジェクトを appendix との結び付きを解かれた状態にして、原因を示すエラーコードを返します。

`int eb_is_appendix_bound (EB_Appendix *app)`

関数 eb_is_appendix_bound() は、app が appendix に結び付いているかどうかを調べます。結び付いていれば 1 を返し、そうでなければ 0 を返します。

`EB_Error_Code eb_appendix_path (EB_Appendix app, char path)`

関数 eb_appendix_path() は、app に結び付いている appendix のパスもしくは遠隔アクセス識別子を、path の指す領域に書き込みます。

成功すると、関数は EB_SUCCESS を返します。失敗すると、path の指す領域に空文字列を書き込み、原因を示すエラーコードを返します。

app は、あらかじめ書籍に結び付いている必要があります。結びついていない場合は、EB_ERR_UNBOUND_BOOK を返します。

path に書き込むパス名のバイト数は、最長で EB_MAX_PATH_LENGTH になります。この長さは、末尾のナル文字を含みません。関数が返すパスは正規化された形になっているので、 eb_bind_appendix() に渡したときのものと同じとは限りません。たとえば、相対パスだった場合は、絶対パスに変換されます。

`EB_Error_Code eb_load_all_appendix_subbooks (EB_Appendix *app)`

関数 eb_load_all_appendix_subbooks() は、app 内のすべての副本を初期化します。通常、副本の初期化は、その副本が初めて選択されたときに自動的に行われますが、この関数は初期化を前倒しで行います。初期化の対象となるのは、この関数を呼び出した時点でまだ初期化していないすべての副本です。この関数は、スタンドアロンで動作するサーバアプリケーションなどで有効です。クライアントからの接続を受ける前にこの関数を呼ぶことで、副本の初期化のためにクライアントを待たせなくて済みます。

app は、あらかじめ appendix に結び付けられていなくてはなりません。結びついていない場合は、EB_ERR_UNBOUND_APP を返します。

この関数を呼び出すと、app は、副本を選択していない状態になります。

`EB_Error_Code eb_appendix_subbook_list (EB_Book app, EB_Subbook_Code subbook_list, int *subbook_count)`

関数 eb_appendix_subbook_list() は、app 内のすべて副本の副本コードを EB_Subbook_Code 型の配列にして、 subbook_list の指す領域に書き込みます。配列は、最大で EB_MAX_SUBBOOKS 個の要素を持ちます。加えて、appendix が収録している副本の個数を subbook_count の指す領域に書き込みます。

成功すると、関数は EB_SUCCESS を返します。失敗すると、subbook_count の指す領域に 0 を書き込み、原因を示すエラーコードを返します。

app は、あらかじめ appendix に結び付けられていなくてはなりません。結びついていない場合は、EB_ERR_UNBOUND_APP を返します。

`EB_Error_Code eb_appendix_subbook (EB_Book app, EB_Subbook_Code subbook_code)`

関数 eb_appendix_subbook() は、app が選択中の副本の副本コードを subbook_code の指す領域に書き込みます。

あらかじめ、app はいずれかの副本を選択していなくてはなりません。選択していない場合は、EB_ERR_NO_CUR_APPSUB を返します。

`EB_Error_Code eb_appendix_subbook_directory (EB_Book app, char directory)`

関数 eb_appendix_subbook_directory() は、app 内で現在選択中の副本のデータファイルを収めたディレクトリ名を、 directory の指す領域に書き込みます。

成功すると、関数は EB_SUCCESS を返します。失敗すると、directory の指す領域に空文字列を書き込み、原因にを示すエラーコードを返します。

あらかじめ、app 内のいずれかの副本が選択されていなくてはなりません。選択していない場合は、EB_ERR_NO_CUR_APPSUB を返します。

`EB_Error_Code eb_appendix_subbook_directory2 (EB_Book app, EB_Subbook_Code subbook_code, char directory)`

eb_appendix_subbook_directory() と似ていますが、選択中の副本ではなく、引数 subbook_code で指定された副本のディレクトリ名を書き込む点が異なります。

app は副本を選択していなくても構いませんが、あらかじめ appendix に結び付けられていなければなりません。結びついていない場合は、EB_ERR_UNBOUND_APP を返します。

`EB_Error_Code eb_set_appendix_subbook (EB_Book *app, EB_Subbook_Code code)`

関数 eb_set_appendix_subbook() は、app の副本 code を選択します。すでに副本を選択していた場合は、いったん未選択の状態にしてから副本 subbook_code を選択します。

あらかじめ、app は appendix に結び付けられていなければなりません。結びついていない場合は、EB_ERR_UNBOUND_APP を返します。

`void eb_unset_appendix_subbook (EB_Book *app)`

関数 eb_unset_appendix_subbook() は、app が選択している副本を未選択の状態にします。 app が appendix に結び付いていないか、副本が選択されていない場合は、何もしません。

`int eb_have_stop_code (EB_Book *app)`

関数 eb_have_stop_code() は、app が選択中の副本で区切りコードが定義されているかどうかを調べます。

定義していれば 1 を返します。定義していないか、そもそも副本が選択されていない場合は 0 を返します。

`EB_Error_Code eb_stop_code (EB_Book app, int stop_code)`

関数 eb_stop_code() は、app が選択中の副本で定義している区切りコードを stop_code の指す領域に書き込みます。 stop_code[0], stop_code[1] に、区切りコードの値としてそれぞれ 0x0000 ～ 0xffff が書き込まれます。

成功すると、関数は EB_SUCCESS を返します。失敗すると、関数は stop_code[0] と stop_code[1] に -1 を書き込み、原因を示すエラーコードを返します。

あらかじめ、app は副本を選択していなくてはなりません。選択していない場合は、EB_ERR_NO_CUR_APPSUB を返します。副本が区切りコードを定義していない場合は、EB_ERR_NO_STOPCODE を返します。

`int eb_have_narrow_alt (EB_Book *app)`

`int eb_have_wide_alt (EB_Book *app)`

関数 eb_have_narrow_alt() は、選択中の副本が半角外字に対する代替文字列を定義しているかどうかを調べます。同様に、関数 eb_have_wide_alt() は、全角外字に対する代替文字列を定義しているかどうかを調べます。

定義していれば 1 を、定義していなければ 0 を返します。 app が副本を選択していない場合も 0 を返します。

`EB_Error_Code eb_narrow_alt_start (EB_Book app, int start)`

`EB_Error_Code eb_wide_alt_start (EB_Book app, int start)`

関数 eb_narrow_alt_start() は、app が選択中の副本における半角外字に対する代替文字列の定義範囲を調べ、先頭の文字番号 (半角外字の文字番号の中で最小のもの) を start の指す領域に書き込みます。

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

あらかじめ、app は副本を選択していなくてはなりません。選択していない場合は、EB_ERR_NO_CUR_APPSUB を返します。副本が半角外字に対する代替文字列を定義していない場合は、 EB_ERR_NO_ALT を返します。

関数 eb_wide_font_start() は、半角外字ではなく全角外字について調べるという点を除いて、eb_narrow_font_start() と同じです。

`EB_Error_Code eb_narrow_alt_end (EB_Book app, int end)`

`EB_Error_Code eb_wide_alt_end (EB_Book app, int end)`

関数 eb_narrow_alt_end() は、app が選択中の副本における半角外字に対する代替文字列の定義範囲を調べ、最後の文字番号 (半角外字の文字番号の中で最大のもの) を start の指す領域に書き込みます。

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

関数 eb_wide_font_start() は、半角外字ではなく全角外字について調べるという点を除いて、eb_narrow_font_start() と同じです。

`EB_Error_Code eb_narrow_alt_character_text (EB_Book app, int character_number, char text)`

`EB_Error_Code eb_wide_alt_character_text (EB_Book app, int character_number, char text)`

関数 eb_narrow_alt_character_text() は、book が選択中の副本で定義している、半角外字の代替文字列を取り出します。外字の文字番号を、character_number で指定します。

成功すると、関数は代替文字列を text の指す領域に書き込み、 EB_SUCCESS を返します。失敗すると、text の指す領域に空文字列を書き込み、原因を示すエラーコードを返します。

代替文字列は最長で EB_MAX_ALTERNATION_TEXT_LENGTH バイト (= 31 バイト) です。ただし、この長さにはナル文字の分は含んでいないので、text の領域にはもう 1 バイト分必要です。

代替文字列がどの文字コードで書かれているかは、appendix の中には記録されていません。しかし、appendix は必ず特定の書籍に対応して作成されるものなので、書籍の文字コードから次のように判断すれば、問題ないでしょう。

書籍が ISO 8859-1 で書かれている場合は、代替文字列も ISO 8859-1
それ以外の場合、代替文字列は日本語 EUC

あらかじめ、app は副本を選択していなくてはなりません。選択していない場合は、EB_ERR_NO_CUR_APPSUB を返します。文字番号 character_number が外字の定義範囲外にある場合は、 EB_ERR_NO_SUCH_CHAR_TEXT を返します。

副本が半角外字に対する代替文字列を (character_number に限らずまったく) 定義していない場合は、EB_ERR_NO_ALT を返します。そうではなく、一部の文字番号については半角外字に対する代替文字列を定義しているものの、character_number に対する代替文字列は存在しない場合、関数は EB_SUCCESS を返し、text の指す領域には空文字列が書き込まれます。

関数 eb_wide_alt_character_text() は、半角外字ではなく全角外字に対する代替文字列を取り出すという点を除いて、 eb_narrow_alt_character_text() と同じです。

`EB_Error_Code eb_backward_narrow_alt_character (EB_Book book, int n, int character_number)`

`EB_Error_Code eb_backward_wide_alt_character (EB_Book book, int n, int character_number)`

関数 eb_forward_narrow_alt_character() は、app が選択中の副本において定義されている、半角外字に対する代替文字列の文字番号 character_number の n 個後ろに位置する文字の文字番号を取得します。

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

n 個後ろにもう外字がない場合や、呼び出した際に character_number の指す領域に書き込んであった文字番号が外字の定義範囲外にある場合は EB_ERR_NO_SUCH_CHAR_TEXT を返します。

n には負の数を指定することもできます。この場合、次の呼び出しと等価になります。

/* n < 0 とする */
eb_backward_narrow_font_character (book, -n, character_number);

関数 eb_forward_wide_alt_character() は、半角外字ではなく全角外字について操作するという点を除いて、 eb_forward_narrow_alt_character() と同じです。

サンプルプログラム

サーバ上の書籍一覧

EBNET サーバから遠隔アクセスを行う際、サーバがそのクライアントに対してアクセスを許可している書籍や appendix データの一覧を取得することができます。

このとき、EBNET サーバを指定する遠隔アクセス記述子には、特定の書籍や appendix データに対するアクセスとは異なり、書籍名は指定しません。すなわち、一般形は次のようになります。

ebnet://ホスト:ポート/

末尾の `/' はなくても構いません。 : とそれに続くポート番号は省略可能で、その場合は 22010 番ポートを利用することを意味します。

ebinfo コマンドの --book-list オプション指定時の挙動は、EB ライブラリのこの機能によって実装されています。 (ebinfo についての詳細は、 @pxref{Book list on EBNET server, , EBNET サーバの書籍一覧, ebinfo-ja, ebinfo-ja}。)

% ebinfo --book-list ebnet://localhost
名前             題名
encycl           ブラウンコンサイス百科事典
encycl.app       ブラウンコンサイス百科事典 (appendix)
crossword        クロスワードパズル辞典
travel           ワールドトラベルガイド

名前の末尾が .app になっているものは appendix データで、その他は書籍本体です。この例の書籍 encycl に対してアクセスするなら、遠隔アクセス識別子は ebnet://localhost/encycl になります。

なお、クライアントに対してアクセスを許可していない書籍や appendix データは、サーが側で一覧から除外されます。

`EB_BookList` オブジェクト

EBNET サーバの提供する書籍および appendix データの一覧を取得するには、まず EB_BookList 型のオブジェクトを用意する必要があります。

EB_BookList bl;

オブジェクトの領域は、malloc() で確保しても構いません。

EB_BookList *bl_pointer;

bl_pointer = (EB_BookList *) malloc(sizeof(EB_BookList));

EB_Book オブジェクトと同様に、EB_BookList オブジェクトも使う前に中身を初期化する必要があります。これは、eb_initialize_booklist() という関数で行います。

eb_initialize_booklist(&bl);
eb_initialize_booklist(bl_pointer);

初期化が完了したら、特定のサーバとオブジェクトを結びつけます。たとえば、ebnet://localhost で表されるサーバに対して、オブジェクトを結びつけるには次のようにします。

if (eb_bind_booklist(&bl, "ebnet://localhost") != EB_SUCCESS) {
    printf("eb_bind_booklist() failed\n");
    return;
}

これはちょうど、EB_Book オブジェクトに対して eb_bind() を呼ぶのと同じです。

こうして、ようやく書籍一覧の情報を取り出すことができます。これには eb_booklist_book_count(), eb_booklist_book_name(), eb_booklist_book_title() という 3 つの関数を使用します。これらの関数はそれぞれ、クライアントがアクセス可能な書籍の数、各書籍および appendix データの名称 (アクセス識別子として指定する名前)、各書籍と appendix データの題名を得ることができます。

char *name, *title;
int count, i;

count = eb_booklist_book_count(&bl);
for (i = 0; i < count; i++) {
    if (eb_booklist_book_name(&bl, i, &name) != EB_SUCCESS) {
        printf("eb_booklist_book_name(%d) failed\n", i);
        return;
    }
    if (eb_booklist_book_title(&bl, i, &title) != EB_SUCCESS) {
        printf("eb_booklist_book_title(%d) failed\n", i);
        return;
    }
    printf("name = %s, title = %s\n", name, title);
}

EB_BookList オブジェクトを使い終わったら、必ず後始末を行います。

eb_finalize_booklist(&bl);
eb_finalize_booklist(bl_pointer);

オブジェクトの領域を malloc() で確保した場合は、 eb_finalize_booklist() を呼んだ後ならば、オブジェクトの領域を安全に解放することができます。

free(bl_pointer);

データ型の詳細

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

#include <eb/booklist.h>

`EB_BookList` 型

EB_BookList 型は、EBNET サーバ上が使っている書籍および appendix の一覧を取得する際に用いるオクジェクトの型です。

EB_BookList オブジェクトを使用する際は、まずそのオブジェクトに対して eb_initialize_booklist() を呼んで初期化する必要があります。

関数の詳細

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

#include <eb/booklist.h>

`void eb_initialize_booklist (EB_BookList *bl)`

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

`EB_Error_Code eb_bind_booklist (EB_BookList bl, const char path)`

関数 eb_bind_booklist() は、app の指す EB_BookList オブジェクトを、遠隔アクセス記述子 path で指定された EBNET サーバに結び付けます。

オブジェクトがすでにサーバに結び付いていた場合、そのサーバとの結び付きを解いてから、path にあるサーバに結び付けます。

成功すると、関数は EB_SUCCESS を返します。失敗すると、オブジェクトをサーバとの結び付きを解かれた状態にして、原因を示すエラーコードを返します。

path は、EB_MAX_PATH_LENGTH バイトに収まていなくてはなりません。これを超えると、EB_ERR_TOO_LONG_FILE_NAME を返します。また、書籍名を指定していない遠隔アクセス記述子でなければなりません。それ以外の形式だと、EB_ERR_BAD_FILE_NAME を返します。

使用している EB ライブラリのバイナリが、遠隔アクセスに非対応のものである場合、EB_ERR_EBNET_UNSUPPORTED が返ります。

`void eb_finalize_booklist (EB_BookList *bl)`

関数 eb_finalize_booklist() は、bl が指す EB_BookList オブジェクトの後始末を行います。

オブジェクトが割り当てて管理していたメモリはすべて解放され、ファイルディスクリプタもすべて閉じられます。オブジェクトが EBNET サーバと結び付いていた場合は、結び付きが解かれます。

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

`int eb_booklist_book_count (EB_BookList *bl)`

関数 eb_booklist_book_count() は、EBNET サーバがこのクライアントに対してアクセスを許可している書籍および appendix データの数を取得します。

オブジェクト bl の指す EB_BookList オブジェクトは、あらかじめ EBNET サーバに結びついている必要があります。結びついていない場合は、EB_ERR_UNBOUND_BOOKLIST を返します。

`EB_Error_Code eb_booklist_book_name (EB_BookList *bl, int i, char **name)`

`EB_Error_Code eb_booklist_book_title (EB_BookList *bl, int i, char **title)`

関数 eb_booklist_book_name() は、EBNET サーバの書籍や appendix データの名称を取得します。ここで言う「名称」とは、遠隔アクセス識別子で指定する書籍名のことです。つまり、ebnet://localhost/dict の dict の部分を指します。同様に、関数 eb_booklist_book_title() は、書籍や appendix の題名を取得します。

いずれの関数も、EBNET サーバ上の何番目の書籍もしくは appendix の情報を取得するのかを、引数 i で指定します。先頭は 1 番目ではなく 0 番目になります。

成功すると、関数は書籍の名称、題名へのポインタを *name, *title に書き込み、EB_SUCCESS を返します。なお、このポインタ値はオブジェクト bl が保持している文字列を指すようになっています。 bl に対して eb_finalize_booklist() を呼んでしまうと、この文字列も参照不可能になってしまいますので、注意して下さい。

オブジェクト bl の指す EB_BookList オブジェクトは、あらかじめ EBNET サーバに結びついている必要があります。結びついていない場合は、EB_ERR_UNBOUND_BOOKLIST を返します。また、i は 0 以上かつサーバが提供している書籍および appendix の総数未満でなければなりません。これ以外の値のときは、EB_ERR_NO_SUCH_BOOK が返ります。