9432 lines
313 KiB
HTML
9432 lines
313 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
|
||
<!-- #file "eb.html" -->
|
||
<html lang="ja">
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=euc-jp">
|
||
<link rel="stylesheet" type="text/css" href="eb.css">
|
||
<link rev="made" href="mailto:m-kasahr@sra.co.jp">
|
||
<title>EB ライブラリ</title>
|
||
</head>
|
||
|
||
<body>
|
||
<h1><a name="toc">EB ライブラリ</a></h1>
|
||
<p>
|
||
この文書は、EB ライブラリバージョン
|
||
<!-- #include "version.html" -->
|
||
に対応しています。
|
||
</p>
|
||
|
||
<p>
|
||
目次:
|
||
</p>
|
||
|
||
<!-- #include "eb-toc.html" -->
|
||
|
||
<p>
|
||
Copyright (c) 2001-2006 Motoyuki Kasahara
|
||
</p>
|
||
|
||
<!-- ================================================================ -->
|
||
<h2><a name="introduction">はじめに</a></h2>
|
||
|
||
<p>
|
||
EB ライブラリは CD-ROM 書籍にアクセスするための C のライブラリです。
|
||
UNIX 系 OS および Windows (2000以降) のシステム上で動作させることが
|
||
できます。
|
||
</p>
|
||
|
||
<p>
|
||
EB ライブラリは EB, EBG, EBXA, EBXA-C, S-EBXA および EPWING 形式の
|
||
CD-ROM 書籍に対応しています。
|
||
これらは、主に日本で販売されている辞書に使われています。
|
||
CD-ROM 書籍自体は ISO 9660 形式になっていますので、他の ISO 9660 形式
|
||
と同じ要領でマウントすることができます。
|
||
</p>
|
||
|
||
<p>
|
||
本書は、EB ライブラリを使ってアプリケーションプログラムを作成する
|
||
開発者向けに、ライブラリの仕様を解説した文書です。
|
||
そして、ライブラリの公式な参照マニュアルでもあります。
|
||
読み進めるにあたって、読者は EB ライブラリおよび CD-ROM 書籍の内部構造
|
||
について知っている必要はありませんが、電子ブックか EPWING を利用して、
|
||
実際に CD-ROM 書籍がどのようなものかを理解しておくことをお薦めします。
|
||
また、C 言語によるプログラミングについては、十分に理解していることを前提
|
||
とします。
|
||
</p>
|
||
|
||
<p>
|
||
本書の内容に沿って EB ライブラリを使ったアプリケーションプログラムを
|
||
作成するには、お使用いのシステムに EB ライブラリと C コンパイラを
|
||
インストールしておいて下さい。
|
||
なお、本書では主に UNIX 系 OS を使用した場合について、記述しています。
|
||
</p>
|
||
|
||
<p>
|
||
EB ライブラリはフリーソフトウェアです。ソースコードおよびバイナリを、
|
||
いわゆる Modified BSD ライセンスの下で使用することが可能です。
|
||
(バージョン 4.1 よりも前のものは、GPL を採用していました。)
|
||
詳しくは、ソースコードに付属している COPYING という英文のファイルを参照
|
||
して下さい。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="electronic-book-and-epwing">電子ブックと EPWING について</a></h3>
|
||
|
||
<p>
|
||
電子ブックと EPWING は、いずれも主に日本で使われている電子書籍の
|
||
データ形式の名称で、CD-ROM に収めた形で数々の書籍が市販されています。
|
||
CD-ROM は ISO 9660 形式 なので、CD-ROM ドライブが扱えるシステムであれば、
|
||
容易にアクセスすることができます。
|
||
電子書籍のデータ形式とはいっても、実際は辞書向けに特化した構造となって
|
||
おり、市販されている書籍も辞書の類が圧倒的に多いようです。
|
||
</p>
|
||
|
||
<p>
|
||
電子ブック、EPWING ともに、データ形式に関する規格の全容は一般公開されて
|
||
いませんが、EPWING ついては規格の一部が日本工業規格 JIS X 4081
|
||
「電子出版検索データ構造」として公開されています。
|
||
さらに、EPWING と電子ブックのデータ形式は、酷似していることが知られて
|
||
います。
|
||
</p>
|
||
|
||
<p>
|
||
EB ライブラリの開発者も、電子ブック、EPWING 規格の全容は知りません。
|
||
EB ライブラリでは JIS X 4081 の記述をもとに、電子ブック、EPWING を読める
|
||
ようにしてあります。
|
||
しかしながら、規格の全容が分からない状態で開発しているため、残念ながら
|
||
一部に正しく読めない書籍が存在します。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="construction-of-this-book">本書の構成について</a></h3>
|
||
|
||
<p>
|
||
次章「EB ライブラリの特徴」では、EB ライブラリが対応している機能、対応
|
||
していない機能について、簡単に説明します。
|
||
また、ライブラリの概略に関して、最初に知っておいたほうが良いと思われる
|
||
事柄をいくつか説明しています。
|
||
</p>
|
||
|
||
<p>
|
||
さらに次の章「プログラムのコンパイル方法」では、EB ライブラリを利用した
|
||
プログラムのコンパイル方法を説明します。
|
||
本書のサンプルプログラムをコンパイルするために必要な情報も、この章に
|
||
記してあります。
|
||
</p>
|
||
|
||
<p>
|
||
そして、その次の章「ライブラリの初期化と後始末」からが、実際の
|
||
EB ライブラリのプログラミングの解説となります。
|
||
それぞれの章は、次のような節から構成されています。
|
||
ただし、章によっては一部の節がない場合もあります。
|
||
</p>
|
||
|
||
<dl>
|
||
<dt>解説</dt>
|
||
<dd>
|
||
その章で解説する機能や概念についての基礎知識、EB ライブラリの仕様の
|
||
概要について解説しています。
|
||
|
||
<dt>サンプルプログラム</dt>
|
||
<dd>
|
||
「解説」ではプログラムの断片だけを示すことが多いので、動作可能な
|
||
プログラムのサンプルをここで示します。
|
||
|
||
<dt>データ型の詳細</dt>
|
||
<dd>
|
||
データ型や関数、定数値などについての参照マニュアルです。
|
||
</dl>
|
||
|
||
<!-- ================================================================ -->
|
||
<h2><a name="features">EB ライブラリの特徴</a></h2>
|
||
|
||
<p>
|
||
前に述べたように、EB ライブラリは、電子ブック (EB, EBG, EBXA, EBXA-C, S-EBXA)
|
||
と EPWING 形式の CD-ROM 書籍に対応しています。
|
||
</p>
|
||
|
||
<p>
|
||
EB ライブラリは、これらの CD-ROM 書籍に対して、次の処理を行うことが
|
||
できます。
|
||
</p>
|
||
|
||
<ul>
|
||
<li>前方一致検索
|
||
<li>後方一致検索
|
||
<li>完全一致検索
|
||
<li>条件検索
|
||
<li>複合検索
|
||
<li>見出しデータの取得
|
||
<li>本文データの取得
|
||
<li>メニューの取得
|
||
<li>著作権表示の取得
|
||
<li>カラー図版データの取得 (ただし EPWING のみ)
|
||
<li>モノクロ図版データの取得
|
||
<li>外字データの取得
|
||
<li>動画データの取得
|
||
</ul>
|
||
|
||
<p>
|
||
この章では、EB ライブラリの概要に関して、あらかじめ知っておいて頂いた
|
||
ほうが良いと思われるその他の事柄について、何点か説明します。
|
||
</p>
|
||
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="header-files">ヘッダファイル</a></h3>
|
||
|
||
<p>
|
||
EB ライブラリには、いくつかのヘッダファイルが用意されています。
|
||
</p>
|
||
|
||
<dl>
|
||
<dt><code>appendix.h</code></dt>
|
||
<dd>
|
||
appendix (付録) に関連した宣言、定義を行う。
|
||
<dt><code>binary.h</code></dt>
|
||
<dd>
|
||
バイナリデータに関連した宣言、定義を行う。
|
||
<dt><code>eb.h</code></dt>
|
||
<dd>
|
||
EB ライブラリの基本ヘッダファイル。
|
||
<dt><code>error.h</code></dt>
|
||
<dd>
|
||
エラーコードに関連した宣言、定義を行う。
|
||
<dt><code>font.h</code></dt>
|
||
<dd>
|
||
外字に関連した宣言、定義を行う。
|
||
<dt><code>text.h</code></dt>
|
||
<dd>
|
||
テキストデータ (本文、見出しなど) に関連した宣言、定義を行う。
|
||
</dl>
|
||
|
||
<p>
|
||
これ以外にもいくつかのファイルがインストールされますが、上に挙げた
|
||
ヘッダファイルから読み込まれるもので、アプリケーションプログラムが
|
||
直接読み込む必要はありません。
|
||
</p>
|
||
|
||
<p>
|
||
アプリケーションプログラムは、EB ライブラリを使う際にこのヘッダファイル
|
||
をファイルの先頭付近で読み込みます。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
#include <eb/eb.h>
|
||
#include <eb/error.h>
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
<code>eb.h</code> ではなく、<code>eb/eb.h</code> を読み込むようにして下さい。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="character-code">文字コード</a></h3>
|
||
|
||
<p>
|
||
EB ライブラリでは、CD-ROM 書籍内のデータを文字列にしてアプリケーション
|
||
に渡す際の文字コードを規定しています。
|
||
</p>
|
||
|
||
<p>
|
||
EBG (海外の電子ブック) については、データが ISO 8859-1 (ラテン文字 1、
|
||
ただし制御文字を除く) で書かれているため、データのやり取りも ISO 8859-1
|
||
で行います。
|
||
ただし、外字だけは 2 バイトで表現し、0x0101 ～ 0x1efe の領域を使用します。
|
||
(外字領域の下位 16 ビットは 0x01 ～ 0xfe の範囲を使用します。)
|
||
</p>
|
||
|
||
<p>
|
||
EBG, EBXA-C を除いた電子ブック、および EPWING については、データが
|
||
JIS X 0208 (日本語のかな漢字) で書かれており、JIS X 0208 を 0x2121 ～
|
||
0x7e7e にマッピングし、0xa121 ～ 0xfe7e を外字領域にしています (下図)。
|
||
</p>
|
||
|
||
<blockquote>
|
||
<pre>
|
||
上位８ビット
|
||
|
||
００ ２１ ７ｅ ａ１ ｆｅ
|
||
００┌──┬─────┬──┬─────┬┐
|
||
│ │ │ │ ││
|
||
２１├──┼─────┼──┼─────┼┤
|
||
│ │ │ │ ││
|
||
│ │ＪＩＳ Ｘ│ │ 外字 ││
|
||
│ │０２０８ │ │ ││
|
||
│ │ │ │ ││
|
||
７ｅ├──┼─────┼──┼─────┼┤
|
||
下位８ビット │ │ │ │ ││
|
||
ａ１├──┼─────┼──┼─────┼┤
|
||
│ │ │ │ ││
|
||
│ │ │ │ ││
|
||
│ │ │ │ ││
|
||
│ │ │ │ ││
|
||
ｆｅ├──┼─────┼──┼─────┼┤
|
||
└──┴─────┴──┴─────┴┘
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
EB ライブラリでは JIS X 0208 部分を日本語 EUC (EUC-JP) にエンコード
|
||
して、アプリケーションとのやり取りも日本語 EUC で行います。
|
||
したがって、JIS X 0208 部分は 0xa1a1 ～ 0xfefe にマッピングされます。
|
||
</p>
|
||
|
||
<p>
|
||
EBXA-C (中日・日中辞書の電子ブック) については、データが JIS X 0208
|
||
(日本語のかな漢字) と GB 2312 (中国語の簡体字) で書かれており、
|
||
JIS X 0208 を 0x2121 ～ 0x7e7e にマッピング、
|
||
GB 2312 を 0x21a1 ～ 0x7efe にマッピングし、
|
||
0xa121 ～ 0xfe7e を外字領域にしています (下図)。
|
||
</p>
|
||
|
||
<blockquote>
|
||
<pre>
|
||
上位８ビット
|
||
|
||
００ ２１ ７ｅ ａ１ ｆｅ
|
||
００┌──┬─────┬──┬─────┬┐
|
||
│ │ │ │ ││
|
||
２１├──┼─────┼──┼─────┼┤
|
||
│ │ │ │ ││
|
||
│ │ＪＩＳ Ｘ│ │ 外字 ││
|
||
│ │０２０８ │ │ ││
|
||
│ │ │ │ ││
|
||
７ｅ├──┼─────┼──┼─────┼┤
|
||
下位８ビット │ │ │ │ ││
|
||
ａ１├──┼─────┼──┼─────┼┤
|
||
│ │ │ │ ││
|
||
│ │ＧＢ │ │ ││
|
||
│ │２３１２ │ │ ││
|
||
│ │ │ │ ││
|
||
ｆｅ├──┼─────┼──┼─────┼┤
|
||
└──┴─────┴──┴─────┴┘
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
EB ライブラリでは、アプリケーションとのやり取りに使う文字コードは、
|
||
日本語 EUC および中国語 EUC (EUC-ZH) です。
|
||
したがって、そのままでは JIS X 0208 と GB 2312 が 0xa1a1 ～ 0xfefe に
|
||
マッピングされ、衝突してしまいます。
|
||
この問題をどう回避するのかは、アプリケーション側で決める必要があります
|
||
(詳しくは、<a href="#hook-and-character-code">「フックと文字コードの関係」</a> を参照のこと)。
|
||
</p>
|
||
|
||
<p>
|
||
電子ブック、EPWING ともに、外字については、アプリケーション側でどう
|
||
扱うかを決める必要があります。
|
||
外字について詳しくは <a href="#local-character">「外字」</a> を参照のこと。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="compressed-book">圧縮された書籍について</a></h3>
|
||
|
||
<p>
|
||
EB ライブラは、データを圧縮して収録した書籍を扱うことができます。
|
||
今のところ、次の 4 種類の圧縮方法に対応しています。
|
||
</p>
|
||
|
||
<dl>
|
||
<dt><code>ebzip</code> 圧縮形式</dt>
|
||
<dd>
|
||
EB ライブラリ独自の圧縮形式です。
|
||
付属の <code>ebzip</code> コマンドを使うと、この形式で圧縮した書籍を作れます。
|
||
|
||
<dt>EPWING V4, V5 形式</dt>
|
||
<dd>
|
||
市販の EPWING V4, V5 の書籍の一部に、この形式で圧縮したものがあります。
|
||
|
||
<dt>EPWING V6 形式</dt>
|
||
<dd>
|
||
市販の EPWING V6 の書籍の一部に、この形式で圧縮したものがあります。
|
||
EPWING V4, V5 形式の改良型です。
|
||
|
||
<dt>S-EBXA 形式</dt>
|
||
<dd>
|
||
市販の S-EBXA の書籍の一部に、この形式で圧縮したものがあります。
|
||
</dl>
|
||
|
||
<p>
|
||
データの伸長は EB ライブラリ側で自動的に行われるため、
|
||
アプリケーションプログラムからは、アクセスしている書籍が圧縮されているか
|
||
どうか分かりません。
|
||
アプリケーションプログラムは、書籍が圧縮されているかどうかで処理を変える
|
||
必要はありません。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="remote-access">遠隔ホスト上の書籍について</a></h3>
|
||
|
||
<p>
|
||
バージョン 4.0 から、EB ライブラリは他のホストの書籍にアクセスできる
|
||
ようになりました。
|
||
</p>
|
||
|
||
<p>
|
||
遠隔アクセスの処理はすべて EB ライブラリ側で行われますので、
|
||
アプリケーションプログラムは、書籍が自分のホスト上にあるかどうかで、
|
||
EB ライブラリの呼び出し手順を変える必要はありません。
|
||
</p>
|
||
|
||
<p>
|
||
ただし、他のホストからアクセスすると、処理速度は非常に遅くなります。
|
||
そのため、効率良く処理できるよう、アプリケーションの処理方法を工夫すべき
|
||
状況が生じることはあるかも知れません。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="system-requirements">システムの要件</a></h3>
|
||
|
||
<p>
|
||
アプリケーションプログラムのコンパイルに用いるコンパイラには、
|
||
ANSI (ANSI X3.159-1989, ISO/IEC 9899-1990) 対応のものを対象としています。
|
||
また、システムには POSIX.1 (IEEE Std. 1003.2-1990, ISO/IEC 9945-1:1990)
|
||
準拠ないし互換のものを対象としています。
|
||
</p>
|
||
|
||
<p>
|
||
永らく EB ライブラリでは、古いコンパイラや UNIX 系システムへの対応も
|
||
それなりに行われていましたが、バージョン 4.1 からは対応を打ち切っています。
|
||
特に ANSI 対応のコンパイラは必須ですので、ご注意ください。
|
||
</p>
|
||
|
||
<!-- ================================================================ -->
|
||
<h2><a name="compilation">プログラムのコンパイル方法</a></h2>
|
||
|
||
<p>
|
||
本章では、EB ライブラリを利用したプログラムのコンパイルの仕方について、
|
||
2 通りの方法を説明します。
|
||
</p>
|
||
|
||
<p>
|
||
一つ目は、ごく私的な、小規模のプログラムをコンパイルする際に向いている
|
||
てっとり早くコンパイルするための方法です。
|
||
EB ライブラリの使い方を覚える目的で簡単なプログラムを組む際は、こちら
|
||
が良いでしょう。
|
||
</p>
|
||
|
||
<p>
|
||
二つ目は、EB ライブラリを組み込んだアプリケーションをフリーソフトウェア
|
||
としてリリースする際に向いている方法です。
|
||
EB ライブラリには、GNU Autoconf, Automake, Libtool を併用する仕組みを
|
||
用意してありますので、これらを使ったコンパイル方法について説明します。
|
||
</p>
|
||
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="compilation-simple-way">てっとり早いコンパイル方法</a></h3>
|
||
|
||
<p>
|
||
アプリケーションプログラムをコンパイルする際は、ヘッダファイルの
|
||
ディレクトリ位置を C コンパイラに教えてやる必要があるかも知れません。
|
||
一般に UNIX の C コンパイラでは、<samp>-I</samp> オプションで位置を指定
|
||
します。
|
||
</p>
|
||
|
||
<blockquote>
|
||
<pre>
|
||
cc -I/usr/local/include -c sample.c
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
<code>/usr/local/include/eb</code> ではなく、その一つ上を指定します
|
||
(<a href="#header-files">「ヘッダファイル」</a> を参照のこと)。
|
||
</p>
|
||
|
||
<p>
|
||
次に、リンクして実行バイナリを生成する工程ですが、
|
||
以下に記したライブラリの一部、もしくは全部をリンクします。
|
||
括弧内は、ライブラリのファイル名です (ただし、<code>.a</code> や
|
||
<code>.so</code> といった接尾子は省略)。
|
||
</p>
|
||
|
||
<dl>
|
||
<dt>EB ライブラリ (libeb)</dt>
|
||
<dd>
|
||
EB ライブラリの本体です。このライブラリは必須です。
|
||
|
||
<dt>zlib (libz)</dt>
|
||
<dd>
|
||
圧縮と伸長を行うライブラリです
|
||
(詳しくは @url{http://www.gzip.org/zlib/})。
|
||
<code>ebzip</code> コマンドで圧縮した辞書を扱うために使います。
|
||
このライブラリは必須です。
|
||
EB ライブラリのソースコードには zlib も収録されています。
|
||
システムに zlib が インストールされていなければ、EB ライブラリを
|
||
インストールする際に、zlib も自動的にインストールされます。
|
||
|
||
<dt>gettext ライブラリ (libintl)</dt>
|
||
<dd>
|
||
メッセージの国際化機能 (NLS) を提供するライブラリです
|
||
メッセージの国際化機能を有効にして EB ライブラリをコンパイルしている
|
||
場合は、必要になるかも知れません。
|
||
gettext の実装は何種類かありますが、EB ライブラリで使用できるのは
|
||
メッセージカタログの形式が GNU gettext 互換のものだけです。
|
||
|
||
メッセージの国際化機能を有効にしている場合でも、OS の標準 C ライブラリ
|
||
として glibc を採用しているシステムでは、指定する必要はありません。
|
||
|
||
<dt>iconv ライブラリ</dt>
|
||
<dd>
|
||
文字コード変換のライブラリです。
|
||
gettext ライブラリをリンクする場合、一緒に必要となるかも知れません。
|
||
iconv の実装も何種類かあり、OS によっては最初から添付されています。
|
||
</dl>
|
||
|
||
<p>
|
||
必要なライブラリファイルの名称を、C コンパイラに指定してやります。
|
||
加えて、ファイルの置かれているディレクトリ位置を、C コンパイラに教える
|
||
必要があるかも知れません。
|
||
一般に UNIX の C コンパイラでは、<samp>-L</samp> オプションでディレクトリ
|
||
位置を指定し、<samp>-l</samp> オプションでライブラリのファイル名を指定
|
||
します。
|
||
</p>
|
||
|
||
<blockquote>
|
||
<pre>
|
||
cc sample.o -L/usr/local/lib -leb -lz -lintl -liconv
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
ただし、共有ライブラリをリンクする場合は、実行時におけるライブラリの
|
||
検索パスも合わせて指定する必要があるかも知れません。
|
||
</p>
|
||
|
||
<blockquote>
|
||
<pre>
|
||
cc sample.o -R/usr/local/lib -L/usr/local/lib -leb -lz -lintl -liconv
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
C コンパイラの使い方に関しての詳細は、C コンパイラのマニュアルを参照
|
||
して下さい。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="compilation-with-autoconf">Autoconf を併用したコンパイル方法</a></h3>
|
||
|
||
<p>
|
||
作業の前に、Autoconf, Automake, Libtool は、あらかじめインストールして
|
||
おいて下さい。
|
||
Autoconf はバージョン 2.50 以降が必要です。
|
||
</p>
|
||
|
||
<p>
|
||
まず、アプリケーションプログラムの <code>configure.ac</code>
|
||
(もしくは <code>configure.in</code>) に、次の行を加えます。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
eb_LIB_EB4
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
マクロ <code>eb_LIB_EB4</code> は、EB ライブラリの使用に必要な一切の
|
||
チェックを行い、さらに <code>configure</code> に次のオプションを追加
|
||
します。
|
||
</p>
|
||
|
||
<blockquote>
|
||
<pre>
|
||
--with-eb-conf=FILE eb.conf file is FILE [SYSCONFDIR/eb.conf]
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
<code>eb.conf</code> は、EB ライブラリをインストールしたときの情報を記録
|
||
したファイルで、ライブラリと一緒にインストールされます。
|
||
<code>eb_LIB_EB4</code> はこのファイルを読み込んで、C コンパイラに
|
||
渡さなければいけないオプションなどの情報を得ます。
|
||
<samp>--eb-conf-file</samp> は、<code>eb.conf</code> のファイル名を
|
||
明示的に指定するオプションです。
|
||
</p>
|
||
|
||
<p>
|
||
マクロ <code>eb_LIB_EB4</code> は、<code>eb4.m4</code> というファイルで
|
||
提供されています。
|
||
EB ライブラリを <code>/usr/local</code> にインストールし、個々のファイル
|
||
のインストール先を変更していなければ、<code>/usr/local/share/aclocal</code>
|
||
にインストールされます。
|
||
この <code>eb4.m4</code> をソースコードの適当なディレクトリの下 (たとえば
|
||
<code>m4</code>) にコピーして下さい。
|
||
</p>
|
||
|
||
<p>
|
||
<code>aclocal</code> コマンドで <code>aclocal.m4</code> を再生成する際は、
|
||
<samp>-I</samp> オプションでマクロファイルのディレクトリを指定します。
|
||
</p>
|
||
|
||
<blockquote>
|
||
<pre>
|
||
aclocal -I m4
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
加えて、トップディレクトリの <code>Makefile.am</code> の中にも
|
||
<code>aclocal</code> へ渡すオプションを書いておきます。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
ACLOCAL_AMFLAGS = -I m4
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
また、ソースコードのディレクトリに Libtool パッケージがまだ用意されて
|
||
いなければ、用意します。
|
||
<code>libtoolize</code> コマンドを実行して下さい。
|
||
Libtool パッケージが、ソースコードのディレクトリにコピーされます。
|
||
</p>
|
||
|
||
<blockquote>
|
||
<pre>
|
||
libtoolize
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
最後に、コンパイルを行うディレクトリの <code>Makefile.am</code> ファイル
|
||
の <code>_LDFLAGS</code> と <code>INCLUDES</code> に、次のような値を追加
|
||
します。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
program_LDFLAGS = $(EBCONF_EBLIBS) $(EBCONF_ZLIBLIBS) $(EBCONF_INTLLIBS)
|
||
INCLUDES = $(EBCONF_EBINCS)
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
(<code>program_LDFLAGS</code> の <code>program</code> のところは、
|
||
アプリケーションプログラムの実際のコマンド名にします。)
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="debug-eb-library">EB ライブラリ本体のデバッグ</a></h3>
|
||
|
||
<p>
|
||
「自分が作ったアプリケーションが正しく動かないのは、ひょっとすると
|
||
EB ライブラリのバグが原因ではないか?」という疑問を抱き、EB ライブラリ
|
||
の挙動を確認したいと思うことがあるかも知れません。
|
||
</p>
|
||
|
||
<p>
|
||
そのような場合は、環境変数 <code>EB_DEBUG</code> をセットした状態で
|
||
アプリケーションを実行してみて下さい。
|
||
EB ライブラリは標準エラー出力に、次のようなログを (かなり大量ですが)
|
||
出力するようになります。
|
||
</p>
|
||
|
||
<blockquote>
|
||
<pre>
|
||
[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
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
これらのログは、関数の呼び出し時の引数列、および関数からの戻り値を
|
||
示しています。
|
||
<code>ebfixlog</code> という Perl5 スクリプトを使うと、ログを整形すること
|
||
ができます。
|
||
このスクリプトは、EB ライブラリのソースコードの <code>misc</code>
|
||
ディレクトリに収められています。
|
||
</p>
|
||
|
||
<p>
|
||
<code>ebfixlog</code> は、コマンド行の引数として与えられたファイル
|
||
(引数が指定されなければ標準入力) からメッセージデータを読み込み、
|
||
次のように字下げして出力します。
|
||
</p>
|
||
|
||
<blockquote>
|
||
<pre>
|
||
[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
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
通常 <code>ebfixlog</code> スクリプトは、zio および ebnet と呼ばれる、
|
||
EB ライブラリでファイル入出力を受け持つ処理部のログは読み捨てるように
|
||
なっています。
|
||
これにより、ログの量がかなり減ります。
|
||
</p>
|
||
|
||
<p>
|
||
zio は EB ライブラリの低レベル入出力の処理部で、頻繁に呼び出されます。
|
||
問題の原因を調べる際も、まずは読み捨てた方がライブラリの内部動作を追跡
|
||
しやすいでしょう。
|
||
</p>
|
||
|
||
<p>
|
||
<code>ebfixlog</code> の <samp>-z</samp> オプションを使うと、zio の
|
||
メッセージを読み捨てずに出力するようになります。
|
||
</p>
|
||
|
||
<p>
|
||
ebnet は遠隔アクセスの入出力を処理する部分で、zio よりもさらに
|
||
下位レベルに位置します。
|
||
遠隔アクセスの挙動を追跡するとき以外は、読み捨てた方が良いと思います。
|
||
</p>
|
||
|
||
<p>
|
||
<code>ebfixlog</code> の <samp>-n</samp> オプションを使うと、ebnet,
|
||
zio 両方のメッセージを読み捨てずに出力するようになります。
|
||
</p>
|
||
|
||
<!-- ================================================================ -->
|
||
<h2><a name="init-and-exit">ライブラリの初期化と後始末</a></h2>
|
||
|
||
<p>
|
||
この章からは、EB ライブラリのプログラミングについての解説になります。
|
||
</p>
|
||
|
||
<p>
|
||
まず、アプリケーションプログラムから EB ライブラリを利用するには、
|
||
最初にライブラリを初期化する必要があります。
|
||
</p>
|
||
|
||
<p>
|
||
ライブラリの初期化を行うには、<code>eb_initialize_library()</code>
|
||
という関数を呼び出します。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
if (eb_initialize_library() != EB_SUCCESS) {
|
||
printf("eb_initialize_library() failed\n");
|
||
exit(1);
|
||
}
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
同様に、ライブラリを使い終わったら、<code>eb_finalize_library()</code>
|
||
という関数を呼び出して後始末をします。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
eb_finalize_library();
|
||
</pre>
|
||
</blockquote>
|
||
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="init-and-exit-sample">サンプルプログラム</a></h3>
|
||
|
||
<!-- #include "eb-sample-initexit.html" -->
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="init-and-exit-functions">関数の詳細</a></h3>
|
||
|
||
<p>
|
||
この項で説明している関数を使うには、<code>eb/eb.h</code> を読み込んで下さい。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
#include <eb/eb.h>
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:initialize_library"><code>EB_Error_Code eb_initialize_library ()</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_initialize_library()</code> は、EB ライブラリを初期化します。
|
||
アプリケーションプログラムは、EB ライブラリの他の関数を呼ぶ前に、必ず
|
||
一回だけこの関数を呼ぶ必要があります。
|
||
</p>
|
||
|
||
<p>
|
||
メッセージの国際化機能 (NLS) を有効にして EB ライブラリをコンパイル
|
||
した場合、<code>eb_initialize_library()</code> は <code>bindtextdomain()</code> を
|
||
呼び出します。
|
||
したがって、アプリケーションプログラムが <code>setlocale()</code> を
|
||
呼び出すのは、この関数を呼び出す前である必要があります。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、関数は <code>EB_SUCCESS</code> を返します。
|
||
失敗すると、原因を示すエラーコードを返します。
|
||
</p>
|
||
|
||
<p>
|
||
ライブラリを初期化せずに、EB ライブラリの他の関数を呼んだ場合の動作は
|
||
未定義です。
|
||
また、すでに初期化を済ませた状態で、再度 <code>eb_initialize_library()</code>
|
||
を呼んでもいけません。
|
||
呼んだ場合の動作は未定義です。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:finalize_library"><code>void eb_finalize_library ()</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_finalize_library()</code> は、EB ライブラリを使い終わった
|
||
際の後始末を行います。
|
||
ただし、アプリケーションプログラム側で使用した
|
||
<code>EB_Book</code>、<code>EB_Hookset</code>、<code>EB_Appendix</code> オブジェクトの後始末は行いません。
|
||
オブジェクトを後始末するには、それぞれ専用の関数
|
||
<code>eb_finalize_book()</code>、<code>eb_finalize_hookset()</code>、
|
||
<code>eb_finalize_appendix()</code> を各オブジェクトに対して別途
|
||
呼んでやる必要があります。
|
||
</p>
|
||
|
||
<p>
|
||
ライブラリの後始末をした後は、EB ライブラリのいかなる関数も呼んでは
|
||
いけません。
|
||
呼んだ場合の動作は未定義です。
|
||
</p>
|
||
|
||
<!-- ================================================================ -->
|
||
<h2><a name="eb_book">CD-ROM 書籍と <code>EB_Book</code> オブジェクト</a></h2>
|
||
|
||
<p>
|
||
EB ライブラリでは、CD-ROM 書籍へのアクセスは、すべて <code>EB_Book</code> 型
|
||
のオブジェクトを介して行います。
|
||
したがって、ほとんどのアプリケーションプログラムは、本章で記述している
|
||
処理を必要とするはずです。
|
||
</p>
|
||
|
||
<p>
|
||
本章では <code>EB_Book</code> オブジェクトの初期化、後始末といった基本的な
|
||
取り扱い方について説明します。
|
||
</p>
|
||
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="eb_book-explanation"><code>EB_Book</code> オブジェクト</a></h3>
|
||
|
||
<p>
|
||
CD-ROM 書籍へアクセスするには、まず <code>EB_Book</code> 型のオブジェクトを
|
||
用意します。
|
||
同時に複数の CD-ROM 書籍にアクセスするなら、書籍一冊毎にオブジェクトを
|
||
作る必要があります。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
EB_Book book;
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
もちろん、オブジェクトの領域は、<code>malloc()</code> で確保しても
|
||
構いません。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
EB_Book *book_pointer;
|
||
|
||
book_pointer = (EB_Book *) malloc(sizeof(EB_Book));
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
<code>EB_Book</code> オブジェクトの中身 (変数 <code>book</code> の中身
|
||
および <code>book_pointer</code> の指す領域) はまだ初期化されていませんので、
|
||
次の要領でオブジェクトを初期化します。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
eb_initialize_book(&book);
|
||
eb_initialize_book(book_pointer);
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
<code>eb_initialize()</code> へ渡す引数は <code>EB_Book</code> オブジェクト
|
||
へのポインタであって、<code>EB_Book</code> オブジェクトそのものでは
|
||
ないことに注意して下さい。
|
||
(EB ライブラリの他の関数も、すべてオブジェクトをポインタで渡します。)
|
||
</p>
|
||
|
||
<p>
|
||
CD-ROM 書籍を使うには、続いて <code>EB_Book</code> オブジェクトを
|
||
CD-ROM 書籍の実体に結び付けます。
|
||
これは、関数 <code>eb_bind()</code> によって行います。
|
||
</p>
|
||
|
||
<blockquote>
|
||
<pre>
|
||
ＥＢ＿Ｂｏｏｋ ＣＤ－ＲＯＭ書籍
|
||
オブジェクト ┌────────────┐
|
||
┌───┐ │ │
|
||
│ ┝━━━━━━━━━━━┥ ／ｍｎｔ／ｃｄｒｏｍ │
|
||
└───┘ ｅｂ＿ｂｉｎｄ（） │ │
|
||
└────────────┘
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
実際のプログラムでは、次のようにします。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
if (eb_bind(&book, "/mnt/cdrom") != EB_SUCCESS) {
|
||
printf("eb_bind() failed\n");
|
||
return;
|
||
}
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
<code>eb_bind()</code> に渡す書籍のパス (この例では <code>/mnt/cdrom</code>)
|
||
は書籍のトップディレクトリ、つまり <code>catalog</code> または
|
||
<code>catalogs</code> ファイルのあるディレクトリを指定します。
|
||
</p>
|
||
|
||
<p>
|
||
<code>EB_Book</code> オブジェクトを使い終わったら、
|
||
<code>eb_finalize_book()</code> を呼んで後始末をします。
|
||
オブジェクトは書籍との結び付きを解かれた状態に戻り、内部で割り当てられた
|
||
メモリは解放され、開いていたファイルもすべて閉じられます。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
eb_finalize_book(&book);
|
||
eb_finalize_book(book_pointer);
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
オブジェクトの領域を <code>malloc()</code> で確保した場合は、
|
||
<code>eb_finalize_book()</code> を呼んだ後ならば、オブジェクトの領域を
|
||
安全に解放することができます。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
free(book_pointer);
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="eb_bind-to-remote-host">遠隔ホストへの <code>eb_bind()</code></a></h3>
|
||
|
||
<p>
|
||
前節で説明した <code>eb_bind()</code> を用いて、<code>EB_Book</code>
|
||
オブジェクトを遠隔ホストの書籍に結びつけることができます。
|
||
これには、書籍のパスの代わりに、遠隔アクセス用の識別子を指定します。
|
||
識別子は、次のような形式をとります。
|
||
</p>
|
||
|
||
<blockquote>
|
||
<pre>
|
||
ebnet://<var>ホスト</var>:<var>ポート</var>/<var>書籍名</var>
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
<var>ホスト</var> は遠隔ホストの IP アドレスもしくはホスト名です。
|
||
ただし、IPv6 アドレスを指定する場合は、アドレスを <code>[</code> と
|
||
<code>]</code> で囲む必要があります。
|
||
<var>ポート</var> は、そのホストが待ち受けているポートの番号です。
|
||
ホストが待ち受けているポートが標準の 22010 番であれば、<var>:ポート</var>
|
||
の部分は省略可能です。
|
||
</p>
|
||
|
||
<p>
|
||
以下に <code>eb_bind()</code> のコード例を記します。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
if (eb_bind(&book, "ebnet://localhost/cdrom") != EB_SUCCESS) {
|
||
printf("eb_bind() failed\n");
|
||
return;
|
||
}
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="eb_book-sample">サンプルプログラム</a></h3>
|
||
|
||
<p>
|
||
このサンプルプログラムでは、CD-ROM 書籍の種類を調べるために、
|
||
<code>eb_disc_code()</code> という関数を使用しています。
|
||
この関数については、<a href="#eb_book-functions">「関数の詳細」</a> を参照のこと。
|
||
</p>
|
||
|
||
<!-- #include "eb-sample-disctype.html" -->
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="eb_book-data-types">データ型の詳細</a></h3>
|
||
|
||
<p>
|
||
この節で説明しているデータ型を使うには、次のようにヘッダファイルを
|
||
読み込んで下さい。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
#include <eb/eb.h>
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="type:Book"><code>EB_Book</code> 型</a></h4>
|
||
|
||
<p>
|
||
<code>EB_Book</code> 型は、一冊の CD-ROM 書籍を表します。
|
||
CD-ROM 書籍へのアクセスは、すべてこの型のオブジェクトを介して行います。
|
||
同時に複数の CD-ROM 書籍にアクセスする際は、書籍一冊毎にオブジェクトを
|
||
作る必要があります。
|
||
</p>
|
||
|
||
<p>
|
||
<code>EB_Book</code> オブジェクトの操作は、すべて EB ライブラリが用意
|
||
している関数で行います。
|
||
アプリケーションプログラムは、直接 <code>EB_Book</code> オブジェクトの
|
||
メンバを参照したり、セットしたりすべきではありません。
|
||
</p>
|
||
|
||
<p>
|
||
<code>EB_Book</code> オブジェクトを使用する際は、まずそのオブジェクトに
|
||
対して <code>eb_initialize_book()</code> を呼んで初期化しなくては
|
||
なりません。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="type:Disc_Code"><code>EB_Disc_Code</code> 型</a></h4>
|
||
|
||
<p>
|
||
データ型 <code>EB_Disc_Code</code> は、CD-ROM 書籍の形式コードを表します。
|
||
現在のところ、次の値が定義されています。
|
||
</p>
|
||
|
||
<dl>
|
||
<dt><code>EB_DISC_EB</code></dt>
|
||
<dd>
|
||
電子ブック (EB, EBG, EBXA, EBXA-C, S-EBXA) であることを表します。
|
||
|
||
<dt><code>EB_DISC_EPWING</code></dt>
|
||
<dd>
|
||
EPWING であることを表します。
|
||
|
||
<dt><code>EB_DISC_INVALID</code></dt>
|
||
<dd>
|
||
不正な形式コード値を表します。
|
||
</dl>
|
||
|
||
<p>
|
||
この型は符合付き整数型の別名として定義されていますので、2 つのコードを
|
||
2 項演算子 <code>==</code> と <code>!=</code> で一致比較することができます。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="type:EB_Character_Code"><code>EB_Character_Code</code> 型</a></h4>
|
||
|
||
<p>
|
||
データ型 <code>EB_Character_Code</code> は、CD-ROM 書籍で使用される
|
||
文字コードを表します。
|
||
現在のところ、次の値が定義されています。
|
||
</p>
|
||
|
||
<dl>
|
||
<dt><code>EB_CHARCODE_ISO8859_1</code></dt>
|
||
<dd>
|
||
ISO 8859-1 (ラテン文字 1) を使用していることを表します。
|
||
電子ブックの EBG はこれです。
|
||
|
||
<dt><code>EB_CHARCODE_JISX0208</code></dt>
|
||
<dd>
|
||
JIS X 0208 (日本語のかな漢字) を使用していることを表します。
|
||
EBG, EBXA-C 以外の電子ブック、および EPWING はすべてこれです。
|
||
|
||
<dt><code>EB_CHARCODE_JISX0208_GB2312</code></dt>
|
||
<dd>
|
||
JIS X 0208 (日本語のかな漢字) と GB 2312 (中国語の簡体字) を併用している
|
||
ことを表します。
|
||
電子ブックの EBXA-C はこれです。
|
||
|
||
<dt><code>EB_CHARCODE_INVALID</code></dt>
|
||
<dd>
|
||
不正な文字コード値を表します。
|
||
</dl>
|
||
|
||
<p>
|
||
この型は符合付き整数型の別名として定義されていますので、2 つのコードを
|
||
2 項演算子 <code>==</code> と <code>!=</code> で一致比較することができます。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="eb_book-functions">関数の詳細</a></h3>
|
||
|
||
<p>
|
||
この節で説明している関数を使うには、次のようにヘッダファイルを読み込んで
|
||
下さい。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
#include <eb/eb.h>
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:initialize_book"><code>void eb_initialize_book (EB_Book *<var>book</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_initialize_book()</code> は、<var>book</var> の指す
|
||
<code>EB_Book</code> オブジェクトを初期化します。
|
||
<code>EB_Book</code> オブジェクトに対して EB ライブラリの他の関数を呼ぶ前に、
|
||
必ずそのオブジェクトを初期化しなくてはなりません。
|
||
初期化していないオブジェクトに対して、EB ライブラリの他の関数を呼んだ
|
||
場合の動作は未定義です。
|
||
また、すでに初期化したオブジェクトに対して、再度
|
||
<code>eb_initialize_book()</code> を呼んではいけません。
|
||
呼んだ場合の動作は未定義です。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:bind"><code>EB_Error_Code eb_bind (EB_Book *<var>book</var>, const char *<var>path</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_bind()</code> は、<var>book</var> の指す <code>EB_Book</code>
|
||
オブジェクトを、パス <var>path</var> にある CD-ROM 書籍に結び付けます。
|
||
パスには、書籍のトップディレクトリか遠隔アクセス識別子を指定します。
|
||
書籍のトップディレクトリとは、<code>catalog</code> あるいは
|
||
<code>catalogs</code> ファイルの存在するディレクトリを指します。
|
||
</p>
|
||
|
||
<p>
|
||
オブジェクトがすでに書籍に結び付いていた場合、その書籍との結び付きを
|
||
解いてから、<var>path</var> にある書籍に結び付けます。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、関数は <code>EB_SUCCESS</code> を返します。
|
||
このとき、副本は未選択の状態になります。
|
||
失敗すると、オブジェクトを書籍との結び付きを解かれた状態にして、原因
|
||
を示すエラーコードを返します。
|
||
</p>
|
||
|
||
<p>
|
||
<var>path</var> は、<code>EB_MAX_PATH_LENGTH</code> バイトに収まていなくては
|
||
なりません。
|
||
さらに、<var>path</var> が相対パスのときは、絶対パスに変換した結果がこの長さ
|
||
に収まっていなくてはなりません。
|
||
これを超えると、<code>EB_ERR_TOO_LONG_FILE_NAME</code> を返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:finalize_book"><code>void eb_finalize_book (EB_Book *<var>book</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_finalize_book()</code> は、<var>book</var> が指す
|
||
<code>EB_Book</code> オブジェクトの後始末を行います。
|
||
</p>
|
||
|
||
<p>
|
||
オブジェクトが割り当てて管理していたメモリはすべて解放され、
|
||
ファイルディスクリプタもすべて閉じられます。
|
||
オブジェクトが書籍と結び付いていた場合は、結び付きが解かれます。
|
||
</p>
|
||
|
||
<p>
|
||
後始末をしたオブジェクトに対して <code>eb_bind()</code> を呼ぶことで、
|
||
オブジェクトを再利用することができます。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:is_bound"><code>int eb_is_bound (EB_Book *<var>book</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_is_bound()</code> は、<var>book</var> が書籍に結び付いているか
|
||
どうかを調べます。
|
||
結び付いていれば 1 を返し、そうでなければ 0 を返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:path"><code>EB_Error_Code eb_path (EB_Book *<var>book</var> const char *<var>path</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_path()</code> は、<var>book</var> に結び付いている書籍のパス
|
||
もしくは遠隔アクセス識別子を、<var>path</var> の指す領域に書き込みます。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、関数は <code>EB_SUCCESS</code> を返します。
|
||
失敗すると、<var>path</var> の指す領域に空文字列を書き込み、原因を示す
|
||
エラーコードを返します。
|
||
</p>
|
||
|
||
<p>
|
||
<var>book</var> は、あらかじめ書籍に結び付いている必要があります。
|
||
結びついていない場合は、<code>EB_ERR_UNBOUND_BOOK</code> を返します。
|
||
</p>
|
||
|
||
<p>
|
||
<var>path</var> に書き込むパス名のバイト数は、最長で
|
||
<code>EB_MAX_PATH_LENGTH</code> になります。
|
||
この長さは、末尾のナル文字を含みません。
|
||
関数が返すパスは正規化された形になっているので、<code>eb_bind()</code> に
|
||
渡したときのものと同じとは限りません。
|
||
たとえば、相対パスだった場合は、絶対パスに変換されます。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:disc_type"><code>EB_Error_Code eb_disc_type (EB_Book *<var>book</var>, EB_Disc_Code *<var>disc_code</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_disc_type()</code> は、<var>book</var> のディスクの形式を
|
||
<var>disc_code</var> の指す領域に書き込みます。
|
||
書き込むディスクの形式の値は、<code>EB_Disc_Code</code> 型
|
||
(<a href="#eb_book-data-types">「[CD-ROM 書籍と <code>EB_Book</code> オブジェクト] データ型の詳細」</a> を参照のこと)
|
||
のいずれかの定数値です。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、関数は <code>EB_SUCCESS</code> を返します。
|
||
失敗すると、<var>disc_code</var> の指す領域に <code>EB_DISC_INVALID</code>
|
||
を書き込み、原因を示すエラーコードを返します。
|
||
</p>
|
||
|
||
<p>
|
||
<var>book</var> は、あらかじめ書籍に結び付いていなければなりません。
|
||
結びついていない場合は、<code>EB_ERR_UNBOUND_BOOK</code> を返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:character_code"><code>EB_Error_Code eb_character_code (EB_Book *<var>book</var>, EB_Character_Code *<var>character_code</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_character_code()</code> は、<var>book</var> が書かれている
|
||
文字コードを <var>character_code</var> の指す領域に書き込みます。
|
||
書き込む文字コードの値は、<code>EB_Character_Code</code> 型
|
||
(<a href="#eb_book-data-types">「[CD-ROM 書籍と <code>EB_Book</code> オブジェクト] データ型の詳細」</a> を参照のこと)
|
||
のいずれかの定数値です。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、関数は <code>EB_SUCCESS</code> を返します。
|
||
失敗すると、<var>character_code</var> の指す領域に
|
||
<code>EB_CHARCODE_INVALID</code> を書き込み、原因を示すエラーコードを
|
||
返します。
|
||
</p>
|
||
|
||
<p>
|
||
<var>book</var> は、あらかじめ書籍に結び付いていなければなりません。
|
||
結びついていない場合は、<code>EB_ERR_UNBOUND_BOOK</code> を返します。
|
||
</p>
|
||
|
||
<!-- ================================================================ -->
|
||
<h2><a name="error-handling">エラー処理</a></h2>
|
||
|
||
<p>
|
||
EB ライブラリの関数の呼び出しは、常に成功するとは限りません。
|
||
たとえば、<code>EB_Book</code> オブジェクトを書籍に結びつける関数
|
||
<code>eb_bind()</code> には、引数として書籍のトップディレクトリを渡しますが、
|
||
存在しないディレクトリを指定した場合、処理は失敗に終わります。
|
||
</p>
|
||
|
||
<p>
|
||
一般にこうした事象は、ユーザが誤ったパスを指定したときに起こりますが、
|
||
メモリ不足のように、ユーザのミスが原因ではない失敗も起こりえます。
|
||
</p>
|
||
|
||
<p>
|
||
本章では、関数の呼び出しが失敗した場合の処理について説明します。
|
||
</p>
|
||
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="error-code-and-message">エラーコードとエラーメッセージ</a></h3>
|
||
|
||
<p>
|
||
EB ライブラリの関数の多くは、戻り値として <code>EB_Error_Code</code>
|
||
型の値を返します。
|
||
処理が成功したときに返す値は <code>EB_SUCCESS</code> ですが、失敗したときは
|
||
エラーの原因に応じて様々な値を返します。
|
||
このため、EB ライブラリでは次のような <code>EB_SUCCESS</code> との比較処理
|
||
がよく行われます。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
EB_Error_Code error_code;
|
||
|
||
error_code = eb_bind(&book, "/mnt/cdrom");
|
||
if (error_code != EB_SUCCESS) {
|
||
printf("eb_bind() failed\n");
|
||
return;
|
||
}
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
エラーコードの値は、関数 <code>eb_error_message()</code> によって
|
||
エラーメッセージに変換することもできます。
|
||
こうすることで、エラーの原因をアプリケーションプログラムのユーザに
|
||
もう少し分かりやすく伝えることができます。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
error_code = eb_bind(&book, "/mnt/cdrom");
|
||
if (error_code != EB_SUCCESS) {
|
||
printf("eb_bind() failed, %s\n",
|
||
eb_error_message(error_code));
|
||
return;
|
||
}
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
<code>error_code</code> が <code>EB_ERR_TOO_LONG_FILENAME</code> に
|
||
セットされていれば、次のようなエラーメッセージが出力されます。
|
||
</p>
|
||
|
||
<blockquote>
|
||
<pre>
|
||
too long filename
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
あるいは、次のように日本語のメッセージかも知れません。
|
||
</p>
|
||
|
||
<blockquote>
|
||
<pre>
|
||
ファイル名が長すぎます
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
メッセージの国際化機能 (NLS) を無効にして EB ライブラリをコンパイル
|
||
した場合は、常に英語のメッセージが返ります。
|
||
有効にした場合は、ロケールの設定によってどちらの言語のメッセージが
|
||
返るかが決まります。
|
||
</p>
|
||
|
||
<p>
|
||
本書ではプログラムを簡潔にするために、エラー処理は最低限しか行って
|
||
いません。
|
||
けれども一般のアプリケーションプログラムでは、関数の呼び出しが成功
|
||
したかどうかを常にチェックし、処理が失敗した際はエラーメッセージを出力
|
||
して、ユーザにエラーの原因を伝えるのが望ましいといえます。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="tolerance-to-error">エラーに対する寛容さ</a></h3>
|
||
|
||
<p>
|
||
<code>EB_Book</code> オブジェクトは、状態に関するパラメタをいくつか持って
|
||
います。
|
||
オブジェクトが CD-ROM 書籍に結び付いているかどうかも、こうしたパラメタ
|
||
のうちの一つです。
|
||
</p>
|
||
|
||
<p>
|
||
引数に <code>EB_Book</code> オブジェクトへのポインタを取る関数には、
|
||
あらかじめオブジェクトの特定のパラメタがセットされていることを前提と
|
||
しているものもあります。
|
||
たとえば、<code>eb_path()</code> は、オブジェクトが書籍に結び付いていること
|
||
を前提としています。
|
||
では、もしも書籍に結び付いていないオブジェクトを <code>eb_path()</code> に
|
||
渡したらどうなるでしょうか。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
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); /* どうなる? */
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
この場合、<code>eb_path()</code> は <code>EB_ERR_UNBOUND_BOOK</code> を
|
||
返します。
|
||
EB ライブラリの関数は、必要なパラメタがセットされていないオブジェクトを
|
||
検知して拒絶します。
|
||
</p>
|
||
|
||
<p>
|
||
しかしながら、参照マニュアルで明示されている場合を除いて、EB ライブラリ
|
||
の関数は、与えられたポインタが <code>NULL</code> かどうかまでは調べません。
|
||
次のようなことをすると、プログラムを異常終了させてしまいます。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
eb_bind(NULL, "/mnt/cdrom"); /* 異常終了! */
|
||
eb_bind(&book, NULL); /* これも異常終了! */
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="error-data-types">データ型の詳細</a></h3>
|
||
|
||
<p>
|
||
この節で説明しているデータ型を使うには、次のようにヘッダファイルを
|
||
読み込んで下さい。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
#include <eb/error.h>
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="type:Error_Code"><code>EB_Error_Code</code> 型</a></h4>
|
||
|
||
<p>
|
||
データ型 <code>EB_Error_Code</code> は、EB ライブラリのエラーコードを
|
||
表します。
|
||
この型は符合付き整数型の別名として定義されていますので、2 つのコードを
|
||
2 項演算子 <code>==</code> と <code>!=</code> で一致比較することができます。
|
||
</p>
|
||
|
||
<p>
|
||
EB ライブラリでは、全部で <code>EB_NUMBER_OF_ERRORS</code> 個の
|
||
フックコードを定義しています。
|
||
エラーコードの一覧については、
|
||
次の節 (<a href="#error-code-list">「エラーコードの一覧」</a> を参照のこと)
|
||
を参照して下さい。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="error-code-list">エラーコードの一覧</a></h3>
|
||
|
||
<p>
|
||
この節で説明しているエラーコードを使うには、次のようにヘッダファイルを
|
||
読み込んで下さい。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
#include <eb/error.h>
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SUCCESS">定数 <code>EB_SUCCESS</code></a></h4>
|
||
|
||
<p>
|
||
成功。
|
||
エラーは起きていない。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_MEMORY_EXHAUSTED">定数 <code>EB_ERR_MEMORY_EXHAUSTED</code></a></h4>
|
||
|
||
<p>
|
||
EB ライブラリが <code>malloc()</code> を呼び出したが、<code>NULL</code>
|
||
が返ってきた。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_TOO_LONG_FILE_NAME">定数 <code>EB_ERR_TOO_LONG_FILE_NAME</code></a></h4>
|
||
|
||
<p>
|
||
与えられた書籍のパス名が長すぎる。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_BAD_FILE_NAME">定数 <code>EB_ERR_BAD_FILE_NAME</code></a></h4>
|
||
|
||
<p>
|
||
書籍のパス名が不正である。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_BAD_DIR_NAME">定数 <code>EB_ERR_BAD_DIR_NAME</code></a></h4>
|
||
|
||
<p>
|
||
ディレクトリ名が不正である。
|
||
(EB ライブラリの内部処理用なので、
|
||
このエラーコードがアプリケーションプログラムに返ることはありません。)
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_TOO_LONG_WORD">定数 <code>EB_ERR_TOO_LONG_WORD</code></a></h4>
|
||
|
||
<p>
|
||
与えられた検索語は長すぎる。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_BAD_WORD">定数 <code>EB_ERR_BAD_WORD</code></a></h4>
|
||
|
||
<p>
|
||
与えられた検索語に不正な文字が含まれている。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_EMPTY_WORD">定数 <code>EB_ERR_EMPTY_WORD</code></a></h4>
|
||
|
||
<p>
|
||
与えられた検索語は空である。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_FAIL_GETCWD">定数 <code>EB_ERR_FAIL_GETCWD</code></a></h4>
|
||
|
||
<p>
|
||
<code>getcwd()</code> もしくは <code>getwd()</code> が失敗した。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_FAIL_OPEN_CAT">定数 <code>EB_ERR_FAIL_OPEN_CAT</code></a></h4>
|
||
|
||
<p>
|
||
EB ライブラリが、書籍のカタログファイルを開くことに失敗した。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_FAIL_OPEN_CATAPP">定数 <code>EB_ERR_FAIL_OPEN_CATAPP</code></a></h4>
|
||
|
||
<p>
|
||
EB ライブラリが、appendix のカタログファイルを開くことに失敗した。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_FAIL_OPEN_TEXT">定数 <code>EB_ERR_FAIL_OPEN_TEXT</code></a></h4>
|
||
|
||
<p>
|
||
EB ライブラリが、書籍の本文ファイルを開くことに失敗した。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_FAIL_OPEN_FONT">定数 <code>EB_ERR_FAIL_OPEN_FONT</code></a></h4>
|
||
|
||
<p>
|
||
EB ライブラリが、書籍の外字ファイルを開くことに失敗した。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_FAIL_OPEN_APP">定数 <code>EB_ERR_FAIL_OPEN_APP</code></a></h4>
|
||
|
||
<p>
|
||
EB ライブラリが、appendix ファイルを開くことに失敗した。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_FAIL_OPEN_BINARY">定数 <code>EB_ERR_FAIL_OPEN_BINARY</code></a></h4>
|
||
|
||
<p>
|
||
EB ライブラリが、バイナリデータファイルを開くことに失敗した。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_FAIL_READ_CAT">定数 <code>EB_ERR_FAIL_READ_CAT</code></a></h4>
|
||
|
||
<p>
|
||
EB ライブラリが、書籍のカタログファイルを読み込むことに失敗した。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_FAIL_READ_CATAPP">定数 <code>EB_ERR_FAIL_READ_CATAPP</code></a></h4>
|
||
|
||
<p>
|
||
EB ライブラリが、appendix のカタログファイルを読み込むことに失敗した。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_FAIL_READ_TEXT">定数 <code>EB_ERR_FAIL_READ_TEXT</code></a></h4>
|
||
|
||
<p>
|
||
EB ライブラリが、書籍の本文ファイルを読むことに失敗した。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_FAIL_READ_FONT">定数 <code>EB_ERR_FAIL_READ_FONT</code></a></h4>
|
||
|
||
<p>
|
||
EB ライブラリが、書籍の外字ファイルを読み込むことに失敗した。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_FAIL_READ_APP">定数 <code>EB_ERR_FAIL_READ_APP</code></a></h4>
|
||
|
||
<p>
|
||
EB ライブラリが、appendix のメインファイルを読み込むことに失敗した。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_FAIL_READ_BINARY">定数 <code>EB_ERR_FAIL_READ_BINARY</code></a></h4>
|
||
|
||
<p>
|
||
EB ライブラリが、書籍のバイナリデータファイルを読み込むことに失敗した。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_FAIL_SEEK_CAT">定数 <code>EB_ERR_FAIL_SEEK_CAT</code></a></h4>
|
||
|
||
<p>
|
||
EB ライブラリが、書籍のカタログファイルのシークに失敗した。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_FAIL_SEEK_CATAPP">定数 <code>EB_ERR_FAIL_SEEK_CATAPP</code></a></h4>
|
||
|
||
<p>
|
||
EB ライブラリが、appendix のカタログファイルのシークに失敗した。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_FAIL_SEEK_TEXT">定数 <code>EB_ERR_FAIL_SEEK_TEXT</code></a></h4>
|
||
|
||
<p>
|
||
EB ライブラリが、書籍の本文ファイルのシークに失敗した。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_FAIL_SEEK_FONT">定数 <code>EB_ERR_FAIL_SEEK_FONT</code></a></h4>
|
||
|
||
<p>
|
||
EB ライブラリが、書籍の外字ファイルのシークに失敗した。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_FAIL_SEEK_APP">定数 <code>EB_ERR_FAIL_SEEK_APP</code></a></h4>
|
||
|
||
<p>
|
||
EB ライブラリが、appendix のメインファイルのシークに失敗した。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_FAIL_SEEK_BINARY">定数 <code>EB_ERR_FAIL_SEEK_BINARY</code></a></h4>
|
||
|
||
<p>
|
||
EB ライブラリが、書籍のバイナリデータファイルのシークに失敗した。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_UNEXP_CAT">定数 <code>EB_ERR_UNEXP_CAT</code></a></h4>
|
||
|
||
<p>
|
||
EB ライブラリが、書籍のカタログファイル内で、期待とは異なるデータ列を
|
||
見つけた。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_UNEXP_CATAPP">定数 <code>EB_ERR_UNEXP_CATAPP</code></a></h4>
|
||
|
||
<p>
|
||
EB ライブラリが、appendix のカタログファイル内で、想定外のデータ列を
|
||
見つけた。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_UNEXP_TEXT">定数 <code>EB_ERR_UNEXP_TEXT</code></a></h4>
|
||
|
||
<p>
|
||
EB ライブラリが、書籍の本文ファイル内で、想定外のデータ列を見つけた。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_UNEXP_FONT">定数 <code>EB_ERR_UNEXP_FONT</code></a></h4>
|
||
|
||
<p>
|
||
EB ライブラリが、書籍の外字ファイル内で、想定外のデータ列を見つけた。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_UNEXP_APP">定数 <code>EB_ERR_UNEXP_APP</code></a></h4>
|
||
|
||
<p>
|
||
EB ライブラリが、appendix のメインファイル内で、想定外のデータ列を
|
||
見つけた。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_UNEXP_BINARY">定数 <code>EB_ERR_UNEXP_BINARY</code></a></h4>
|
||
|
||
<p>
|
||
EB ライブラリが、書籍のバイナリデータファイル内で、想定外のデータ列を
|
||
見つけた。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_UNBOUND_BOOK">定数 <code>EB_ERR_UNBOUND_BOOK</code></a></h4>
|
||
|
||
<p>
|
||
呼び出された EB ライブラリの関数は、書籍に結び付けられた
|
||
<code>EB_Book</code> オブジェクトを引数にとるが、与えられたオブジェクトは
|
||
書籍に結び付けられていなかった。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_UNBOUND_APP">定数 <code>EB_ERR_UNBOUND_APP</code></a></h4>
|
||
|
||
<p>
|
||
呼び出された EB ライブラリの関数は、appendix に結び付けられた
|
||
<code>EB_Appendix</code> オブジェクトを引数にとるが、与えられた
|
||
オブジェクトは appendix に結び付けられて
|
||
いなかった。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_NO_SUB">定数 <code>EB_ERR_NO_SUB</code></a></h4>
|
||
|
||
<p>
|
||
書籍は副本を一つも持っていない。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_NO_APPSUB">定数 <code>EB_ERR_NO_APPSUB</code></a></h4>
|
||
|
||
<p>
|
||
appendix は副本を一つも持っていない。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_NO_FONT">定数 <code>EB_ERR_NO_FONT</code></a></h4>
|
||
|
||
<p>
|
||
選択中の副本は、外字を一種類も持っていない。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_NO_TEXT">定数 <code>EB_ERR_NO_TEXT</code></a></h4>
|
||
|
||
<p>
|
||
選択中の副本は、本文データを持っていない。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_NO_CUR_SUB">定数 <code>EB_ERR_NO_CUR_SUB</code></a></h4>
|
||
|
||
<p>
|
||
呼び出された関数は、副本が選択されている <code>EB_Book</code>
|
||
オブジェクトを引数としてとるが、与えられたオブジェクトでは選択されて
|
||
いなかった。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_NO_CUR_APPSUB">定数 <code>EB_ERR_NO_CUR_APPSUB</code></a></h4>
|
||
|
||
<p>
|
||
呼び出された関数は、副本が選択されている <code>EB_Appendix</code>
|
||
オブジェクトを引数にとるが、与えられたオブジェクトでは選択されて
|
||
いなかった。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_NO_CUR_FONT">定数 <code>EB_ERR_NO_CUR_FONT</code></a></h4>
|
||
|
||
<p>
|
||
呼び出された関数は、外字が選択されている <code>EB_Book</code>
|
||
オブジェクトを引数にとるが、与えられたオブジェクトでは選択されて
|
||
いなかった。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_NO_CUR_BINARY">定数 <code>EB_ERR_NO_CUR_BINARY</code></a></h4>
|
||
|
||
<p>
|
||
呼び出された関数は、バイナリデータの読み込み要求をセットしている
|
||
<code>EB_Book</code> オブジェクトを引数にとるが、与えられたオブジェクトでは
|
||
セットされていなかった。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_NO_SUCH_SUB">定数 <code>EB_ERR_NO_SUCH_SUB</code></a></h4>
|
||
|
||
<p>
|
||
<code>EB_Book</code> オブジェクトと副本コードが関数に与えられたが、
|
||
<code>EB_Book</code> オブジェクトに結び付けられている書籍は、その
|
||
副本コードに一致する副本を持っていない。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_NO_SUCH_APPSUB">定数 <code>EB_ERR_NO_SUCH_APPSUB</code></a></h4>
|
||
|
||
<p>
|
||
<code>EB_Appendix</code> オブジェクトと副本コードが関数に与えられたが、
|
||
<code>EB_Appendix</code> オブジェクトに結び付けられている appendix は、
|
||
その副本コードに一致する副本を持っていない。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_NO_SUCH_FONT">定数 <code>EB_ERR_NO_SUCH_FONT</code></a></h4>
|
||
|
||
<p>
|
||
<code>EB_Book</code> オブジェクトと外字の縦のサイズが関数に与えられたが、
|
||
<code>EB_Book</code> オブジェクトに結びつけられていた書籍で選択中の副本は、
|
||
そのサイズの外字を持っていない。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_NO_SUCH_CHAR_BMP">定数 <code>EB_ERR_NO_SUCH_CHAR_BMP</code></a></h4>
|
||
|
||
<p>
|
||
<code>EB_Book</code> オブジェクトと文字番号が関数に与えられたが、
|
||
<code>EB_Book</code> オブジェクトに結び付けられていた書籍で選択中の副本は、
|
||
その番号の外字のビットマップデータを持っていない。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_NO_SUCH_CHAR_TEXT">定数 <code>EB_ERR_NO_SUCH_CHAR_TEXT</code></a></h4>
|
||
|
||
<p>
|
||
<code>EB_Appendix</code> オブジェクトと文字番号が関数に与えられたが、
|
||
<code>EB_Appendix</code> オブジェクトに結び付けられている appendix で
|
||
選択中の副本は、その番号の外字の代替文字列を持っていない。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_NO_SUCH_SEARCH">定数 <code>EB_ERR_NO_SUCH_SEARCH</code></a></h4>
|
||
|
||
<p>
|
||
選択中の副本は、指定された検索メソッドを持っていないので、検索は行えない。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_NO_SUCH_HOOK">定数 <code>EB_ERR_NO_SUCH_HOOK</code></a></h4>
|
||
|
||
<p>
|
||
不正なフックコードが関数に渡された。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_NO_SUCH_BINARY">定数 <code>EB_ERR_NO_SUCH_BINARY</code></a></h4>
|
||
|
||
<p>
|
||
指定された位置に、指定された形式のバイナリデータは存在しない。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_DIFF_CONTENT">定数 <code>EB_ERR_DIFF_CONTENT</code></a></h4>
|
||
|
||
<p>
|
||
アプリケーションプログラムからテキストデータの取得を要求されたが、指定
|
||
されたテキストデータの種類が、前回リクエストされたときと一致していない。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_NO_PREV_SEARCH">定数 <code>EB_ERR_NO_PREV_SEARCH</code></a></h4>
|
||
|
||
<p>
|
||
<code>eb_hit_list()</code> が呼び出されたが、アプリケーションプログラム
|
||
から前もって検索のリクエストがなされていない。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_NO_SUCH_MULTI_ID">定数 <code>EB_ERR_NO_SUCH_MULTI_ID</code></a></h4>
|
||
|
||
<p>
|
||
<code>EB_Book</code> オブジェクトと複合検索コードが関数に渡されたが、
|
||
結び付けられた書籍で選択中の副本は、そのコードに一致する複合検索を持って
|
||
いない。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_NO_SUCH_ENTRY_ID">定数 <code>EB_ERR_NO_SUCH_ENTRY_ID</code></a></h4>
|
||
|
||
<p>
|
||
<code>EB_Book</code> オブジェクトと複合検索エントリコードが関数に
|
||
渡されたが、結び付けられた書籍で選択中の副本は、そのエントリコードに
|
||
一致する複合検索エントリを持っていない。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_TOO_MANY_WORDS">定数 <code>EB_ERR_TOO_MANY_WORDS</code></a></h4>
|
||
|
||
<p>
|
||
アプリケーションプログラムから条件検索もしくは複合検索の検索をリクエスト
|
||
されたが、検索語の個数が多すぎる。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_NO_WORD">定数 <code>EB_ERR_NO_WORD</code></a></h4>
|
||
|
||
<p>
|
||
アプリケーションプログラムから条件検索もしくは複合検索の検索をリクエスト
|
||
されたが、検索語がすべて空である。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_NO_CANDIDATES">定数 <code>EB_ERR_NO_CANDIDATES</code></a></h4>
|
||
|
||
<p>
|
||
<code>eb_multi_entry_candidates()</code> が呼び出されたが、
|
||
指定された複合検索エントリは、検索語の候補一覧データを持っていない。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_END_OF_CONTENT">定数 <code>EB_ERR_END_OF_CONTENT</code></a></h4>
|
||
|
||
<p>
|
||
<code>eb_forward_text()</code> あるいは <code>eb_backward_text()</code>
|
||
で本文の頭出しを行おうとしたが、すでに本文の末尾ないし先頭に達していて、
|
||
それ以上先に進むことができなかった。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_NO_PREV_SEEK">定数 <code>EB_ERR_NO_PREV_SEEK</code></a></h4>
|
||
|
||
<p>
|
||
あらかじめ <code>eb_seek_text()</code> でシークを行っていない状態で、
|
||
テキストデータの読み込みや頭出しを行おうとした。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_EBNET_UNSUPPORTED">定数 <code>EB_ERR_EBNET_UNSUPPORTED</code></a></h4>
|
||
|
||
<p>
|
||
この EB ライブラリは、遠隔ホストへのアクセスには対応していない。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_EBNET_FAIL_CONNECT">定数 <code>EB_ERR_EBNET_FAIL_CONNECT</code></a></h4>
|
||
|
||
<p>
|
||
遠隔ホストへのアクセスを試みたが、サーバ (EBNETD) に接続できなかった。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_EBNET_SERVER_BUSY">定数 <code>EB_ERR_EBNET_SERVER_BUSY</code></a></h4>
|
||
|
||
<p>
|
||
遠隔ホストへの接続を行ったが、書籍にアクセスしているクライアントの数が
|
||
すでに上限に達しているため、その書籍を利用できなかった。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_EBNET_NO_PERMISSION">定数 <code>EB_ERR_EBNET_NO_PERMISSION</code></a></h4>
|
||
|
||
<p>
|
||
遠隔ホストへの接続を行ったが、その書籍への利用権限がないため、サーバ
|
||
からアクセスを拒否された。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_UNBOUND_BOOKLIST">定数 <code>EB_ERR_UNBOUND_BOOKLIST</code></a></h4>
|
||
|
||
<p>
|
||
呼び出された EB ライブラリの関数は、遠隔ホストに結び付けられた
|
||
<code>EB_BookList</code> オブジェクトを引数にとるが、与えられたオブジェクト
|
||
は遠隔ホストに結び付けられていなかった。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:ERR_NO_SUCH_BOOK">定数 <code>EB_ERR_NO_SUCH_BOOK</code></a></h4>
|
||
|
||
<p>
|
||
<code>EB_BookList</code> オブジェクトと書籍の要素番号を関数に渡されたが、
|
||
<code>EB_BookList</code> に結び付けられた遠隔ホスト上には、その要素番号に
|
||
該当する書籍は存在しない。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="error-functions">関数の詳細</a></h3>
|
||
|
||
<p>
|
||
この節で説明している関数を使うには、次のようにヘッダファイルを読み込んで
|
||
下さい。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
#include <eb/error.h>
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:error_string"><code>const char *eb_error_string (EB_Error_Code <var>error_code</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_error_string()</code> は、エラーコード <var>error_code</var>
|
||
を文字列に変換したものを返します。
|
||
文字列の文字コードは、ASCII になります。
|
||
たとえば、エラーコード値 <code>EB_SUCCESS</code> を渡すと文字列
|
||
<samp>"EB_SUCCESS"</samp> を返します。
|
||
未知のエラーコードを渡したときは、<samp>"EB_ERR_UNKNOWN"</samp> を返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:error_message"><code>const char *eb_error_message (EB_Error_Code <var>error_code</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_error_message()</code> は、エラーコード <var>error_code</var>
|
||
に対応したメッセージを文字列にして返します。
|
||
関数の返すメッセージは、英語か日本語になります。
|
||
</p>
|
||
|
||
<p>
|
||
国際化機能を有効にして EB ライブラリをコンパイルしていない場合は、常に
|
||
英語のメッセージを返します。
|
||
このときのメッセージの文字コードは、ASCII になります。
|
||
</p>
|
||
|
||
<p>
|
||
メッセージの国際化機能 (NLS) を有効にして EB ライブラリをコンパイル
|
||
した場合は、ロケールの設定に応じてどちらの言語のメッセージを返すのか
|
||
が決まります。
|
||
また、GNU gettext バージョン 0.36 以降では iconv() と連携することにより、
|
||
メッセージの文字コードもロケールに応じて変化します。
|
||
gettext が iconv() との連携を行わなければ、英語のメッセージは ASCII、
|
||
日本語のメッセージは日本語 EUC になります。
|
||
この関数の呼び出しによって、gettext のテキストドメインの設定は変化
|
||
しません。
|
||
</p>
|
||
|
||
<p>
|
||
未知のエラーコードを渡したときに返すメッセージは、英語では
|
||
<samp>"unknown error"</samp>、日本語では <samp>"未知のエラーです"</samp>
|
||
になります。
|
||
</p>
|
||
|
||
<!-- ================================================================ -->
|
||
<h2><a name="subbook">副本</a></h2>
|
||
|
||
<p>
|
||
紙に印刷された本では別々の書籍になっているものでも、電子ブックや EPWING
|
||
では 1 枚の CD-ROM にまとめることができます。
|
||
</p>
|
||
|
||
<p>
|
||
たとえば、ある CD-ROM 書籍は、国語辞書、英々辞典、百科事典という 3 つ
|
||
の (印刷された本で言うところの) 「書籍」を持っていることもあり得ます。
|
||
紛らわしさを避けるために、EB ライブラリではここで言う「書籍」のことを
|
||
<dfn>副本 (subbook)</dfn> と呼んでいます。
|
||
</p>
|
||
|
||
<blockquote>
|
||
<pre>
|
||
ＣＤ－ＲＯＭ書籍
|
||
┌─────────────┐
|
||
│ 副本０： ［国語辞典］ │
|
||
│ 副本１： ［英々辞典］ │
|
||
│ 副本２： ［百科事典］ │
|
||
└─────────────┘
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
CD-ROM 書籍では、それぞれの副本はそれ自体が独立した書籍になっています。
|
||
また、副本のデータも、副本毎に別々のファイルに収められています。
|
||
したがって、EB ライブラリでも、アプリケーションプログラムの主要な処理
|
||
である単語の検索や本文データの取得などは、すべて副本単位で行うように
|
||
なっています。
|
||
</p>
|
||
|
||
<p>
|
||
本章では、EB ライブラリでの副本の扱い方について説明します。
|
||
</p>
|
||
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="subbook-code">副本コード</a></h3>
|
||
|
||
<p>
|
||
EB ライブラリでは、それぞれの副本に対して <dfn>副本コード (subbook code)</dfn>
|
||
を割り当てます。
|
||
このコードは EB ライブラリが副本を識別するために用いますので、個々の
|
||
副本コードは、書籍内で同じものがないようになっています。
|
||
</p>
|
||
|
||
<p>
|
||
以下のソースコードは、<code>eb_subbook_list()</code> という関数の
|
||
使用例です。
|
||
この関数は、書籍内のすべての副本の副本コードを取得することができます。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
/* <code>book</code> が <code>EB_Book</code> のオブジェクトで、すでに
|
||
* 書籍に結び付けられていると仮定しています。*/
|
||
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;
|
||
}
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
<code>eb_subbook_list()</code> が成功すると、書籍内のすべての副本コードが
|
||
配列 <code>sub_codes[]</code> に格納されます。
|
||
配列の先頭の副本コードは <code>sub_codes[0]</code> と表され、次の
|
||
コードは <code>sub_codes[1]</code>、という具合になります。
|
||
副本の個数は、<code>sub_count</code> に格納されます。
|
||
</p>
|
||
|
||
<p>
|
||
個々の副本には、必ず題名が付けられています。
|
||
先頭の副本 (<code>sub_codes[0]</code>) の題名は、次のようにして
|
||
得ることができます。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
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;
|
||
}
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
<code>eb_subbook_title2()</code> の呼び出しが成功すると、
|
||
<code>title</code> に題名を表す文字列が格納されます。
|
||
</p>
|
||
|
||
<p>
|
||
蛇足ですが、(副本ではなく) CD-ROM の題名を取得する関数はありません。
|
||
なぜなら、題名を示すデータが CD-ROM の中には何処にもないからです。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="current-subbook">選択中の副本</a></h3>
|
||
|
||
<p>
|
||
<code>EB_Book</code> オブジェクトは、結びつけられた CD-ROM 書籍の中の
|
||
任意の副本から一つ選んで、<dfn>選択中の副本 (current subbook)</dfn>
|
||
として指定することができます。
|
||
複数の副本を、同時に選択することはできません。
|
||
単語の検索や、本文データの取得など、ほとんどの操作は、選択中の副本に
|
||
対してだけ行えます。
|
||
</p>
|
||
|
||
<p>
|
||
<code>eb_bind()</code> で <code>EB_Book</code> オブジェクトを書籍に
|
||
結び付けた直後は、いずれの副本も選択されていない状態になっています。
|
||
</p>
|
||
|
||
<blockquote>
|
||
<pre>
|
||
ＥＢ＿Ｂｏｏｋ ＣＤ－ＲＯＭ書籍
|
||
オブジェクト
|
||
┌────┐ ┌─────────────┐
|
||
│選択中 │ │ 副本０： ［国語辞典］ │
|
||
│の副本 │ │ 副本１： ［英々辞典］ │
|
||
│＜なし＞│ │ 副本２： ［百科事典］ │
|
||
└────┘ └─────────────┘
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
副本の選択を行うには、関数 <code>eb_set_subbook()</code> を使用します。
|
||
<code>eb_set_subbook()</code> は、引数として渡された副本コードに
|
||
したがって副本を選択します。
|
||
以下は、先頭の副本 (<code>sub_codes[0]</code>) を選択する場合の例です。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
/* <code>book</code> が <code>EB_Book</code> のオブジェクトで、すでに
|
||
* 書籍に結び付けられていると仮定しています。*/
|
||
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;
|
||
}
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
成功すると、次のように副本が選択された状態になります。
|
||
</p>
|
||
|
||
<blockquote>
|
||
<pre>
|
||
ＥＢ＿Ｂｏｏｋ ＣＤ－ＲＯＭ書籍
|
||
オブジェクト
|
||
┌────┐ ┌─────────────┐
|
||
│選択中 │ ┏━━━━┿━副本０： ［国語辞典］ │
|
||
│の副本 │ ┃ │ 副本１： ［英々辞典］ │
|
||
│ ＊━━┿━━┛ │ 副本２： ［百科事典］ │
|
||
└────┘ └─────────────┘
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="subbook-sample">サンプルプログラム</a></h3>
|
||
|
||
<!-- #include "eb-sample-subbook.html" -->
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="subbook-data-types">データ型の詳細</a></h3>
|
||
|
||
<p>
|
||
この節で説明しているデータ型を使うには、次のようにヘッダファイルを
|
||
読み込んで下さい。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
#include <eb/eb.h>
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="type:Subbook_Code"><code>EB_Subbook_Code</code> 型</a></h4>
|
||
|
||
<p>
|
||
データ型 <code>EB_Subbook_Code</code> は副本コードを表します。
|
||
一冊の書籍の中の副本は、それぞれ一意の副本コードを持っています。
|
||
この型は符合付き整数型の別名として定義されていますので、2 つのコードを
|
||
2 項演算子 <code>==</code> と <code>!=</code> で一致比較することが
|
||
できます。
|
||
</p>
|
||
|
||
<p>
|
||
また、不正な副本コード値を表す <code>EB_SUBBOOK_INVALID</code> という
|
||
特別な副本コードが定義されています。
|
||
利用可能な副本に対して、この副本コードが割り当てられることはありません。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="subbook-functions">関数の詳細</a></h3>
|
||
|
||
<p>
|
||
この節で説明している関数を使うには、次のようにヘッダファイルを読み込んで
|
||
下さい。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
#include <eb/eb.h>
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:load_all_subbooks"><code>EB_Error_Code eb_load_all_subbooks (EB_Book *<var>book</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_load_all_subbooks()</code> は、<var>book</var> 内のすべての
|
||
副本を初期化します。
|
||
通常、副本の初期化は、その副本が初めて選択されたときに自動的に行われますが、
|
||
この関数は初期化を前倒しで行います。
|
||
初期化の対象となるのは、この関数を呼び出した時点でまだ初期化していない
|
||
すべての副本です。
|
||
この関数は、スタンドアロンで動作するサーバアプリケーションなどで有効です。
|
||
クライアントからの接続を受ける前にこの関数を呼ぶことで、副本の初期化の
|
||
ためにクライアントを待たせなくて済みます。
|
||
</p>
|
||
|
||
<p>
|
||
初期化の対象となったすべての副本の初期化に成功すれば、関数は
|
||
<code>EB_SUCCESS</code> を返します。
|
||
一冊でも初期化に失敗した場合は、残りの副本の初期化を諦め、原因を示す
|
||
エラーコードを返します。
|
||
</p>
|
||
|
||
<p>
|
||
<var>book</var> は、あらかじめ書籍に結び付けられていなくてはなりません。
|
||
結びついていない場合は、<code>EB_ERR_UNBOUND_BOOK</code> を返します。
|
||
</p>
|
||
|
||
<p>
|
||
この関数を呼び出すと、<var>book</var> は、副本を選択していない状態になります。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:subbook_list"><code>EB_Error_Code eb_subbook_list (EB_Book *<var>book</var>, EB_Subbook_Code *<var>subbook_list</var>, int *<var>subbook_count</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_subbook_list()</code> は、<var>book</var> 内のすべて副本の
|
||
副本コードを <code>EB_Subbook_Code</code> 型の配列にして、
|
||
<var>subbook_list</var> の指す領域に書き込みます。
|
||
配列は、最大で <code>EB_MAX_SUBBOOKS</code> 個の要素を持ちます。
|
||
加えて、書籍が収録している副本の個数を <var>subbook_count</var> の指す
|
||
領域に書き込みます。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、関数は <code>EB_SUCCESS</code> を返します。
|
||
失敗すると、<var>subbook_count</var> の指す領域に 0 を書き込み、原因を
|
||
示すエラーコードを返します。
|
||
</p>
|
||
|
||
<p>
|
||
<var>book</var> は、あらかじめ書籍に結び付けられていなくてはなりません。
|
||
結びついていない場合は、<code>EB_ERR_UNBOUND_BOOK</code> を返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:subbook"><code>EB_Error_Code eb_subbook (EB_Book *<var>book</var>, EB_Subbook_Code *<var>subbook_code</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_subbook()</code> は、<var>book</var> が選択中の副本の
|
||
副本コードを <var>subbook_code</var> の指す領域に書き込みます。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、関数は <code>EB_SUCCESS</code> を返します。
|
||
失敗すると、<var>subbook_code</var> の指す領域に
|
||
<code>EB_SUBBOOK_INVALID</code> を書き込み、原因を示すエラーコードを
|
||
返します。
|
||
</p>
|
||
|
||
<p>
|
||
あらかじめ、<var>book</var> はいずれかの副本を選択していなくてはなりません。
|
||
選択していない場合は、<code>EB_ERR_NO_CUR_SUB</code> を返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:subbook_title"><code>EB_Error_Code eb_subbook_title (EB_Book *<var>book</var>, char *<var>title</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_subbook_title()</code> は、<var>book</var> が選択中の副本の
|
||
題名を <var>title</var> の指す領域に文字列として書き込みます。
|
||
題名の文字列の長さは、最長で <code>EB_MAX_TITLE_LENGTH</code> バイトです。
|
||
この長さは、末尾のナル文字を含みません。
|
||
</p>
|
||
|
||
<p>
|
||
書籍の文字コード
|
||
(<a href="#eb_book-data-types">「[CD-ROM 書籍と <code>EB_Book</code> オブジェクト] データ型の詳細」</a> を参照のこと)
|
||
が <code>EB_CHARCODE_ISO8859_1</code> なら、題名を表す文字列は ISO 8859-1
|
||
になり、それ以外の文字コードなら日本語 EUC になります。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、関数は <code>EB_SUCCESS</code> を返します。
|
||
失敗すると、<var>title</var> の指す領域に空文字列を書き込み、原因を示す
|
||
エラーコードを返します。
|
||
</p>
|
||
|
||
<p>
|
||
あらかじめ、<var>book</var> 内のいずれかの副本が選択されていなくては
|
||
なりません。
|
||
選択していない場合は、<code>EB_ERR_NO_CUR_SUB</code> を返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:subbook_title2"><code>EB_Error_Code eb_subbook_title2 (EB_Book *<var>book</var>, EB_Subbook_Code <var>subbook_code</var>, char *<var>title</var>)</code></a></h4>
|
||
|
||
<p>
|
||
<code>eb_subbook_title()</code> と似ていますが、選択中の副本ではなく、
|
||
引数 <var>subbook_code</var> で指定された副本の題名を書き込む点が
|
||
異なります。
|
||
</p>
|
||
|
||
<p>
|
||
<var>book</var> は副本を選択していなくても構いませんが、あらかじめ書籍
|
||
に結び付けられていなければなりません。
|
||
結びついていない場合は、<code>EB_ERR_UNBOUND_BOOK</code> を返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:subbook_directory"><code>EB_Error_Code eb_subbook_directory (EB_Book *<var>book</var>, char *<var>directory</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_subbook_directory()</code> は、<var>book</var> 内で現在
|
||
選択中の副本のデータファイルを収めたディレクトリ名を、<var>directory</var>
|
||
の指す領域に書き込みます。
|
||
</p>
|
||
|
||
<p>
|
||
ディレクトリ名の文字列の長さは、最長で
|
||
<code>EB_MAX_DIRECTORY_NAME_LENGTH</code> バイトです。
|
||
この長さに、末尾のナル文字は含みません。
|
||
ディレクトリ名は ASCII の数字、英小文字、アンダースコアで構成されます。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、関数は <code>EB_SUCCESS</code> を返します。
|
||
失敗すると、<var>directory</var> の指す領域に空文字列を書き込み、原因に
|
||
を示すエラーコードを返します。
|
||
</p>
|
||
|
||
<p>
|
||
あらかじめ、<var>book</var> 内のいずれかの副本が選択されていなくては
|
||
なりません。
|
||
選択していない場合は、<code>EB_ERR_NO_CUR_SUB</code> を返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:subbook_directory2"><code>EB_Error_Code eb_subbook_directory2 (EB_Book *<var>book</var>, EB_Subbook_Code <var>subbook_code</var>, char *<var>directory</var>)</code></a></h4>
|
||
|
||
<p>
|
||
<code>eb_subbook_directory()</code> と似ていますが、選択中の副本ではなく、
|
||
引数 <var>subbook_code</var> で指定された副本のディレクトリ名を書き込む点
|
||
が異なります。
|
||
</p>
|
||
|
||
<p>
|
||
<var>book</var> は副本を選択していなくても構いませんが、あらかじめ
|
||
書籍に結び付けられていなければなりません。
|
||
結びついていない場合は、<code>EB_ERR_UNBOUND_BOOK</code> を返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:set_subbook"><code>EB_Error_Code eb_set_subbook (EB_Book *<var>book</var>, EB_Subbook_Code <var>code</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_set_subbook()</code> は、<var>book</var> の副本
|
||
<var>code</var> を選択します。
|
||
すでに副本を選択していた場合は、いったん未選択の状態にしてから副本
|
||
<var>subbook_code</var> を選択します。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、関数は <code>EB_SUCCESS</code> を返します。
|
||
このとき、外字は未選択の状態となり、検索、テキストデータの読み込み、
|
||
バイナリデータの読み込みについての状態記録は、すべてリセットされます。
|
||
失敗すると、副本を未選択の状態にして、原因を示すエラーコードを返します。
|
||
</p>
|
||
|
||
<p>
|
||
あらかじめ、<var>book</var> は書籍に結び付けられていなければなりません。
|
||
結びついていない場合は、<code>EB_ERR_UNBOUND_BOOK</code> を返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:unset_subbook"><code>void eb_unset_subbook (EB_Book *<var>book</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_unset_subbook()</code> は、<var>book</var> が選択している
|
||
副本を未選択の状態にします。
|
||
<var>book</var> が書籍に結び付いていないか、副本が選択されていない場合は、
|
||
何もしません。
|
||
</p>
|
||
|
||
<!-- ================================================================ -->
|
||
<h2><a name="search">検索</a></h2>
|
||
|
||
<p>
|
||
CD-ROM 書籍において、検索は非常に重要な機能です。
|
||
EB ライブラリでは、次のような検索メソッドが利用できます。
|
||
</p>
|
||
|
||
<ul>
|
||
<li>前方一致検索 (word search)
|
||
<li>後方一致検索 (end-word search)
|
||
<li>完全一致検索 (exact-word search)
|
||
<li>条件検索 (keyword search)
|
||
<li>クロス検索 (cross search)
|
||
<li>複合検索 (multi search)
|
||
</ul>
|
||
|
||
<p>
|
||
ただし、すべての CD-ROM 書籍、すべての副本で、ここに挙げたすべての
|
||
検索メソッドが利用可能なわけではありません。
|
||
副本の中には、いずれの検索メソッドも提供しないものも存在します。
|
||
</p>
|
||
|
||
<p>
|
||
EB ライブラリでは、検索を行うことができるのは、選択中の副本に対して
|
||
だけです。
|
||
</p>
|
||
|
||
<p>
|
||
この章では、それぞれの検索メソッドの簡単な説明と、EB ライブラリでの
|
||
扱い方について説明します。
|
||
</p>
|
||
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="word-search">前方一致、後方一致、完全一致検索</a></h3>
|
||
|
||
<p>
|
||
前方一致、後方一致、完全一致検索は、いずれも一個の入力語に一致する
|
||
エントリを探し出す検索メソッドです。
|
||
</p>
|
||
|
||
<p>
|
||
前方一致検索は、入力語と先頭部分が一致するエントリを検索します。
|
||
たとえば、「江戸」という語は、「江戸」「江戸時代」「江戸っ子」といった
|
||
エントリに一致します。
|
||
</p>
|
||
|
||
<p>
|
||
後方一致検索は、入力語と末尾が一致するエントリを検索します。
|
||
たとえば、`bye' という語は、`bye'、`good bye'、`bye bye' といった
|
||
エントリに一致します。
|
||
</p>
|
||
|
||
<p>
|
||
完全一致検索は、一個の検索語と完全に一致するエントリだけを検索します。
|
||
</p>
|
||
|
||
<p>
|
||
以下は、前方一致検索のプログラムの例です。
|
||
選択中の副本の中から、先頭が <samp>librar</samp> で始まるエントリを探して
|
||
います。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
/* <code>book</code> が <code>EB_Book</code> のオブジェクトで、すでに
|
||
* 書籍に結び付けられ、副本を選択中だと仮定しています。*/
|
||
#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;
|
||
}
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
<code>eb_search_word()</code> は前方一致検索をリクエストする関数です。
|
||
この例では、<samp>librar</samp> という検索文字列を与えています。
|
||
ただし、この関数は一致したエントリを返すことはしません。
|
||
</p>
|
||
|
||
<p>
|
||
一致したエントリの取得は、続く <code>eb_hit_list()</code> 関数を
|
||
呼び出した際に行われます。
|
||
<code>eb_hit_list()</code> は一致したエントリの一覧を配列
|
||
<code>hits[]</code> の指す領域に書き込み、見つかった一致エントリの個数
|
||
を <code>&hit_count</code> の指す領域に書き込みます。
|
||
この例では、<code>eb_hit_list()</code> は最大で <code>MAX_HITS</code>
|
||
(= 50) 個 のエントリを探します。
|
||
(つまり、50 個見つかったら検索を止めます。)
|
||
</p>
|
||
|
||
<p>
|
||
もし、選択中の副本が英々辞典だとすると、少なくとも <samp>library</samp>
|
||
と <samp>librarian</samp> という 2 つのエントリに関する情報が得られる
|
||
でしょう。
|
||
このとき、配列 <code>hits[]</code> は次のようになっています。
|
||
(ただし、<samp>library</samp> と <samp>librarian</samp> エントリの
|
||
順序は、下の絵とは異なっているかも知れません。)
|
||
</p>
|
||
|
||
<blockquote>
|
||
<pre>
|
||
┌───────────┬───────────┬─
|
||
│ ｌｉｂｒａｒｉａｎ │ ｌｉｂｒａｒｙ │
|
||
└───────────┴───────────┴─
|
||
ｈｉｔｓ［０］ ｈｉｔｓ［１］
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
<code>hits[]</code> の中身については、本章の後ろの節でもう少し詳しく
|
||
説明します。
|
||
</p>
|
||
|
||
<p>
|
||
ここまでは前方一致検索を例にとりましたが、後方一致の場合は
|
||
<code>eb_search_word()</code> の代わりに <code>eb_search_endword()</code>
|
||
を呼ぶようにします。
|
||
他はすべて同じです。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
if (eb_search_endword(&book, "nalization") != EB_SUCCESS) {
|
||
printf("eb_search_endword() failed\n");
|
||
return;
|
||
}
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
完全一致の場合も同様です。
|
||
<code>eb_search_exactword()</code> を呼ぶようにする以外は、すべて同じ
|
||
です。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
if (eb_search_exactword(&book, "library") != EB_SUCCESS) {
|
||
printf("eb_search_exactword() failed\n");
|
||
return;
|
||
}
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="keyword-search">条件検索</a></h3>
|
||
|
||
<p>
|
||
条件検索は、複数個の入力語にすべて一致するエントリを検索します。
|
||
たとえば、英々辞典の条件検索では、入力語をすべて含んだ例文を検索する
|
||
ようになっているかも知れません。
|
||
</p>
|
||
|
||
<p>
|
||
以下は、条件検索で <samp>make</samp>, <samp>with</samp> という語の双方と
|
||
一致するエントリを、選択中の副本の中から探し出すプログラムの断片です。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
/* <code>book</code> が <code>EB_Book</code> のオブジェクトで、すでに
|
||
* 書籍に結び付けられ、副本を選択中だと仮定しています。*/
|
||
static const char *keywords[3] = {"make", "with", NULL};
|
||
|
||
if (eb_search_word(&book, keywords) != EB_SUCCESS) {
|
||
printf("eb_search_word() failed\n");
|
||
return;
|
||
}
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
条件検索を行う関数は、<code>eb_search_keyword()</code> です。
|
||
前方一致、後方一致、完全一致検索の関数と基本的に扱い方は一緒ですが、
|
||
複数の入力語を受け付けるようになっています。
|
||
関数には、入力語の文字列 (へのポインタ) を配列にしたものを渡します。
|
||
配列の最後には <code>NULL</code> を置き、配列の終端を明示する必要が
|
||
ある点に注意して下さい。
|
||
</p>
|
||
|
||
<p>
|
||
前方一致、後方一致、完全一致検索と同様に、<code>eb_search_keyword()</code>
|
||
も検索のリクエストを行うだけで、一致したエントリの取得は行いません。
|
||
エントリの取得には、やはり同様に <code>eb_hit_list()</code> 関数を
|
||
使います。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
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;
|
||
}
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="cross-search">クロス検索</a></h3>
|
||
|
||
<p>
|
||
クロス検索は、条件検索の亜種とも言うべき検索メソッドです。
|
||
EPWING や電子ブックをみても、どういうルールで使い分けがなされているのか
|
||
分からない程、両者は実によく似ています。
|
||
</p>
|
||
|
||
<p>
|
||
EB ライブラリでクロス検索を行う関数は <code>eb_search_cross()</code>
|
||
ですが、使い方は条件検索の関数 <code>eb_search_keyword()</code> と
|
||
まったく同じです。
|
||
使い方の詳細は、<a href="#keyword-search">「条件検索」</a> をご覧下さい。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="multi-search">複合検索</a></h3>
|
||
|
||
<p>
|
||
複合検索は、条件検索と同じく、複数個の入力語にすべて一致するエントリを
|
||
検索しますが、個々の入力語にあらかじめ題目が付けられています。
|
||
</p>
|
||
|
||
<p>
|
||
また、前方一致、後方一致、完全一致、条件検索はすべて、各副本につき
|
||
一種類しかありませんが、複合検索だけは一つの副本の中で複数の種類が用意
|
||
されていることがあります。
|
||
たとえば、ある世界人名事典には、次のように人名検索用と頻出用語の検索用
|
||
の 2 種類の複合検索が用意されているかも知れません。
|
||
</p>
|
||
|
||
<blockquote>
|
||
<pre>
|
||
(複合検索その 1: 人名を検索する)
|
||
入力語 0: 国・地域
|
||
入力語 1: 時代
|
||
入力語 2: 性別
|
||
入力語 3: キーワード
|
||
入力語 4: キーワード
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<blockquote>
|
||
<pre>
|
||
(複合検索その 2: 頻出用語を検索する)
|
||
入力語 0: 用語
|
||
入力語 1: キーワード
|
||
入力語 2: キーワード
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
この例のように、個々の複合検索は、入力語の題目だけでなく、入力語の数も
|
||
まちまちです。
|
||
また、検索する際はすべての入力語を埋める必要はなく、少なくとも一個の
|
||
入力語が空でなければ、検索は成功します。
|
||
</p>
|
||
|
||
<p>
|
||
副本内の複合検索は、種類毎に <dfn>複合検索コード (multi search code)</dfn>
|
||
によって識別されます。
|
||
関数 <code>eb_multi_search_list()</code> を使うと、選択中の副本で利用可能
|
||
な複合検索の一覧が得られます。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
/* <code>book</code> が <code>EB_Book</code> のオブジェクトで、すでに
|
||
* 書籍に結び付けられ、副本を選択中だと仮定しています。*/
|
||
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;
|
||
}
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
この複合検索コードは、複合検索のための関数で必要となります。
|
||
たとえば、<code>eb_multi_title()</code> は、指定した複合検索の題名
|
||
(例:「人名検索」「頻出用語検索」) を取得する関数ですが、このときの
|
||
複合検索の指定には、複合検索コードを用います。
|
||
以下の例では、一覧の先頭に載っている複合検索 (<code>multi_codes[0]</code>)
|
||
を指定しています。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
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;
|
||
}
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
さらに関数によっては、複合検索コードに加えて、何番目の入力語かも指定
|
||
してやる必要があります。
|
||
たとえば、特定の入力語の題目を得る関数 <code>eb_multi_entry_label()</code>
|
||
が、これに該当します。
|
||
0 番目の入力語 (つまり先頭の入力語) の題目を取得するには、次のように
|
||
します。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
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;
|
||
}
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
複合検索を行う関数は、<code>eb_search_multi()</code> です。
|
||
使い方は条件検索とほぼ同じで、入力語の文字列を配列にしたものを引数
|
||
として渡し、配列の最後には <code>NULL</code> を置いて下さい。
|
||
埋められていない入力語のところには、空文字列を置きます。
|
||
</p>
|
||
|
||
<p>
|
||
<code>eb_search_multi()</code> も検索のリクエストを行うだけで、一致した
|
||
エントリの取得は行いません。
|
||
取得するには <code>eb_hit_list()</code> を使います。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
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;
|
||
}
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
なお、複合検索の入力語によっては
|
||
<dfn>候補一覧 (candidates)</dfn> があらじめ用意されていることがあります。
|
||
これは、入力語として有効な語をあらかじめ列挙しておき、
|
||
アプリケーションプログラムのユーザに選択させる仕組みです。
|
||
候補一覧については、この章ではなく「テキストデータ」の章で説明します
|
||
(<a href="#multi-candidates">「複合検索の候補一覧」</a> を参照のこと)。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="eb_hit">一致エントリの情報</a></h3>
|
||
|
||
<p>
|
||
<code>eb_hit_list()</code> は、リクエストされた検索 (前方一致、後方一致、
|
||
完全一致、条件、複合) に一致したエントリの情報と見つかったエントリの
|
||
個数を、それぞれ <code>EB_Hit</code> 型の配列領域および <code>int</code> 型の
|
||
領域に書き込みます。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
/* <code>book</code> が <code>EB_Book</code> のオブジェクトで、すでに書籍に結び付け
|
||
* られ、副本を選択中だと仮定しています。*/
|
||
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;
|
||
}
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
<code>EB_Hit</code> 配列の個々の要素には、一致したエントリの
|
||
<dfn>見出し (heading)</dfn> と <dfn>本文 (text)</dfn> の開始位置が
|
||
書き込まれています。
|
||
</p>
|
||
|
||
<blockquote>
|
||
<pre>
|
||
見出し
|
||
┌────────────┐
|
||
ＥＢ＿Ｈｉｔ ┏━┿ｌｉｂｒａｒｉａｎ ｎ．│
|
||
┌───────┐ ┃ └────────────┘
|
||
│ｈｅａｄｉｎｇ┿━┛ 本文
|
||
│ │ ┌────────────────────┐
|
||
│ ｔｅｘｔ┿━━━┿ｌｉｂｒａｒｉａｎ │
|
||
└───────┘ │ｎ．（１）Ａ ｐｅｒｓｏｎ ｗｈｏ ｉｓ│
|
||
│ａ ｓｐｅｃｉａｌｉｓｔ ｉｎ │
|
||
│ｌｉｂｒａｒｙ ｗｏｒｋ．（２）．．． │
|
||
└────────────────────┘
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
見出しと本文についてのより詳しい解説と取得方法については、
|
||
<a href="#text-data">「テキストデータ」</a> を参照のこと。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="get-remained-entries">残っているエントリの取得</a></h3>
|
||
|
||
<p>
|
||
前に述べたように、<code>eb_hit_list()</code> を呼び出すときは、一致する
|
||
エントリを最大で何個まで探すのかを引数で指定します。
|
||
また、<code>eb_hit_list()</code> は処理が成功すると、実際に見つかった
|
||
エントリの数をアプリケーションプログラムに教えます。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
error_code = eb_hit_list(&book, MAX_HITS, hits, &hit_count);
|
||
if (error_code == EB_SUCCESS)
|
||
printf("%d entries found\n", hit_count);
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
指定した最大個数よりも多くの一致エントリが副本に存在している場合は、
|
||
<code>eb_hit_list()</code> を繰り返し呼び出すことで、残りのエントリを
|
||
取得することができます。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
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;
|
||
/* 取得した一致エントリの処理 */
|
||
}
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
一致エントリがもう残っていなければ、<code>eb_hit_list()</code> は
|
||
<code>&hit_count</code> の指す領域に 0 を書き込んで、
|
||
<code>EB_SUCCESS</code> を返します。
|
||
</p>
|
||
|
||
<p>
|
||
ただし、途中で <code>eb_hit_list()</code> が失敗すると
|
||
(<code>EB_SUCCESS</code> 以外の値を返すと)、検索リクエストに関する
|
||
状態記録はリセットされるため、一致エントリの取得をそれ以上続けることは
|
||
できません。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="unify-duplicated-entries">重複エントリの削除</a></h3>
|
||
|
||
<p>
|
||
<code>eb_hit_list()</code> を用いて一致したエントリを取得すると、中身が
|
||
実質的に変わらないエントリが複数含まれていることがあります。
|
||
EB ライブラリは、こうした重複エントリの削除は行いません。
|
||
必要なら、アプリケーション側で行うことになります。
|
||
</p>
|
||
|
||
<p>
|
||
重複を完璧に取り除くなら、以下のすべての条件に一致するエントリを
|
||
重複エントリとみなし、二度目以降に出現したエントリを削除します。
|
||
</p>
|
||
|
||
<ul>
|
||
<li>エントリの指す本文の位置が同じ
|
||
<li>エントリの指す見出しの文字列 (位置ではなく文字列そのもの) が同じ
|
||
</ul>
|
||
|
||
<p>
|
||
(見出し文字列の取得方法については、
|
||
<a href="#text-data">「テキストデータ」</a> を参照のこと。)
|
||
</p>
|
||
|
||
<p>
|
||
重複は、直前のエントリに対してのみ起こるとは限りません。
|
||
たとえば、<code>eb_hit_list()</code> で一致エントリが 50 個得られた場合、
|
||
最後の 50 個目は前方の 49 個と重複検査を行う必要があります。
|
||
したがって、全体ではエントリ同士の比較を 1 + 2 + ... + 49 = 1225 回
|
||
行うことになります。
|
||
</p>
|
||
|
||
<p>
|
||
書籍によっては重複エントリが取りきれない可能性もありますが、もう少し
|
||
簡単な方法もいくつかあります。
|
||
処理を簡単にする第一の方法は、重複エントリの判定条件を次のように変える
|
||
ことです。
|
||
</p>
|
||
|
||
<ul>
|
||
<li>エントリの指す本文の位置が同じ
|
||
<li>エントリの指す見出しの文字列の位置が同じ
|
||
</ul>
|
||
|
||
<p>
|
||
さらに処理を簡単にするには、直前の 1個のエントリに対してだけ重複検査を
|
||
行うという方法もあります。
|
||
これなら、50 個の一致エントリに対して、比較は 49 回で済みます。
|
||
ただしこの方法は、書籍によってはまったく効果がありません。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="search-sample">サンプルプログラム</a></h3>
|
||
|
||
<!-- #include "eb-sample-word.html" -->
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="search-data-types">データ型の詳細</a></h3>
|
||
|
||
<p>
|
||
この節で説明しているデータ型を使うには、次のようにヘッダファイルを
|
||
読み込んで下さい。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
#include <eb/eb.h>
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="type:Hit"><code>EB_Hit</code> 型</a></h4>
|
||
|
||
<p>
|
||
<code>EB_Hit</code> は、検索に一致したエントリの情報を格納するための
|
||
データ型です。
|
||
内部構造は、次のように定義されています。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
typedef struct EB_Hit_Struct EB_Hit;
|
||
|
||
struct EB_Hit_Struct {
|
||
EB_Position heading; /* 見出しの位置 */
|
||
EB_Position text; /* 本文の位置 */
|
||
};
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
アプリケーションプログラムは、直接 <code>EB_Hit</code> オブジェクトの
|
||
メンバを参照したり、セットしたりしても構いません。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="type:Position"><code>EB_Position</code> 型</a></h4>
|
||
|
||
<p>
|
||
データ型 <code>EB_Position</code> は、副本のデータの位置を表します。
|
||
内部構造は、次のように定義されています。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
typedef struct EB_Position_Struct EB_Position;
|
||
|
||
struct EB_Position_Struct {
|
||
int page; /* ページ番号 */
|
||
int offset; /* ページ内のオフセット */
|
||
};
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
ページ番号は 1 から始まり、ページ内のオフセットは 0 ～ 2047 の範囲と
|
||
なります。
|
||
ただし、アプリケーションプログラムを作成する上で、このことを覚えておく
|
||
必要はありません。
|
||
</p>
|
||
|
||
<p>
|
||
アプリケーションプログラムは、直接 <code>EB_Position</code> オブジェクト
|
||
のメンバを参照したり、セットしたりしても構いません。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="type:Multi_Search_Code"><code>EB_Multi_Search_Code</code> 型</a></h4>
|
||
|
||
<p>
|
||
データ型 <code>EB_Multi_Search_Code</code> は複合検索コードを表します。
|
||
副本に用意されている複合検索は、それぞれ一意の複合検索コードを
|
||
持っています。
|
||
この型は符合付き整数型の別名として定義されていますので、2 つのコードを
|
||
2 項演算子 <code>==</code> と <code>!=</code> で一致比較することが
|
||
できます。
|
||
</p>
|
||
|
||
<p>
|
||
また、不正な複合検索コード値を表す <code>EB_MULTI_INVALID</code> という
|
||
特別な副本コードが定義されています。
|
||
利用可能な複合検索に対して、この複合検索コードが割り当てられることは
|
||
ありません。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="search-functions">関数の詳細</a></h3>
|
||
|
||
<p>
|
||
この節で説明している関数を使うには、次のようにヘッダファイルを読み込んで
|
||
下さい。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
#include <eb/eb.h>
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:have_word_search"><code>int eb_have_word_search (EB_Book *<var>book</var>)</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:have_endword_search"><code>int eb_have_endword_search (EB_Book *<var>book</var>)</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:have_exactword_search"><code>int eb_have_exactword_search (EB_Book *<var>book</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_have_word_search()</code> は、<var>book</var> が選択中の
|
||
副本で前方一致検索メソッドが利用可能どうかを調べます。
|
||
同様に <code>eb_have_endword_search()</code> は後方一致検索メソッドに
|
||
ついて、<code>eb_have_exactword_search()</code> は完全一致検索メソッドに
|
||
ついて利用可能どうかを調べます。
|
||
</p>
|
||
|
||
<p>
|
||
利用可能なら 1 を返します。
|
||
メソッドを持っていないか、そもそも副本が選択されていない場合は 0 を
|
||
返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:have_keyword_search"><code>int eb_have_keyword_search (EB_Book *<var>book</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_have_keyword_search()</code> は、<var>book</var> が選択中の
|
||
副本で条件検索メソッドが利用可能どうかを調べます。
|
||
</p>
|
||
|
||
<p>
|
||
利用可能なら 1 を返します。
|
||
メソッドを持っていないか、そもそも副本が選択されていない場合は 0 を
|
||
返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:have_multi_search"><code>int eb_have_multi_search (EB_Book *<var>book</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_have_multi_search()</code> は、<var>book</var> が選択中の
|
||
副本で複合検索メソッドが利用可能どうかを調べます。
|
||
</p>
|
||
|
||
<p>
|
||
最低 1 種類でも利用可能なら 1 を返します。
|
||
メソッドを持っていないか、そもそも副本が選択されていない場合は 0 を
|
||
返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:multi_search_list"><code>EB_Error_Code eb_multi_search_list (EB_Book *<var>book</var>, EB_Multi_Search_Code *<var>multi_list</var>, int *<var>multi_count</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_multi_search_list()</code> は、<var>book</var> が選択中の
|
||
副本に用意されている複合検索を調べ、複合検索コードの一覧を
|
||
<code>EB_Multi_Search_Code</code> 型の配列にして、<var>multi_list</var>
|
||
の指す領域に書き込みます。
|
||
配列は、最大で <code>EB_MAX_MULTI_SEARCHES</code> 個の要素を持ちます。
|
||
加えて、複合検索の種類数を <var>multi_count</var> の指す領域に書き込みます。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、関数は <code>EB_SUCCESS</code> を返します。
|
||
失敗すると、<var>subbook_count</var> の指す領域に 0 を書き込み、原因を示す
|
||
エラーコードを返します。
|
||
</p>
|
||
|
||
<p>
|
||
あらかじめ、<var>book</var> はいずれかの副本を選択していなくてはなりません。
|
||
選択していない場合は、<code>EB_ERR_NO_CUR_SUB</code> を返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:multi_entry_count"><code>EB_Error_Code eb_multi_entry_count (EB_Book *<var>book</var>, EB_Multi_Search_Code <var>multi_id</var>, int *<var>entry_count</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_multi_search_list()</code> は、<var>book</var> が選択中の
|
||
副本に用意されている複合検索 <var>multi_id</var> について調べ、入力語の
|
||
個数を <var>entry_count</var> の指す領域に書き込みます。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、関数は <code>EB_SUCCESS</code> を返します。
|
||
このとき書き込まれる入力語の個数は、1 以上 <code>EB_MAX_MULTI_ENTRIES</code>
|
||
以下になります。
|
||
失敗すると、<var>entry_count</var> の指す領域には 0 を書き込み、原因を示す
|
||
エラーコードを返します。
|
||
</p>
|
||
|
||
<p>
|
||
あらかじめ、<var>book</var> はいずれかの副本を選択していなくてはなりません。
|
||
選択していない場合は、<code>EB_ERR_NO_CUR_SUB</code> を返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:multi_title"><code>EB_Error_Code eb_multi_title (EB_Book *<var>book</var>, EB_Multi_Search_Code <var>multi_id</var>, char *<var>title</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_multi_search_list()</code> は、<var>book</var> が選択中の
|
||
副本に用意されている複合検索 <var>multi_id</var> の題名を <var>title</var>
|
||
の指す領域に書き込みます。
|
||
題目は最長で <code>EB_MAX_MULTI_TITLE_LENGTH</code> バイトになります。
|
||
この長さに、ナル文字は含みません。
|
||
</p>
|
||
|
||
<p>
|
||
書籍の文字コード
|
||
(<a href="#eb_book-data-types">「[CD-ROM 書籍と <code>EB_Book</code> オブジェクト] データ型の詳細」</a> を参照のこと)
|
||
が <code>EB_CHARCODE_ISO8859_1</code> なら、題目を表す文字列は ISO 8859-1
|
||
になり、それ以外の文字コードなら日本語 EUC になります。
|
||
</p>
|
||
|
||
<p>
|
||
書籍によっては、複合検索は用意していても、複合検索の題名データを持って
|
||
いないことがあります。
|
||
その場合、EB ライブラリが代わりに付けた題名が <var>title</var> に
|
||
書き込まれます。
|
||
</p>
|
||
|
||
<p>
|
||
書籍の文字コードが <code>EB_CHARCODE_ISO8859_1</code> なら、
|
||
EB ライブラリが付ける題名は、"Multi Search 1", "Multi Search 2", ...
|
||
になります。
|
||
それ以外の文字コードであれば、題名は日本語 EUC で書かれた「複合検索 1」
|
||
「複合検索 2」... という文字列になります。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、関数は <code>EB_SUCCESS</code> を返します。
|
||
失敗すると、<var>label</var> の指す領域には空文字列を書き込み、原因を示す
|
||
エラーコードを返します。
|
||
</p>
|
||
|
||
<p>
|
||
あらかじめ、<var>book</var> はいずれかの副本を選択していなくてはなりません。
|
||
選択していない場合は、<code>EB_ERR_NO_CUR_SUB</code> を返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:multi_entry_label"><code>EB_Error_Code eb_multi_entry_label (EB_Book *<var>book</var>, EB_Multi_Search_Code <var>multi_id</var>, int <var>entry_index</var>, char *<var>label</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_multi_search_list()</code> は、<var>book</var> が選択中の
|
||
副本に用意されている複合検索 <var>multi_id</var> について調べ、
|
||
<var>entry_index</var> 番目の検索語の題目を <var>label</var> の指す領域に
|
||
書き込みます。
|
||
<var>entry_index</var> は、先頭の検索語を 0 番目と数えます。
|
||
題目は最長で <code>EB_MAX_MULTI_LABEL_LENGTH</code> バイトになります。
|
||
この長さに、ナル文字は含みません。
|
||
</p>
|
||
|
||
<p>
|
||
書籍の文字コード
|
||
(<a href="#eb_book-data-types">「[CD-ROM 書籍と <code>EB_Book</code> オブジェクト] データ型の詳細」</a> を参照のこと)
|
||
が <code>EB_CHARCODE_ISO8859_1</code> なら、題目を表す文字列は ISO 8859-1
|
||
になり、それ以外の文字コードなら日本語 EUC になります。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、関数は <code>EB_SUCCESS</code> を返します。
|
||
失敗すると、<var>label</var> の指す領域には空文字列を書き込み、原因を示す
|
||
エラーコードを返します。
|
||
</p>
|
||
|
||
<p>
|
||
あらかじめ、<var>book</var> はいずれかの副本を選択していなくてはなりません。
|
||
選択していない場合は、<code>EB_ERR_NO_CUR_SUB</code> を返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:multi_entry_have_candidates"><code>int eb_multi_entry_have_candidates (EB_Book *<var>book</var>, EB_Multi_Search_Code <var>multi_id</var>, int <var>entry_index</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_multi_search_list()</code> は、<var>book</var> が選択中の
|
||
副本に用意されている複合検索 <var>multi_id</var> について調べ、
|
||
<var>entry_index</var> 番目の検索語が候補一覧を持っているかどうか調べます。
|
||
<var>entry_index</var> は、先頭の検索語を 0 番目と数えます。
|
||
</p>
|
||
|
||
<p>
|
||
持っていれば 1 を返します。
|
||
持っていないか、そもそも副本が選択されていない場合、あるいは
|
||
<var>multi_id</var>, や <var>entry_index</var> が不正な値だった場合は
|
||
0 を返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:multi_entry_candidates"><code>EB_Error_Code eb_multi_entry_candidates (EB_Book *<var>book</var>, EB_Multi_Search_Code <var>multi_id</var>, int <var>entry_index</var>, EB_Position *<var>position</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_multi_search_list()</code> は、<var>book</var> が選択中の
|
||
副本に用意されている複合検索 <var>multi_id</var> について調べ、
|
||
<var>entry_index</var> 番目の検索語の候補一覧の位置を <var>position</var>
|
||
の指す領域に書き込みます。
|
||
先頭の検索語が 0 番目になります。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、関数は <code>EB_SUCCESS</code> を返します。
|
||
失敗すると、<var>positin</var> の指す領域には <code>eb_seek_text()</code>
|
||
が必ず失敗する位置情報を書き込み、原因を示すエラーコードを返します。
|
||
</p>
|
||
|
||
<p>
|
||
あらかじめ、<var>book</var> はいずれかの副本を選択していなくてはなりません。
|
||
選択していない場合は、<code>EB_ERR_NO_CUR_SUB</code> を返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:search_word"><code>EB_Error_Code eb_search_word (EB_Book *<var>book</var>, const char *<var>input_word</var>)</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:search_endword"><code>EB_Error_Code eb_search_endword (EB_Book *<var>book</var>, const char *<var>input_word</var>)</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:search_exactword"><code>EB_Error_Code eb_search_exactword (EB_Book *<var>book</var>, const char *<var>input_word</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_search_word()</code> は、<var>book</var> が選択中の副本に
|
||
対する前方一致検索をリクエストします。
|
||
同様に <code>eb_search_endword()</code> は後方一致検索を、
|
||
<code>eb_search_exactword()</code> は完全一致検索をリクエストします。
|
||
</p>
|
||
|
||
<p>
|
||
検索する語は、引数 <var>input_word</var> で指定します。
|
||
ただし、これらの関数は検索をリクエストするだけで、一致したエントリの
|
||
情報を返すことはしません。
|
||
一致したエントリの取得には <code>eb_hit_list()</code> を使います。
|
||
関数は、成功すると <code>EB_SUCCESS</code> を返します。
|
||
失敗すると、原因を示すエラーコードを返します。
|
||
失敗すると、関数を呼び出す前にリクエストしていた検索の状態記録はリセット
|
||
されますので、その状態のまま <code>eb_hit_list()</code> を呼び出しても、
|
||
やはり失敗に終わります。
|
||
</p>
|
||
|
||
<p>
|
||
書籍の文字コード
|
||
(<a href="#eb_book-data-types">「[CD-ROM 書籍と <code>EB_Book</code> オブジェクト] データ型の詳細」</a> を参照のこと)
|
||
が <code>EB_CHARCODE_ISO8859_1</code> なら、関数に渡す検索語は ISO 8859-1
|
||
で書かれていなければなりません。
|
||
それ以外の文字コードの場合は、日本語 EUC で書かれていなければなりません。
|
||
不正な文字番号を含んでいた場合、関数は <code>EB_ERR_BAD_WORD</code> を
|
||
返します。
|
||
</p>
|
||
|
||
<p>
|
||
加えて、検索語は 1 バイト以上、<code>EB_MAX_WORD_LENGTH</code> (= 255)
|
||
バイト以下でなければなりません。
|
||
この長さに、ナル文字は含みません。
|
||
長すぎる場合は、<code>EB_ERR_TOO_LONG_WORD</code> を、
|
||
長さが 0 (空文字列) の場合は <code>EB_ERR_EMPTY_WORD</code> を返します。
|
||
</p>
|
||
|
||
<p>
|
||
あらかじめ、<var>book</var> はいずれかの副本を選択していなくてはなりません。
|
||
選択していない場合は、<code>EB_ERR_NO_CUR_SUB</code> を返します。
|
||
なお、一致するエントリが最低 1 個あるかどうかは、戻り値には影響しません。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:search_keyword"><code>EB_Error_Code eb_search_keyword (EB_Book *<var>book</var>, const char * const <var>input_words</var>[])</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:search_cross"><code>EB_Error_Code eb_search_cross (EB_Book *<var>book</var>, const char * const <var>input_words</var>[])</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:search_multi"><code>EB_Error_Code eb_search_multi (EB_Book *<var>book</var>, EB_Multi_Search_Code <var>multi_id</var>, const char * const <var>input_words</var>[])</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_search_keyword()</code> は、<var>book</var> が選択中の
|
||
副本に対する条件検索をリクエストします。
|
||
同様に <code>eb_search_cross()</code> はクロス検索を、
|
||
<code>eb_search_multi()</code> は複合検索をそれぞれリクエストします。
|
||
</p>
|
||
|
||
<p>
|
||
検索する語は、引数 <var>input_words</var> で指定します。
|
||
条件検索と複合検索はいずれも複数個の検索語を受け付けますので、検索語を
|
||
配列にして渡します。
|
||
このとき、配列の末尾の要素には <code>NULL</code> を置き、配列の終端を
|
||
明示します。
|
||
</p>
|
||
|
||
<p>
|
||
いずれの関数も検索をリクエストするだけで、一致したエントリの情報を
|
||
返すことはしません。
|
||
一致したエントリの取得には <code>eb_hit_list()</code> を使います。
|
||
関数は、成功すると <code>EB_SUCCESS</code> を返します。
|
||
失敗すると、原因を示すエラーコードを返します。
|
||
失敗すると、関数を呼び出す前にリクエストしていた検索の状態記録はリセット
|
||
されますので、その状態のまま <code>eb_hit_list()</code> を呼び出しても、
|
||
やはり失敗に終わります。
|
||
</p>
|
||
|
||
<p>
|
||
書籍の文字コード
|
||
(<a href="#eb_book-data-types">「[CD-ROM 書籍と <code>EB_Book</code> オブジェクト] データ型の詳細」</a> を参照のこと)
|
||
が <code>EB_CHARCODE_ISO8859_1</code> なら、関数に渡す検索語は ISO 8859-1
|
||
で書かれていなければなりません。
|
||
それ以外の文字コードの場合は、日本語 EUC で書かれていなければなりません。
|
||
不正な文字番号を含んでいた場合、関数は <code>EB_ERR_BAD_WORD</code> を
|
||
返します。
|
||
</p>
|
||
|
||
<p>
|
||
加えて、個々の検索語は <code>EB_MAX_WORD_LENGTH</code> (= 255) バイト以下
|
||
でなければなりません。
|
||
この長さに、ナル文字は含みません。
|
||
長すぎる場合は、<code>EB_ERR_TOO_LONG_WORD</code> を返します。
|
||
長さが 0 バイトの検索語は無視されますが、少なくとも 1 個の検索語は長さ
|
||
が 1 以上ないといけません。
|
||
長さが 1 以上の検索語が 1 つもないときは、<code>EB_ERR_NO_WORD</code> を
|
||
返します。
|
||
</p>
|
||
|
||
<p>
|
||
末尾の NULL を除いた配列の要素数は、条件検索では <code>EB_MAX_KEYWORDS</code>
|
||
以下、クロス検索では <code>EB_MAX_CROSS_ENTRIES</code> 以下、
|
||
複合検索では <code>EB_MAX_MULTI_ENTRIES</code> 以下でなくては
|
||
なりません。
|
||
個数が多すぎると <code>EB_ERRO_TOO_MANY_WORDS</code> を返します。
|
||
空文字列の要素を差し引いた個数ではなく、単純に渡された要素数が上限を
|
||
超えているとエラーになりますので、注意が必要です。
|
||
</p>
|
||
|
||
<p>
|
||
あらかじめ、<var>book</var> はいずれかの副本を選択していなくてはなりません。
|
||
選択していない場合は、<code>EB_ERR_NO_CUR_SUB</code> を返します。
|
||
なお、一致するエントリが最低 1 個あるかどうかは、戻り値には影響しません。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:hit_list"><code>EB_Error_Code eb_hit_list (EB_Book *<var>book</var>, int <var>max_hit_count</var>, EB_Hit *<var>hit_list</var>, int *<var>hit_count</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_hit_list()</code> は、あらかじめ以下のいずれかの関数で
|
||
リクエストされた検索を実行し、一致したエントリを取得します。
|
||
</p>
|
||
|
||
<ul>
|
||
<li><code>eb_search_word()</code> (前方一致検索)
|
||
<li><code>eb_search_endword()</code> (後方一致検索)
|
||
<li><code>eb_search_exactword()</code> (完全一致検索)
|
||
<li><code>eb_search_keyword()</code> (条件検索)
|
||
<li><code>eb_search_cross()</code> (クロス検索)
|
||
<li><code>eb_search_multi()</code> (複合検索)
|
||
</ul>
|
||
|
||
<p>
|
||
したがって、この関数を呼ぶ前に、上記のいずれかの関数の呼び出しに成功して
|
||
いなくてはなりません。
|
||
</p>
|
||
|
||
<p>
|
||
<code>eb_hit_list()</code> は最大で <var>max_hit_count</var> 個の
|
||
一致エントリを <var>hit_list</var> に書き込みます。
|
||
そして、書き込んだ一致エントリの数を <var>hit_count</var> が指す領域に
|
||
書き込みます。
|
||
それ以上の個数の一致エントリが存在する場合、残ったエントリの情報は、
|
||
この関数を繰り返し呼び出すことで得ることができます。
|
||
</p>
|
||
|
||
<p>
|
||
ただし、以下に挙げた関数を呼び出すと、リクエストした検索に関する状態記録
|
||
がリセットされますので、一致したエントリの取得は継続できなくなります。
|
||
</p>
|
||
|
||
<ul>
|
||
<li><code>eb_set_subbook()</code>
|
||
<li><code>eb_unset_subbook()</code>
|
||
<li><code>eb_load_all_subbooks()</code>
|
||
<li><code>eb_bind()</code>
|
||
<li><code>eb_finalize_book()</code>
|
||
<li><code>eb_search_word()</code>
|
||
<li><code>eb_search_endword()</code>
|
||
<li><code>eb_search_exactword()</code>
|
||
<li><code>eb_search_keyword()</code>
|
||
<li><code>eb_search_cross()</code>
|
||
<li><code>eb_search_multi()</code>
|
||
</ul>
|
||
|
||
<p>
|
||
繰り返し呼んだ場合も、一致したエントリの情報はその都度 <var>hit_list</var>
|
||
の先頭から書き込み、<var>hit_count</var> が指す領域に書き込む値も、その回
|
||
の <code>eb_hit_list()</code> の呼び出しで書き込んだ一致エントリの数に
|
||
なります。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、この関数は <code>EB_SUCCESS</code> を返します。
|
||
たとえ一致したエントリがなくても、処理が正常に終了すれば、関数は
|
||
<code>EB_SUCCESS</code> を返します。
|
||
</p>
|
||
|
||
<p>
|
||
失敗すると、<var>hit_count</var> が指す領域に 0 を書き込み、原因を示す
|
||
エラーコードを返します。
|
||
この場合、リクエストしていた検索の状態記録はリセットされますので、
|
||
これ以上 <code>eb_hit_list()</code> を呼んで、残った一致エントリを取得
|
||
することはできなくなります。
|
||
</p>
|
||
|
||
<p>
|
||
あらかじめ、<var>book</var> はいずれかの副本を選択していなくてはなりません。
|
||
選択していない場合は、<code>EB_ERR_NO_CUR_SUB</code> を返します。
|
||
また、先に挙げた検索のリクエストが成功していない状態でこの関数を呼ぶと、
|
||
<code>EB_ERR_NO_PREV_SEARCH</code> を返します。
|
||
</p>
|
||
|
||
<!-- ================================================================ -->
|
||
<h2><a name="text-data">テキストデータ</a></h2>
|
||
|
||
<p>
|
||
テキストデータの取得は、検索と並ぶ重要な機能です。
|
||
</p>
|
||
|
||
<p>
|
||
ここで言う <dfn>テキストデータ (text data)</dfn> は、
|
||
<dfn>本文 (text body)</dfn> という意味ではありません。
|
||
CD-ROM 書籍には確かに本文も存在しますが、本文と同じデータ形式を用いて
|
||
書かれたデータが数種類あります。
|
||
本書では、これらのデータをまとめてテキストデータと呼んでいます。
|
||
EB ライブラリが扱えるテキストデータの種類には、次のものがあります。
|
||
</p>
|
||
|
||
<ul>
|
||
<li>見出し
|
||
<li>本文
|
||
<li>メニュー
|
||
<li>著作権表示
|
||
<li>複合検索の入力語の候補一覧
|
||
</ul>
|
||
|
||
<p>
|
||
本章では、これらのテキストデータの取得と加工方法について説明します。
|
||
</p>
|
||
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="seek-and-read-text-data">テキストデータのシークと読み込み</a></h3>
|
||
|
||
<p>
|
||
UNIX でプログラムを組んだ経験のある方には、ファイルからデータを読み込む
|
||
際に用いる <code>lseek()</code>, <code>read()</code> というシステムコール
|
||
をご存じの方も多いでしょう。
|
||
</p>
|
||
|
||
<p>
|
||
EB ライブラリでも、テキストデータの取得には、<dfn>シーク (seek)</dfn> と
|
||
<dfn>読み込み (read)</dfn> という 2 つの操作で行います。
|
||
ただし、EB ライブラリではファイルポインタやディスクリプタはなく、
|
||
<code>EB_Book</code> オブジェクトを通じてシークや読み込みの操作を行います。
|
||
</p>
|
||
|
||
<p>
|
||
また、シーク時に指定する位置も <code>off_t</code> 型ではなく、
|
||
<code>EB_Position</code> 型 (<a href="#search-data-types">「[検索] データ型の詳細」</a> を参照のこと)
|
||
のオブジェクトを用います。
|
||
たとえば、本文の先頭位置は、<code>eb_text()</code> という関数を使って
|
||
次のように取得できますが、このときも位置データは <code>EB_Position</code>
|
||
型オブジェクトに書き込まれます。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
EB_Position position;
|
||
|
||
/* 関数の処理が成功すると、<code>position</code> に本文の開始位置が
|
||
* 書き込まれます。 */
|
||
if (eb_text(&book, &position) != EB_SUCCESS) {
|
||
fprintf(stderr, "an error occurs.\n");
|
||
return;
|
||
}
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
参考までに、<code>EB_Position</code> 型の内部構造は、次のようになっています。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
typedef struct EB_Position_Struct EB_Position;
|
||
|
||
struct EB_Position_Struct {
|
||
int page; /* ページ番号 */
|
||
int offset; /* ページ内のオフセット */
|
||
};
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
検索して見つかった一致エントリの見出しや本文を読み込む際にも、位置情報
|
||
の指定には <code>EB_Position</code> 型が使われます。
|
||
一致したエントリの情報は、関数 <code>eb_hit_list()</code> によって
|
||
<code>EB_Hit</code> という型のオブジェクトに書き込まれますが、
|
||
<code>EB_Hit</code> 型は次のように定義されています。
|
||
(詳しくは <a href="#search-data-types">「[検索] データ型の詳細」</a> を参照のこと。)
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
typedef struct {
|
||
EB_Position heading; /* 見出しの位置 */
|
||
EB_Position text; /* 本文の位置 */
|
||
} EB_Hit;
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
つまり、このときの見出しと本文の位置も、<code>EB_Position</code> 型で
|
||
表現されているのです。
|
||
</p>
|
||
|
||
<p>
|
||
では、実際のプログラムを例にして、シークと読み込みを行ってみます。
|
||
まずは、シークからです。
|
||
これには関数 <code>eb_seek_text()</code> を用います。
|
||
ここでもやはり、位置は <code>EB_Position</code> 型で渡します。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
if (eb_seek_text(&book, &position) != EB_SUCCESS) {
|
||
fprintf(stderr, "an error occurs.\n");
|
||
return;
|
||
}
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
データの種類 (見出し、本文 ...) によらず、テキストデータのシークは
|
||
すべて <code>eb_seek_text()</code> で行います。
|
||
</p>
|
||
|
||
<p>
|
||
ただし、<code>EB_Book</code> オブジェクトは、テキストデータの種類別に
|
||
読み込み位置を覚えているわけではなく、全種類のテキストデータで共有する
|
||
位置情報を一つ覚えているだけです。
|
||
たとえば、本文を読み込んだ後で、別の位置にシークして見出しを読み込むと、
|
||
<code>EB_Book</code> は本文の読み込み位置のことは忘れてしまいます。
|
||
</p>
|
||
|
||
<p>
|
||
さて、シークが終わったら、データを読み込みます。
|
||
読み込もうとするテキストデータの種類によって、使用する関数が異なります。
|
||
見出しだけは <code>eb_read_heading()</code> を使いますが、それ以外では
|
||
<code>eb_read_text()</code> を使います。
|
||
</p>
|
||
|
||
<p>
|
||
以下は、<code>eb_read_text()</code> の使用例です。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
#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;
|
||
}
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
成功すると、<code>text</code> にはテキストデータが、
|
||
<code>text_length</code> には実際に読み込んだバイト数が書き込まれます。
|
||
テキストは最大で <code>MAX_LENGTH</code> バイト書き込まれます。
|
||
テキストデータはさらにナル文字で終端されますので、<code>buffer</code> には
|
||
もう 1 バイト分の領域が必要になります。
|
||
</p>
|
||
|
||
<p>
|
||
<code>eb_read_heading()</code> の呼び出し方も、<code>eb_read_text()</code>
|
||
とまったく変わりません。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
if (eb_read_heading(&book, NULL, NULL, NULL, MAX_LENGTH,
|
||
text, &text_length) != EB_SUCCESS) {
|
||
fprintf(stderr, "an error occurs.\n");
|
||
return;
|
||
}
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
<code>eb_read_text()</code> や <code>eb_read_heading()</code> で読み込んだ
|
||
テキストデータは平文のテキストになっていて、ナル文字で終端されています。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
printf("%s\n", text); /* 出力してみる */
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
読み込みたいテキストデータが長すぎて、<code>eb_read_text()</code>
|
||
あるいは <code>eb_read_heading()</code> を一回呼び出しただけでは全部
|
||
読み込めなかった場合は、再度呼び出すことで続きのデータを読み込むことが
|
||
できます。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="text-data-format">テキストデータの内部形式</a></h3>
|
||
|
||
<p>
|
||
前節の例では、読み込んだテキストデータは、平文テキストになっていました。
|
||
けれども、CD-ROM 書籍内に平文テキストのデータが、そのまま収録されている
|
||
わけではありません。
|
||
</p>
|
||
|
||
<p>
|
||
実際のテキストデータの例を、以下に示します。
|
||
左側のブロックは 16 進数でダンプした様子で、右側はそれを基に JIS X 0208
|
||
(日本語のかな漢字) の文字を表している部分を <samp>[ ]</samp> という形に
|
||
直したものです。
|
||
</p>
|
||
|
||
<blockquote>
|
||
<pre>
|
||
(16進数によるダンプ) (可能な部分をかな漢字に変換)
|
||
1f0900011f41010026321f611f042121 1f0900011f410100[Σ]1f611f04[ ]
|
||
212721211f053e704a734a541f0a1f04 [：][ ]1f05[情][報][編]1f0a1f04
|
||
214e1f0525372530255e1f04214f2121 [［]1f05[シ][グ][マ]1f04[］][ ]
|
||
214a237323692367236d236121212370 [（][ｓ][ｉ][ｇ][ｍ][ａ][ ][ｐ]
|
||
2372236f236a236523632374214b1f05 [ｒ][ｏ][ｊ][ｅ][ｃ][ｔ][）]1f05
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
右側のブロックを見ると、おおよそ平文に近い形でテキストデータが収められて
|
||
いることが分かりますが、ところどころに「文字」ではないデータも含まれて
|
||
います。
|
||
</p>
|
||
|
||
<p>
|
||
文字ではない部分は、すべて「エスケープシーケンス」と呼ばれるものです。
|
||
エスケープシーケンスとは、テキストデータを出力する際に、改行の禁止や
|
||
強調修飾といった制御情報を伝えるための仕組みです。
|
||
16 進数の <samp>1f</samp> が、エスケープシーケンスの開始を意味します。
|
||
</p>
|
||
|
||
<p>
|
||
参考までに、上のテキストデータで使われているエスケープシーケンスを
|
||
すべて列挙すると、次のようになります。
|
||
</p>
|
||
|
||
<dl>
|
||
<dt><samp>1f09 0001</samp></dt>
|
||
<dd>
|
||
字下げ (インデント) の量を指定。
|
||
(引数が 0001 なので、字下げ量は 1。)
|
||
<dt><samp>1f41 0100</samp></dt>
|
||
<dd>
|
||
検索キーの開始。
|
||
(引数 0100 の意味については、JIS X 4081 に記述がないため不明。)
|
||
<dt><samp>1f61</samp></dt>
|
||
<dd>
|
||
検索キーの終了。
|
||
<dt><samp>1f04</samp></dt>
|
||
<dd>
|
||
半角表示の開始。
|
||
<dt><samp>1f05</samp></dt>
|
||
<dd>
|
||
半角表示の終了。
|
||
<dt><samp>1f0a</samp></dt>
|
||
<dd>
|
||
改行
|
||
</dl>
|
||
|
||
<p>
|
||
前節のプログラムで、読み込んだデータが平文テキストになっていたのは、
|
||
実は EB ライブラリが加工処理をしたからです。
|
||
つまり、「改行」のように平文テキストでも表現可能なエスケープシーケンス
|
||
については処理し、「検索キーの開始」のように表現できないものについては
|
||
無視するようにして、平文テキストになるように加工していたのです。
|
||
</p>
|
||
|
||
<p>
|
||
しかし、平文テキストは表現力が乏しいので、元のデータには含まれている
|
||
エスケープシーケンスの多くを無視することになってしまいます。
|
||
HTML のように、もっと表現力のある形式で出力するなら、無視せずに済む
|
||
シーケンスを増やせそうです。
|
||
では、HTML 形式でテキストデータを取得する関数が EB ライブラリに用意されて
|
||
いるかというと、残念ながらありません。
|
||
</p>
|
||
|
||
<p>
|
||
その代わりに、かなり手間はかかりますが、自由にテキストデータを加工できる
|
||
ための仕組みが用意されています。
|
||
それが、次の節で説明する <dfn>フック (hook)</dfn> です。
|
||
フックを使うことで、テキストデータを柔軟に加工することができます。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="hook">フック</a></h3>
|
||
|
||
<p>
|
||
特に何も指定しなければ、<code>eb_read_text()</code>,
|
||
<code>eb_read_heading()</code> が返すテキストデータの加工は、あらかじめ
|
||
決められた通りの方法で行われます。
|
||
たとえば、「改行」のエスケープシーケンスに対しては、<samp>\n</samp> を
|
||
書き込むようになっています。
|
||
</p>
|
||
|
||
<p>
|
||
<dfn>フック (hook)</dfn> を使うと、こうした加工方法を変えることができます。
|
||
フックは、あらかじめ決められたフック設定位置に対して、フック関数を登録
|
||
することで有効になります。
|
||
フック関数が登録されていると、<code>eb_read_text()</code> や
|
||
<code>eb_read_heading()</code> は、あらかじめ決まったやり方でデータを
|
||
書き込む代わりに、フック関数を呼び出します。
|
||
呼び出されたフック関数がデータの書き込み処理を行うことで、
|
||
<code>eb_read_text()</code> や <code>eb_read_heading()</code> から返る
|
||
テキストデータが変化するというわけです。
|
||
</p>
|
||
|
||
<p>
|
||
EB ライブラリには、多数のフック設定位置が用意されています。
|
||
各エスケープシーケンスには、それぞれ専用にフックが用意されており、
|
||
それ以外にも文字のためのフックが存在します。
|
||
(どのようなフック設定位置があるか、詳しくは
|
||
<a href="#hook-code-list">「フックコードの一覧」</a> を参照のこと。)
|
||
</p>
|
||
|
||
<p>
|
||
それぞれのフック設定位置は、<dfn>フックコード (hook code)</dfn> と
|
||
呼ばれるコード値で識別されます。
|
||
たとえば、前述の「改行」のエスケープシーケンスに対応するフックコード
|
||
は <code>EB_HOOK_NEWLINE</code> になります。
|
||
</p>
|
||
|
||
<p>
|
||
アプリケーションプログラムがフックを扱うには、フックの集合である
|
||
<dfn>フックセット (hook set)</dfn> を用意します。
|
||
これは、EB ライブラリで利用可能なすべてのフック設定位置に対して、どの
|
||
フック関数を使うのかを記録するためのオブジェクトです。
|
||
</p>
|
||
|
||
<p>
|
||
では、実際にどうやってフックセットを扱うのか、説明していきましょう。
|
||
フックセットは <code>EB_Hookset</code> 型のオブジェクトで表しますので、
|
||
まず <code>EB_Hookset</code> オブジェクトを用意します。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
EB_Hookset hookset;
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
<code>EB_Hookset</code> オブジェクトは、<code>EB_Book</code> オブジェクト
|
||
と同様に、使用前に必ず初期化する必要があります。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
eb_initialize_hookset(&hookset);
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
実際のフック関数は、次のようなものになります。
|
||
この例では、フック関数の中で <code>eb_write_text_string()</code> という
|
||
関数を呼び出して、<samp><br></samp> という文字列をテキストデータ
|
||
として書き込んでいます。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
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;
|
||
}
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
関数 <code>eb_set_hook()</code> を用いることで、このフック関数を
|
||
フックセットに登録することができます。
|
||
ただし、まず <code>EB_Hook</code> という型のオブジェクトにいったん
|
||
フックコードとフック関数を設定し、それを <code>eb_set_hook()</code> を
|
||
渡してやる必要があります。
|
||
ここでは、「改行」を表すエスケープシーケンスに対して、上記のフック関数
|
||
を登録してみます。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
EB_Hook hook;
|
||
|
||
hook.code = EB_HOOK_NEWLINE; # フックコードをセット
|
||
hook.function = hook_newline; # フック関数をセット
|
||
eb_set_hook(&hookset, &hook);
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
なお、同じフック設定位置 (フックコード) に複数回フック関数を登録しても、
|
||
有効になるのは最後に登録したものだけですので、注意して下さい。
|
||
フック関数として <code>NULL</code> を指定すると、登録されているフックが
|
||
解除されます。
|
||
</p>
|
||
|
||
<p>
|
||
関数 <code>eb_set_hooks()</code> (最後に <code>s</code> が付く) を使えば、
|
||
複数のフック関数を一度に登録できます。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
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);
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
配列の末尾を明示するために、<code>EB_HOOK_NULL</code> という特殊な
|
||
フックコードを置きます。
|
||
この点も注意して下さい。
|
||
</p>
|
||
|
||
<p>
|
||
こうしてフック関数を登録したフックセットを、<code>eb_raed_text()</code>,
|
||
<code>eb_raed_heading()</code> への引数として渡します。
|
||
前節までの例では、<code>NULL</code> を渡していましたが、代わりに
|
||
<code>&hookset</code> を渡してみます。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
if (eb_read_text(&book, NULL, &hookset, NULL, MAX_LENGTH,
|
||
text, &text_length) != EB_SUCCESS) {
|
||
fprintf(stderr, "an error occurs.\n");
|
||
return;
|
||
}
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
これによって、テキストデータ中に改行を表すエスケープシーケンスがあると、
|
||
<samp>\n</samp> の代わりに <samp><br></samp> という文字列が
|
||
書き込まれるようになります。
|
||
</p>
|
||
|
||
<p>
|
||
<code>EB_Hookset</code> オブジェクトを使い終わったら、
|
||
<code>eb_finalize_hookset()</code> を呼んで後始末をします。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
eb_finalize_hookset(&hookset);
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="hook-and-character-code">フックと文字コードの関係</a></h3>
|
||
|
||
<p>
|
||
前節では、エスケープシーケンスに対するフックを例にとりましたが、この他
|
||
にも、EB ライブラリには文字に対するフックが用意されています。
|
||
</p>
|
||
|
||
<dl>
|
||
<dt><code>EB_HOOK_ISO8859_1</code></dt>
|
||
<dd>
|
||
ISO 8859-1 (ラテン文字 1) 文字へのフック。ただし制御文字を除きます。
|
||
引数として、ISO 8859-1 の文字番号がフック関数に渡されます。
|
||
|
||
<dt><code>EB_HOOK_NARROW_JISX0208</code></dt>
|
||
<dd>
|
||
半角の JIS X 0208 (日本語のかな漢字) 文字へのフック。
|
||
引数として、日本語 EUC で表現した場合の文字番号が、フック関数に渡されます。
|
||
|
||
<dt><code>EB_HOOK_WIDE_JISX0208</code></dt>
|
||
<dd>
|
||
全角の JIS X 0208 (日本語のかな漢字) 文字へのフック。
|
||
引数として、日本語 EUC で表現した場合の文字番号が、フック関数に渡されます。
|
||
|
||
<dt><code>EB_HOOK_GB2312</code></dt>
|
||
<dd>
|
||
GB 2312 (中国語の簡体字) 文字へのフック。
|
||
引数として、中国語 EUC で表現した場合の文字番号が、フック関数に渡されます。
|
||
|
||
<dt><code>EB_HOOK_NARROW_FONT</code></dt>
|
||
<dd>
|
||
半角の外字へのフック。
|
||
引数として、外字の文字番号が、フック関数に渡されます。
|
||
|
||
<dt><code>EB_HOOK_WIDE_FONT</code></dt>
|
||
<dd>
|
||
半角の外字へのフック。
|
||
引数として、外字の文字番号が、フック関数に渡されます。
|
||
</dl>
|
||
|
||
<p>
|
||
いずれも、その文字がテキストデータ中に現れる度に、フック関数が呼び出され
|
||
ます。
|
||
</p>
|
||
|
||
<p>
|
||
上の記述を見ても分かるように、フック関数に渡される文字番号は、書籍の文字
|
||
コードに応じて、ISO 8859-1, 日本語 EUC、中国語 EUC のいずれかの文字コード
|
||
で表現されたものになります。
|
||
</p>
|
||
|
||
<p>
|
||
フック関数を登録しなければ、その文字番号がテキストデータとしてそのまま
|
||
書き込まれます。
|
||
</p>
|
||
|
||
<p>
|
||
もし、アプリケーションプログラムが、EB ライブラリの内部コードとは異なる
|
||
文字コードを使用したい場合は、これらのフックのフック関数を登録して、
|
||
コード変換処理をするのも手です。
|
||
ただし、一文字毎にフック関数が呼び出されるので、相応の負荷がかかります。
|
||
</p>
|
||
|
||
<p>
|
||
また、EBXA-C を扱うには、特別な処理が必要です。
|
||
EBXA-C では、文字コードとして GB 2312 と JIS X 0208 が使われますが
|
||
(<a href="#character-code">「文字コード」</a> を参照のこと)、EB ライブラリによる標準の処理
|
||
では、どちらも 0xa1a1 ～ 0xfefe にマッピングされて衝突するため、最低
|
||
でもどちらか一方をフックして文字の表現方法を変えないと、正しく出力
|
||
できません。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="cross-search-result">クロス検索の検索結果</a></h3>
|
||
|
||
<p>
|
||
すでに <a href="#search">「検索」</a> の章で述べたように、CD-ROM 書籍
|
||
には前方一致検索、後方一致検索といった複数の検索メソッドがあります。
|
||
EB ライブラリで検索を行うと、どの検索メソッドでも、一致したエントリの
|
||
情報は、以下のような <code>EB_Hit</code> 型のオブジェクトとして
|
||
受け取ります。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
typedef struct {
|
||
EB_Position heading; /* 見出しの位置 */
|
||
EB_Position text; /* 本文の位置 */
|
||
} EB_Hit;
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
しかしクロス検索では、<code>EB_Hit</code> の見出しと本文の位置は
|
||
まったく同じになります。
|
||
したがって、見出しと本文のテキストデータを読み込むには、他の検索メソッド
|
||
のようにそれぞれの位置にシークして読み込むというやり方ではうまく
|
||
いきません。
|
||
</p>
|
||
|
||
<p>
|
||
以下に、クロス検索の見出しと本文を読み込むプログラム例を示します。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
/* 見出し位置へのシークを行う */
|
||
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;
|
||
}
|
||
</pre>
|
||
</blockquote class="program">
|
||
|
||
<p>
|
||
クロス検索でも、見出しの内容を読み込む方法は他の検索メソッドと変わり
|
||
はなく、<code>eb_read_heading()</code> を使います。
|
||
変わっているのは、本文の読み込みです。
|
||
<code>eb_read_text()</code> ではなく、<code>eb_read_heading()</code>
|
||
を使います。
|
||
見出しを読み込むための関数 <code>eb_read_heading()</code> を、本文を
|
||
読み込むために呼ぶというのは奇妙な話ですが、これはクロス検索の本文が
|
||
見出しと同じ形式になっているためです。
|
||
通常、見出しは一行程度しか書かれていませんが、実際のところクロス検索
|
||
の本文も一行程度しかありません。
|
||
</p>
|
||
|
||
<p>
|
||
また、本文は見出しのすぐ後に書かれているため、上記のように見出しを
|
||
読み込んだ後で <code>eb_forward_heading()</code> という関数を呼び、
|
||
その後で本文を読み込むためにもう一度 <code>eb_read_heading()</code> を
|
||
呼ぶという変わった手順を踏みます。
|
||
</p>
|
||
|
||
<p>
|
||
本文だけが必要で見出しが要らなければ、シーク直後に
|
||
<code>eb_forward_heading()</code> を呼ぶようにします。
|
||
その後で <code>eb_read_heading()</code> を呼ぶと、本文を読み込みます。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="copyright-notice">著作権表示</a></h3>
|
||
|
||
<p>
|
||
先に記したように、テキストデータには何種類かあり、その中に
|
||
<dfn>著作権表示 (copyright notice)</dfn> というものがあります。
|
||
名前の通り、著作権表示に関するテキストデータを収めたものです。
|
||
</p>
|
||
|
||
<p>
|
||
一般に、著作権表示は本文とはまったく独立したデータとして用意されます。
|
||
したがって、本文を先頭から末尾まで読んでみても、著作権表示はどこにも
|
||
見つかりません。
|
||
</p>
|
||
|
||
<p>
|
||
選択中の副本について、著作権表示の開始位置を知るには
|
||
<code>eb_copyright()</code> を使います。
|
||
この関数は、副本が著作権表示を持っていなければ
|
||
<code>EB_ERR_NO_SUCH_SEARCH</code> を返しますので、著作権表示の有無も
|
||
同時に分かります。
|
||
(開始位置は取得せずに、有無だけを調べたいときは、
|
||
<code>eb_have_copyright()</code> という関数が使えます。)
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
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;
|
||
}
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
後は、得られた位置 (<code>position</code>) にシークして、
|
||
<code>eb_read_text()</code> でテキストデータを読み込みます。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="menu">メニュー</a></h3>
|
||
|
||
<p>
|
||
本文とは独立したテキストデータとしては、著作権表示の他に
|
||
<dfn>メニュー (menu)</dfn> というものがあります。
|
||
メニューは、主に本文の補助となるデータを収録しています。
|
||
代表的なものでは、「前書き (序)」「凡例」といったものが挙げられます。
|
||
</p>
|
||
|
||
<p>
|
||
メニューでは「別項目参照」というエスケープシーケンスを多用して、階層的
|
||
な構造になっているのが一般的です。
|
||
このエスケープシーケンスには、参照先のテキストの位置が記録されています。
|
||
</p>
|
||
|
||
<p>
|
||
たとえば、ある CD-ROM 書籍のメニューが次のようになっていたとします。
|
||
この例では、メニューには 3 つの項目があります。
|
||
</p>
|
||
|
||
<blockquote>
|
||
<pre>
|
||
* 序文
|
||
* 表記について
|
||
* 奥付
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
メニューのそれぞれの項目には、参照先があります。
|
||
テキストデータの内部表現では、「序文」「表記について」「奥付」の
|
||
それぞれの文字列の前後に別項目参照開始および終了エスケープシーケンスが
|
||
付いた形になっています。
|
||
視覚的に分かるように記すと、次のような形になっています。
|
||
</p>
|
||
|
||
<blockquote>
|
||
<pre>
|
||
* <別項目参照開始シーケンス> "序文" <別項目参照終了シーケンス>
|
||
* <別項目参照開始シーケンス> "表記" <別項目参照終了シーケンス>
|
||
* <別項目参照開始シーケンス> "奥付" <別項目参照終了シーケンス>
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
HTML の書き方を知っているなら、<samp>a</samp> タグと言えば分かるのでは
|
||
ないかと思います。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
<a href="./index.html">EB ライブラリのホームページ</a>
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
ただし、参照先の位置情報は終了シーケンス側に記載されますので、この点は
|
||
HTML とは逆になります。
|
||
蛇足ですが、別位置参照はメニューだけでなく、本文でも一般的に使用されます。
|
||
</p>
|
||
|
||
<p>
|
||
別項目参照開始および終了シーケンスに対して、それぞれフック
|
||
<code>EB_HOOK_BEGIN_REFERENCE</code> と <code>EB_HOOK_END_REFERENCE</code>
|
||
が用意されています。
|
||
参照先の位置情報は、終了シーケンスへのフック関数に対して、引数として
|
||
渡されます。
|
||
たとえば、<code>EB_HOOK_END_REFERENCE</code> へのフック関数の冒頭では、
|
||
次のようにすると良いかも知れません。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
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]; # 参照先のオフセット
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
参照先は、メニューの第 2 層となります。
|
||
この書籍の「奥付」の参照先を辿ったら、次のような表記になっていました。
|
||
</p>
|
||
|
||
<blockquote>
|
||
<pre>
|
||
○○堂出版社 新国語辞典 第 2 版 (EPWING 版)
|
||
第 1 版 発行 1988年 2月
|
||
第 2 版 発行 1999年 11月
|
||
第 2 版 (EPWING 版) 発行 2000年 2月
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
同様に「序文」「表記に付いて」の参照先についても、こうした文章データ
|
||
が用意されていました。
|
||
図示すると、メニューの階層は次のようになります。
|
||
</p>
|
||
|
||
<blockquote>
|
||
<pre>
|
||
┌─────┐
|
||
第１層 │メニュー │
|
||
└──┰──┘
|
||
┃
|
||
┏━━━━━━━╋━━━━━━━┓
|
||
┃ ┃ ┃
|
||
┌──┸──┐ ┌──┸──┐ ┌──┸──┐
|
||
第２層 │メニュー │ │メニュー │ │メニュー │
|
||
└─────┘ └─────┘ └─────┘
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
この辞書の例では、メニューはここで終わりになっていますが、書籍によっては
|
||
さらに第 3 層、第 4 層と続く場合もあります。
|
||
また、メニュー全体が均一の階層数になっているとは限りません。
|
||
メニューの参照先が本文や著作権表示になっていることもあります。
|
||
</p>
|
||
|
||
<p>
|
||
選択中の副本について、(第 1 層の) メニューの開始位置 を知るには
|
||
<code>eb_menu()</code> を使います。
|
||
この関数は、副本がメニューを持っていなければ
|
||
<code>EB_ERR_NO_SUCH_SEARCH</code> を返しますので、メニューの有無も同時に
|
||
分かります。
|
||
(開始位置は取得せずに、有無だけを調べたいときは、
|
||
<code>eb_have_menu()</code> という関数が使えます。)
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
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;
|
||
}
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
後は、得られた位置 (<code>position</code>) にシークして、
|
||
<code>eb_read_text()</code> でテキストデータを読み込みます。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="multi-candidates">複合検索の候補一覧</a></h3>
|
||
|
||
<p>
|
||
「複合検索」(<a href="#multi-search">「複合検索」</a> を参照のこと) のところで述べたように、
|
||
複合検索では、入力語に <dfn>候補一覧 (candidates)</dfn> が用意されている
|
||
ことがあります。
|
||
これは、入力語として有効な語をあらかじめ列挙しておき、
|
||
アプリケーションプログラムのユーザに選択させる仕組みです。
|
||
</p>
|
||
|
||
<p>
|
||
たとえば、人名を検索するのために、次のような複合検索があったとします。
|
||
</p>
|
||
|
||
<blockquote>
|
||
<pre>
|
||
入力語 0: 国・地域
|
||
入力語 1: 時代
|
||
入力語 2: 性別
|
||
入力語 3: キーワード
|
||
入力語 4: キーワード
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
このうち、入力語 3 の「性別」には、入力語として有効な語は「男」と「女」
|
||
の 2 つしかないでしょう。
|
||
このように、入力語として有効な語が限られている場合に、候補一覧が用意
|
||
されていることがあります。
|
||
</p>
|
||
|
||
<p>
|
||
候補一覧は検索のためのデータではありますが、内部構造はテキストデータ
|
||
そのものです。
|
||
ユーザに対して候補を列記した示したテキストを示し、その中の一つを選択
|
||
してもらうようになっています。
|
||
</p>
|
||
|
||
<p>
|
||
しかも、候補一覧のデータ構造はメニューと非常に似ており、メニューの
|
||
ような階層構造を持っています
|
||
(<a href="#menu">「メニュー」</a> を参照のこと)。
|
||
たとえば、上の複合検索の入力語 2 「国・地域」にも候補の一覧を設けると
|
||
したら、最初の階層は次のようになるかも知れません。
|
||
</p>
|
||
|
||
<blockquote>
|
||
<pre>
|
||
* 日本 (→選択)
|
||
* 日本以外のアジア (→詳細)
|
||
* ヨーロッパ (→詳細)
|
||
* 北アメリカ (→詳細)
|
||
* その他 (→詳細)
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
「日本」を選ぶと、そこで入力語が決定されたことになります。しかし、
|
||
それ以外の項目についてはさらに細かく分類された選択肢が用意されて
|
||
います。
|
||
ここでは、「北アメリカ」を選んでみましょう。
|
||
すると、さらに次のような候補一覧のデータが提示されます。
|
||
</p>
|
||
|
||
<blockquote>
|
||
<pre>
|
||
* アメリカ (→選択)
|
||
* カナダ (→選択)
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
ここで、「アメリカ」「カナダ」を選ぶと、入力語が決定されます。
|
||
</p>
|
||
|
||
<p>
|
||
次に実際に、EB ライブラリを使ってこうした候補一覧を扱う方法について
|
||
説明します。
|
||
まず、アプリケーションプログラムは、複合検索の入力語が候補一覧を持って
|
||
いるかどうかを、確認する必要があるでしょう。
|
||
<code>eb_multi_entry_candidates()</code> を使うと、候補一覧データの開始位置
|
||
を取得することができます。
|
||
この関数は、候補一覧を持っていなければ <code>EB_ERR_NO_CANDIDATES</code> を
|
||
返しますので、候補一覧の有無も分かります。
|
||
(開始位置は取得せずに、有無だけを調べたいときは、
|
||
<code>eb_multi_entry_have_candidates()</code> という関数が使えます。)
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
EB_Position position;
|
||
EB_Error_Code err;
|
||
|
||
/* <code>mulit_id</code>, <code>entry_id</code> で、どの複合検索の
|
||
* 何番目の入力語について確認するのかを指定します。*/
|
||
err = eb_multi_entry_candidates(&book, multi_id, entry_id, &position);
|
||
if (err == EB_ERR_NO_CANDIDATES) {
|
||
/* この入力語には、候補一覧が用意されていない */
|
||
return;
|
||
} else if (err != EB_SUCCESS) {
|
||
/* それ以外のエラー */
|
||
return;
|
||
}
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
後は、得られた位置 (<code>position</code>) にシークして、
|
||
<code>eb_read_text()</code> でテキストデータを読み込みます。
|
||
読み込んだテキストでは、候補となる語のそれぞれが候補開始と終了を表す
|
||
エスケープシーケンスに挟まれた形になっています。
|
||
</p>
|
||
|
||
<blockquote>
|
||
<pre>
|
||
* <候補開始シーケンス> "日本" <候補終了シーケンス>
|
||
* <候補開始シーケンス> "日本以外のアジア" <候補終了シーケンス>
|
||
* <候補開始シーケンス> "ヨーロッパ" <候補終了シーケンス>
|
||
* <候補開始シーケンス> "北アメリカ" <候補終了シーケンス>
|
||
* <候補開始シーケンス> "その他" <候補終了シーケンス>
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
候補開始シーケンスに対しては、フックとして
|
||
<code>EB_HOOK_BEGIN_CANDIDATE</code> が用意されています。
|
||
終了シーケンスに対するフックは 2 種類あって、さらに次の階層へ続く場合
|
||
に呼ばれる <code>EB_HOOK_END_CANDIDATE_GROUP</code> と、その語がそのまま
|
||
入力語の候補となる場合に呼ばれる <code>EB_HOOK_END_GROUP_LEAF</code> に
|
||
分かれています。
|
||
</p>
|
||
|
||
<p>
|
||
次の階層のデータの開始位置は、終了シーケンスのフック関数に、引数として
|
||
渡ってきます。
|
||
(この点もメニューと同様なので、メニューの解説を参考にして下さい。)
|
||
</p>
|
||
|
||
<p>
|
||
終了シーケンスに対するフック関数の中では、<code>eb_current_candidate()</code>
|
||
という関数が使えます。
|
||
この関数は、開始シーケンスと終了シーケンスの間に挟まれた「候補」の文字列
|
||
(ポインタ) を返します。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
const char *candidate;
|
||
|
||
candidate = eb_current_candidate(book);
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="stop-code-issue">区切りコードの問題</a></h3>
|
||
|
||
<p>
|
||
本文は、先頭から末尾まで一本の繋がったデータ列になっています。
|
||
英語辞典なら、最初の単語 `A' から最後の `zzz' までの説明が、すべて一つの
|
||
「本文」の中に書かれることになります。
|
||
</p>
|
||
|
||
<p>
|
||
一般に、アプリケーションプログラムがある単語を検索した際は、本文の中から
|
||
その単語を説明した部分だけを抜き出して出力することになるでしょう。
|
||
たとえば、`dictionary' という単語を引いた場合、次のような文章が出力される
|
||
事が期待されます。
|
||
その次や、次の次の単語の説明まで延々と表示されることを、おそらく大半の
|
||
ユーザは望まない筈です。
|
||
</p>
|
||
|
||
<blockquote>
|
||
<pre>
|
||
dictionary [名] (複: dictionaries)
|
||
辞典、事典
|
||
[類義] lexicon, glossary (用語辞典), encyclopedia (百科事典)
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
しかし、困ったことに CD-ROM 書籍には、単語の説明の終わりを示す印
|
||
(エスケープシーケンス) が定義されていません。
|
||
つまり、ある語の説明部分を正確に抜き出すことは、電子ブックや EPWING では
|
||
不可能なのです。
|
||
</p>
|
||
|
||
<p>
|
||
しかしながら、幸いにも市販の書籍の多くには、単語の説明の終了位置にだけ
|
||
出現する、特有のエスケープシーケンスが存在します。
|
||
もちろん、このエスケープシーケンスは本来「単語の説明の終了」を示すもの
|
||
ではなく別の用途として用いるのですが、「終了位置」として代用できる
|
||
という意味です。
|
||
</p>
|
||
|
||
<p>
|
||
EB ライブラリでは、この「終了位置」の印に使えるエスケープシーケンスの
|
||
ことを、<dfn>区切りコード (stop code)</dfn> と呼んでいます。
|
||
EB ライブラリは区切りコードを自動判定する機能を持っていますが、判定は
|
||
完璧ではないので外れることもあります。
|
||
外れると本文が途中で途切れたり、本文の続きが延々と出力されたりします。
|
||
</p>
|
||
|
||
<p>
|
||
その場合は、明示的に appendix
|
||
(詳しくは <a href="ebappendix.html">ebappendix コマンドのマニュアル</a>
|
||
の「appendix (付録) とは」を参照のこと)
|
||
で区切りコードを指定することによって回避できる書籍もありますが、
|
||
残念ながら区切りコードがまったく存在しない書籍も少数ながら存在します。
|
||
区切りコードを持たない書籍に対して、有効な対処方法は今のところありません。
|
||
</p>
|
||
|
||
<p>
|
||
<code>eb_read_text()</code> による本文の取得では、区切りコードが検出された
|
||
時点で読み込みを止めます。
|
||
さらに繰り返し <code>eb_read_text()</code> を呼んでも、区切りコードより先の
|
||
本文は読み込めません。
|
||
</p>
|
||
|
||
<p>
|
||
区切りコードを検出したかどうかの判定には、<code>eb_is_text_stopped()</code>
|
||
を使います。
|
||
この関数は、最後に読み込みを行ったテキストデータの中に、区切りコードを
|
||
検出していれば 1 を返します。
|
||
</p>
|
||
|
||
<p>
|
||
本文以外のテキストデータにも区切りコードの概念は存在しますので、
|
||
<code>eb_is_text_stopped()</code> を使って区切りコードを検出できます。
|
||
しかし、本文以外では EB ライブラリが確実に区切りを判別できますので、
|
||
誤判定の問題は起きません。
|
||
</p>
|
||
|
||
<p>
|
||
見出しにおける区切りは、それぞれの単語の見出しの終了位置となります。
|
||
メニューおよび複合検索の候補一覧では、階層化された個々のメニューデータ
|
||
の終了位置で区切りと判定されます。
|
||
(同一階層に複数個のメニューデータがあっても、個々のメニューデータで
|
||
区切られます。)
|
||
著作権表示では、全文の終了位置で区切りと判定されます。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="text-data-sample">サンプルプログラム</a></h3>
|
||
|
||
<!-- #include "eb-sample-text.html" -->
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="text-data-types">データ型の詳細</a></h3>
|
||
|
||
<p>
|
||
この節で説明しているデータ型を使うには、次のようにヘッダファイルを
|
||
読み込んで下さい。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
#include <eb/eb.h>
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="type:Hook_Code"><code>EB_Hook_Code</code> 型</a></h4>
|
||
|
||
<p>
|
||
データ型 <code>EB_Hook_Hook</code> は、フックの設定位置コードを表します。
|
||
</p>
|
||
|
||
<p>
|
||
この型は符合付き整数型の別名として定義されていますので、2 つのコードを
|
||
2 項演算子 <code>==</code> と <code>!=</code> で一致比較することができます。
|
||
</p>
|
||
|
||
<p>
|
||
EB ライブラリでは、全部で <code>EB_NUMBER_OF_HOOKS</code> 個のフックコード
|
||
を定義しています。
|
||
定義されている設定位置コードの一覧については、
|
||
次の節 (<a href="#hook-code-list">「フックコードの一覧」</a> を参照のこと)
|
||
を参照して下さい。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="type:Hook"><code>EB_Hook</code> 型</a></h4>
|
||
|
||
<p>
|
||
データ型 <code>EB_Hook</code> は、フックコードとそれに対応するフック関数
|
||
の組を表します。
|
||
内部構造は、次のように定義されています。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
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 *);
|
||
};
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
アプリケーションプログラムは、直接 <code>EB_Hook</code> オブジェクトの
|
||
メンバを参照したり、セットしたりしても構いません。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="type:Hookset"><code>EB_Hookset</code> 型</a></h4>
|
||
|
||
<p>
|
||
データ型 <code>EB_Hookset</code> は、フック一式を表します。
|
||
EB ライブラリで利用可能なすべてのフック設定位置に対して、どのような
|
||
フック関数を指定するのかを記録するための型です。
|
||
</p>
|
||
|
||
<p>
|
||
<code>EB_Hookiset</code> オブジェクトの操作は、すべて EB ライブラリが用意
|
||
している関数で行います。
|
||
アプリケーションプログラムは、直接 <code>EB_Hookset</code> オブジェクトの
|
||
メンバを参照したり、セットしたりすべきではありません。
|
||
</p>
|
||
|
||
<p>
|
||
<code>EB_Hookset</code> オブジェクトを使用する際は、まずそのオブジェクトに
|
||
対して <code>eb_initialize_hookset()</code> を呼んで初期化しなくては
|
||
なりません。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="hook-function-details">フック関数の詳細</a></h3>
|
||
|
||
<p>
|
||
この節では、フック関数の仕様について記します。
|
||
</p>
|
||
|
||
<p>
|
||
まず、フック関数を呼び出す <code>eb_read_text()</code> および
|
||
<code>eb_read_heading()</code> のプロトタイプは次のようになっています。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
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)
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
一方、フック関数のプロトタイプは、次のようになっています。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
EB_Error_Code
|
||
hook_function(EB_Book *book, EB_Appendix *appendix, void *container,
|
||
EB_Hook_Code code, int argc, const unsigned int *argv);
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
引数 <var>book</var>, <var>appendix</var>, <var>container</var> は、
|
||
<code>eb_read_text()</code> あるいは <code>eb_read_heading()</code> に
|
||
渡された値がそのままフック関数にも渡ってきます。
|
||
</p>
|
||
|
||
<p>
|
||
<var>appendix</var> というのは、書籍に対する補助データを提供するオブジェクト
|
||
です
|
||
(appendix (付録) について詳しくは
|
||
<a href="ebappendix.html">ebappendix コマンドのマニュアル</a>
|
||
の「appendix (付録) とは」を参照のこと)。
|
||
|
||
<p>
|
||
引数 <var>container</var> は、アプリケーションプログラムからフック関数に
|
||
何かデータを渡したいときに使います。
|
||
</p>
|
||
|
||
<p>
|
||
最後の <var>argc</var> と <var>argv</var> には、加工前のテキストデータが
|
||
渡されます。
|
||
文字に対するフックでは、文字コード番号が渡ってきます。
|
||
エスケープシーケンスに対するフックでは、そのシーケンス自体のコード
|
||
(<samp>1f</samp> で始まるコード) と、もしあればエスケープシーケンスへの
|
||
引数をが渡ってきます。
|
||
個々のフックにおいて、<var>argc</var> と <var>argv</var> にどうような値が
|
||
渡ってくるのか、詳しくは <a href="#hook-code-list">「フックコードの一覧」</a> を参照のこと。
|
||
</p>
|
||
|
||
<p>
|
||
フック関数の中から次に挙げる関数を呼び出すことで、テキストデータへの
|
||
書き込みを行うことができます。
|
||
</p>
|
||
|
||
<ul>
|
||
<li><code>eb_write_text()</code>
|
||
<li><code>eb_write_text_string()</code>
|
||
<li><code>eb_write_text_byte1()</code>
|
||
<li><code>eb_write_text_byte2()</code>
|
||
</ul>
|
||
|
||
<p>
|
||
これらの関数の仕様に関して詳しくは
|
||
<a href="#text-data-functions">「[テキストデータ] 関数の詳細」</a> を参照のこと。
|
||
</p>
|
||
|
||
<p>
|
||
フック関数が <code>EB_SUCCESS</code> 以外の値を返すと、フック関数を
|
||
呼び出した <code>eb_read_text()</code>, <code>eb_read_heading()</code>
|
||
はエラーが発生したものと見なし、そのエラーコードをそのまま
|
||
アプリケーションプログラムに返します。
|
||
</p>
|
||
|
||
<p>
|
||
フック関数の中では、<var>book</var> に対して以下の関数を呼び出しては
|
||
いけません。
|
||
呼び出したときの動作は、未定義です。
|
||
</p>
|
||
|
||
<ul>
|
||
<li><code>eb_seek_text()</code>
|
||
<li><code>eb_read_text()</code>
|
||
<li><code>eb_read_heading()</code>
|
||
<li><code>eb_read_rawtext()</code>
|
||
<li><code>eb_forward_text()</code>
|
||
<li><code>eb_backward_text()</code>
|
||
<li><code>eb_set_subbook()</code>
|
||
<li><code>eb_unset_subbook()</code>
|
||
<li><code>eb_load_all_subbook()</code>
|
||
<li><code>eb_bind()</code>
|
||
<li><code>eb_finalize_book()</code>
|
||
<li><code>eb_finalize_library()</code>
|
||
</ul>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="hook-code-list">フックコードの一覧</a></h3>
|
||
|
||
<p>
|
||
この節で説明しているフックコードを使うには、次のようにヘッダファイルを
|
||
読み込んで下さい。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
#include <eb/text.h>
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HOOK_NULL">定数 <code>EB_HOOK_NULL</code></a></h4>
|
||
|
||
<p>
|
||
<code>EB_HOOK_NULL</code> は厳密にはフックではなく、
|
||
<code>eb_set_hooks()</code> で複数のフック関数を登録する際に、
|
||
<code>EB_Hook</code> 配列の末尾の要素を示すために用います。
|
||
このフックコードに対して、フック関数は登録できません。
|
||
</p>
|
||
|
||
<p>
|
||
詳しくは、<a href="#text-data-functions">「[テキストデータ] フック関数の詳細」</a> を参照のこと。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HOOK_INITIALIZE">定数 <code>EB_HOOK_INITIALIZE</code></a></h4>
|
||
|
||
<p>
|
||
<code>EB_HOOK_INITIALIZE</code> は、<code>eb_seek_text()</code> を
|
||
呼び出した直後の最初の <code>eb_read_text()</code>,
|
||
<code>eb_read_heading()</code> の呼び出し時に処理されます。
|
||
何か初期化処理をしたいときに、使うと良いでしょう。
|
||
</p>
|
||
|
||
<p>
|
||
このフックが、フック関数に渡す <code>argc</code> は 0 です。
|
||
フック関数を登録していない状態では、このフックはテキストデータに何も
|
||
書き込みません。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HOOK_BEGIN_NARROW">定数 <code>EB_HOOK_BEGIN_NARROW</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HOOK_END_NARROW">定数 <code>EB_HOOK_END_NARROW</code></a></h4>
|
||
|
||
<p>
|
||
<code>EB_HOOK_BEGIN_NARROW</code> および <code>EB_HOOK_END_NARROW</code>
|
||
は、半角表示の開始と終了を表すエスケープシーケンスに対するフックです。
|
||
</p>
|
||
|
||
<p>
|
||
どちらのフックも、フック関数に渡す <code>argc</code> は 1 です。
|
||
<code>argv[0]</code> はエスケープシーケンスのコードそのもので、
|
||
<code>EB_HOOK_BEGIN_NARROW</code> なら <samp>0x1f04</samp>、
|
||
<code>EB_HOOK_END_NARROW</code> なら <samp>0x1f05</samp> になります。
|
||
</p>
|
||
|
||
<p>
|
||
フック関数を登録していない状態では、これらのフックはテキストデータに何も
|
||
書き込みません。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HOOK_BEGIN_SUBSCRIPT">定数 <code>EB_HOOK_BEGIN_SUBSCRIPT</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HOOK_END_SUBSCRIPT">定数 <code>EB_HOOK_END_SUBSCRIPT</code></a></h4>
|
||
|
||
<p>
|
||
<code>EB_HOOK_BEGIN_SUBSCRIPT</code> および
|
||
<code>EB_HOOK_END_SUBSCRIPT</code> は、下付き表示の開始と終了を表す
|
||
エスケープシーケンスに対するフックです。
|
||
</p>
|
||
|
||
<p>
|
||
どちらのフックも、フック関数に渡す <code>argc</code> は 1 です。
|
||
<code>argv[0]</code> の値はエスケープシーケンスのコードそのもので、
|
||
<code>EB_HOOK_BEGIN_SUBSCRIPT</code> なら <samp>0x1f06</samp>、
|
||
<code>EB_HOOK_END_SUBSCRIPT</code> なら <samp>0x1f07</samp> になります。
|
||
</p>
|
||
|
||
<p>
|
||
フック関数を登録していない状態では、これらのフックはテキストデータに
|
||
何も書き込みません。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HOOK_SET_INDENT">定数 <code>EB_HOOK_SET_INDENT</code></a></h4>
|
||
|
||
<p>
|
||
<code>EB_HOOK_SET_INDENT</code> は、テキストデータの行頭の字下げ指定を
|
||
表すエスケープシーケンスに対するフックです。
|
||
</p>
|
||
|
||
<p>
|
||
このフックが、フック関数に渡す <code>argc</code> は 2 です。
|
||
<code>argv[0]</code> はエスケープシーケンスのコードそのもので、
|
||
<samp>0x1f09</samp> になります。
|
||
<code>argv[1]</code> が、字下げの量を表します。
|
||
</p>
|
||
|
||
<p>
|
||
字下げの量の単位が、何であるのかは不明です。
|
||
また、字下げ量の最小値は、0 の場合と 1 の場合の二通りがあります。
|
||
いずれにしろ、字下げは 1 ずつ増えたり減ったりします。
|
||
</p>
|
||
|
||
<p>
|
||
フック関数を登録していない状態では、このフックはテキストデータに何も
|
||
書き込みません。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HOOK_NEWLINE">定数 <code>EB_HOOK_NEWLINE</code></a></h4>
|
||
|
||
<p>
|
||
<code>EB_HOOK_SET_NEWLINE</code> は、改行を表すエスケープシーケンスに
|
||
対するフックです。
|
||
</p>
|
||
|
||
<p>
|
||
ただし、<code>eb_read_heading()</code> (見出しの読み込み) による処理では、
|
||
改行を表すエスケープシーケンスは区切りコードとしても扱われます。
|
||
そのため、エスケープシーケンスが見つかってもこのフックの処理は行われず、
|
||
ただちに読み込み処理は終了します。
|
||
</p>
|
||
|
||
<p>
|
||
このフックが、フック関数に渡す <code>argc</code> は 1 です。
|
||
<code>argv[0]</code> はエスケープシーケンスのコードそのもので、
|
||
<samp>0x1f0a</samp> になります。
|
||
</p>
|
||
|
||
<p>
|
||
フック関数を登録していない状態では、このフックはテキストデータに何も
|
||
書き込みませんが、<code>eb_initialize_hookset()</code> で
|
||
<code>EB_Hook</code> オブジェクトを初期化すると、フック関数として
|
||
<code>eb_hook_newline()</code> が自動的に登録されます。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HOOK_BEGIN_SUPERSCRIPT">定数 <code>EB_HOOK_BEGIN_SUPERSCRIPT</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HOOK_END_SUPERSCRIPT">定数 <code>EB_HOOK_END_SUPERSCRIPT</code></a></h4>
|
||
|
||
<p>
|
||
<code>EB_HOOK_BEGIN_SUPERSCRIPT</code> および
|
||
<code>EB_HOOK_END_SUPERSCRIPT</code> は、上付き表示の開始と終了を表す
|
||
エスケープシーケンスに対するフックです。
|
||
</p>
|
||
|
||
<p>
|
||
どちらのフックも、フック関数に渡す <code>argc</code> は 1 です。
|
||
<code>argv[0]</code> はエスケープシーケンスのコードそのもので、
|
||
<code>EB_HOOK_BEGIN_SUPERSCRIPT</code> なら <samp>0x1f0e</samp>、
|
||
<code>EB_HOOK_END_SUPERSCRIPT</code> なら <samp>0x1f0f</samp> になります。
|
||
</p>
|
||
|
||
<p>
|
||
フック関数を登録していない状態では、これらのフックはテキストデータに何も
|
||
書き込みません。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HOOK_BEGIN_NO_NEWLINE">定数 <code>EB_HOOK_BEGIN_NO_NEWLINE</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HOOK_END_NO_NEWLINE">定数 <code>EB_HOOK_END_NO_NEWLINE</code></a></h4>
|
||
|
||
<p>
|
||
<code>EB_HOOK_BEGIN_NO_NEWLINE</code> および
|
||
<code>EB_HOOK_END_NO_NEWLINE</code> は、改行禁止の開始と終了を表す
|
||
エスケープシーケンスに対するフックです。
|
||
</p>
|
||
|
||
<p>
|
||
どちらのフックも、フック関数に渡す <code>argc</code> は 1 です。
|
||
<code>argv[0]</code> はエスケープシーケンスのコードそのもので、
|
||
<code>EB_HOOK_BEGIN_NO_NEWLINE</code> なら <samp>0x1f10</samp>、
|
||
<code>EB_HOOK_END_NO_NEWLINE</code> なら <samp>0x1f11</samp> になります。
|
||
</p>
|
||
|
||
<p>
|
||
フック関数を登録していない状態では、これらのフックはテキストデータに何も
|
||
書き込みません。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HOOK_BEGIN_EMPHASIS">定数 <code>EB_HOOK_BEGIN_EMPHASIS</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HOOK_END_EMPHASIS">定数 <code>EB_HOOK_END_EMPHASIS</code></a></h4>
|
||
|
||
<p>
|
||
<code>EB_HOOK_BEGIN_EMPHASIS</code> および <code>EB_HOOK_END_EMPHASIS</code>
|
||
は、強調表示の開始と終了を表すエスケープシーケンスに対するフックです。
|
||
</p>
|
||
|
||
<p>
|
||
どちらのフックも、フック関数に渡す <code>argc</code> は 1 です。
|
||
<code>argv[0]</code> はエスケープシーケンスのコードそのもので、
|
||
<code>EB_HOOK_BEGIN_EMPHASIS</code> なら <samp>0x1f12</samp>、
|
||
<code>EB_HOOK_END_EMPHASIS</code> なら <samp>0x1f13</samp> になります。
|
||
</p>
|
||
|
||
<p>
|
||
フック関数を登録していない状態では、これらのフックはテキストデータに何も
|
||
書き込みません。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HOOK_BEGIN_CANDIDATE">定数 <code>EB_HOOK_BEGIN_CANDIDATE</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HOOK_END_CANDIDATE_LEAF">定数 <code>EB_HOOK_END_CANDIDATE_LEAF</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HOOK_END_CANDIDATE_GROUP">定数 <code>EB_HOOK_END_CANDIDATE_GROUP</code></a></h4>
|
||
|
||
<p>
|
||
<code>EB_HOOK_BEGIN_CANDIDATE</code> は、複合検索の候補となる語の開始を
|
||
表すエスケープシーケンスに対するフックです。
|
||
</p>
|
||
|
||
<p>
|
||
それに対して、終了を表すエスケープシーケンスに対するフックは 2 種類
|
||
あります。
|
||
一つは <code>EB_HOOK_END_CANDIDATE_LEAF</code> で、候補となる語が実際に
|
||
検索の入力語として使えるものであることを示します。
|
||
もう一つは <code>EB_HOOK_END_CANDIDATE_GROUP</code> で、候補となる語は
|
||
さらに細かい選択肢に分かれていることを示します。
|
||
(したがって、候補となる語を検索の入力語として使うことはできません。)
|
||
</p>
|
||
|
||
<p>
|
||
フック <code>EB_HOOK_BEGIN_CANDIDATES</code> が、フック関数に渡す
|
||
<code>argc</code> は 1 です。
|
||
<code>argv[0]</code> はエスケープシーケンスのコードそのもので、
|
||
<samp>0x1f43</samp> になります。
|
||
</p>
|
||
|
||
<p>
|
||
フック <code>EB_HOOK_END_CANDIDATE_LEAF</code> および
|
||
<code>EB_HOOK_END_CANDIDATE_GROUP</code> が、フック関数に渡す
|
||
<code>argc</code> は 3 です。
|
||
どちらのフックも、<code>argv[0]</code> はエスケープシーケンスのコード
|
||
そのもので、<samp>0x1f63</samp> になります。
|
||
フック <code>EB_HOOK_END_CANDIDATE_GROUP</code> の <code>argv[1]</code>
|
||
と <code>argv[2]</code> は、次の階層の候補一覧データの開始ページ番号と
|
||
オフセットです。
|
||
これは、<code>EB_Position</code> オブジェクト
|
||
(<a href="#search-data-types">「[検索] データ型の詳細」</a> を参照のこと)
|
||
の <code>page</code> および <code>offset</code> メンバの値に相当します。
|
||
フック <code>EB_HOOK_END_CANDIDATE_LEAF</code> では、<code>argv[1]</code>,
|
||
<code>argv[2]</code> は 2 つとも 0 になっています。
|
||
</p>
|
||
|
||
<p>
|
||
フック関数を登録していない状態では、これらのフックはテキストデータに何も
|
||
書き込みません。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HOOK_BEGIN_REFERENCE">定数 <code>EB_HOOK_BEGIN_REFERENCE</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HOOK_END_REFERENCE">定数 <code>EB_HOOK_END_REFERENCE</code></a></h4>
|
||
|
||
<p>
|
||
<code>EB_HOOK_BEGIN_REFERENCE</code> および
|
||
<code>EB_HOOK_END_REFERENCE</code> は、別位置のテキストデータの参照開始と
|
||
終了を表すエスケープシーケンスに対するフックです。
|
||
</p>
|
||
|
||
<p>
|
||
フック <code>EB_HOOK_BEGIN_REFERENCE</code> が、フック関数に渡す
|
||
<code>argc</code> は 2 です。
|
||
<code>argv[0]</code> はエスケープシーケンスのコードそのもので、
|
||
<samp>0x1f42</samp> になります。
|
||
<code>argv[1]</code> の意味は不明です。
|
||
</p>
|
||
|
||
<p>
|
||
<code>EB_HOOK_END_REFERENCE</code> が、フック関数に渡す <code>argc</code>
|
||
は 3 です。
|
||
<code>argv[0]</code> はエスケープシーケンスのコードそのもので、
|
||
<samp>0x1f62</samp> になります。
|
||
<code>argv[1]</code> と <code>argv[2]</code> は、参照先のページ番号と
|
||
オフセットです。
|
||
これは、<code>EB_Position</code> オブジェクト
|
||
(<a href="#search-data-types">「[検索] データ型の詳細」</a> を参照のこと)
|
||
の <code>page</code> および <code>offset</code> メンバの値に相当します。
|
||
</p>
|
||
|
||
<p>
|
||
フック関数を登録していない状態では、これらのフックはテキストデータに何も
|
||
書き込みません。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HOOK_BEGIN_KEYWORD">定数 <code>EB_HOOK_BEGIN_KEYWORD</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HOOK_END_KEYWORD">定数 <code>EB_HOOK_END_KEYWORD</code></a></h4>
|
||
|
||
<p>
|
||
<code>EB_HOOK_BEGIN_KEYWORD</code> および <code>EB_HOOK_END_KEYWORD</code> は、
|
||
検索キーの開始と終了を表すエスケープシーケンスに対するフックです。
|
||
</p>
|
||
|
||
<p>
|
||
フック <code>EB_HOOK_BEGIN_KEYWORD</code> が、フック関数に渡す
|
||
<code>argc</code> は 2 です。
|
||
<code>argv[0]</code> はエスケープシーケンスのコードそのもので、
|
||
<samp>0x1f41</samp> になります。
|
||
<code>argv[1]</code> の意味は不明です。
|
||
</p>
|
||
|
||
<p>
|
||
<code>EB_HOOK_END_KEYWORD</code> は、フック関数に 1 個の引数を渡します。
|
||
<code>argv[0]</code> はエスケープシーケンスのコードそのもので、
|
||
<samp>0x1f61</samp> になります。
|
||
</p>
|
||
|
||
<p>
|
||
フック関数を登録していない状態では、これらのフックはテキストデータに何も
|
||
書き込みません。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HOOK_BEGIN_DECORATION">定数 <code>EB_HOOK_BEGIN_DECORATION</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HOOK_END_DECORATION">定数 <code>EB_HOOK_END_DECORATION</code></a></h4>
|
||
|
||
<p>
|
||
<code>EB_HOOK_BEGIN_DECORATION</code> および
|
||
<code>EB_HOOK_END_DECORATION</code> は、文字修飾の開始と終了を表す
|
||
エスケープシーケンスに対するフックです。
|
||
</p>
|
||
|
||
<p>
|
||
フック <code>EB_HOOK_BEGIN_DECORATION</code> が、フック関数に渡す
|
||
<code>argc</code> は 2 です。
|
||
<code>argv[0]</code> はエスケープシーケンスのコードそのもので、
|
||
<samp>0x1fe0</samp> になります。
|
||
<code>argv[1]</code> の意味は不明です。
|
||
</p>
|
||
|
||
<p>
|
||
<code>EB_HOOK_END_KEYWORD</code> は、フック関数に 1 個の引数を渡します。
|
||
<code>argv[0]</code> はエスケープシーケンスのコードそのもので、
|
||
<samp>0x1fe1</samp> になります。
|
||
</p>
|
||
|
||
<p>
|
||
フック関数を登録していない状態では、これらのフックはテキストデータに何も
|
||
書き込みません。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HOOK_NARROW_FONT">定数 <code>EB_HOOK_NARROW_FONT</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HOOK_WIDE_FONT">定数 <code>EB_HOOK_WIDE_FONT</code></a></h4>
|
||
|
||
<p>
|
||
<code>EB_HOOK_NARROW_FONT</code> および <code>EB_HOOK_WIDE_FONT</code> は、
|
||
それぞれ半角外字と全角外字に対するフックです。
|
||
</p>
|
||
|
||
<p>
|
||
どちらのフックも、フック関数に渡す <code>argc</code> は 1 です。
|
||
<code>argv[0]</code> は、外字の文字番号を表します。
|
||
</p>
|
||
|
||
<p>
|
||
フック関数を登録していない状態では、このフックはテキストデータに何も
|
||
書き込みませんが、<code>eb_initialize_hookset()</code> で
|
||
<code>EB_Hook</code> オブジェクトを初期化すると、フック関数として
|
||
<code>eb_hook_narrow_character_text()</code> および
|
||
<code>eb_hook_wide_character_text()</code> が自動的に登録されます。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HOOK_ISO8859_1">定数 <code>EB_HOOK_ISO8859_1</code></a></h4>
|
||
|
||
<p>
|
||
<code>EB_HOOK_ISO8859_1</code> は、ISO 8859-1 (ラテン文字 1) 文字に対する
|
||
フックです。
|
||
</p>
|
||
|
||
<p>
|
||
このフックが、フック関数に渡す <code>argc</code> は 1 です。
|
||
<code>argv[0]</code> は、ISO 8859-1 の文字番号を表します。
|
||
</p>
|
||
|
||
<p>
|
||
フック関数を登録していない状態では、<code>argv[0]</code> の値をそのまま
|
||
テキストデータに書き込みます。
|
||
つまり、文字はそのまま ISO 8859-1 として、1 バイト書き込まれます。
|
||
</p>
|
||
|
||
<p>
|
||
このフックが利用されるのは、処理中の書籍の文字コードが
|
||
<code>EB_CHARCODE_ISO8859_1</code> の場合だけです。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HOOK_NARROW_JISX0208">定数 <code>EB_HOOK_NARROW_JISX0208</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HOOK_WIDE_JISX0208">定数 <code>EB_HOOK_WIDE_JISX0208</code></a></h4>
|
||
|
||
<p>
|
||
<code>EB_HOOK_NARROW_JISX0208</code> と <code>EB_HOOK_WIDE_JISX0208</code>
|
||
は、半角および全角の JIS X 0208 (日本語のかな漢字) 文字に対するフックです。
|
||
</p>
|
||
|
||
<p>
|
||
どちらのフックも、フック関数に渡す <code>argc</code> は 1 です。
|
||
<code>argv[0]</code> は、JIS X 0208 の文字を日本語 EUC で表現したときの
|
||
文字番号を表します。
|
||
</p>
|
||
|
||
<p>
|
||
フック関数を登録していない状態では、<code>argv[0]</code> の値をそのまま
|
||
テキストデータに書き込みます。
|
||
つまり、文字はそのまま日本語 EUC として、2 バイト書き込まれます。
|
||
</p>
|
||
|
||
<p>
|
||
このフックが利用されるのは、
|
||
処理中の書籍の文字コードが <code>EB_CHARCODE_JISX0208</code> か
|
||
<code>EB_CHARCODE_JISX0208_GB2312</code> の場合だけです。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HOOK_GB2312">定数 <code>EB_HOOK_GB2312</code></a></h4>
|
||
|
||
<p>
|
||
<code>EB_HOOK_GB2312</code> は、GB 2312 (中国語の簡体字) 文字に対する
|
||
フックです。
|
||
</p>
|
||
|
||
<p>
|
||
このフックが、フック関数に渡す <code>argc</code> は 1 です。
|
||
<code>argv[0]</code> は、GB 2312 の文字を中国語 EUC で表現したときの
|
||
文字番号を表します。
|
||
</p>
|
||
|
||
<p>
|
||
フック関数を登録していない状態では、<code>argv[0]</code> の値をそのまま
|
||
テキストデータに書き込みます。
|
||
つまり、文字はそのまま中国語 EUC として、2 バイト書き込まれます。
|
||
</p>
|
||
|
||
<p>
|
||
このフックが利用されるのは、処理中の書籍の文字コードが
|
||
<code>EB_CHARCODE_JISX0208_GB2312</code> の場合だけです。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HOOK_BEGIN_MONO_GRAPHIC">定数 <code>EB_HOOK_BEGIN_MONO_GRAPHIC</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HOOK_END_MONO_GRAPHIC">定数 <code>EB_HOOK_END_MONO_GRAPHIC</code></a></h4>
|
||
|
||
<p>
|
||
<code>EB_HOOK_BEGIN_MONO_GRAPHIC</code> および
|
||
<code>EB_HOOK_END_MONO_GRAPIHC</code> は、モノクロ図版の開始と終了を
|
||
表すエスケープシーケンスに対するフックです。
|
||
</p>
|
||
|
||
<p>
|
||
フック <code>EB_HOOK_BEGIN_MONO_GRAPHIC</code> が、フック関数に渡す
|
||
<code>argc</code> は 4 です。
|
||
<code>argv[0]</code> はエスケープシーケンスのコードそのもので、
|
||
<samp>0x1f32</samp> か <samp>0x1f44</samp> のいずれかになります。
|
||
<code>argv[2]</code> と <code>argv[3]</code> は、図版の高さと幅
|
||
(ピクセル数) を意味します。
|
||
ただし、電子ブックのモノクロ図版 (最初の引数が <samp>0x1f32</samp> の
|
||
場合) には、図版の高さと幅の情報が欠けているので、値はどちらも 0 に
|
||
なります。
|
||
<code>argv[1]</code> の意味は不明です。
|
||
</p>
|
||
|
||
<p>
|
||
<code>EB_HOOK_END_MONO_GRAPHIC</code> が、フック関数に渡す
|
||
<code>argc</code> は 3 です。
|
||
<code>argv[0]</code> は、エスケープシーケンスのコードそのものです。
|
||
<code>EB_HOOK_BEGIN_MONO_GRAPHIC</code> の <code>argv[0]</code> が
|
||
<samp>0x1f32</samp> なら、<code>EB_HOOK_END_MONO_GRAPHIC</code> の
|
||
<code>argv[0]</code> は <samp>0x1f52</samp> になり、<samp>0x1f44</samp>
|
||
なら <samp>0x1f64</samp> になります。
|
||
<code>argv[1]</code> と <code>argv[2]</code> は、図版データのページ番号
|
||
とオフセットです。
|
||
これは、<code>EB_Position</code> オブジェクト
|
||
(<a href="#search-data-types">「[検索] データ型の詳細」</a> を参照のこと)
|
||
の <code>page</code> および <code>offset</code> メンバの値に相当します。
|
||
</p>
|
||
|
||
<p>
|
||
図版データの取り出し方については、<a href="#monochrome-image">「モノクロ図版」</a>
|
||
を参照してください。
|
||
</p>
|
||
|
||
<p>
|
||
フック関数を登録していない状態では、これらのフックはテキストデータに何も
|
||
書き込みません。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HOOK_BEGIN_GRAY_GRAPHIC">定数 <code>EB_HOOK_BEGIN_GRAY_GRAPHIC</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HOOK_END_GRAY_GRAPHIC">定数 <code>EB_HOOK_END_GRAY_GRAPHIC</code></a></h4>
|
||
|
||
<p>
|
||
これらのフック名称は、グレースケール図版のために予約されていますが、
|
||
本バージョンの EB ライブラリではまだ対応していません。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HOOK_BEGIN_COLOR_BMP">定数 <code>EB_HOOK_BEGIN_COLOR_BMP</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HOOK_BEGIN_COLOR_JPEG">定数 <code>EB_HOOK_BEGIN_COLOR_JPEG</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HOOK_END_COLOR_GRAPHIC">定数 <code>EB_HOOK_END_COLOR_GRAPHIC</code></a></h4>
|
||
|
||
<p>
|
||
<code>EB_HOOK_BEGIN_COLOR_BMP</code> と <code>EB_HOOK_COLOR_JPEG</code>
|
||
は、それぞれ BMP 形式と JPEG 形式のカラー図版の開始を表す
|
||
エスケープシーケンスに対するフックです。
|
||
開始のフックは BMP と JPEG とでフックが分かれていますが、終了の
|
||
フックは共通で、<code>EB_HOOK_END_COLOR_GRAPIHC</code> になります。
|
||
</p>
|
||
|
||
<p>
|
||
フック <code>EB_HOOK_BEGIN_COLOR_BMP</code> と
|
||
<code>EB_HOOK_COLOR_JPEG</code> が、フック関数に渡す <code>argc</code> は
|
||
4 です。
|
||
<code>argv[0]</code> はエスケープシーケンスのコードそのもので、
|
||
<samp>0x1f4d</samp> になります。
|
||
<code>argv[2]</code> と <code>argv[3]</code> は、図版の幅と高さ
|
||
(ピクセル数) を意味します。
|
||
<code>argv[1]</code> の意味は不明です。
|
||
</p>
|
||
|
||
<p>
|
||
フック <code>EB_HOOK_END_COLOR_BMP</code> が、フック関数に渡す
|
||
<code>argc</code> は 3 です。
|
||
<code>argv[0]</code> はエスケープシーケンスのコードそのもので、
|
||
<samp>0x1f6d</samp> になります。
|
||
<code>argv[1]</code> と <code>argv[2]</code> は、図版データのページ番号
|
||
とオフセットです。
|
||
これは、<code>EB_Position</code> オブジェクト
|
||
(<a href="#search-data-types">「[検索] データ型の詳細」</a> を参照のこと)
|
||
の <code>page</code> および <code>offset</code> メンバの値に相当します。
|
||
</p>
|
||
|
||
<p>
|
||
図版データの取り出し方については、<a href="#color-image">「カラー図版」</a>
|
||
を参照してください。
|
||
</p>
|
||
|
||
<p>
|
||
フック関数を登録していない状態では、これらのフックはテキストデータに何も
|
||
書き込みません。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HOOK_BEGIN_IN_COLOR_BMP">定数 <code>EB_HOOK_BEGIN_IN_COLOR_BMP</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HOOK_BEGIN_IN_COLOR_JPEG">定数 <code>EB_HOOK_BEGIN_IN_COLOR_JPEG</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HOOK_END_IN_COLOR_GRAPHIC">定数 <code>EB_HOOK_END_IN_COLOR_GRAPHIC</code></a></h4>
|
||
|
||
<p>
|
||
<code>EB_HOOK_BEGIN_IN_COLOR_BMP</code> と <code>EB_HOOK_IN_COLOR_JPEG</code> は、
|
||
それぞれ BMP 形式と JPEG 形式のインラインカラー図版の開始を表す
|
||
エスケープシーケンスに対するフックです。
|
||
開始のフックは BMP と JPEG とでフックが分かれていますが、終了の
|
||
フックは共通で、<code>EB_HOOK_END_IN_COLOR_GRAPIHC</code> になります。
|
||
</p>
|
||
|
||
<p>
|
||
フック <code>EB_HOOK_BEGIN_IN_COLOR_BMP</code> と
|
||
<code>EB_HOOK_IN_COLOR_JPEG</code> が、フック関数に渡す <code>argc</code>
|
||
は 4 です。
|
||
<code>argv[0]</code> はエスケープシーケンスのコードそのもので、
|
||
<samp>0x1f3c</samp> になります。
|
||
<code>argv[2]</code> と <code>argv[3]</code> は、図版の幅と高さ
|
||
(ピクセル数) を意味します。
|
||
<code>argv[1]</code> の意味は不明です。
|
||
</p>
|
||
|
||
<p>
|
||
フック <code>EB_HOOK_END_IN_COLOR_BMP</code> が、フック関数に渡す
|
||
<code>argc</code> は 3 です。
|
||
<code>argv[0]</code> はエスケープシーケンスのコードそのもので、
|
||
<samp>0x1f5c</samp> になります。
|
||
<code>argv[1]</code> と <code>argv[2]</code> は、図版データのページ番号と
|
||
オフセットです。
|
||
これは、<code>EB_Position</code> オブジェクト
|
||
(<a href="#search-data-types">「[検索] データ型の詳細」</a> を参照のこと)
|
||
の <code>page</code> および <code>offset</code> メンバの値に相当します。
|
||
</p>
|
||
|
||
<p>
|
||
図版データの取り出し方については、<a href="#color-image">「カラー図版」</a>
|
||
を参照してください。
|
||
</p>
|
||
|
||
<p>
|
||
フック関数を登録していない状態では、これらのフックはテキストデータに何も
|
||
書き込みません。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HOOK_BEGIN_CLICKABLE_AREA">定数 <code>EB_HOOK_BEGIN_CLICKABLE_AREA</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HOOK_END_CLICKABLE_AREA">定数 <code>EB_HOOK_END_CLICKABLE_AREA</code></a></h4>
|
||
|
||
<p>
|
||
<code>EB_HOOK_BEGIN_CLICKABLE_AREA</code> は、カラー図版およびインラインカラー図版内の特定矩形領域に対して、参照先情報を表現した開始エスケープシーケンスに対するフックです。
|
||
同様に、<code>EB_HOOK_END_CLICKABLE_AREA</code> は終了エスケープシーケンスに対するフックです。
|
||
</p>
|
||
|
||
<p>
|
||
フック <code>EB_HOOK_BEGIN_CLICKABLE_AREA</code> が、フック関数に渡す
|
||
<code>argc</code> は 7 です。
|
||
<code>argv[0]</code> はエスケープシーケンスのコードそのもので、
|
||
<samp>0x1f4f</samp> になります。
|
||
<code>argv[1]</code> と <code>argv[2]</code> は、それぞれ矩形領域の開始
|
||
x, y 座標を表します。
|
||
それぞれ矩形領域の開始 x, y 座標を表します。
|
||
カラー図版の左上の座標が (0, 0) です。
|
||
同様に、<code>argv[3]</code> と <code>argv[4]</code> が図版の右方向への
|
||
幅と、下方向への高さを表します。
|
||
最後の <code>argv[5]</code> と <code>argv[6]</code> が参照先のページ番号
|
||
とオフセットとなります。
|
||
</p>
|
||
|
||
<blockquote>
|
||
<pre>
|
||
参照先付きカラー図版
|
||
（０，０）
|
||
┌─────────────────────┐
|
||
│ │
|
||
│（ｘ，ｙ） │
|
||
│ ┌ ─ ─ ─ ─ ─ ─ ┐ │
|
||
│ │ 高さ↑ │ │
|
||
│ │ │
|
||
│ │ 矩形領域 │ │ │
|
||
│ │ │
|
||
│ │ │ │ │
|
||
│ 幅 │ │
|
||
│ │←──────────┼→│ │
|
||
│ ↓ │
|
||
│ └ ─ ─ ─ ─ ─ ─ ┘ │
|
||
│ │
|
||
└─────────────────────┘
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
<code>EB_HOOK_END_CLICKABLE_AREA</code> が、フック関数に渡す
|
||
<code>argc</code> は 1 です。
|
||
<code>argv[0]</code> はエスケープシーケンスのコードそのもので、
|
||
<samp>0x1f6f</samp> になります。
|
||
</p>
|
||
|
||
<p>
|
||
参照先情報の取り出し方については、
|
||
<a href="#clickable-color-image">「参照先付きカラー図版」</a>
|
||
を参照して下さい。
|
||
</p>
|
||
|
||
<p>
|
||
フック関数を登録していない状態では、これらのフックはテキストデータに何も
|
||
書き込みません。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HOOK_BEGIN_WAVE">定数 <code>EB_HOOK_BEGIN_WAVE</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HOOK_END_WAVE">定数 <code>EB_HOOK_END_WAVE</code></a></h4>
|
||
|
||
<p>
|
||
<code>EB_HOOK_BEGIN_WAVE</code> および <code>EB_HOOK_END_WAVE</code> は、
|
||
WAVE (PCM) 形式の音声データの開始と終了を表すエスケープシーケンスに対する
|
||
フックです。
|
||
</p>
|
||
|
||
<p>
|
||
フック <code>EB_HOOK_BEGIN_WAVE</code> が、フック関数に渡す
|
||
<code>argc</code> は 6 です。
|
||
<code>argv[0]</code> はエスケープシーケンスのコードそのもので、
|
||
<samp>0x1f4a</samp> になります。
|
||
<code>argv[2]</code> と <code>argv[3]</code> は音声データの開始位置の
|
||
ページ番号とオフセット、<code>argv[4]</code> と <code>argv[5]</code> は
|
||
終了位置のページ番号とオフセットをそれぞれ表します。
|
||
<code>argv[1]</code> の意味は不明です。
|
||
</p>
|
||
|
||
<p>
|
||
<code>EB_HOOK_END_WAVE</code> が、フック関数に渡す <code>argc</code> は
|
||
1 です。
|
||
<code>argv[0]</code> はエスケープシーケンスのコードそのもので、
|
||
<samp>0x1f6a</samp> になります。
|
||
</p>
|
||
|
||
<p>
|
||
音声データの取り出し方については、<a href="#wave-sound">「WAVE 音声」</a>
|
||
を参照して下さい。
|
||
</p>
|
||
|
||
<p>
|
||
フック関数を登録していない状態では、これらのフックはテキストデータに何も
|
||
書き込みません。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HOOK_BEGIN_MPEG">定数 <code>EB_HOOK_BEGIN_MPEG</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HOOK_END_MPEG">定数 <code>EB_HOOK_END_MPEG</code></a></h4>
|
||
|
||
<p>
|
||
<code>EB_HOOK_BEGIN_MPEG</code> および <code>EB_HOOK_END_MPEG</code> は、
|
||
MPEG 形式の動画データの開始と終了を表すエスケープシーケンスに対するフック
|
||
です。
|
||
</p>
|
||
|
||
<p>
|
||
フック <code>EB_HOOK_BEGIN_MPEG</code> が、フック関数に渡す
|
||
<code>argc</code> は 6 です。
|
||
<code>argv[0]</code> はエスケープシーケンスのコードそのもので、
|
||
<samp>0x1f39</samp> になります。
|
||
<code>argv[2]</code> ～ <code>argv[5]</code> は、動画データのファイル名を
|
||
エンコードした数値列になります。
|
||
<code>argv[1]</code> の意味は不明です。
|
||
</p>
|
||
|
||
<p>
|
||
<code>EB_HOOK_END_MPEG</code> が、フック関数に渡す <code>argc</code> は
|
||
1 です。
|
||
<code>argv[0]</code> はエスケープシーケンスのコードそのもので、
|
||
<samp>0x1f59</samp> になります。
|
||
</p>
|
||
|
||
<p>
|
||
動画データの取り出し方については、<a href="#mpeg-movie">「MPEG 動画」</a>
|
||
を参照して下さい。
|
||
</p>
|
||
|
||
<p>
|
||
フック関数を登録していない状態では、これらのフックはテキストデータに何も
|
||
書き込みません。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="hookset-access-functions">フックセット操作関数の詳細</a></h3>
|
||
|
||
<p>
|
||
この節で説明している関数を使うには、次のようにヘッダファイルを読み込んで
|
||
下さい。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
#include <eb/text.h>
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:initialize_hookset"><code>void eb_initialize_hookset (EB_Hookset *<var>hookset</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>initialize_hookset()</code> は、<var>hookset</var> の指す
|
||
<code>EB_Hookset</code> オブジェクトを初期化します。
|
||
<code>EB_Hookiset</code> オブジェクトに対して EB ライブラリの他の関数を
|
||
呼ぶ前に、
|
||
必ずそのオブジェクトを初期化しなくてはなりません。
|
||
初期化していないオブジェクトに対して、EB ライブラリの他の関数を呼んだ
|
||
場合の動作は未定義です。
|
||
また、すでに初期化したオブジェクトに対して、再度
|
||
<code>eb_initialize_hookset()</code> を呼んではいけません。
|
||
呼んだ場合の動作は未定義です。
|
||
</p>
|
||
|
||
<p>
|
||
この関数は、各フックの初期値を次のようにセットします。
|
||
</p>
|
||
|
||
<table summary="各フックの初期値">
|
||
<tr>
|
||
<td>フック
|
||
<td>フック関数
|
||
</tr>
|
||
<tr>
|
||
<td><code>EB_HOOK_NARROW_JISX0208</code>
|
||
<td><code>eb_hook_euc_to_ascii()</code>
|
||
</tr>
|
||
<tr>
|
||
<td><code>EB_HOOK_NARROW_FONT</code>
|
||
<td><code>eb_hook_narrow_character_text()</code>
|
||
</tr>
|
||
<tr>
|
||
<td><code>EB_HOOK_WIDE_FONT</code>
|
||
<td><code>eb_hook_wide_character_text()</code>
|
||
</tr>
|
||
<tr>
|
||
<td><code>EB_HOOK_NEWLINE</code>
|
||
<td><code>eb_hook_newline()</code>
|
||
</tr>
|
||
<tr>
|
||
<td>上記以外のフック
|
||
<td> <code>NULL</code> (フック関数なし)
|
||
</tr>
|
||
</table>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:finalize_hookset"><code>EB_Error_Code eb_finalize_hookset (EB_Hookset *<var>hookset</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_finalize_hookset()</code> は、<var>hookset</var> が指す
|
||
<code>EB_Hooksest</code> オブジェクトの後始末を行います。
|
||
</p>
|
||
|
||
<p>
|
||
オブジェクトが割り当てて管理していたメモリは、すべて解放されます。
|
||
すべてのフックには、フック関数として <code>NULL</code> がセットされます。
|
||
</p>
|
||
|
||
<p>
|
||
後始末をしたオブジェクトに対して <code>eb_set_hook()</code>, <code>eb_set_hooks()</code>
|
||
を呼ぶことで、オブジェクトを再利用することができます。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:set_hook"><code>EB_Error_Code eb_set_hook (EB_Hookset *<var>hookset</var>, const EB_Hook *<var>hook</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_set_hook()</code> は、<var>hookset</var> が指す <code>EB_Hooksest</code>
|
||
オブジェクトに、フック関数を一つ登録します。
|
||
登録するフックの種類とフック関数は、<var>hook</var> で指定します。
|
||
</p>
|
||
|
||
<p>
|
||
同じフックコードに複数回フック関数を登録しても、有効になるのは最後に
|
||
登録したものだけですので、注意して下さい。
|
||
フック関数として <code>NULL</code> を指定すると、登録されているフックが
|
||
解除されます。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、この関数は <code>EB_SUCCESS</code> を返します。
|
||
失敗すると、原因を示すエラーコードを返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:set_hooks"><code>EB_Error_Code eb_set_hooks (EB_Hookset *<var>hookset</var>, const EB_Hook *<var>hooks</var>)</code></a></h4>
|
||
|
||
<p>
|
||
この関数は <code>eb_set_hook()</code> に似ていますが、任意の個数の
|
||
フック関数を一度に登録できる点が異なります。
|
||
</p>
|
||
|
||
<p>
|
||
登録するフックの種類とフック関数は、<var>hooks</var> で指定します。
|
||
<var>hooks</var> は <code>EB_Hook</code> オブジェクトの配列 (の先頭) を
|
||
指していなければなりません。
|
||
また、この配列の末尾には、フックコード <code>EB_HOOK_NULL</code> をセット
|
||
した <code>EB_Hook</code> オブジェクトを配列要素として置く必要があります。
|
||
</p>
|
||
|
||
<p>
|
||
<code>eb_set_hooks()</code> は、配列の先頭から順番に、指定されたフックコード
|
||
に対してフック関数を登録していきます。
|
||
エラーが発生すると、残りのフックの登録はせずに、原因を示すエラーコード
|
||
をただちに返します。
|
||
すべてのフック関数の登録に成功すると、<code>EB_SUCCESS</code> を返します。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="builtin-hook-functions">組み込みフック関数の詳細</a></h3>
|
||
|
||
<p>
|
||
EB ライブラリは、基本的なフック関数をいくつか用意しています。
|
||
本節では、これらのフック関数についての仕様を解説します。
|
||
</p>
|
||
|
||
<p>
|
||
この節で説明している関数を使うには、次のようにヘッダファイルを読み込んで
|
||
下さい。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
#include <eb/text.h>
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
いずれのフック関数も、引数 <var>appendix</var> と <var>container</var> に
|
||
<code>NULL</code> を渡されても、動作に支障はないようになっています。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:hook_euc_to_ascii"><code>EB_Error_Code eb_hook_euc_to_ascii (EB_Book *<var>book</var>, EB_Appendix *<var>appendix</var>, void *<var>container</var>, EB_Hook_Code <var>code</var>, int <var>argc</var>, const unsigned int *<var>argv</var>)</code></a></h4>
|
||
|
||
<p>
|
||
<code>eb_hook_euc_to_ascii()</code> は、フックコード
|
||
<code>EB_HOOK_NARROW_JISX0208</code> (半角 JIS X 0208 文字) のための
|
||
フック関数です。
|
||
</p>
|
||
|
||
<p>
|
||
<code>EB_Hookset</code> オブジェクトを関数
|
||
<code>eb_initialiez_hookset()</code> で初期化すると、この関数が自動的に
|
||
登録されます。
|
||
</p>
|
||
|
||
<p>
|
||
このフック関数は、<code>argv[0]</code> として渡された JIS X 0208 の文字
|
||
(エンコーディングは日本語 EUC) を調べ、対応する ASCII 文字が存在すれば
|
||
その ASCII 文字をテキストデータとして書き込み、なければ JIS X 0208 の
|
||
文字をそのまま書き込みます。
|
||
</p>
|
||
|
||
<p>
|
||
常に <code>EB_SUCCESS</code> を返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:hook_narrow_character_text"><code>EB_Error_Code eb_hook_narrow_character_text (EB_Book *<var>book</var>, EB_Appendix *<var>appendix</var>, void *<var>container</var>, EB_Hook_Code <var>code</var>, int <var>argc</var>, const unsigned int *<var>argv</var>)</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:hook_wide_character_text"><code>EB_Error_Code eb_hook_wide_character_text (EB_Book *<var>book</var>, EB_Appendix *<var>appendix</var>, void *<var>container</var>, EB_Hook_Code <var>code</var>, int <var>argc</var>, const unsigned int *<var>argv</var>)</code></a></h4>
|
||
|
||
<p>
|
||
<code>eb_hook_narrow_character_text()</code> は、フックコード
|
||
<code>EB_HOOK_NARROW_FONT</code> (半角外字) のためのフック関数です。
|
||
同様に <code>eb_hook_wide_character_text()</code> は、フックコード
|
||
<code>EB_HOOK_WIDE_FONT</code> (全角外字) のためのフック関数です。
|
||
</p>
|
||
|
||
<p>
|
||
<code>EB_Hookset</code> オブジェクトを関数
|
||
<code>eb_initialiez_hookset()</code> で初期化すると、これらの関数が自動的
|
||
に登録されます。
|
||
</p>
|
||
|
||
<p>
|
||
この関数は、<var>appendix</var> の選択中している副本が、
|
||
<code>argv[0]</code> として渡された外字の代替文字列を持っているかどうか
|
||
調べます。
|
||
持っていればその文字列をテキストデータとして書き込み、持っていなければ
|
||
<samp><?></samp> という文字列を書き込みます。
|
||
</p>
|
||
|
||
<p>
|
||
<var>appendix</var> が <code>NULL</code> の場合や、付録が副本を選択中で
|
||
ない場合も、代替文字列を持っていないものとして扱います。
|
||
</p>
|
||
|
||
<p>
|
||
この関数は、常に <code>EB_SUCCESS</code> を返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:hook_newline"><code>EB_Error_Code eb_hook_newline (EB_Book *<var>book</var>, EB_Appendix *<var>appendix</var>, void *<var>container</var>, EB_Hook_Code <var>code</var>, int <var>argc</var>, const unsigned int *<var>argv</var>)</code></a></h4>
|
||
|
||
<p>
|
||
<code>eb_hook_narrow_newline()</code> は、フックコード
|
||
<code>EB_HOOK_NEWLINE</code> (改行) のためのフック関数です。
|
||
</p>
|
||
|
||
<p>
|
||
<code>EB_Hookset</code> オブジェクトを関数
|
||
<code>eb_initialiez_hookset()</code> で初期化すると、これらの関数が自動的
|
||
に登録されます。
|
||
</p>
|
||
|
||
<p>
|
||
この関数は、テキストデータに <samp>\n</samp> を書き込みます。
|
||
常に <code>EB_SUCCESS</code> を返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:hook_empty"><code>EB_Error_Code eb_hook_empty (EB_Book *<var>book</var>, EB_Appendix *<var>appendix</var>, void *<var>container</var>, EB_Hook_Code <var>code</var>, int <var>argc</var>, const unsigned int *<var>argv</var>)</code></a></h4>
|
||
|
||
<p>
|
||
<code>eb_hook_empty()</code> は、何もしないフック関数です。
|
||
常に <code>EB_SUCCESS</code> を返します。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="text-data-functions">テキストデータ操作関数の詳細</a></h3>
|
||
|
||
<p>
|
||
この節で説明している関数を使うには、次のようにヘッダファイルを読み込んで
|
||
下さい。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
#include <eb/text.h>
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:have_text"><code>int eb_have_text (EB_Book *<var>book</var>)</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:have_menu"><code>int eb_have_menu (EB_Book *<var>book</var>)</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:have_copyright"><code>int eb_have_copyright (EB_Book *<var>book</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_have_text()</code> は、<var>book</var> の選択している副本が、
|
||
本文を持っているかどうかを調べます。
|
||
同様に、<code>eb_have_menu()</code> はメニューを持っているかどうか、
|
||
<code>eb_have_copyright()</code> は著作権表示を持っているかどうか調べます。
|
||
</p>
|
||
|
||
<p>
|
||
いずれの関数も、持っていれば 1 を返し、持っていなければ 0 を返します。
|
||
<var>book</var> が副本を選択していない場合も 0 を返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:text"><code>EB_Error_Code eb_text (EB_Book *<var>book</var>, EB_Position *<var>position</var>)</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:menu"><code>EB_Error_Code eb_menu (EB_Book *<var>book</var>, EB_Position *<var>position</var>)</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:copyright"><code>EB_Error_Code eb_copyright (EB_Book *<var>book</var>, EB_Position *<var>position</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_text()</code> は、<var>book</var> が選択している副本の本文
|
||
の開始位置を <var>position</var> の指す領域に書き込みます。
|
||
同様に、<code>eb_menu()</code> はメニューの開始位置を、
|
||
<code>eb_have_copyright()</code> は著作権表示の開始位置を書き込みます。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、これらの関数は <code>EB_SUCCESS</code> を返します。
|
||
失敗すると、<var>position</var> に必ずシークが失敗する位置を書き込んで、
|
||
原因を示すエラーコードを返します。
|
||
</p>
|
||
|
||
<p>
|
||
あらかじめ、<var>book</var> 内のいずれかの副本が選択されていなくては
|
||
なりません。
|
||
<var>book</var> が副本を選択していなければ、<code>EB_ERR_NO_CUR_SUB</code>
|
||
を返します。
|
||
選択中の副本が、対象となるテキストデータを持っていなければ、
|
||
<code>EB_ERR_NO_SUCH_SEARCH</code> を返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:seek_text"><code>EB_Error_Code eb_seek_text (EB_Book *<var>book</var>, const EB_Position *<var>position</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_seek_text()</code> は、<var>book</var> が選択している副本の
|
||
テキストデータファイルをシークします。
|
||
シーク位置は <var>position</var> で指定します。
|
||
このとき、<var>position</var> は常にファイルの先頭からの位置として解釈
|
||
されます。
|
||
(相対位置へのシーク機能は、EB ライブラリにはありません。)
|
||
</p>
|
||
|
||
<p>
|
||
シークを行うと、それまでに行った読み込みの状態記録がリセットされます。
|
||
<code>eb_read_text()</code>, <code>eb_read_heading()</code>,
|
||
<code>eb_read_rawtext()</code> を用いてテキストデータを読み込むには、
|
||
前もってこの関数を呼び出しておく必要があります。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、この関数は <code>EB_SUCCESS</code> を返します。
|
||
失敗すると、原因を示すエラーコードを返します。
|
||
</p>
|
||
|
||
<p>
|
||
あらかじめ、<var>book</var> 内のいずれかの副本が選択されていなくては
|
||
なりません。
|
||
<var>book</var> が副本を選択していなければ、<code>EB_ERR_NO_CUR_SUB</code>
|
||
を返します。
|
||
選択中の副本にテキストデータが存在しないときは、<code>EB_ERR_NO_TEXT</code>
|
||
を返します。
|
||
</p>
|
||
|
||
<p>
|
||
なお、書籍によっては、テキストデータを収めたファイルには他のデータも
|
||
一緒に格納されていることがありますが、テキスト以外のデータにアクセス
|
||
しても、テキストデータの現在位置、読み込みに関する状態記録は変化しません。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:tell_text"><code>EB_Error_Code eb_tell_text (EB_Book *<var>book</var>, EB_Position *<var>position</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_seek_text()</code> は、<var>book</var> が選択している副本の
|
||
テキストデータファイルの現在のアクセス位置を返します。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、<var>position</var> の指す領域に現在のアクセス位置を書き込み、
|
||
<code>EB_SUCCESS</code> を返します。
|
||
失敗すると、シークが必ず失敗する位置を書き込み、原因を示すエラーコード
|
||
を返します。
|
||
</p>
|
||
|
||
<p>
|
||
あらかじめ、<var>book</var> 内のいずれかの副本が選択されていなくては
|
||
なりません。
|
||
<var>book</var> が副本を選択していなければ、<code>EB_ERR_NO_CUR_SUB</code>
|
||
を返します。
|
||
選択中の副本にテキストデータが存在しないときは、<code>EB_ERR_NO_TEXT</code>
|
||
を返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:read_text"><code>EB_Error_Code eb_read_text (EB_Book *<var>book</var>, EB_Appendix *<var>appendix</var>, EB_Hookset *<var>hookset</var>, void *<var>container</var>, size_t <var>text_max_length</var>, char *<var>text</var>, ssize_t *<var>text_length</var>)</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:read_heading"><code>EB_Error_Code eb_read_heading (EB_Book *<var>book</var>, EB_Appendix *<var>appendix</var>, EB_Hookset *<var>hookset</var>, void *<var>container</var>, size_t <var>text_max_length</var>, char *<var>text</var>, ssize_t *<var>text_length</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_read_text()</code> と <code>eb_read_heading()</code> は、
|
||
<var>book</var>
|
||
が選択している副本のテキストデータファイルの現在のアクセス位置からデータ
|
||
を読み込みます。
|
||
<code>eb_read_heading()</code> は見出しの読み込みに用い、
|
||
<code>eb_read_text()</code> はそれ以外のテキストデータの読み込みに用います。
|
||
</p>
|
||
|
||
<p>
|
||
読み込まれたテキストデータは、必要に応じて文字コードの変換
|
||
(<a href="#character-code">「文字コード」</a> を参照のこと) が行われた後に、<var>hookset</var>
|
||
の指すフックセットにしたがって加工されます。
|
||
<var>hookset</var> が <code>NULL</code> のときは、代わりに EB ライブラリ側
|
||
で用意している <dfn>標準のフックセット (default hookset)</dfn> が
|
||
用いられます。
|
||
このフックセットは、<code>eb_initialize_hookset()</code> によって
|
||
初期化しただけのフックセットと等価です。
|
||
</p>
|
||
|
||
<p>
|
||
フックセットによって加工された後に、テキストデータは <var>text</var> の
|
||
指す領域に書き込まれ、書き込んだバイト数が <var>text_length</var> の指す
|
||
領域に書き込まれます。
|
||
<var>text</var> はナル文字で終端されますが、<var>text_length</var> には
|
||
ナル文字の分は勘定に入れません。
|
||
テキストデータは、<var>text_max_length</var> で指定されたバイト数を超えて
|
||
書き込むことはありません。
|
||
ただし、<var>text_max_length</var> にもナル文字の分は勘定に入っていません
|
||
ので、<var>text</var> は <var>text_max_length</var> + 1 バイト分のデータ
|
||
を格納できる大きさが必要です。
|
||
</p>
|
||
|
||
<p>
|
||
どちらの関数も、成功すれば <code>EB_SUCCESS</code> を返し、失敗すれば
|
||
<var>text_length</var> の指す領域に 0 を書き込んで原因を示すエラーコード
|
||
を返します。
|
||
</p>
|
||
|
||
<p>
|
||
あらかじめ、<var>book</var> 内のいずれかの副本が選択されていなくては
|
||
なりません。
|
||
<var>book</var> が副本を選択していなければ、<code>EB_ERR_NO_CUR_SUB</code>
|
||
を返します。
|
||
</p>
|
||
|
||
<p>
|
||
また、<code>eb_read_text()</code> と <code>eb_read_heading()</code> を
|
||
呼び出すには、
|
||
あらかじめ <code>eb_seek_text()</code> の呼び出しを成功させ、テキストデータ
|
||
のアクセス位置がセットされた状態にしておかなくてはなりません。
|
||
シークをせずに呼び出すと、<code>EB_ERR_NO_PREV_SEEK</code> を返します。
|
||
</p>
|
||
|
||
<p>
|
||
逆に一度シークすれば、区切りコードが検出されるまでの間なら、関数を
|
||
繰り返し呼ぶことでテキストデータの続きを読み込むことができます。
|
||
区切りコードが検出されると、関数を呼び出しても読み込みは行われません。
|
||
その場合でも、他にエラーが発生しなければ <code>EB_SUCCESS</code> が返り、
|
||
<var>text</var> には空文字列が書き込まれます。
|
||
</p>
|
||
|
||
<p>
|
||
ただし、一度 <code>eb_read_text()</code> を呼び出してテキストデータを
|
||
読み込み始めたら、繰り返し呼び出す際も、<code>eb_read_text()</code> を
|
||
使わなければなりません。
|
||
途中から <code>eb_read_heading()</code> および後述の
|
||
<code>eb_read_rawtext()</code> に切り替えて呼び出すと
|
||
<code>EB_ERR_DIFF_CONTENT</code> エラーが返ります。
|
||
関数 <code>eb_read_heading()</code> についても同様です。
|
||
この制限は、再度 <code>eb_seek_text()</code> を呼び出すか、
|
||
<code>eb_set_subbook()</code> で副本を選択し直すまで続きます。
|
||
</p>
|
||
|
||
<p>
|
||
渡された <var>appendix</var> が区切りコードの情報を持った副本を選択中
|
||
であれば、本文の区切りコードとしてその値を使用します。
|
||
それ以外の場合は、<code>eb_read_text()</code> が区切りコードを自動判別を
|
||
試みます。
|
||
ただし、この判定は完璧なものではないので、書籍によっては変な位置で本文
|
||
が切れてしまうかも知れません。
|
||
(本文以外のテキストデータに関しては、このような問題は起きません。)
|
||
</p>
|
||
|
||
<p>
|
||
引数 <var>container</var> は、アプリケーションプログラムからフック関数に
|
||
データを渡すためのものです。
|
||
<code>eb_read_text()</code>, <code>eb_read_heading()</code> では、直接
|
||
この引数の値を参照することはありません。
|
||
</p>
|
||
|
||
<p>
|
||
引数 <var>appendix</var>, <var>container</var> は、そのままフック関数に
|
||
渡されます。
|
||
これらの引数は <code>NULL</code> でも構いません。
|
||
(呼び出されるフック関数で支障がなければ。)
|
||
</p>
|
||
|
||
<p>
|
||
なお、フック関数や <code>eb_read_text()</code>, <code>eb_read_heading()</code>
|
||
自身が文字ないしエスケープシーケンス一個分に対するデータを書き込もうと
|
||
したときに、<var>text</var> に十分な空き領域がないということが起こり
|
||
得ます。
|
||
その場合、関数は途中まで <var>text</var> に書き込むことはせずに、
|
||
いったん処理を終えて戻ります。
|
||
したがって、マルチバイト文字のデータが途中で切れたりすることはありません。
|
||
</p>
|
||
|
||
<p>
|
||
書き込めなかった分は、当然ながら <var>text_length</var> の勘定には
|
||
入りません。
|
||
書き込めなかったデータは <var>book</var> 内部に保存されているので、
|
||
もう一度 <code>eb_read_text()</code>, <code>eb_read_heading()</code> を
|
||
呼び出すと、前回の呼び出しで書き込めなかったデータがまず <var>text</var>
|
||
の先頭に書き込まれます。
|
||
書き込んだデータは <var>text_length</var> の勘定に入ります。
|
||
</p>
|
||
|
||
<p>
|
||
ただし、<code>book</code> が保存しているデータの長さが
|
||
<var>text_max_length</var> を超えていると、何も書き込まずに関数は終了
|
||
します。
|
||
このとき、書き込めなかったデータは引き続き保存されます。
|
||
つまり、<code>text_max_length</code> があまりに小さく、かつ保持している
|
||
データのほうが長いと、何度呼び出しても <code>text</code> への書き込みが
|
||
進みませんので、注意が必要です。
|
||
</p>
|
||
|
||
<p>
|
||
<code>eb_seek_text()</code> を呼び出すか、<code>eb_set_subbook()</code>
|
||
で副本を選択し直すと、保存していたデータは破棄されます。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:read_rawtext"><code>EB_Error_Code eb_read_rawtext (EB_Book *<var>book</var>, size_t <var>text_max_length</var>, char *<var>text</var>, ssize_t *<var>text_length</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_read_rawtext()</code> は、<var>book</var> が選択している
|
||
副本のテキストデータファイルの現在のアクセス位置からデータを読み込みます。
|
||
</p>
|
||
|
||
<p>
|
||
<code>eb_read_text()</code> と似ていますが、この関数はフックセットによる
|
||
データの加工や文字コードの変換を一切行わず、データを内部表現のまま返します。
|
||
読み込むテキストデータの種類は、何であっても構いません。
|
||
</p>
|
||
|
||
<p>
|
||
読み込んだテキストデータは <var>text</var> の指す領域に書き込まれ、
|
||
書き込んだバイト数が <var>text_length</var> の指す領域に書き込まれます。
|
||
テキストデータは、<var>text_max_length</var> で指定されたバイト数を超えて
|
||
書き込むことはありません。
|
||
ただし、<code>eb_read_text()</code> と異なり、<var>text</var> はナル文字
|
||
で終端されません。
|
||
マルチバイト文字やエスケープシーケンスの途中で <var>text</var> の残り領域
|
||
が足りなくなった場合も、途中までは書き込みます。
|
||
</p>
|
||
|
||
<p>
|
||
処理が成功すれば <code>EB_SUCCESS</code> を返し、失敗すれば
|
||
<var>text_length</var> の指す領域に 0 を書き込んで原因を示すエラーコード
|
||
を返します。
|
||
</p>
|
||
|
||
<p>
|
||
あらかじめ、<var>book</var> 内のいずれかの副本が選択されていなくては
|
||
なりません。
|
||
<var>book</var> が副本を選択していなければ、<code>EB_ERR_NO_CUR_SUB</code>
|
||
を返します。
|
||
</p>
|
||
|
||
<p>
|
||
また、この関数を呼び出すには、あらかじめ <code>eb_seek_text()</code> の
|
||
呼び出しを成功させ、テキストデータのアクセス位置がセットされた状態にして
|
||
おかなくてはなりません。
|
||
シークをせずに呼び出すと、<code>EB_ERR_NO_PREV_SEEK</code> を返します。
|
||
</p>
|
||
|
||
<p>
|
||
この関数は、繰り返し呼び出すことで、前回読み込んだテキストデータの続き
|
||
を読み込むことができます。
|
||
ただし、区切りコードの検出を行いませんので、ひたすら呼び出しを続けると、
|
||
テキストデータファイルの末尾まで行ってしまいます。
|
||
</p>
|
||
|
||
<p>
|
||
一度 <code>eb_read_rawtext()</code> を呼び出してテキストデータを読み込み
|
||
始めたら、繰り返し呼び出す際も、<code>eb_read_rawtext()</code> を
|
||
使わなければなりません。
|
||
途中から、<code>eb_read_text()</code> や <code>eb_read_heading()</code> に
|
||
切り替えると、
|
||
<code>EB_ERR_DIFF_CONTENT</code> エラーが返ります。
|
||
この制限は、再度 <code>eb_seek_text()</code> を呼び出すか、
|
||
<code>eb_set_subbook()</code> で副本を選択し直すまで続きます。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:is_text_stopped"><code>int eb_is_text_stopped (EB_Book *<var>book</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_is_text_stopped()</code> は、最後に読み込んだテキストデータ
|
||
が末尾に達したかどうかを判定します。
|
||
</p>
|
||
|
||
<p>
|
||
<var>book</var> が選択中の副本で、最後に <code>eb_read_text()</code>
|
||
または <code>eb_read_heading()</code> でテキストデータを読み込んだ際に、
|
||
区切りコードを検出したか、テキストデータ全体の一番後ろの位置に達して
|
||
読み込みを終えていれば、この関数は 1 を返します。
|
||
それ以外のときは、0 を返します。
|
||
</p>
|
||
|
||
<p>
|
||
<var>book</var> が副本を選択していない場合や、選択中の副本にテキストデータ
|
||
が存在しない場合も 0 が返ります。
|
||
</p>
|
||
|
||
<p>
|
||
<code>eb_read_text()</code> または <code>eb_read_heading()</code> で
|
||
テキストデータを読み込んでいない場合も、同様に 0 が返ります。
|
||
テキストデータを読み込んだ後であっても、テキストデータの読み込みに関する
|
||
状態記録をリセットする関数 (eb_read_text() の項を参照) を呼んでしまうと、
|
||
読み込んでいないと見なされますので、注意して下さい。
|
||
</p>
|
||
|
||
<p>
|
||
通常はこの関数を使わなくても、<code>eb_read_text()</code> や
|
||
<code>eb_read_heading()</code> が 0 を返したら、テキストデータの末尾に
|
||
達したとみなして差し支えないでしょう。
|
||
ただしその際は、引数 <code>text_max_length</code> の値を十分大きく取って
|
||
下さい。
|
||
</p>
|
||
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:write_text_byte1"><code>EB_Error_Code eb_write_text_byte1 (EB_Book *<var>book</var>, int <var>byte1</var>)</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:write_text_byte2"><code>EB_Error_Code eb_write_text_byte2 (EB_Book *<var>book</var>, int <var>byte1</var>, int <var>byte2</var>)</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:write_text_string"><code>EB_Error_Code eb_write_text_string (EB_Book *<var>book</var>, const char *<var>string</var>)</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:write_text"><code>EB_Error_Code eb_write_text (EB_Book *<var>book</var>, const char *<var>stream</var>, size_t <var>stream_length</var>)</code></a></h4>
|
||
|
||
<p>
|
||
これらの関数は、いずれもフック関数の中から、テキストデータを書き込む
|
||
ために用います。
|
||
書き込むデータの種類によって、使い分けて下さい。
|
||
</p>
|
||
|
||
<p>
|
||
<code>eb_write_text_byte1()</code> は、<var>byte1</var> で指定した
|
||
1 バイトの値を書き込みます。
|
||
<code>eb_write_text_byte2()</code> は、<var>byte1</var>, <var>byte2</var>
|
||
で指定した 2 バイトを書き込みます。
|
||
<code>eb_write_text_string()</code> は、<var>string</var> で指定した
|
||
文字列を書き込みます。
|
||
<code>eb_write_text()</code> は、<var>stream</var> から始まる長さ
|
||
<var>stream_length</var> バイトのバイト列を書き込みます。
|
||
</p>
|
||
|
||
<p>
|
||
どの関数も、成功すると <code>EB_SUCCESS</code> を返し、失敗すると原因を
|
||
示すエラーコードを返します。
|
||
</p>
|
||
|
||
<p>
|
||
最終的に、書き込んだテキストデータは、フック関数の呼び出し元である
|
||
<code>eb_read_text()</code>, <code>eb_read_heading()</code> から
|
||
アプリケーションプログラムに渡されます。
|
||
</p>
|
||
|
||
<p>
|
||
フック関数として呼び出されていないときに、これらの関数を呼び出した場合
|
||
の動作は未定義です。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:current_candidate"><code>const char *eb_current_candidate (EB_Book *<var>book</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_current_candidate()</code> は、アクセス中のテキストデータの
|
||
現在位置に書かれている、複合検索の候補となる語を返します。
|
||
</p>
|
||
|
||
<p>
|
||
返す文字列の長さは、最長で <code>EB_MAX_WORD_LENGTH</code> バイトになります。
|
||
ただし、この長さにナル文字は含みません。
|
||
</p>
|
||
|
||
<p>
|
||
この関数は非常に特殊で、複合検索の候補となる語の終了を意味する
|
||
エスケープシーケンスへのフックである <code>EB_HOOK_END_CANDIDATE_LEAF</code>
|
||
および <code>EB_HOOK_END_CANDIDATE_GROUP</code> に対するフック関数の中で
|
||
のみ呼び出すことができます。
|
||
それ以外の場所で呼び出したときの動作は、未定義です。
|
||
</p>
|
||
|
||
<p>
|
||
この関数の呼び出し方ですが、フック関数に渡ってきた <code>EB_Book</code>
|
||
オブジェクト (へのポインタ) を、そのままこの関数に引数として渡して
|
||
やります。
|
||
</p>
|
||
|
||
<p>
|
||
<var>book</var> の文字コード
|
||
(<a href="#eb_book-data-types">「[CD-ROM 書籍と <code>EB_Book</code> オブジェクト] データ型の詳細」</a> を参照のこと)
|
||
が <code>EB_CHARCODE_ISO8859_1</code> なら、関数の返す文字列は ISO 8859-1
|
||
になり、それ以外の文字コードの場合は日本語 EUC になります。
|
||
関数の返す文字列は、他のフックによる加工処理の影響を受けません。
|
||
文字コードの変換を行う以外は、内部データをそのまま返します。
|
||
</p>
|
||
|
||
<p>
|
||
なお、この関数が返した文字列を参照できるのは、フック関数から戻るまでの
|
||
間だけですので、注意して下さい。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:forward_text"><code>EB_Error_Code eb_forward_text (EB_Book *<var>book</var>, EB_Appendix *<var>appendix</var>)</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:backward_text"><code>EB_Error_Code eb_backward_text (EB_Book *<var>book</var>, EB_Appendix *<var>appendix</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_forward_text()</code> と <code>eb_backward_text()</code> は、
|
||
<var>book</var> が選択している副本の本文のアクセス位置を前後に移動させ、
|
||
本文の区切りコードを単位とした頭出しを行います。
|
||
ちょうど、音楽 CD の曲の頭出しと同じです。
|
||
</p>
|
||
|
||
<p>
|
||
<code>eb_forward_text()</code> は本文の末尾方向に向かってアクセス位置を
|
||
進め、<code>eb_backward_text()</code> は先頭方向に向かってアクセス位置を
|
||
戻します。
|
||
</p>
|
||
|
||
<p>
|
||
<code>eb_forward_text()</code> の呼び出しでは、アクセス位置は必ず次の語の
|
||
説明の開始位置まで移動します。
|
||
それに対して <code>eb_backward_text()</code> の呼び出しでは、移動先が状態
|
||
によって異なります。
|
||
もし、現在のアクセス位置がその単語の説明の先頭にあるときは、
|
||
<code>eb_backward_text()</code> の呼び出しによって、一つ前の単語の説明の
|
||
先頭にアクセス位置が移動します。
|
||
アクセス位置が単語の説明の途中や末尾にあるときは、その単語の説明の
|
||
先頭に移動します。
|
||
</p>
|
||
|
||
<p>
|
||
この関数は、成功すると <code>EB_SUCCESS</code> を返し、失敗すると原因を示す
|
||
エラーコードを返します。
|
||
</p>
|
||
|
||
<p>
|
||
あらかじめ、<var>book</var> 内のいずれかの副本が選択されていなくては
|
||
なりません。
|
||
<var>book</var> が副本を選択していなければ、<code>EB_ERR_NO_CUR_SUB</code>
|
||
を返します。
|
||
</p>
|
||
|
||
<p>
|
||
加えて、これらの関数を呼び出すには、あらかじめ <code>eb_seek_text()</code>
|
||
か <code>eb_read_text()</code> を呼び出しが成功していないといけません。
|
||
(<code>eb_read_text()</code> の呼び出しを成功させるには、さらに前もって
|
||
<code>eb_seek_text()</code> の呼び出しを成功させることが条件となります。)
|
||
</p>
|
||
|
||
<p>
|
||
<code>eb_read_text()</code> ではなく、<code>eb_read_heading()</code> や
|
||
<code>eb_read_rawtext()</code> の呼び出しに成功した後でこの関数を
|
||
呼び出すと、<code>EB_ERR_DIFF_CONTENT</code> を返します。
|
||
また、前もって <code>eb_seek_text()</code> でシークせずにこの関数を
|
||
呼び出すと、<code>EB_ERR_NO_PREV_SEEK</code> を返します。
|
||
</p>
|
||
|
||
<p>
|
||
本文データの末尾や先頭に達してしまって、その方向にもう本文がないときは、
|
||
<code>EB_ERR_END_OF_CONTENT</code> を返します。
|
||
</p>
|
||
|
||
<p>
|
||
<var>appendix</var> が <code>NULL</code> ではなく、区切りコードの情報を
|
||
持った副本を選択中であれば、本文の区切りコードとしてその値を使用します。
|
||
それ以外の場合は、<code>eb_read_text()</code> と同じ方法で区切りコードの
|
||
自動判別を試みます。
|
||
</p>
|
||
|
||
<p>
|
||
アクセス位置上にあるのがメニューや著作権表示のように、本文以外の
|
||
テキストデータであっても構いません。
|
||
ただし、本文以外のテキストデータの内部には、頭出し位置がデータの
|
||
先頭位置にしかありませんので、この関数が役に立つ状況はほとんど
|
||
ありません。
|
||
</p>
|
||
|
||
<p>
|
||
(メニューでは、個々の階層のメニューデータが、それぞれ独立した
|
||
テキストデータになっているため、頭出しを行っても前後のメニューデータへは
|
||
移動できません。
|
||
複合検索の候補一覧も同様です。)
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:forward_heading"><code>EB_Error_Code eb_forward_heading (EB_Book *<var>book</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_forward_heading()</code> は、<var>book</var> が選択している
|
||
副本の見出しのアクセス位置を後に移動させ、見出しの区切りを単位とした頭出し
|
||
を行います。
|
||
</p>
|
||
|
||
<p>
|
||
本文の頭出しを行う関数 <code>eb_forward_text()</code> の見出し版です。
|
||
ただし、見出しで頭出しを行う機会は、クロス検索の本文取得に限られるため、
|
||
<code>eb_backward_heading()</code> という関数は用意していません。
|
||
</p>
|
||
|
||
<p>
|
||
この関数を呼ぶと、アクセス位置が次の見出しの開始位置まで移動します。
|
||
(クロス検索では、見出し領域の中に「見出し」と「本文」が交互に書かれて
|
||
いますが、データ構造上「本文」と「見出し」は区別が付きません。
|
||
アクセス位置がクロス検索の見出し領域内の場合、この関数を呼ぶと最も近い
|
||
「見出し」もしくは「本文」の開始位置まで移動します。)
|
||
</p>
|
||
|
||
<p>
|
||
<code>eb_read_heading()</code> ではなく、<code>eb_read_text()</code> や
|
||
<code>eb_read_rawtext()</code> の呼び出しに成功した後でこの関数を
|
||
呼び出すと、<code>EB_ERR_DIFF_CONTENT</code> を返します。
|
||
また、前もって <code>eb_seek_text()</code> でシークせずにこの関数を
|
||
呼び出すと、<code>EB_ERR_NO_PREV_SEEK</code> を返します。
|
||
</p>
|
||
|
||
<p>
|
||
この関数は、成功すると <code>EB_SUCCESS</code> を返し、失敗すると原因を示す
|
||
エラーコードを返します。
|
||
</p>
|
||
|
||
<p>
|
||
クロス検索以外の検索メソッドの見出しの格納位置に対して、この関数を
|
||
呼ぶことも可能ですが、そのような必要に迫られる機会はないでしょう。
|
||
</p>
|
||
|
||
<!-- ================================================================ -->
|
||
<h2><a name="local-character">外字</a></h2>
|
||
|
||
<p>
|
||
文字コードに収録されていない、私的に定義した文字のことを、俗に「外字」
|
||
と言います。
|
||
外字として定義した個々の文字を識別するために、文字コードに収録された
|
||
文字とは重複しない位置に、各文字の文字番号に割り振るのが普通です。
|
||
(割り当てる文字番号の詳細については、<a href="#character-code">「文字コード」</a> を参照のこと。)
|
||
</p>
|
||
|
||
<p>
|
||
市販の電子ブック、EPWING でも、ほとんどが外字を使っています。
|
||
外字の定義状況は書籍同士でバラバラで、まったく統一感はありません。
|
||
つまり、同じ文字番号を使っていても、定義されている外字は書籍によって
|
||
違います。
|
||
外字は副本毎に定義することが可能ですが、一つの CD-ROM 書籍内でも副本に
|
||
よって定義が異なることも珍しくありません。
|
||
副本によっては、数百から数千の外字を定義していることもあります。
|
||
</p>
|
||
|
||
<p>
|
||
CD-ROM 書籍では、定義した外字の字形データ (つまりフォント) を用意して
|
||
います。
|
||
フォントはビットマップデータであり、書籍によっては大きさの異なる数種類
|
||
のフォントを用意しています。
|
||
</p>
|
||
|
||
<p>
|
||
逆に言えば、外字に対して提供されるデータは、フォントだけです。
|
||
ある文字番号を割り当てられた外字が、漢字なのか、発音記号なのか、
|
||
そういった補助的な情報は用意されていません。
|
||
アプリケーションプログラムが外字をサポートするためには、外字のフォント
|
||
をそのまま表示する以外に方法はないでしょう。
|
||
</p>
|
||
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="narrow-and-wide-font">半角外字と全角外字</a></h3>
|
||
|
||
<p>
|
||
CD-ROM 書籍における外字には、「全角外字」「半角外字」の二種類があります。
|
||
全角外字は用意されているフォントの横と縦の長さがおよそ 1:1 になっており、
|
||
半角外字では 1:2 になっています。
|
||
</p>
|
||
|
||
<blockquote>
|
||
<pre>
|
||
全角外字 半角外字
|
||
（１６×１６） （８×１６）
|
||
□□□□□□□□□□□□□□□□ □□□□□□□□
|
||
□□□□□□□□□□□□□□□□ □□■■□■□□
|
||
□□□■■■■■■□□□■□□□ □□□□■□□□
|
||
□□□□□□□□■□■□■□□□ □□□■■□□□
|
||
□□□□■□□■□□■□■□□□ □□■□□■□□
|
||
□□□□■□□■■■■■■□□□ □■□□□■□□
|
||
□□■■■■■□□□■□■□□□ □□□■□■□□
|
||
□□□□□□□□□□■□■□□□ □□■□■■□□
|
||
□□□■□□□□□□□□■□□□ □■□□□■□□
|
||
□□□■□□□□□□□□■□□□ □■□□□■□□
|
||
□□□■■■■■■■■■■□□□ □■□□□■□□
|
||
□□□■□□□□□□□□■□□□ □■□□□■□□
|
||
□□□■□□□□□□□□■□□□ □■□□□■□□
|
||
□□□■■■■■■■■■■□□□ □■□□□■□□
|
||
□□□□□□□□□□□□□□□□ □□■■■□□□
|
||
□□□□□□□□□□□□□□□□ □□□□□□□□
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
テキストデータには、半角表示の開始と終了を表すエスケープシーケンスが
|
||
あり (<a href="#text-data-format">「テキストデータの内部形式」</a> を参照のこと)、
|
||
開始と終了の間に置かれたものは半角外字、それ以外のところなら全角外字に
|
||
なります。
|
||
</p>
|
||
|
||
<p>
|
||
文字番号は同じでも、字形が全角と半角ではまったく異なることもあります
|
||
ので、外字の文字番号だけから、全角と半角のどちらかを判断することは
|
||
できません。
|
||
かならず、前方に半角開始のエスケープシーケンスが出現していたかどうか
|
||
という情報に基づいて判断しないといけません。
|
||
</p>
|
||
|
||
<p>
|
||
ただし、全角か半角かの判定は EB ライブラリ側で行いますので、
|
||
アプリケーションプログラムが文脈の解析を行う必要はありません。
|
||
</p>
|
||
|
||
<p>
|
||
CD-ROM 書籍の副本には、半角外字あるいは全角外字のどちらか一方だけを
|
||
定義しているものもありますし、両方とも定義しているものもあります。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="font-size-and-font-code">外字の大きさと外字コード</a></h3>
|
||
|
||
<p>
|
||
各副本には、定義している外字のフォントがビットマップ形式で収録されて
|
||
います。
|
||
フォントの大きさは、縦のピクセル数を基準にすると 16, 24, 30, 48 の
|
||
4 種類があり、全角外字、半角外字それぞれのフォントの大きさ
|
||
(横のピクセル数×縦のピクセル数) は次の通りになります。
|
||
</p>
|
||
|
||
<table summary="フォントの大きさ">
|
||
<tr><td>縦のピクセル数 <td> 全角全角 <td> 半角外字</tr>
|
||
<tr><td>16 <td> 16x16 <td> 8x16</tr>
|
||
<tr><td>24 <td> 24x24 <td> 16x24</tr>
|
||
<tr><td>30 <td> 32x30 <td> 16x30</tr>
|
||
<tr><td>48 <td> 48x48 <td> 24x48</tr>
|
||
</table>
|
||
|
||
<p>
|
||
ただし、すべての副本でこれら 4 種類のフォントを用意しているわけでは
|
||
ありません。
|
||
縦が 16 ピクセルのものは必ず用意されていますが、それ以外はないことも
|
||
珍しくありません。
|
||
(外字がまったく定義されていなければ、16 ピクセルのフォントも用意され
|
||
ません。)
|
||
</p>
|
||
|
||
<p>
|
||
EB ライブラリでは、このように縦方向のピクセル数、つまり
|
||
<dfn>フォントの高さ (font height)</dfn> を基準に、外字フォントの大きさを
|
||
区別しています。
|
||
そして、それぞれのフォントの高さ (16, 24, 30, 48) に対して、
|
||
<dfn>外字コード (font code)</dfn> というものを割り当てています。
|
||
フォントの高さを指定する際は、必ずこの外字コードを使います。
|
||
</p>
|
||
|
||
<table summary="フォントの高さと外字コードの対応表">
|
||
<tr><td>縦のピクセル数 <td> 外字コード</tr>
|
||
<tr><td>16 <td> <code>EB_FONT_16</code></tr>
|
||
<tr><td>24 <td> <code>EB_FONT_24</code></tr>
|
||
<tr><td>30 <td> <code>EB_FONT_30</code></tr>
|
||
<tr><td>48 <td> <code>EB_FONT_48</code></tr>
|
||
</table>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="current-font-height">選択中の外字フォントの高さ</a></h3>
|
||
|
||
<p>
|
||
<code>EB_Book</code> オブジェクトで選択中の副本が用意している外字フォント
|
||
の高さの中から一つ選んで、
|
||
<dfn>選択中の外字フォントの高さ (current font height)</dfn> として指定する
|
||
ことができます。
|
||
EB ライブラリで外字のフォントデータ (ビットマップデータ) を取り出すには、
|
||
外字フォントの高さをあらかじめ選択しておく必要があります。
|
||
</p>
|
||
|
||
<p>
|
||
選択するには、関数 <code>eb_set_font()</code> を使います。
|
||
以下のプログラムは、高さ 24 ピクセルのフォントを選択する場合の例です。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
/* <code>book</code> が <code>EB_Book</code> のオブジェクトで、すでに
|
||
* 書籍に結び付けられ、副本を選択中だと仮定しています。*/
|
||
if (eb_set_font(&book, EB_FONT_24) != EB_SUCCESS) {
|
||
printf("eb_set_font_() failed\n");
|
||
return;
|
||
}
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
このプログラムでは、高さ 24 ピクセルのフォントを選択中の副本が用意して
|
||
いるものと仮定していますが、実際には用意していない副本も珍しくありません。
|
||
もし、副本が高さ 24 ピクセルのフォントを用意していなければ、
|
||
<code>eb_set_font()</code> は <code>EB_ERR_NO_SUCH_FONT</code> を返します。
|
||
</p>
|
||
|
||
<p>
|
||
しかし、外字を選択する前に、前もってその副本が用意しているフォントを
|
||
知りたいときもあります。
|
||
これには、2 通りの方法があります。
|
||
</p>
|
||
|
||
<p>
|
||
まず 1 つ目は、選択中の副本が用意しているフォントの高さの一覧を
|
||
<code>eb_font_list()</code> で取得する方法です。
|
||
これは、副本コードの一覧を取得する <code>eb_subbook_list()</code> と
|
||
使い方が良く似ています。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
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");
|
||
}
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
2 つ目は、<code>eb_have_font()</code> を使うやり方です。
|
||
この関数は、特定の高さのフォントを、選択中の副本が用意しているかどうか
|
||
調べることができます。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
if (eb_have_font(&book, EB_FONT_24)) {
|
||
printf("this subbook has EB_FONT_24\n");
|
||
}
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
また、選択中の副本が半角外字、全角外字を定義しているかどうかは、それぞれ
|
||
<code>eb_have_narrow_font()</code>, <code>eb_have_wide_font()</code>
|
||
を使って調べることができます。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
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");
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
なお、あらかじめ副本を選択しておかないと、外字の高さは選択できないので
|
||
注意して下さい。
|
||
<code>eb_set_subbook()</code> で選択中の副本を切り替えると、外字フォント
|
||
の高さは常に未選択の状態に戻ります。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="get-font">外字フォントの取り出し</a></h3>
|
||
|
||
<p>
|
||
外字の高さを選択した状態であれば、外字のフォントデータ
|
||
(ビットマップデータ) を取り出すことができます。
|
||
</p>
|
||
|
||
<p>
|
||
フォントデータを取り出す関数は、
|
||
全角外字なら <code>eb_wide_font_character_bitmap()</code>、
|
||
半角外字なら <code>eb_narrow_font_character_bitmap()</code> です。
|
||
</p>
|
||
|
||
<p>
|
||
全角外字 <samp>0xa121</samp> のフォントデータを取り出すプログラムは、
|
||
次のようになります。
|
||
半角外字の場合は、呼び出す関数名が変わるだけです。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
/* <code>book</code> が <code>EB_Book</code> のオブジェクトで、すでに
|
||
* 書籍に結び付けられ、副本と外字の高さを選択中だと仮定しています。*/
|
||
char bitmap[EB_SIZE_WIDE_FONT_48];
|
||
|
||
if (eb_wide_font_character_bitmap(book, 0xa121, bitmap)
|
||
!= EB_SUCCESS) {
|
||
return;
|
||
}
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
ここでは、<code>bitmap</code> にフォントデータを格納しています。
|
||
<code>bitmap</code> の領域として <code>EB_SIZE_WIDE_FONT_48</code>
|
||
バイトを確保していますが、これは高さ 48 ピクセルの外字データを格納する
|
||
ために必要なサイズを表します。
|
||
</p>
|
||
|
||
<p>
|
||
フォントデータのサイズは、外字の高さに応じて一定です。
|
||
高さ 48 ピクセルは外字の中でも最大のサイズなので、このサイズの領域を
|
||
用意すれば、どの高さの外字でも格納できます。
|
||
</p>
|
||
|
||
<p>
|
||
外字データは、ビットマップ形式のデータになっています。
|
||
背景色をビット値 0, 前景色をビット値 1 として、各ピクセルの値を並べて
|
||
あります。
|
||
並び方ですが、左上からまずは右に向かってピクセルを拾っていき、左端まで
|
||
来たら一つ下の段に降りて、また右方向にピクセルを拾います。
|
||
以下、一番下の段までこれを繰り返します。
|
||
</p>
|
||
|
||
<p>
|
||
ただし、バイト内では、128, 64, 32, ...1 の桁の順にビット値を格納して
|
||
います。
|
||
つまり、128 の桁は一番左のピクセル、1 の桁は一番右のピクセルに対応
|
||
します。
|
||
</p>
|
||
|
||
<p>
|
||
以下に、16x16 の全角外字のビットマップの例と、そのバイト列を記します。
|
||
背景色が□、前景色が■です。
|
||
</p>
|
||
|
||
<blockquote>
|
||
<pre>
|
||
□□□□□□□□□□□□□□□□ 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,
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="convert-font">外字フォントの変換</a></h3>
|
||
|
||
<p>
|
||
EB ライブラリには、外字のビットマップデータを XBM, XPM, GIF, BMP, PNG
|
||
の各画像形式に変換する関数が用意されています。
|
||
変換を行う関数は、次の 5 つです。
|
||
</p>
|
||
|
||
<table summary="外字のビットマップデータの変換関数">
|
||
<tr><td><code>eb_bitmap_to_xbm()</code> <td> XBM への変換</tr>
|
||
<tr><td><code>eb_bitmap_to_xpm()</code> <td> XPM への変換</tr>
|
||
<tr><td><code>eb_bitmap_to_gif()</code> <td> GIF への変換</tr>
|
||
<tr><td><code>eb_bitmap_to_bmp()</code> <td> BMP への変換</tr>
|
||
<tr><td><code>eb_bitmap_to_png()</code> <td> PNG への変換</tr>
|
||
</table>
|
||
|
||
<p>
|
||
どの関数も呼び出し方は同じですが、ここでは XBM への変換のプログラム例
|
||
を示します。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
/* <code>bitmap</code> に高さ 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;
|
||
}
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
XPM, GIF, PNG への変換では、前景色は黒、背景色は透明になります。
|
||
BMP への変換では、前景色は黒、背景色は白になります。
|
||
XBM はモノクロ図版用のデータ形式なので、色の設定はありません。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="local-character-in-text">テキスト中の外字</a></h3>
|
||
|
||
<p>
|
||
外字はテキストデータ (本文、メニューなど) の中で使われています。
|
||
</p>
|
||
|
||
<p>
|
||
アプリケーションプログラムが、テキストデータ中に出現する外字を識別して
|
||
処理を行うには、外字に対するフックを設定して、フック関数の中で処理する
|
||
ことになります。
|
||
</p>
|
||
|
||
<p>
|
||
外字に対するフックは、全角外字に対する <code>EB_HOOK_WIDE_FONT</code> と
|
||
半角外字に対する <code>EB_HOOK_NARROW_FONT</code> の二種類があります。
|
||
いずれも、外字が一字出現する度に、設定したフック関数を呼び出します。
|
||
</p>
|
||
|
||
<p>
|
||
フックの扱い方については、<a href="#hook-code-list">「フックコードの一覧」</a> を参照のこと。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="font-data-types">データ型の詳細</a></h3>
|
||
|
||
<p>
|
||
この節で説明しているデータ型を使うには、次のようにヘッダファイルを
|
||
読み込んで下さい。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
#include <eb/eb.h>
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="type:Font_Code"><code>EB_Font_Code</code> 型</a></h4>
|
||
|
||
<p>
|
||
外字コードは、外字の高さ (ピクセル数) を表します。
|
||
現在のところ、定義されている高さは次の通りです。
|
||
</p>
|
||
|
||
<ul>
|
||
<li><code>EB_FONT_16</code>
|
||
<li><code>EB_FONT_24</code>
|
||
<li><code>EB_FONT_30</code>
|
||
<li><code>EB_FONT_48</code>
|
||
<li><code>EB_FONT_INVALID</code>
|
||
</ul>
|
||
|
||
<p>
|
||
外字コードの実体は整数値ですが、<code>EB_FONT_16</code> の値は 16 では
|
||
ありません。
|
||
他も同様ですので、注意して下さい。
|
||
</p>
|
||
|
||
<p>
|
||
<code>EB_FONT_INVALID</code> は特別な外字コードで、不正な外字コード値を
|
||
表すために用います。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="font-constants">定数の詳細</a></h3>
|
||
|
||
<p>
|
||
この節で説明している定数を使うには、次のようにヘッダファイルを
|
||
読み込んで下さい。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
#include <eb/font.h>
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:WIDTH_NARROW_FONT_16">定数 <code>EB_WIDTH_NARROW_FONT_16</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:WIDTH_NARROW_FONT_24">定数 <code>EB_WIDTH_NARROW_FONT_24</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:WIDTH_NARROW_FONT_30">定数 <code>EB_WIDTH_NARROW_FONT_30</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:WIDTH_NARROW_FONT_48">定数 <code>EB_WIDTH_NARROW_FONT_48</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:WIDTH_WIDE_FONT_16">定数 <code>EB_WIDTH_WIDE_FONT_16</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:WIDTH_WIDE_FONT_24">定数 <code>EB_WIDTH_WIDE_FONT_24</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:WIDTH_WIDE_FONT_30">定数 <code>EB_WIDTH_WIDE_FONT_30</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:WIDTH_WIDE_FONT_48">定数 <code>EB_WIDTH_WIDE_FONT_48</code></a></h4>
|
||
|
||
<p>
|
||
これらの定数は、半角、全角およびそれぞれの高さ (外字コード) の外字一個
|
||
分の幅 (横方向のピクセル数) を <code>int</code> 型で表しています。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HEIGHT_NARROW_FONT_16">定数 <code>EB_HEIGHT_NARROW_FONT_16</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HEIGHT_NARROW_FONT_24">定数 <code>EB_HEIGHT_NARROW_FONT_24</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HEIGHT_NARROW_FONT_30">定数 <code>EB_HEIGHT_NARROW_FONT_30</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HEIGHT_NARROW_FONT_48">定数 <code>EB_HEIGHT_NARROW_FONT_48</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HEIGHT_WIDE_FONT_16">定数 <code>EB_HEIGHT_WIDE_FONT_16</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HEIGHT_WIDE_FONT_24">定数 <code>EB_HEIGHT_WIDE_FONT_24</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HEIGHT_WIDE_FONT_30">定数 <code>EB_HEIGHT_WIDE_FONT_30</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:HEIGHT_WIDE_FONT_48">定数 <code>EB_HEIGHT_WIDE_FONT_48</code></a></h4>
|
||
|
||
<p>
|
||
これらの定数は、半角、全角およびそれぞれの高さ (外字コード) の外字一個分
|
||
の縦方向のピクセル数を <code>int</code> 型で表しています。
|
||
</p>
|
||
|
||
<p>
|
||
<code>EB_HEIGHT_NARROW_FONT_16</code> および
|
||
<code>EB_HEIGHT_WIDE_FONT_16</code> の実際の値は 16 です。
|
||
(外字コード <code>EB_FONT_16</code> の実際の値は 16 ではありませんので、
|
||
注意して下さい。)
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_NARROW_FONT_16">定数 <code>EB_SIZE_NARROW_FONT_16</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_NARROW_FONT_24">定数 <code>EB_SIZE_NARROW_FONT_24</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_NARROW_FONT_30">定数 <code>EB_SIZE_NARROW_FONT_30</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_NARROW_FONT_48">定数 <code>EB_SIZE_NARROW_FONT_48</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_WIDE_FONT_16">定数 <code>EB_SIZE_WIDE_FONT_16</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_WIDE_FONT_24">定数 <code>EB_SIZE_WIDE_FONT_24</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_WIDE_FONT_30">定数 <code>EB_SIZE_WIDE_FONT_30</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_WIDE_FONT_48">定数 <code>EB_SIZE_WIDE_FONT_48</code></a></h4>
|
||
|
||
<p>
|
||
これらの定数は、半角、全角およびそれぞれの高さ (外字コード) の外字一個分
|
||
のビットマップデータを格納するのに必要な領域の大きさを表しています。
|
||
値は <code>int</code> 型で、単位はバイトです。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_NARROW_FONT_16_XBM">定数 <code>EB_SIZE_NARROW_FONT_16_XBM</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_NARROW_FONT_24_XBM">定数 <code>EB_SIZE_NARROW_FONT_24_XBM</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_NARROW_FONT_30_XBM">定数 <code>EB_SIZE_NARROW_FONT_30_XBM</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_NARROW_FONT_48_XBM">定数 <code>EB_SIZE_NARROW_FONT_48_XBM</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_WIDE_FONT_16_XBM">定数 <code>EB_SIZE_WIDE_FONT_16_XBM</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_WIDE_FONT_24_XBM">定数 <code>EB_SIZE_WIDE_FONT_24_XBM</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_WIDE_FONT_30_XBM">定数 <code>EB_SIZE_WIDE_FONT_30_XBM</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_WIDE_FONT_48_XBM">定数 <code>EB_SIZE_WIDE_FONT_48_XBM</code></a></h4>
|
||
|
||
<p>
|
||
これらの定数は、半角、全角およびそれぞれの高さ (外字コード) の外字一個分
|
||
のビットマップデータを <code>eb_bitmap_to_xbm()</code> を用いて XBM 形式
|
||
に変換する際に、変換後の XBM 形式のデータの大きさを表しています。
|
||
値は <code>int</code> 型で、単位はバイトです。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_NARROW_FONT_16_XPM">定数 <code>EB_SIZE_NARROW_FONT_16_XPM</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_NARROW_FONT_24_XPM">定数 <code>EB_SIZE_NARROW_FONT_24_XPM</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_NARROW_FONT_30_XPM">定数 <code>EB_SIZE_NARROW_FONT_30_XPM</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_NARROW_FONT_48_XPM">定数 <code>EB_SIZE_NARROW_FONT_48_XPM</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_WIDE_FONT_16_XPM">定数 <code>EB_SIZE_WIDE_FONT_16_XPM</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_WIDE_FONT_24_XPM">定数 <code>EB_SIZE_WIDE_FONT_24_XPM</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_WIDE_FONT_30_XPM">定数 <code>EB_SIZE_WIDE_FONT_30_XPM</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_WIDE_FONT_48_XPM">定数 <code>EB_SIZE_WIDE_FONT_48_XPM</code></a></h4>
|
||
|
||
<p>
|
||
これらの定数は、半角、全角およびそれぞれの高さ (外字コード) の外字一個分
|
||
のビットマップデータを <code>eb_bitmap_to_xpm()</code> を用いて XPM 形式
|
||
に変換する際に、変換後の XPM 形式のデータの大きさを表しています。
|
||
値は <code>int</code> 型で、単位はバイトです。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_NARROW_FONT_16_GIF">定数 <code>EB_SIZE_NARROW_FONT_16_GIF</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_NARROW_FONT_24_GIF">定数 <code>EB_SIZE_NARROW_FONT_24_GIF</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_NARROW_FONT_30_GIF">定数 <code>EB_SIZE_NARROW_FONT_30_GIF</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_NARROW_FONT_48_GIF">定数 <code>EB_SIZE_NARROW_FONT_48_GIF</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_WIDE_FONT_16_GIF">定数 <code>EB_SIZE_WIDE_FONT_16_GIF</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_WIDE_FONT_24_GIF">定数 <code>EB_SIZE_WIDE_FONT_24_GIF</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_WIDE_FONT_30_GIF">定数 <code>EB_SIZE_WIDE_FONT_30_GIF</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_WIDE_FONT_48_GIF">定数 <code>EB_SIZE_WIDE_FONT_48_GIF</code></a></h4>
|
||
|
||
<p>
|
||
これらの定数は、半角、全角およびそれぞれの高さ (外字コード) の外字一個分
|
||
のビットマップデータを <code>eb_bitmap_to_gif()</code> を用いて GIF 形式
|
||
に変換する際に、変換後の GIF 形式のデータの大きさを表しています。
|
||
値は <code>int</code> 型で、単位はバイトです。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_NARROW_FONT_16_BMP">定数 <code>EB_SIZE_NARROW_FONT_16_BMP</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_NARROW_FONT_24_BMP">定数 <code>EB_SIZE_NARROW_FONT_24_BMP</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_NARROW_FONT_30_BMP">定数 <code>EB_SIZE_NARROW_FONT_30_BMP</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_NARROW_FONT_48_BMP">定数 <code>EB_SIZE_NARROW_FONT_48_BMP</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_WIDE_FONT_16_BMP">定数 <code>EB_SIZE_WIDE_FONT_16_BMP</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_WIDE_FONT_24_BMP">定数 <code>EB_SIZE_WIDE_FONT_24_BMP</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_WIDE_FONT_30_BMP">定数 <code>EB_SIZE_WIDE_FONT_30_BMP</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_WIDE_FONT_48_BMP">定数 <code>EB_SIZE_WIDE_FONT_48_BMP</code></a></h4>
|
||
|
||
<p>
|
||
これらの定数は、半角、全角およびそれぞれの高さ (外字コード) の外字一個分
|
||
のビットマップデータを <code>eb_bitmap_to_bmp()</code> を用いて BMP 形式
|
||
に変換する際に、変換後の BMP 形式のデータの大きさを表しています。
|
||
値は <code>int</code> 型で、単位はバイトです。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_NARROW_FONT_16_PNG">定数 <code>EB_SIZE_NARROW_FONT_16_PNG</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_NARROW_FONT_24_PNG">定数 <code>EB_SIZE_NARROW_FONT_24_PNG</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_NARROW_FONT_30_PNG">定数 <code>EB_SIZE_NARROW_FONT_30_PNG</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_NARROW_FONT_48_PNG">定数 <code>EB_SIZE_NARROW_FONT_48_PNG</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_WIDE_FONT_16_PNG">定数 <code>EB_SIZE_WIDE_FONT_16_PNG</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_WIDE_FONT_24_PNG">定数 <code>EB_SIZE_WIDE_FONT_24_PNG</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_WIDE_FONT_30_PNG">定数 <code>EB_SIZE_WIDE_FONT_30_PNG</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="const:SIZE_WIDE_FONT_48_PNG">定数 <code>EB_SIZE_WIDE_FONT_48_PNG</code></a></h4>
|
||
|
||
<p>
|
||
これらの定数は、半角、全角およびそれぞれの高さ (外字コード) の外字一個分
|
||
のビットマップデータを <code>eb_bitmap_to_png()</code> を用いて PNG 形式
|
||
に変換する際に、変換後の PNG 形式のデータの大きさを表しています。
|
||
値は <code>int</code> 型で、単位はバイトです。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="font-functions">関数の詳細</a></h3>
|
||
|
||
<p>
|
||
この節で説明している関数を使うには、次のようにヘッダファイルを読み込んで
|
||
下さい。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
#include <eb/font.h>
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:font"><code>EB_Error_Code eb_font (EB_Book *<var>book</var>, EB_Font_Code *<var>font_code</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_font()</code> は、選択している副本において、選択中の
|
||
外字フォントの高さを表す外字コードを <var>font_code</var> の指す領域に
|
||
書き込みます。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると関数は <code>EB_SUCCESS</code> を返します。
|
||
失敗すると <var>font_code</var> の指す領域に <code>EB_FONT_INVALID</code>
|
||
を書き込み、原因を示すエラーコードを返します。
|
||
</p>
|
||
|
||
<p>
|
||
あらかじめ、外字フォントの高さが選択されていなければなりません。
|
||
外字が選択されていなければ、<code>EB_ERR_NO_CUR_FONT</code> を返します。
|
||
副本そのものを選択していない場合も、同様です。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:set_font"><code>EB_Error_Code eb_set_font (EB_Book *<var>book</var>, EB_Font_Code <var>font_code</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_set_font()</code> は、選択中の副本における外字フォントの
|
||
高さをセットします。
|
||
セットする外字フォントの「高さ」は、対応する外字コードを引数
|
||
<var>font_code</var> で指定します。
|
||
</p>
|
||
|
||
<p>
|
||
この関数は、成功すると <code>EB_SUCCESS</code> を返し、指定した「高さ」が
|
||
「選択中の外字フォントの高さ」となります。
|
||
すでに外字フォントの高さを選択していた場合は、いったん未選択の状態に
|
||
してからあらためて <var>font_code</var> を選択します。
|
||
</p>
|
||
|
||
<p>
|
||
失敗すると原因を示すエラーコードを返し、外字フォントの高さは未選択の
|
||
状態になります。
|
||
</p>
|
||
|
||
<p>
|
||
あらかじめ、<var>book</var> 内のいずれかの副本が選択されていなくては
|
||
なりません。
|
||
<var>book</var> が副本を選択していなければ、<code>EB_ERR_NO_CUR_SUB</code>
|
||
を返します。
|
||
また、その副本が持っていない外字フォントの高さが指定されると、
|
||
<code>EB_ERR_NO_SUCH_FONT</code> を返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:unset_font"><code>void eb_unset_font (EB_Book *<var>book</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_unset_font()</code> は、選択中の外字フォントの高さを未選択
|
||
の状態に戻します。
|
||
<var>book</var> が書籍に結び付いていない場合や副本が選択されていない場合、
|
||
もしくは外字フォントの高さが選択されていない場合は何もしません。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:font_list"><code>EB_Error_Code eb_font_list (EB_Book *<var>book</var>, EB_Font_Code *<var>font_list</var>, int *<var>font_count</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_font_list()</code> は、選択中の副本が定義している外字の
|
||
高さの一覧を <code>EB_Font_Code</code> 型の配列にして、<var>font_list</var>
|
||
の指す領域に書き込みます。
|
||
</p>
|
||
|
||
<p>
|
||
配列は、最大で <code>EB_MAX_FONTS</code> 個の要素を持ちます。
|
||
加えて、書籍が収録している副本の個数を <var>font_count</var> の指す領域に
|
||
書き込みます。
|
||
(現在のバージョンでは 、<code>EB_MAX_FONTS</code> の値は 4 になっています。
|
||
高さ 16, 24, 30, 48 ピクセルの 4 種類です。)
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、関数は <code>EB_SUCCESS</code> を返します。
|
||
失敗すると、<var>font_count</var> の指す領域に 0 を書き込み、原因を示す
|
||
エラーコードを返します。
|
||
</p>
|
||
|
||
<p>
|
||
あらかじめ、<var>book</var> 内のいずれかの副本が選択されていなくては
|
||
なりません。
|
||
<var>book</var> が副本を選択していなければ、<code>EB_ERR_NO_CUR_SUB</code>
|
||
を返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:have_font"><code>int eb_have_font (EB_Book *<var>book</var>, EB_Font_Code <var>font_code</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_font()</code> は、<var>font_code</var> で指定した高さの
|
||
外字フォントを、選択中の副本が持っているかどうかを調べます。
|
||
</p>
|
||
|
||
<p>
|
||
持っていれば 1 を返し、持っていなければ 0 を返します。
|
||
<var>book</var> が副本を選択していない場合も 0 を返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:font_height"><code>EB_Error_Code eb_font_height (EB_Book *<var>book</var>, int *<var>height</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_font_height()</code> は、<var>book</var> が選択中の
|
||
外字フォントの高さ (縦方向のピクセル数) を <var>height</var> の指す領域に
|
||
書き込みます。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、関数は <code>EB_SUCCESS</code> を返します。
|
||
失敗すると、<var>height</var> の指す領域に 0 を書き込み、原因を示す
|
||
エラーコードを返します。
|
||
</p>
|
||
|
||
<p>
|
||
あらかじめ、<var>book</var> は外字フォントの高さを選択していなくては
|
||
なりません。
|
||
選択していない場合は、<code>EB_ERR_NO_CUR_FONT</code> を返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:font_height2"><code>EB_Error_Code eb_font_height2 (EB_Font_Code <var>font_code</var>, int *<var>height</var>)</code></a></h4>
|
||
|
||
<p>
|
||
<code>eb_font_height()</code> と似ていますが、選択中の副本ではなく、引数
|
||
<var>font_height</var> で指定された外字コードの高さ (縦方向のピクセル数)
|
||
を書き込む点が異なります。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:have_narrow_font"><code>int eb_have_narrow_font (EB_Book *<var>book</var>)</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:have_wide_font"><code>int eb_have_wide_font (EB_Book *<var>book</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_have_narrow_font()</code> は、選択中の副本が半角外字を定義
|
||
しているかどうかを調べます。
|
||
同様に、関数 <code>eb_have_wide_font()</code> は、全角外字を定義しているか
|
||
どうかを調べます。
|
||
</p>
|
||
|
||
<p>
|
||
定義していれば 1 を、定義していなければ 0 を返します。
|
||
<var>book</var> が副本を選択していない場合も 0 を返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:narrow_font_width"><code>EB_Error_Code eb_narrow_font_width (EB_Book *<var>book</var>, int *<var>width</var>)</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:wide_font_width"><code>EB_Error_Code eb_wide_font_width (EB_Book *<var>book</var>, int *<var>width</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_narrow_font_width()</code> は、<var>book</var> が選択中の
|
||
外字フォントの高さにおける半角外字の幅 (横方向のピクセル数) を、
|
||
<var>height</var> の指す領域に書き込みます。
|
||
同様に、<code>eb_wide_font_width()</code> は全角外字の幅を書き込みます。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、関数は <code>EB_SUCCESS</code> を返します。
|
||
失敗すると、<var>width</var> の指す領域に 0 を書き込み、原因を示す
|
||
エラーコードを返します。
|
||
</p>
|
||
|
||
<p>
|
||
あらかじめ、<var>book</var> は外字の高さを選択していなくてはなりません。
|
||
選択していない場合は、<code>EB_ERR_NO_CUR_FONT</code> を返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:narrow_font_width2"><code>EB_Error_Code eb_narrow_font_width2 (EB_Font_Code <var>font_code</var>, int *<var>width</var>)</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:wide_font_width2"><code>EB_Error_Code eb_wide_font_width2 (EB_Font_Code <var>font_code</var>, int *<var>width</var>)</code></a></h4>
|
||
|
||
<p>
|
||
<code>eb_narrow_font_width()</code>, <code>eb_wide_font_width()</code> と
|
||
似ていますが、選択中の副本ではなく、引数<var>font_height</var> で指定された
|
||
外字コードの幅 (横方向のピクセル数) を書き込む点が異なります。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:narrow_font_size"><code>EB_Error_Code eb_narrow_font_size (EB_Book *<var>book</var>, size_t *<var>size</var>)</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:wide_font_size"><code>EB_Error_Code eb_wide_font_size (EB_Book *<var>book</var>, size_t *<var>size</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_narrow_font_size()</code> は、<var>book</var> が選択中の
|
||
外字フォントの高さにおける半角外字一個分のデータサイズ (バイト数) を、
|
||
<var>size</var> の指す領域に書き込みます。
|
||
同様に、<code>eb_wide_font_size()</code> は全角外字のサイズを書き込みます。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、関数は <code>EB_SUCCESS</code> を返します。
|
||
失敗すると、<var>size</var> の指す領域に 0 を書き込み、原因を示す
|
||
エラーコードを返します。
|
||
</p>
|
||
|
||
<p>
|
||
あらかじめ、<var>book</var> は外字フォントの高さを選択していなくては
|
||
なりません。
|
||
選択していない場合は、<code>EB_ERR_NO_CUR_FONT</code> を返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:narrow_font_size2"><code>EB_Error_Code eb_narrow_font_size2 (EB_Font_Code <var>font_code</var>, size_t *<var>size</var>)</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:wide_font_size2"><code>EB_Error_Code eb_wide_font_size2 (EB_Font_Code <var>font_code</var>, size_t *<var>size</var>)</code></a></h4>
|
||
|
||
<p>
|
||
<code>eb_narrow_font_size()</code>, <code>eb_wide_font_size()</code> と
|
||
似ていますが、選択中の副本ではなく、引数 <var>font_height</var> で指定
|
||
された外字コードの外字一個分のデータサイズを書き込む点が異なります。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:narrow_font_start"><code>EB_Error_Code eb_narrow_font_start (EB_Book *<var>book</var>, int *<var>start</var>)</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:wide_font_start"><code>EB_Error_Code eb_wide_font_start (EB_Book *<var>book</var>, int *<var>start</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_narrow_font_start()</code> は、<var>book</var> が選択中の
|
||
副本における半角外字の先頭の文字番号 (半角外字の文字番号の中で最小のもの)
|
||
を、<var>start</var> の指す領域に書き込みます。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、関数は <code>EB_SUCCESS</code> を返します。
|
||
失敗すると、原因を示すエラーコードを返します。
|
||
</p>
|
||
|
||
<p>
|
||
あらかじめ、<var>book</var> は副本を選択していなくてはなりません。
|
||
選択していない場合は、<code>EB_ERR_NO_CUR_SUB</code> を返します。
|
||
副本が半角外字を定義していない場合は、<code>EB_ERR_NO_CUR_FONT</code> を
|
||
返します。
|
||
</p>
|
||
|
||
<p>
|
||
関数 <code>eb_wide_font_start()</code> は、半角外字ではなく全角外字に
|
||
ついて調べるという点を除いて、<code>eb_narrow_font_start()</code> と同じ
|
||
です。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:narrow_font_end"><code>EB_Error_Code eb_narrow_font_end (EB_Book *<var>book</var>, int *<var>end</var>)</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:wide_font_end"><code>EB_Error_Code eb_wide_font_end (EB_Book *<var>book</var>, int *<var>end</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_narrow_font_end()</code> は、<var>book</var> が選択中の副本
|
||
における半角外字の最後の文字番号 (半角外字の文字番号の中で最大のもの) を、
|
||
<var>start</var> の指す領域に書き込みます。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、関数は <code>EB_SUCCESS</code> を返します。
|
||
失敗すると、原因を示すエラーコードを返します。
|
||
</p>
|
||
|
||
<p>
|
||
あらかじめ、<var>book</var> は副本を選択していなくてはなりません。
|
||
選択していない場合は、<code>EB_ERR_NO_CUR_SUB</code> を返します。
|
||
副本が半角外字を定義していない場合は、<code>EB_ERR_NO_CUR_FONT</code> を
|
||
返します。
|
||
</p>
|
||
|
||
<p>
|
||
関数 <code>eb_wide_font_end()</code> は、半角外字ではなく全角外字について
|
||
調べるという点を除いて、<code>eb_narrow_font_end()</code> と同じです。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:narrow_font_character_bitmap"><code>EB_Error_Code eb_narrow_font_character_bitmap (EB_Book *<var>book</var>, int <var>character_number</var>, char *<var>bitmap</var>)</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:wide_font_character_bitmap"><code>EB_Error_Code eb_wide_font_character_bitmap (EB_Book *<var>book</var>, int <var>character_number</var>, char *<var>bitmap</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_narrow_font_character_bitmap()</code> は、<var>book</var>
|
||
が選択中の副本で定義している、半角外字のビットマップデータを取り出します。
|
||
取り出す外字の文字番号を、<var>character_number</var> で指定します。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、関数はビットマップデータを <var>bitmap</var> の指す領域に
|
||
書き込み、<code>EB_SUCCESS</code> を返します。
|
||
失敗すると、<var>bitmap</var> の指す領域に空文字列を書き込み、原因を示す
|
||
エラーコードを返します。
|
||
</p>
|
||
|
||
<p>
|
||
あらかじめ、<var>book</var> は外字フォントの高さを選択していなくては
|
||
なりません。
|
||
選択していない場合は、<code>EB_ERR_NO_CUR_FONT</code> を返します。
|
||
副本が半角外字を定義していない場合も、やはり <code>EB_ERR_NO_CUR_FONT</code>
|
||
を返します。
|
||
文字番号 <var>character_number</var> が外字の定義範囲外にある場合は、
|
||
<code>EB_ERR_NO_SUCH_CHAR_BMP</code> を返します。
|
||
</p>
|
||
|
||
<p>
|
||
関数 <code>eb_wide_font_character_bitmap()</code> は、半角外字ではなく
|
||
全角外字のビットマップデータを取り出すという点を除いて、
|
||
<code>eb_narrow_font_character_bitmap()</code> と同じです。
|
||
</p>
|
||
|
||
<p>
|
||
ビットマップデータの形式については、
|
||
<a href="#get-font">「外字フォントの取り出し」</a> を参照のこと。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:forward_narrow_font_character"><code>EB_Error_Code eb_forward_narrow_font_character (EB_Book *<var>book</var>, int <var>n</var>, int *<var>character_number</var>)</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:forward_wide_font_character"><code>EB_Error_Code eb_forward_wide_font_character (EB_Book *<var>book</var>, int <var>n</var>, int *<var>character_number</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_forward_narrow_font_character()</code> は、<var>book</var>
|
||
が選択中の副本で定義されている半角外字の文字番号 <var>character_number</var>
|
||
の<var>n</var> 個後ろに位置する外字の文字番号を取得します。
|
||
</p>
|
||
|
||
<p>
|
||
まず、関数を呼び出す際に、<var>character_number</var> の指す領域に
|
||
文字番号を書き込んでおきます。
|
||
関数の処理が成功すると、戻ったときに <var>n</var> 個分だけ後方の文字番号
|
||
に書き換わっています。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、関数は <code>EB_SUCCESS</code> を返します。
|
||
失敗すると、原因を示すエラーコードを返します。
|
||
</p>
|
||
|
||
<p>
|
||
あらかじめ、<var>book</var> は副本を選択していなくてはなりません。
|
||
選択していない場合は、<code>EB_ERR_NO_CUR_SUB</code> を返します。
|
||
副本が半角外字を持っていない場合は、<code>EB_ERR_NO_CUR_FONT</code> を
|
||
返します。
|
||
</p>
|
||
|
||
<p>
|
||
<var>n</var> 個後ろにもう外字がない場合や、呼び出した際に
|
||
<var>character_number</var> の指す領域に書き込んであった文字番号が外字の
|
||
定義範囲外にある場合は <code>EB_ERR_NO_SUCH_CHAR_BMP</code> を返します。
|
||
</p>
|
||
|
||
<p>
|
||
<var>n</var> には負の数を指定することもできます。
|
||
この場合、次の呼び出しと等価になります。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
/* n < 0 とする */
|
||
eb_backward_narrow_font_character (book, -n, character_number);
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
関数 <code>eb_forward_wide_font_character()</code> は、半角外字ではなく
|
||
全角外字について操作するという点を除いて、
|
||
<code>eb_forward_narrow_font_character()</code> と同じです。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:backward_narrow_font_character"><code>EB_Error_Code eb_backward_narrow_font_character (EB_Book *<var>book</var>, int <var>n</var>, int *<var>character_number</var>)</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:backward_wide_font_character"><code>EB_Error_Code eb_backward_wide_font_character (EB_Book *<var>book</var>, int <var>n</var>, int *<var>character_number</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_backward_narrow_font_character()</code> は
|
||
<code>eb_forward_narrow_font_character()</code> とはちょうど逆の関数です。
|
||
<var>book</var> が選択中の副本で定義されている半角外字の文字番号
|
||
<var>character_number</var> の <var>n</var> 個前方に位置する外字の
|
||
文字番号を取得します。
|
||
</p>
|
||
|
||
<p>
|
||
同様に、<code>eb_backward_wide_font_character()</code> は、全角外字に
|
||
ついて <var>n</var> 個前方の外字の文字番号を取得する関数で、
|
||
<code>eb_forward_wide_font_character()</code> と反対の関数です。
|
||
</p>
|
||
|
||
<p>
|
||
<var>n</var> には負の数を指定することも可能で、それぞれ次の呼び出しと
|
||
等価になります。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
/* 半角外字の場合 (n < 0) */
|
||
eb_forward_narrow_font_character (book, -n, character_number);
|
||
|
||
/* 全角外字の場合 (n < 0) */
|
||
eb_forward_wide_font_character (book, -n, character_number);
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:narrow_font_xbm_size"><code>EB_Error_Code eb_narrow_font_xbm_size (EB_Font_Code <var>height</var>, size_t *<var>size</var>)</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:narrow_font_xpm_size"><code>EB_Error_Code eb_narrow_font_xpm_size (EB_Font_Code <var>height</var>, size_t *<var>size</var>)</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:narrow_font_gif_size"><code>EB_Error_Code eb_narrow_font_gif_size (EB_Font_Code <var>height</var>, size_t *<var>size</var>)</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:narrow_font_bmp_size"><code>EB_Error_Code eb_narrow_font_bmp_size (EB_Font_Code <var>height</var>, size_t *<var>size</var>)</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:narrow_font_png_size"><code>EB_Error_Code eb_narrow_font_png_size (EB_Font_Code <var>height</var>, size_t *<var>size</var>)</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:wide_font_xbm_size"><code>EB_Error_Code eb_wide_font_xbm_size (EB_Font_Code <var>height</var>, size_t *<var>size</var>)</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:wide_font_xpm_size"><code>EB_Error_Code eb_wide_font_xpm_size (EB_Font_Code <var>height</var>, size_t *<var>size</var>)</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:wide_font_gif_size"><code>EB_Error_Code eb_wide_font_gif_size (EB_Font_Code <var>height</var>, size_t *<var>size</var>)</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:wide_font_bmp_size"><code>EB_Error_Code eb_wide_font_bmp_size (EB_Font_Code <var>height</var>, size_t *<var>size</var>)</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:wide_font_png_size"><code>EB_Error_Code eb_wide_font_png_size (EB_Font_Code <var>height</var>, size_t *<var>size</var>)</code></a></h4>
|
||
|
||
<p>
|
||
最初の 5 つの関数
|
||
(<code>eb_narrow_font_xbm_size()</code> ～
|
||
<code>eb_narrow_font_png_size()</code>) は、外字コード <var>height</var>
|
||
の半角外字一個のビットマップを XBM, XPM, GIF, BMP, PNG 形式にそれぞれ変換
|
||
したときのデータサイズを <var>size</var> の指す領域に書き込みます。
|
||
</p>
|
||
|
||
<p>
|
||
同様に、後ろの 5 つの関数
|
||
(<code>eb_wide_font_xbm_size()</code> ～
|
||
<code>eb_wide_font_png_size()</code>) は、全角外字を変換したときの
|
||
データサイズを書き込みます。
|
||
</p>
|
||
|
||
<p>
|
||
いずれの関数も、成功すると <code>EB_SUCCESS</code> を返します。
|
||
失敗すると、<var>size</var> の指す領域に 0 を書き込み、原因を示す
|
||
エラーコードを返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:bitmap_to_xbm"><code>EB_Error_Code eb_bitmap_to_xbm (const char *<var>bitmap</var>, int <var>width</var>, int <var>height</var>, char *<var>image</var>, size_t *<var>image_length</var>)</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:bitmap_to_xpm"><code>EB_Error_Code eb_bitmap_to_xpm (const char *<var>bitmap</var>, int <var>width</var>, int <var>height</var>, char *<var>image</var>, size_t *<var>image_length</var>)</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:bitmap_to_gif"><code>EB_Error_Code eb_bitmap_to_gif (const char *<var>bitmap</var>, int <var>width</var>, int <var>height</var>, char *<var>image</var>, size_t *<var>image_length</var>)</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:bitmap_to_bmp"><code>EB_Error_Code eb_bitmap_to_bmp (const char *<var>bitmap</var>, int <var>width</var>, int <var>height</var>, char *<var>image</var>, size_t *<var>image_length</var>)</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:bitmap_to_png"><code>EB_Error_Code eb_bitmap_to_png (const char *<var>bitmap</var>, int <var>width</var>, int <var>height</var>, char *<var>image</var>, size_t *<var>image_length</var>)</code></a></h4>
|
||
|
||
<p>
|
||
これら 5 つの関数は、<code>eb_narrow_font_character()</code> または
|
||
<code>eb_wide_font_character()</code> で取り出した外字のビットマップを
|
||
XBM, XPM, GIF, BMP, PNG 形式にそれぞれ変換します。
|
||
</p>
|
||
|
||
<p>
|
||
ビットマップデータの指す領域を <var>bitmap</var> で指定し、ビットマップの
|
||
高さと幅を <var>width</var>, <var>height</var> で渡します。
|
||
</p>
|
||
|
||
<p>
|
||
関数の呼び出しから戻ると、<var>image</var> の指す領域に変換後のデータが
|
||
書き込まれ、<var>image_length</var> の指す領域に変換後のデータの大きさが
|
||
書き込まれます。
|
||
</p>
|
||
|
||
<p>
|
||
XPM, GIF, PNG への変換では、前景色は黒、背景色は透明になります。
|
||
BMP への変換では、前景色は黒、背景色は白になります。
|
||
XBM はモノクロ図版用のデータ形式なので、色の設定はありません。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="font-sample">サンプルプログラム</a></h3>
|
||
|
||
<!-- #include "eb-sample-font.html" -->
|
||
|
||
<!-- ================================================================ -->
|
||
<h2><a name="binary-data">バイナリデータ</a></h2>
|
||
|
||
<p>
|
||
<dfn>バイナリデータ (binary data)</dfn> とは、
|
||
図版や動画、音声といったマルチメディアデータのことを指します。
|
||
バイナリデータは、必ずテキストデータ
|
||
(<a href="#text-data">「テキストデータ」</a> を参照のこと)
|
||
から参照される形で利用されます。
|
||
</p>
|
||
|
||
<p>
|
||
今のところ EB ライブラリでは、全種類のバイナリデータを取り扱うことが
|
||
できるわけではありません。
|
||
電子ブックで扱えるのは、2 階調のモノクロ図版と、カラー図版 (JPEG) だけ
|
||
です。
|
||
EPWING では、モノクロ図版、カラー図版 (BMP および JPEG) に加えて、
|
||
WAVE (PCM) 音声、MPEG 動画を扱うことができます。
|
||
</p>
|
||
|
||
<p>
|
||
ただし、EB ライブラリが提供しているのは、こうしたバイナリデータを
|
||
CD-ROM 書籍から取得する機能だけです。
|
||
表示したり再生したりする機能は用意していませんので、注意して下さい。
|
||
</p>
|
||
|
||
<p>
|
||
アプリケーションは、英和辞書や国語辞書といった辞書だけを対象にするなら、
|
||
バイナリデータの表示や再生には対応しなくても支障はありません。
|
||
しかし一方では、図鑑や数式の表現にモノクロ図版を使っている数学辞典の
|
||
ように、対応しないと不便なものもあります。
|
||
バイナリデータの表示や再生の機能を実装するかどうかは、アプリケーション
|
||
の対象辞書をどの範囲までにするのかによって決めると良いでしょう。
|
||
</p>
|
||
|
||
<p>
|
||
以下、この章では種類別にバイナリデータの扱い方について説明します。
|
||
</p>
|
||
|
||
<p>
|
||
バイナリデータの種類毎にデータの取り出し方は微妙に異なりますが (これは
|
||
データの収録方法が微妙に異なっているからに他なりません)、おおよそ手順
|
||
は、次のようなものになります。
|
||
</p>
|
||
|
||
<ol>
|
||
<li>
|
||
テキストデータのフックを用いて、バイナリデータの参照情報を取得する。
|
||
|
||
<li>
|
||
<code>eb_binary_set_...()</code> 関数を呼び出して、指定した位置の
|
||
バイナリデータをこれから読み込む旨を EB ライブラリに伝える。
|
||
|
||
<li>
|
||
<code>eb_read_binary()</code> で実際にデータを読み込む。
|
||
</ol>
|
||
|
||
<p>
|
||
テキストデータと同様に、バイナリデータも副本に属するデータ
|
||
ですので、副本を選択していないと取得することはできません。
|
||
バイナリデータの読み込みには、テキストデータとは別の
|
||
ファイルディスクリプタが割り当てられます。
|
||
したがって、双方を交互に読み込んでも、動作には影響はありません。
|
||
</p>
|
||
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="monochrome-image">モノクロ図版</a></h3>
|
||
|
||
<p>
|
||
2 階調のモノクロ図版は、電子ブック、EPWING 双方に存在し、EB ライブラリ
|
||
ではどちらも扱うことができます。
|
||
(電子ブックに存在する 16 階調のモノクロ図版は、今のところ EB ライブラリ
|
||
では対応していません。)
|
||
</p>
|
||
|
||
<p>
|
||
モノクロ図版データの内部形式は外字と同じですが、EB ライブラリでは、
|
||
1 ピクセルに 1bit を割り当てた BMP 形式に変換してアプリケーションに
|
||
渡すようにしています。
|
||
したがって、アプリケーションからは、あたかも BMP の図版データが収録
|
||
されているようにみえます。
|
||
</p>
|
||
|
||
<p>
|
||
テキストデータ内からは、バイナリデータであるモノクロ図版を参照する形
|
||
をとります。
|
||
モノクロ図版を取り出すには、この参照情報が必要です。
|
||
参照情報の取得は、テキストデータ処理時に、モノクロ図版の開始と終了を
|
||
表すエスケープシーケンスへのフック <code>EB_HOOK_BEGIN_MONO_GRAPHIC</code>
|
||
と <code>EB_HOOK_END_MONO_GRAPHIC</code> を用いて行います。
|
||
</p>
|
||
|
||
<p>
|
||
フック <code>EB_HOOK_BEGIN_MONO_GRAPHIC</code> がフック関数に渡す引数
|
||
(<code>argv</code>) は 4 つあり、このうちの <code>argv[2]</code> と
|
||
<code>argv[3]</code> が図版の幅と高さ (ピクセル数) を意味します。
|
||
</p>
|
||
|
||
<p>
|
||
また、フック <code>EB_HOOK_END_MONO_GRAPHIC</code> がフック関数に渡す
|
||
引数は 3 つで、<code>argv[1]</code> と <code>argv[2]</code> が、
|
||
図版データのページ番号とオフセットになります。
|
||
</p>
|
||
|
||
<p>
|
||
モノクロ図版を取得するには、上記のフックから得た図版のページ番号と
|
||
オフセット、および幅と高さを記憶しておきます。
|
||
</p>
|
||
|
||
<p>
|
||
次に、<code>eb_set_binary_mono_graphic()</code> を呼び出して、これから
|
||
モノクロ図版のデータを取得することを EB ライブラリに伝えます。
|
||
<code>eb_set_binary_mono_graphic()</code> への引数には、
|
||
<code>EB_Book</code> オブジェクトと、先ほど得た図版へのページ番号、
|
||
オフセット、幅、高さを渡します。
|
||
<code>EB_Book</code> オブジェクトは、これから取り出そうとしている図版を
|
||
収録している副本をあらかじめ選択しておく必要があります。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
/* <code>eb_set_binary_mono_graphic()</code> の関数プロトタイプ */
|
||
EB_Error_Code
|
||
eb_set_binary_mono_graphic(EB_Book *book, EB_Position *position,
|
||
int width, int height);
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
電子ブックでは、フック関数に渡される幅と高さの値は 0 になっていますが、
|
||
そのまま <code>eb_set_binary_mono_graphic()</code> に渡します。
|
||
(EPWING では 0 を渡してはいけません。)
|
||
</p>
|
||
|
||
<p>
|
||
以上で図版データの取得準備ができたので、データを読み込みます。
|
||
これには、<code>eb_read_binary()</code> を使います。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
#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;
|
||
}
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
成功すると、読み込んだ図版データが <code>bitmap</code> に書き込まれ、
|
||
何バイト書き込んだのかが <code>bitmap_length</code> に書き込まれます。
|
||
書き込まれるバイト数は、最大で <code>MAX_LENGTH</code> バイトです。
|
||
</p>
|
||
|
||
<p>
|
||
必ずしも一回の <code>eb_read_binary()</code> の呼び出しで図版データを
|
||
終端まで読み込む必要はなく、関数を繰り返し呼び出せば、前回の続きを
|
||
読み込むことができます。
|
||
<code>eb_read_binary()</code> は、図版データの終端まで来るとそれ以上
|
||
データは読み込みませんので、<code>eb_read_binary()</code> が 0 を返した
|
||
時点で図版データが終端したことを認識できます。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="color-image">カラー図版</a></h3>
|
||
|
||
<p>
|
||
カラー図版は、電子ブックでは JPEG 形式、EPWING では JPEG と BMP (DIB)
|
||
形式のものが使用されています。
|
||
EB ライブラリはこれらをすべて扱うことができますが、電子ブックへの対応
|
||
は限定的なものになっています。(詳しくは後述します。)
|
||
</p>
|
||
|
||
<p>
|
||
カラー図版のデータを取り出すには、モノクロ図版と同様にテキストデータ
|
||
からカラー図版への参照情報をフックを通じて取得し、続いて実際に
|
||
カラー図版のデータを読み込むという手順になります。
|
||
</p>
|
||
|
||
<p>
|
||
<code>eb_set_binary_color_graphic()</code> を呼び出して、これから
|
||
アプリケーションがカラー図版のデータを取得しようとしていることを
|
||
EB ライブラリに伝えます。
|
||
<code>eb_set_binary_color_graphic()</code> への引数には、
|
||
<code>EB_Book</code> オブジェクトに加えて、カラー図版のページ番号と
|
||
オフセットを渡します。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
/* <code>eb_set_binary_color_graphic()</code> の関数プロトタイプ */
|
||
EB_Error_Code
|
||
eb_set_binary_color_graphic(EB_Book *book, EB_Position *position);
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
<code>EB_Book</code> オブジェクトは、これから取り出そうとしている図版を
|
||
収録している副本をあらかじめ選択しておきます。
|
||
|
||
カラー図版のページ番号とオフセットの情報は、カラー図版の開始と終了を表す
|
||
エスケープシーケンスへのフックから得ます。
|
||
フックは、インライン表示用と非インライン用の 2 種類があり、さらに
|
||
それぞれ開始フックが JPEG 用と BMP 用に分かれています。
|
||
</p>
|
||
|
||
<dl>
|
||
<dt><code>EB_HOOK_BEGIN_COLOR_BMP</code></dt>
|
||
<dt><code>EB_HOOK_BEGIN_COLOR_JPEG</code></dt>
|
||
<dd>
|
||
非インライン用 BMP, JPEG の開始フック
|
||
|
||
<dt><code>EB_HOOK_END_COLOR_GRAPHIC</code></dt>
|
||
<dd>
|
||
非インライン用カラー図版 (BMP, JPEG 共通) の終了フック
|
||
|
||
<dt><code>EB_HOOK_BEGIN_IN_COLOR_BMP</code></dt>
|
||
<dt><code>EB_HOOK_BEGIN_IN_COLOR_JPEG</code></dt>
|
||
<dd>
|
||
インライン用 BMP, JPEG の開始フック
|
||
|
||
<dt><code>EB_HOOK_END_IN_COLOR_GRAPHIC</code></dt>
|
||
<dd>
|
||
非インライン用カラー図版 (BMP, JPEG 共通) の終了フック
|
||
</dl>
|
||
|
||
<p>
|
||
非インライン用の終了フック <code>EB_HOOK_END_GRAPHIC</code> では、
|
||
フック関数に渡す引数の <code>argv[2]</code> と <code>argv[3]</code> が、
|
||
図版データのページ番号とオフセットになりますので、これを
|
||
<code>eb_set_binary_color_graphic()</code> に渡してやります。
|
||
同様に、インライン用の終了フック <code>EB_HOOK_END_IN_GRAPHIC</code>
|
||
では、<code>argv[2]</code> と <code>argv[3]</code> がページ番号と
|
||
オフセットですので、これを渡します。
|
||
</p>
|
||
|
||
<p>
|
||
後は、実際にカラー図版のデータを取り出します。
|
||
これには、モノクロ図版と同様に <code>eb_read_binary()</code> を用います。
|
||
使い方はまったく一緒ですので、詳しくは
|
||
<a href="#monochrome-image">「モノクロ図版」</a> を参照してください。
|
||
</p>
|
||
|
||
<p>
|
||
ただし、電子ブックのカラー図版については、データの終了位置が来ても
|
||
EB ライブラリは読み込みを止めないという制限事項があります。
|
||
これは、データの大きさに関する情報が記されていないためで、データの
|
||
終端位置は、アプリケーションが JPEG のデータをデコードして割り出すしか
|
||
ありません。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="clickable-color-image">参照先付きカラー図版</a></h3>
|
||
|
||
<p>
|
||
カラー図版には、画像内の特定の矩形領域に参照先の情報を付け加えたものが
|
||
あります。
|
||
HTML におけるクリッカブル・イメージ (clickable image) とほぼ同じで、その
|
||
矩形領域内にマウスポインタがある間にマウスをクリックすると、あらかじめ
|
||
決められたリンク先に画面が遷移するという仕掛けです。
|
||
リンク先となる矩形領域は、画像一つに対して複数個登録できます。
|
||
</p>
|
||
|
||
<blockquote>
|
||
<pre>
|
||
参照先付きカラー図版の例
|
||
┌────────────────────────┐
|
||
│┌ ─ ─ ─ ─ ┐ ┌ ─ ─ ─ ─ ┐│
|
||
│ │
|
||
││ 矩形領域１ │ │ 矩形領域２ ││
|
||
│ │
|
||
│└ ─ ─ ─ ─ ┘ └ ─ ─ ─ ─ ┘│
|
||
│ │
|
||
│┌ ─ ─ ─ ─ ┐ │
|
||
│ │
|
||
││ 矩形領域３ │ 図版 │
|
||
│ │
|
||
│└ ─ ─ ─ ─ ┘ │
|
||
└────────────────────────┘
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
参照先付きカラー図版の取り扱い方は、通常のカラー図版を拡張した形と
|
||
なります。通常のカラー図版の場合では、たとえば JPEG の非インライン
|
||
画像では、次のような順番でフックが呼び出されます。
|
||
</p>
|
||
|
||
<ol>
|
||
<li><code>EB_HOOK_BEGIN_COLOR_JPEG</code> (非インライン用 JPEG 開始)
|
||
<li><code>EB_HOOK_END_COLOR_GRAPHIC</code> (非インライン用 JPEG 終了)
|
||
</ol>
|
||
|
||
<p>
|
||
これに対して参照先付きのカラー図版では、この2つのフックの間に、矩形領域
|
||
情報に関するフックが挿入されます。
|
||
</p>
|
||
|
||
<ol>
|
||
<li><code>EB_HOOK_BEGIN_COLOR_JPEG</code> (非インライン用 JPEG 開始)
|
||
<li><code>EB_HOOK_BEGIN_CLICKABLE_AREA</code> (矩形領域1 開始)
|
||
<li><code>EB_HOOK_END_CLICKABLE_AREA</code> (矩形領域1 終了)
|
||
<li><code>EB_HOOK_BEGIN_CLICKABLE_AREA</code> (矩形領域2 開始)
|
||
<li><code>EB_HOOK_END_CLICKABLE_AREA</code> (矩形領域2 終了)<br>
|
||
以下、矩形領域3、矩形領域4 ... と矩形領域の個数分だけ続く。
|
||
<li><code>EB_HOOK_END_COLOR_GRAPHIC</code> (非インライン用 JPEG 終了)
|
||
</ol>
|
||
|
||
<p>
|
||
矩形領域に関する具体的な情報は、<code>EB_HOOK_BEGIN_CLICKABLE_AREA</code>
|
||
(開始フック) のほうで取得します。
|
||
フック関数に渡す引数の <code>argv[1]</code> と <code>argv[2]</code> が、
|
||
それぞれ矩形領域の開始 x, y 座標を表します。
|
||
カラー図版の左上の座標が (0, 0) です。
|
||
同様に、<code>argv[3]</code> と <code>argv[4]</code> が矩形領域の右方向
|
||
への幅と、下方向への高さを表します。
|
||
最後の <code>argv[5]</code> と <code>argv[6]</code> が参照先のページ番号
|
||
とオフセットとなります。
|
||
</p>
|
||
|
||
<p>
|
||
アプリケーションが参照先付きカラー図版に対応しない場合は、矩形領域の
|
||
開始情報と終了情報を無視することになります。
|
||
これにより、図版は通常の (参照先を持たない) カラー図版とまったく同じく
|
||
扱われます。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="wave-sound">WAVE (PCM) 音声</a></h3>
|
||
|
||
<p>
|
||
WAVE (PCM) 形式の音声データは EPWING にだけ存在します。
|
||
(代わりに電子ブックには CD-DA 形式の音声データがありますが、EB ライブラリ
|
||
では対応していません。)
|
||
</p>
|
||
|
||
<p>
|
||
WAVE 形式の音声データを取り出すには、まずテキストデータ中から WAVE 音声
|
||
の参照情報を得ます。
|
||
参照開始と終了を表すエスケープシーケンスへのフック
|
||
<code>EB_HOOK_BEGIN_WAVE</code> と <code>EB_HOOK_END_WAVE</code> が
|
||
それぞれありますので、これを用います。
|
||
</p>
|
||
|
||
<p>
|
||
フック <code>EB_HOOK_BEGIN_WAVE</code> がフック関数に渡す引数のうち、
|
||
<code>argv[2]</code> と <code>argv[3]</code> が音声データの開始位置の
|
||
ページ番号とオフセット、<code>argv[4]</code> と <code>argv[5]</code> が
|
||
終了位置のページ番号とオフセットとなります。
|
||
</p>
|
||
|
||
<p>
|
||
この開始位置と終了位置を関数 <code>eb_set_binary_wave()</code> に渡して、
|
||
その位置にある音声データをこれから取り出すことを EB ライブラリに伝えます。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
/* <code>eb_set_binary_wave()</code> の関数プロトタイプ */
|
||
EB_Error_Code
|
||
eb_set_binary_wave(EB_Book *book, EB_Position *start_position,
|
||
EB_Position *end_position);
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
そして後は、実際に音声データを取り出します。
|
||
これには、他のバイナリデータと同様に <code>eb_read_binary()</code> を
|
||
用います。
|
||
<code>eb_read_binary()</code> の使い方は、
|
||
<a href="#monochrome-image">「モノクロ図版」</a> を参照のこと を参照してください。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="mpeg-movie">MPEG1 動画</a></h3>
|
||
|
||
<p>
|
||
MPEG1 形式の動画データは EPWING にだけ存在します。
|
||
動画データは EPWING の CD-ROM の movie というディレクトリの下に、
|
||
動画毎に一個のファイルにした形で収められています。
|
||
</p>
|
||
|
||
<p>
|
||
テキストデータ中に存在する、MPEG データの参照開始と終了を表す
|
||
エスケープシーケンスへのフック <code>EB_HOOK_BEGIN_MPEG</code> と
|
||
<code>EB_HOOK_END_MPEG</code> を使用することで、参照先の MPEG の
|
||
ファイル名を取得できます。
|
||
</p>
|
||
|
||
<p>
|
||
具体的には、フック <code>EB_HOOK_BEGIN_MPEG</code> がフック関数に渡す
|
||
引数のうち、<code>argv[2]</code> ～ <code>argv[5]</code> が合わせて一つ
|
||
のファイル名を表すようになっています。
|
||
</p>
|
||
|
||
<p>
|
||
MPEG 動画のデータを得るには、このファイル名を
|
||
<code>eb_set_binary_mpeg()</code> に渡して、そのファイルの動画データを
|
||
これから取り出す旨を EB ライブラリに伝えます。
|
||
ファイル名は、次のようにして <code>argv + 2</code>
|
||
(<code>&argv[2]</code> でも同じ) を渡します。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
if (eb_set_binary_mpeg(&book, argv + 2) != EB_SUCCESS) {
|
||
fprintf(stderr, "an error occurs.\n");
|
||
return;
|
||
}
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
後は、実際に動画データを取り出します。
|
||
これには、やはり他のバイナリデータと同様に <code>eb_read_binary()</code>
|
||
を用います。
|
||
<code>eb_read_binary()</code> の使い方については、
|
||
<a href="#monochrome-image">「モノクロ図版」</a> を参照のこと を参照してください。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="binary-data-functions">関数の詳細</a></h3>
|
||
|
||
<p>
|
||
この節で説明している関数を使うには、次のようにヘッダファイルを読み込んで
|
||
下さい。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
#include <eb/binary.h>
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:set_binary_mono_graphic"><code>EB_Error_Code eb_set_binary_mono_graphic (EB_Book *<var>book</var>, const EB_Position *<var>position</var>, int <var>width</var>, <var>height</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_set_binary_mono_graphic()</code> は、モノクロ図版のデータを
|
||
これから取得しようとしていることを EB ライブラリに伝えます。
|
||
引数 <var>position</var> は図版の位置、<var>width</var>, <var>height</var>
|
||
には図版の幅と高さを渡します。
|
||
これらの情報は、図版の参照元であるテキストデータに記載されており、通常は
|
||
フック関数を通じて得るようにします。
|
||
ただし、電子ブックでは幅と高さの値の情報がテキストデータに記されていない
|
||
ため、0 を渡すことになります。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、関数は <code>EB_SUCCESS</code> を返します。
|
||
失敗すると、原因に応じたエラーコードを返します。
|
||
</p>
|
||
|
||
<p>
|
||
あらかじめ、図版を取り出そうとしている副本を選択しておかなければ
|
||
なりません。
|
||
<var>book</var> が副本を選択していなければ、<code>EB_ERR_NO_CUR_SUB</code>
|
||
を返します。
|
||
図版の位置、幅、高さの値が明らかにおかしいと EB ライブラリが判断した
|
||
ときは、<code>EB_ERR_NO_SUCH_BINARY</code> を返します。
|
||
</p>
|
||
|
||
<p>
|
||
この関数は、実際に図版データを読み込むことはしません。
|
||
読み込みには、<code>eb_read_binary()</code> を用います。
|
||
モノクロ図版のデータは、1 ピクセルに 1bit を割り当てた BMP 形式になって
|
||
います。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:set_binary_color_graphic"><code>EB_Error_Code eb_set_binary_color_graphic (EB_Book *<var>book</var>, const EB_Position *<var>position</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_set_binary_color_graphic()</code> は、EPWING のカラー図版の
|
||
データをこれから取得しようとしていることを EB ライブラリに伝えます。
|
||
引数 <var>position</var> は図版の位置を渡します。
|
||
位置の情報は、図版の参照元であるテキストデータに記載されており、通常は
|
||
フック関数を通じて得るようにします。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、関数は <code>EB_SUCCESS</code> を返します。
|
||
</p>
|
||
|
||
<p>
|
||
あらかじめ、図版を取り出そうとしている副本を選択しておかなければ
|
||
なりません。
|
||
<var>book</var> が副本を選択していなければ、<code>EB_ERR_NO_CUR_SUB</code>
|
||
を返します。
|
||
図版の位置が明らかにおかしいと EB ライブラリが判断したときは、
|
||
<code>EB_ERR_NO_SUCH_BINARY</code> を返します。
|
||
</p>
|
||
|
||
<p>
|
||
この関数は、実際に図版データを読み込むことはしません。
|
||
読み込みには、<code>eb_read_binary()</code> を用います。
|
||
カラー図版データは、JPEG か BMP (DIB) のいずかの形式になっています。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:set_binary_wave"><code>EB_Error_Code eb_set_binary_wave (EB_Book *<var>book</var>, const EB_Position *<var>start_position</var>, EB_Position *<var>end_position</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_set_binary_wave()</code> は、WAVE (PCM) 形式の音声のデータ
|
||
をこれから取得しようとしていることを EB ライブラリに伝えます。
|
||
引数 <var>start_position</var> と <var>end_position</var> には音声データ
|
||
の開始位置を渡します。
|
||
位置の情報は、音声データの参照元であるテキストデータに記載されており、
|
||
通常はフック関数を通じて得るようにします。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、関数は <code>EB_SUCCESS</code> を返します。
|
||
失敗すると、原因に応じたエラーコードを返します。
|
||
</p>
|
||
|
||
<p>
|
||
あらかじめ、音声データを取り出そうとしている副本を選択しておかなければ
|
||
なりません。
|
||
<var>book</var> が副本を選択していなければ、<code>EB_ERR_NO_CUR_SUB</code> を
|
||
返します。
|
||
音声データの位置が明らかにおかしいと EB ライブラリが判断したときは、
|
||
<code>EB_ERR_NO_SUCH_BINARY</code> を返します。
|
||
</p>
|
||
|
||
<p>
|
||
この関数は、実際に音声データを読み込むことはしません。
|
||
読み込みには、<code>eb_read_binary()</code> を用います。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:set_binary_mpeg"><code>EB_Error_Code eb_set_binary_mpeg (EB_Book *<var>book</var>, const unsigned int *<var>argv</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_set_binary_mpeg()</code> は、MPEG1 形式の動画のデータを
|
||
これから取得しようとしていることを EB ライブラリに伝えます。
|
||
引数 <var>argv</var> には動画データのファイル名を渡します。
|
||
ただし、このファイル名は文字列ではなく、フック関数
|
||
<code>EB_HOOK_BEGIN_MPEG</code> に渡された引数 <code>argv[2]</code>
|
||
～ <code>argv[5]</code> の部分を渡します。
|
||
つまり、フック関数の引数 <code>argv + 2</code> を、
|
||
<code>eb_set_binary_mpeg()</code> への引数 <var>argv</var> として
|
||
渡します。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、関数は <code>EB_SUCCESS</code> を返します。
|
||
失敗すると、原因に応じたエラーコードを返します。
|
||
</p>
|
||
|
||
<p>
|
||
あらかじめ、動画データを取り出そうとしている副本を選択しておかなければ
|
||
なりません。
|
||
<var>book</var> が副本を選択していなければ、<code>EB_ERR_NO_CUR_SUB</code>
|
||
を返します。
|
||
存在しない動画ファイル名を EB ライブラリが判断したときは、
|
||
<code>EB_ERR_NO_SUCH_BINARY</code> を返します。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、関数は <code>EB_SUCCESS</code> を返します。
|
||
</p>
|
||
|
||
<p>
|
||
この関数は、実際に動画データを読み込むことはしません。
|
||
読み込みには、<code>eb_read_binary()</code> を用います。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:read_binary"><code>EB_Error_Code eb_read_binary (EB_Book *<var>book</var>, size_t <var>binary_max_length</var>, char *<var>binary</var>, ssize_t *<var>binary_length</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_read_binary()</code> は、バイナリデータを読み込みます。
|
||
読み込もうとしているバイナリデータは、事前に
|
||
</p>
|
||
|
||
<ul>
|
||
<li><code>eb_set_binary_mono_graphic()</code>
|
||
<li><code>eb_set_binary_color_graphic()</code>
|
||
<li><code>eb_set_binary_wave()</code>
|
||
<li><code>eb_set_binary_mpeg()</code>
|
||
</ul>
|
||
|
||
<p>
|
||
のいずれかの関数で、EB ライブラリに通知しておく必要があります。
|
||
</p>
|
||
|
||
<p>
|
||
読み込んだデータは引数 <var>binary</var> の指す先の領域に書き込まれます。
|
||
また、このとき書き込まれたバイト数は、<var>binary_length</var> の指す
|
||
先の領域にセットされます。
|
||
ただし、書き込まれるバイト数は、最長でも引数 <var>binary_max_length</var>
|
||
に指定した値までとなります。
|
||
</p>
|
||
|
||
<p>
|
||
この関数は、特に読み込んだデータの終端にナル文字を付加するような事は
|
||
しません。
|
||
読み込まれるデータもバイナリ形式なので、途中にナル文字が出現する事も
|
||
あります。
|
||
</p>
|
||
|
||
<p>
|
||
この関数を一回呼び出しだだけで、バイナリデータ全体を一気に取得する
|
||
必要はありません。
|
||
繰り返し呼び出せば、前回の続きからデータが読み込まれます。
|
||
</p>
|
||
|
||
<p>
|
||
ただし、以下に挙げた関数を呼び出すと、バイナリデータの読み込みに関する
|
||
状態記録がリセットされますので、それ以上の読み込みはできなくなります。
|
||
</p>
|
||
|
||
<ul>
|
||
<li><code>eb_set_subbook()</code>
|
||
<li><code>eb_unset_subbook()</code>
|
||
<li><code>eb_load_all_subbooks()</code>
|
||
<li><code>eb_bind()</code>
|
||
<li><code>eb_finalize_book()</code>
|
||
<li><code>eb_set_binary_mono_graphic()</code>
|
||
<li><code>eb_set_binary_color_graphic()</code>
|
||
<li><code>eb_set_binary_wave()</code>
|
||
<li><code>eb_set_binary_mpeg()</code>
|
||
</ul>
|
||
|
||
<p>
|
||
<code>eb_read_binary()</code> を繰り返し呼んだ場合、バイナリデータは
|
||
その都度 <var>binary</var> の先頭から書き込まれ、*<var>binary_length</var>
|
||
の値も、その回の <code>eb_read_binary()</code> の呼び出しで書き込まれた
|
||
バイト数になります。
|
||
</p>
|
||
|
||
<p>
|
||
データの終端に来ると、それ以上この関数を呼んでも関数は <var>binary</var>
|
||
には何も書き込まず、*<var>binary_length</var> に 0 を書き込み、
|
||
<code>EB_SUCCESS</code> を返します。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、この関数は <code>EB_SUCCESS</code> を返します。
|
||
失敗すると、<var>binary_length</var> が指す領域に -1 を書き込み、原因を
|
||
示すエラーコードを返します。
|
||
この場合、バイナリデータの読み込み状態の記録がリセットされますので、
|
||
データの続きを読み込むことはできなくなります。
|
||
</p>
|
||
|
||
<p>
|
||
あらかじめ、<var>book</var> はいずれかの副本を選択していなくては
|
||
なりません。
|
||
選択していない場合は、<code>EB_ERR_NO_CUR_SUB</code> を返します。
|
||
また、冒頭に挙げた関数の呼び出しが成功していない状態でこの関数を呼ぶと、
|
||
<code>EB_ERR_NO_CUR_BINARY</code> を返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:compose_movie_file_name"><code>EB_Error_Code eb_compose_movie_file_name (const unsigned int *<var>argv</var>, char *<var>composed_file_name</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_compose_movie_file_name()</code> は、動画データのファイル名
|
||
を通常の文字列に変換します。
|
||
</p>
|
||
|
||
<p>
|
||
EB ライブラリでは、動画データのファイル名はフック関数
|
||
<code>EB_HOOK_BEGIN_MPEG</code> に渡された 4 つの int 型引数
|
||
(<code>argv[2]</code> ～ <code>argv[5]</code>) によって表現されます。
|
||
</p>
|
||
|
||
<p>
|
||
動画データを読み込む際は、これをそのまま <code>eb_set_binary_mpeg()</code>
|
||
に渡せば良いのですが、ファイル名を通常の文字列で得たい場合は、この関数を
|
||
用います。
|
||
たとえば、個々の動画に一意の ID のようなものを振りたい場合は、ファイル
|
||
名を ID として使うと良いかも知れません。
|
||
なお、この関数で変換して得られるファイル名にはパスが含まれていません。
|
||
</p>
|
||
|
||
<p>
|
||
フック関数の引数 <code>argv + 2</code> をこの関数への引数 <var>argv</var>
|
||
として渡すと、<var>composed_file_name</var> が指す先の領域に、文字列形式
|
||
に変換されたファイル名が格納されます。
|
||
ファイル名は最長で <code>EB_MAX_DIRECTORY_NAME_LENGTH</code> (= 8) バイト
|
||
になります。
|
||
この長さには終端のナル文字の分を含んでいませんので、格納領域にはもう
|
||
1 バイト余裕が要ります。
|
||
</p>
|
||
|
||
<p>
|
||
なお、格納されたファイル名は、実際に存在するファイル名とは若干異なって
|
||
いる可能性があります。
|
||
たとえば、英字の大文字と小文字、接尾子の有無などの違いがこれに当たります。
|
||
この関数は、あくまで文字列に機械的に変換するだけなので、ファイルが実在
|
||
するかどうかのチェックはしません。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、関数は <code>EB_SUCCESS</code> を返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:compose_movie_path_name"><code>EB_Error_Code eb_compose_movie_path_name (EB_Book *<var>book</var>, const unsigned int *<var>argv</var>, char *<var>composed_path_name</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_compose_movie_path_name()</code> は、動画データのファイル名
|
||
を通常の文字列に変換します。
|
||
働きは、前述の関数 <code>eb_compose_movie_file_name()</code> に良く
|
||
似ていますが、<code>eb_compose_movie_path_name()</code> が返すファイル名
|
||
は、絶対パスの形式になっている点が異なります。
|
||
</p>
|
||
|
||
<p>
|
||
また、<code>eb_compose_movie_path_name()</code> では、ファイル名が実在
|
||
するかどうかのチェックを行うという点も、大きな違いです。
|
||
ファイル名を文字列に変換した上で、英字の大文字と小文字の違いや接尾子の
|
||
有無は、実在のファイルに合わせて調整したものを返します。
|
||
したがって、パスを除いた部分で比較しても、
|
||
<code>eb_compose_movie_file_name()</code> が返すファイル名とは必ずしも
|
||
一致しません。
|
||
</p>
|
||
|
||
<p>
|
||
引数 <code>book</code> は、動画ファイルを収録している副本を選択して
|
||
おかなければなりません。
|
||
副本を選択していなければ、<code>EB_ERR_NO_CUR_SUB</code> を返します。
|
||
</p>
|
||
|
||
<p>
|
||
引数 <code>argv</code> の意味は、<code>eb_compose_movie_file_name()</code>
|
||
と同じです。
|
||
</p>
|
||
|
||
<p>
|
||
ファイル名の変換が成功すると、関数は <var>composed_path_name</var> が
|
||
指す先の領域に、文字列形式に変換された動画ファイル名を格納し、
|
||
<code>EB_SUCCESS</code> を返します。
|
||
ファイル名は最長で <code>EB_MAX_PATH_LENGTH</code> バイトになります。
|
||
この長さには終端のナル文字の分を含んでいませんので、格納領域にはもう
|
||
1 バイト余裕が要ります。
|
||
</p>
|
||
|
||
<p>
|
||
ファイル名が実在しないと、<code>EB_ERR_BAD_FILE_NAME</code> を返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:decompose_movie_file_name"><code>EB_Error_Code eb_decompose_movie_file_name (unsigned int *<var>argv</var>, const char *<var>composed_file_name</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_compose_movie_file_name()</code> は、
|
||
<code>eb_compose_movie_file_name()</code> とちょうど逆の働きをします。
|
||
つまり、通常の文字列に変換された動画データのファイル名
|
||
<var>composed_file_name</var> を、4 つの int 型引数 <var>argv</var> に
|
||
戻します。
|
||
したがって、<var>argv</var> の指す領域は、少なくとも int 型の値を 4 つ
|
||
格納できる大きさが必要です。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、関数は <code>EB_SUCCESS</code> を返します。
|
||
</p>
|
||
|
||
<!-- ================================================================ -->
|
||
<h2><a name="appendix-data">appendix データ</a></h2>
|
||
|
||
<p>
|
||
<dfn>appendix</dfn> (<dfn>付録</dfn>) とは CD-ROM 書籍の補助データの
|
||
ことです。
|
||
appendix は CD-ROM 書籍の出版社から提供されているものではなく、
|
||
EB ライブラリに固有のものです。
|
||
<code>ebappendix</code> コマンドを用いて生成します
|
||
(詳しくは <a href="ebappendix.html">ebappendix コマンドのマニュアル</a>
|
||
の「appendix (付録) とは」を参照のこと)。
|
||
</p>
|
||
|
||
<p>
|
||
appendix は以下のデータを CD-ROM 書籍に対して提供します。
|
||
</p>
|
||
|
||
<ul>
|
||
<li>本文の区切りコード
|
||
<li>外字の代替文字列
|
||
</ul>
|
||
|
||
<p>
|
||
appendix のレイアウトは CD-ROM 書籍のものとよく似ています。
|
||
トップディレクトリには <code>catalog</code> もしくは
|
||
<code>catalogs</code> ファイルが存在し、各副本のデータは対応する
|
||
サブディレクトリに配置されています。
|
||
</p>
|
||
|
||
<p>
|
||
アプリケーションは appendix に対応し、本文の区切りコードの情報を使える
|
||
ようにすることをお薦めします。
|
||
外字の代替文字列については、外字のフォントをそのまま表示できるので
|
||
あれば、対応する必要性はかなり乏しいですが、本文の区切りコードは、
|
||
扱えないと正しく本文を表示できない書籍に対応できません
|
||
(区切りコードについては、<a href="#stop-code-issue">「区切りコードの問題」</a> を参照のこと)。
|
||
</p>
|
||
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="eb_appendix"><code>EB_Appendix</code> オブジェクト</a></h3>
|
||
|
||
<p>
|
||
CD-ROM 書籍本体を扱うには <code>EB_Book</code> オブジェクトを
|
||
用いましたが、appendix を扱うには <code>EB_Appendix</code> オブジェクト
|
||
を使います。
|
||
<code>EB_Appendix</code> オブジェクトを操作するための関数は、
|
||
<code>EB_Book</code> のものとは異なりますが、操作手順はよく似ています。
|
||
</p>
|
||
|
||
<p>
|
||
<code>EB_Appendix</code> オブジェクトは、個々の appendix に対して 1 個
|
||
ずつ作る必要があります。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
EB_Appendix app;
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
もちろん、オブジェクトの領域は、<code>malloc()</code> で確保しても
|
||
構いません。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
EB_Appendix *app_pointer;
|
||
|
||
app_pointer = (EB_Appendix *) malloc(sizeof(EB_Appendix));
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
オブジェクトは、使う前に必ず <code>eb_initialize_appendix()</code>
|
||
という関数で中身を初期化しなくてはなりません。
|
||
<code>EB_Book</code> オブジェクトでも <code>eb_initialize_book()</code>
|
||
で初期化する必要がありましたが、それと同じです。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
eb_initialize_appendix(&app);
|
||
eb_initialize_appendix(app_pointer);
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
続いて、オブジェクトを appendix の実体に結び付けるために、
|
||
<code>eb_bind_appendix()</code> を呼び出します。
|
||
これは、<code>EB_Book</code> オブジェクトの <code>eb_bind()</code> に
|
||
相当します。
|
||
</p>
|
||
|
||
<blockquote>
|
||
<pre>
|
||
ＥＢ＿Ａｐｐｅｎｄｉｘ ａｐｐｅｎｄｉｘ
|
||
オブジェクト ┌────────────┐
|
||
┌───┐ │ │
|
||
│ ┝━━━━━━━━━━━━━┥ ／ｍｎｔ／ｄｉｃｔ │
|
||
└───┘ ｅｂ＿ｂｉｎｄ │ │
|
||
＿ａｐｐｅｎｄｉｘ（） └────────────┘
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
実際のプログラムでは、次のようにします。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
if (eb_bind_appendix(&app, "/mnt/dict") != EB_SUCCESS) {
|
||
printf("eb_bind_appendix() failed\n");
|
||
return;
|
||
}
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
<code>eb_bind_appendix()</code> に渡す appendix のパス
|
||
(この例では <code>/mnt/dict</code>) は appendix のトップディレクトリ、
|
||
つまり <code>catalog</code> または <code>catalogs</code> ファイルのある
|
||
ディレクトリを指定します。
|
||
パスには、遠隔アクセス識別子 (例: <samp>ebnet://localhost/dict.app</samp>)
|
||
を指定することも可能です。
|
||
</p>
|
||
|
||
<p>
|
||
<code>EB_Appendix</code> オブジェクトを使い終わったら、
|
||
<code>eb_finalize_appendix()</code> を呼んで後始末をします。
|
||
オブジェクトは appendix との結び付きを解かれた状態に戻り、
|
||
内部で割り当てられたメモリは解放され、開いていたファイルもすべて
|
||
閉じられます。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
eb_finalize_appendix(&app);
|
||
eb_finalize_appendix(app_pointer);
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
オブジェクトの領域を <code>malloc()</code> で確保した場合は、
|
||
<code>eb_finalize_appendix()</code> を呼んだ後ならば、オブジェクトの
|
||
領域を安全に解放することができます。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
free(app_pointer);
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="appendix-subbook">副本</a></h3>
|
||
|
||
<p>
|
||
CD-ROM と同様に、appendix にも副本が存在します。
|
||
appendix の副本も、副本コードを使って識別します。
|
||
個々の副本コードは、appendix 内で同じものがないようになっています。
|
||
</p>
|
||
|
||
<p>
|
||
CD-ROM 書籍内のすべての副本の副本コードを取得する関数として
|
||
<code>eb_subbook_list()</code> がありましたが、appendix にも
|
||
<code>eb_appendix_subbook_list()</code> という同様の関数があります。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
/* <code>app</code> が <code>EB_Appendix</code> のオブジェクトで、
|
||
* すでに書籍に結び付けられていると仮定しています。*/
|
||
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;
|
||
}
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
<code>eb_appendix_subbook_list()</code> が成功すると、書籍内のすべての
|
||
副本コードが 配列 <code>sub_codes[]</code> に格納されます。
|
||
配列の先頭の副本コードは <code>sub_codes[0]</code> と表され、次の
|
||
コードは <code>sub_codes[1]</code>、という具合になります。
|
||
副本の個数は、<code>sub_count</code> に格納されます。
|
||
</p>
|
||
|
||
<p>
|
||
<code>EB_Book</code> と同様に <code>EB_Appendix</code> オブジェクト
|
||
でも、結びつけられた CD-ROM 書籍の中の任意の副本から一つ選んで、
|
||
<dfn>選択中の副本 (current subbook)</dfn> として指定することができます。
|
||
複数の副本を、同時に選択することはできません。
|
||
区切りコードや外字の代替文字列といった appendix 内のデータへのアクセス
|
||
は、選択中の副本に対してだけ行えます。
|
||
</p>
|
||
|
||
<p>
|
||
以下は、先頭の副本 (<code>sub_codes[0]</code>) を選択する場合の例です。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
/* <code>app</code> が <code>EB_Appendix</code> のオブジェクトで、
|
||
* すでに書籍に結び付けられていると仮定しています。*/
|
||
if (eb_set_appendix_subbook(&app, sub_codes[0]) != EB_SUCCESS) {
|
||
printf("eb_subbook_list() failed\n");
|
||
return;
|
||
}
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
<code>eb_bind_appendix()</code> で <code>EB_Appendix</code> オブジェクト
|
||
を appendix に結び付けた直後は、いずれの副本も選択されていない状態に
|
||
なっています。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="appendix-stop-code">本文の区切りコード</a></h3>
|
||
|
||
<p>
|
||
CD-ROM 書籍によっては、EB ライブラリが本文の表示を正しい位置で
|
||
止められないことがあります
|
||
(詳しくは、<a href="#stop-code-issue">「区切りコードの問題」</a> を参照のこと)。
|
||
これは、本文の区切りコードの推測を EB ライブラリが誤ったために起こる
|
||
のですが、appendix データを使うことで、正しい区切りコードを EB ライブラリ
|
||
に教えてやることができます。
|
||
</p>
|
||
|
||
<p>
|
||
CD-ROM 書籍の本文を取得する関数 <code>eb_read_text()</code> は
|
||
第 2 引数に <code>EB_Appendix *</code> をとるのですが、ここに appendix
|
||
オブジェクトを渡してやるようにします。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
/* <code>book</code>, <code>app</code> は、それぞれ <code>EB_Book</code>
|
||
* および <code>EB_Appendix</code> のオブジェクトで、どちらもすでに
|
||
* 副本を選択中と仮定しています。*/
|
||
#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;
|
||
}
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
<code>eb_read_text()</code> は、渡された appendix オブジェクトが副本を
|
||
選択済みで、かつ区切りコードの情報を持っていれば、その区切りコードを
|
||
使用します。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="appendix-alternation-text">外字の代替文字列</a></h3>
|
||
|
||
<p>
|
||
CD-ROM 書籍は、定義している外字の情報としてフォントのデータしか用意して
|
||
いません。
|
||
つまり、その外字がどのような文字なのかをユーザに分かるようにするには、
|
||
アプリケーションがフォントを表示するしかありません。
|
||
しかしこれでは、テキストインターフェースを用いたアプリケーションでは、
|
||
本文中の外字の部分がまったく分かりません。
|
||
外字を多用している書籍では、本文が解読不能に近い状態になるかも知れません。
|
||
</p>
|
||
|
||
<p>
|
||
そこで EB ライブラリでは、外字の代替となる文字列を appendix 内で定義
|
||
できるようにしています。
|
||
appendix が用意されている場合に限り、アプリケーションは外字のフォント
|
||
を描画する代わりにその代替文字列を出力することにすれば、
|
||
テキストインターフェースを用いたアプリケーションでも書籍が読み易く
|
||
なります。
|
||
</p>
|
||
|
||
<p>
|
||
appendix に定義されている代替文字列を取り出す関数は、2 つあります。
|
||
半角外字用の <code>eb_narrow_alt_character_text()</code> と全角外字用の
|
||
<code>eb_wide_alt_character_text()</code> です。
|
||
どちらも、使い方は変わりません。
|
||
</p>
|
||
|
||
<p>
|
||
以下の例では、半角外字の文字番号 0xa121 に対する代替文字列を
|
||
<samp>buffer</samp> に格納しています。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
/* <code>app</code> が <code>EB_Appendix</code> のオブジェクトで、
|
||
* すでに副本を選択中であると仮定しています。*/
|
||
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;
|
||
}
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
外字は個々の副本に対して定義されているので、代替文字列を取り出すには、
|
||
あらかじめ副本を選択しておく必要があります。
|
||
外字のフォントを取り出す際は、これに加えて外字の「高さ」も選択しておく
|
||
必要がありましたが、代替文字列には高さの概念がないので必要ありません。
|
||
</p>
|
||
|
||
<p>
|
||
代替文字列は最長で <code>EB_MAX_ALTERNATION_TEXT_LENGTH</code> バイト
|
||
(= 31 バイト) です。
|
||
ただし、この長さにはナル文字の分は含んでいないので、<samp>buffer</samp>
|
||
はもう 1 バイト分余裕を持たせています。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="appendix-data-types">データ型の詳細</a></h3>
|
||
|
||
<p>
|
||
この節で説明しているデータ型を使うには、次のようにヘッダファイルを
|
||
読み込んで下さい。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
#include <eb/appendix.h>
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="type:Appendix"><code>EB_Appendix</code> 型</a></h4>
|
||
|
||
<p>
|
||
<code>EB_Appendix</code> 型は、一冊の CD-ROM 書籍を表します。
|
||
CD-ROM 書籍へのアクセスは、すべてこの型のオブジェクトを介して行います。
|
||
同時に複数の CD-ROM 書籍にアクセスする際は、書籍一冊毎にオブジェクトを
|
||
作る必要があります。
|
||
</p>
|
||
|
||
<p>
|
||
<code>EB_Appendix</code> オブジェクトの操作は、すべて EB ライブラリが
|
||
用意している関数で行います。
|
||
アプリケーションプログラムは、直接 <code>EB_Appendix</code> オブジェクト
|
||
のメンバを参照したり、セットしたりすべきではありません。
|
||
</p>
|
||
|
||
<p>
|
||
<code>EB_Appendix</code> オブジェクトを使用する際は、まずそのオブジェクト
|
||
に対して <code>eb_initialize_book()</code> を呼んで初期化しなくては
|
||
なりません。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="appendix-functions">関数の詳細</a></h3>
|
||
|
||
<p>
|
||
この節で説明している関数を使うには、次のようにヘッダファイルを読み込んで
|
||
下さい。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
#include <eb/appendix.h>
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:initialize_appendix"><code>void eb_initialize_appendix (EB_Appendix *<var>app</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_initialize_appendix()</code> は、<var>app</var> の指す
|
||
<code>EB_Appendix</code> オブジェクトを初期化します。
|
||
<code>EB_Appendix</code> オブジェクトに対して EB ライブラリの他の関数を
|
||
呼ぶ前に、必ずそのオブジェクトを初期化しなくてはなりません。
|
||
初期化していないオブジェクトに対して、EB ライブラリの他の関数を呼んだ
|
||
場合の動作は未定義です。
|
||
また、すでに初期化したオブジェクトに対して、
|
||
再度 <code>eb_initialize_appendix()</code> を呼んではいけません。
|
||
呼んだ場合の動作は未定義です。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:finalize_appendix"><code>void eb_finalize_appendix (EB_Appendix *<var>app</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_finalize_appendix()</code> は、<var>app</var> が指す
|
||
<code>EB_Appendix</code> オブジェクトの後始末を行います。
|
||
</p>
|
||
|
||
<p>
|
||
オブジェクトが割り当てて管理していたメモリはすべて解放され、
|
||
ファイルディスクリプタもすべて閉じられます。
|
||
オブジェクトが appendix と結び付いていた場合は、結び付きが解かれます。
|
||
</p>
|
||
|
||
<p>
|
||
後始末をしたオブジェクトに対して <code>eb_bind_appendix()</code> を呼ぶことで、
|
||
オブジェクトを再利用することができます。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:bind_appendix"><code>EB_Error_Code eb_bind_appendix (EB_Appendix *<var>app</var>, const char *<var>path</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_bind_appendix()</code> は、<var>app</var> の指す
|
||
<code>EB_Appendix</code> オブジェクトを、パス <var>path</var> にある
|
||
appendix に結び付けます。
|
||
パスには、appendix のトップディレクトリか遠隔アクセス識別子を指定します。
|
||
appendix のトップディレクトリとは、<code>catalog</code> あるいは
|
||
<code>catalogs</code> ファイルの存在するディレクトリを指します。
|
||
</p>
|
||
|
||
<p>
|
||
オブジェクトがすでにappendix に結び付いていた場合、その appendix との
|
||
結び付きを解いてから、<var>path</var> にある appendix に結び付けます。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、関数は <code>EB_SUCCESS</code> を返します。
|
||
このとき、副本は未選択の状態になります。
|
||
失敗すると、オブジェクトを appendix との結び付きを解かれた状態にして、
|
||
原因を示すエラーコードを返します。
|
||
</p>
|
||
|
||
<p>
|
||
<var>path</var> は、<code>EB_MAX_PATH_LENGTH</code> バイトに収まて
|
||
いなくてはなりません。
|
||
さらに、<var>path</var> が相対パスのときは、絶対パスに変換した結果が
|
||
この長さに収まっていなくてはなりません。
|
||
これを超えると、<code>EB_ERR_TOO_LONG_FILE_NAME</code> を返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:is_appendix_bound"><code>int eb_is_appendix_bound (EB_Appendix *<var>app</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_is_appendix_bound()</code> は、<var>app</var> が appendix に
|
||
結び付いているかどうかを調べます。
|
||
結び付いていれば 1 を返し、そうでなければ 0 を返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:appendix_path"><code>EB_Error_Code eb_appendix_path (EB_Appendix *<var>app</var>, char *<var>path</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_appendix_path()</code> は、<var>app</var> に結び付いている
|
||
appendix のパスもしくは遠隔アクセス識別子を、<var>path</var> の指す領域
|
||
に書き込みます。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、関数は <code>EB_SUCCESS</code> を返します。
|
||
失敗すると、<var>path</var> の指す領域に空文字列を書き込み、原因を示す
|
||
エラーコードを返します。
|
||
</p>
|
||
|
||
<p>
|
||
<var>app</var> は、あらかじめ書籍に結び付いている必要があります。
|
||
結びついていない場合は、<code>EB_ERR_UNBOUND_BOOK</code> を返します。
|
||
</p>
|
||
|
||
<p>
|
||
<var>path</var> に書き込むパス名のバイト数は、最長で
|
||
<code>EB_MAX_PATH_LENGTH</code> になります。
|
||
この長さは、末尾のナル文字を含みません。
|
||
関数が返すパスは正規化された形になっているので、
|
||
<code>eb_bind_appendix()</code> に渡したときのものと同じとは限りません。
|
||
たとえば、相対パスだった場合は、絶対パスに変換されます。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:load_all_appendix_subbooks"><code>EB_Error_Code eb_load_all_appendix_subbooks (EB_Appendix *<var>app</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_load_all_appendix_subbooks()</code> は、<var>app</var> 内
|
||
のすべての副本を初期化します。
|
||
通常、副本の初期化は、その副本が初めて選択されたときに自動的に
|
||
行われますが、この関数は初期化を前倒しで行います。
|
||
初期化の対象となるのは、この関数を呼び出した時点でまだ初期化していない
|
||
すべての副本です。
|
||
この関数は、スタンドアロンで動作するサーバアプリケーションなどで有効です。
|
||
クライアントからの接続を受ける前にこの関数を呼ぶことで、副本の初期化の
|
||
ためにクライアントを待たせなくて済みます。
|
||
</p>
|
||
|
||
<p>
|
||
初期化の対象となったすべての副本の初期化に成功すれば、関数は
|
||
<code>EB_SUCCESS</code> を返します。
|
||
一冊でも初期化に失敗した場合は、残りの副本の初期化を諦め、原因を示す
|
||
エラーコードを返します。
|
||
</p>
|
||
|
||
<p>
|
||
<var>app</var> は、あらかじめ appendix に結び付けられていなくては
|
||
なりません。
|
||
結びついていない場合は、<code>EB_ERR_UNBOUND_APP</code> を返します。
|
||
</p>
|
||
|
||
<p>
|
||
この関数を呼び出すと、<var>app</var> は、副本を選択していない状態に
|
||
なります。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:appendix_subbook_list"><code>EB_Error_Code eb_appendix_subbook_list (EB_Book *<var>app</var>, EB_Subbook_Code *<var>subbook_list</var>, int *<var>subbook_count</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_appendix_subbook_list()</code> は、<var>app</var> 内の
|
||
すべて副本の副本コードを <code>EB_Subbook_Code</code> 型の配列にして、
|
||
<var>subbook_list</var> の指す領域に書き込みます。
|
||
配列は、最大で <code>EB_MAX_SUBBOOKS</code> 個の要素を持ちます。
|
||
加えて、appendix が収録している副本の個数を <var>subbook_count</var> の
|
||
指す領域に書き込みます。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、関数は <code>EB_SUCCESS</code> を返します。
|
||
失敗すると、<var>subbook_count</var> の指す領域に 0 を書き込み、原因を
|
||
示すエラーコードを返します。
|
||
</p>
|
||
|
||
<p>
|
||
<var>app</var> は、あらかじめ appendix に結び付けられていなくては
|
||
なりません。
|
||
結びついていない場合は、<code>EB_ERR_UNBOUND_APP</code> を返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:appendix_subbook"><code>EB_Error_Code eb_appendix_subbook (EB_Book *<var>app</var>, EB_Subbook_Code *<var>subbook_code</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_appendix_subbook()</code> は、<var>app</var> が選択中の
|
||
副本の副本コードを <var>subbook_code</var> の指す領域に書き込みます。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、関数は <code>EB_SUCCESS</code> を返します。
|
||
失敗すると、<var>subbook_code</var> の指す領域に
|
||
<code>EB_SUBBOOK_INVALID</code> を書き込み、原因を示すエラーコードを
|
||
返します。
|
||
</p>
|
||
|
||
<p>
|
||
あらかじめ、<var>app</var> はいずれかの副本を選択していなくては
|
||
なりません。
|
||
選択していない場合は、<code>EB_ERR_NO_CUR_APPSUB</code> を返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:appendix_subbook_directory"><code>EB_Error_Code eb_appendix_subbook_directory (EB_Book *<var>app</var>, char *<var>directory</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_appendix_subbook_directory()</code> は、<var>app</var> 内
|
||
で現在選択中の副本のデータファイルを収めたディレクトリ名を、
|
||
<var>directory</var> の指す領域に書き込みます。
|
||
</p>
|
||
|
||
<p>
|
||
ディレクトリ名の文字列の長さは、最長で
|
||
<code>EB_MAX_DIRECTORY_NAME_LENGTH</code> バイトです。
|
||
この長さに、末尾のナル文字は含みません。
|
||
ディレクトリ名は ASCII の数字、英小文字、アンダースコアで構成されます。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、関数は <code>EB_SUCCESS</code> を返します。
|
||
失敗すると、<var>directory</var> の指す領域に空文字列を書き込み、原因に
|
||
を示すエラーコードを返します。
|
||
</p>
|
||
|
||
<p>
|
||
あらかじめ、<var>app</var> 内のいずれかの副本が選択されていなくては
|
||
なりません。
|
||
選択していない場合は、<code>EB_ERR_NO_CUR_APPSUB</code> を返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:appendix_subbook_directory2"><code>EB_Error_Code eb_appendix_subbook_directory2 (EB_Book *<var>app</var>, EB_Subbook_Code <var>subbook_code</var>, char *<var>directory</var>)</code></a></h4>
|
||
|
||
<p>
|
||
<code>eb_appendix_subbook_directory()</code> と似ていますが、選択中の
|
||
副本ではなく、引数 <var>subbook_code</var> で指定された副本の
|
||
ディレクトリ名を書き込む点が異なります。
|
||
</p>
|
||
|
||
<p>
|
||
<var>app</var> は副本を選択していなくても構いませんが、あらかじめ
|
||
appendix に結び付けられていなければなりません。
|
||
結びついていない場合は、<code>EB_ERR_UNBOUND_APP</code> を返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:set_appendix_subbook"><code>EB_Error_Code eb_set_appendix_subbook (EB_Book *<var>app</var>, EB_Subbook_Code <var>code</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_set_appendix_subbook()</code> は、<var>app</var> の副本
|
||
<var>code</var> を選択します。
|
||
すでに副本を選択していた場合は、いったん未選択の状態にしてから副本
|
||
<var>subbook_code</var> を選択します。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、関数は <code>EB_SUCCESS</code> を返します。
|
||
このとき、外字は未選択の状態となり、検索、テキストデータの読み込み、
|
||
バイナリデータの読み込みについての状態記録は、すべてリセットされます。
|
||
失敗すると、副本を未選択の状態にして、原因を示すエラーコードを返します。
|
||
</p>
|
||
|
||
<p>
|
||
あらかじめ、<var>app</var> は appendix に結び付けられていなければ
|
||
なりません。
|
||
結びついていない場合は、<code>EB_ERR_UNBOUND_APP</code> を返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:unset_appendix_subbook"><code>void eb_unset_appendix_subbook (EB_Book *<var>app</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_unset_appendix_subbook()</code> は、<var>app</var> が選択
|
||
している副本を未選択の状態にします。
|
||
<var>app</var> が appendix に結び付いていないか、副本が選択されていない
|
||
場合は、何もしません。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:have_stop_code"><code>int eb_have_stop_code (EB_Book *<var>app</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_have_stop_code()</code> は、<var>app</var> が選択中の副本で
|
||
区切りコードが定義されているかどうかを調べます。
|
||
</p>
|
||
|
||
<p>
|
||
定義していれば 1 を返します。
|
||
定義していないか、そもそも副本が選択されていない場合は 0 を返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:stop_code"><code>EB_Error_Code eb_stop_code (EB_Book *<var>app</var>, int *<var>stop_code</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_stop_code()</code> は、<var>app</var> が選択中の副本で定義
|
||
している区切りコードを <var>stop_code</var> の指す領域に書き込みます。
|
||
<var>stop_code[0]</var>, <var>stop_code[1]</var> に、区切りコードの値
|
||
としてそれぞれ <samp>0x0000</samp> ～ <samp>0xffff</samp> が書き込まれます。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、関数は <code>EB_SUCCESS</code> を返します。
|
||
失敗すると、関数は <var>stop_code[0]</var> と <var>stop_code[1]</var>
|
||
に <samp>-1</samp> を書き込み、原因を示すエラーコードを返します。
|
||
</p>
|
||
|
||
<p>
|
||
あらかじめ、<var>app</var> は副本を選択していなくてはなりません。
|
||
選択していない場合は、<code>EB_ERR_NO_CUR_APPSUB</code> を返します。
|
||
副本が区切りコードを定義していない場合は、<code>EB_ERR_NO_STOPCODE</code>
|
||
を返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:have_narrow_alt"><code>int eb_have_narrow_alt (EB_Book *<var>app</var>)</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:have_wide_alt"><code>int eb_have_wide_alt (EB_Book *<var>app</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_have_narrow_alt()</code> は、選択中の副本が半角外字に対する
|
||
代替文字列を定義しているかどうかを調べます。
|
||
同様に、関数 <code>eb_have_wide_alt()</code> は、全角外字に対する
|
||
代替文字列を定義しているかどうかを調べます。
|
||
</p>
|
||
|
||
<p>
|
||
定義していれば 1 を、定義していなければ 0 を返します。
|
||
<var>app</var> が副本を選択していない場合も 0 を返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:narrow_alt_start"><code>EB_Error_Code eb_narrow_alt_start (EB_Book *<var>app</var>, int *<var>start</var>)</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:wide_alt_start"><code>EB_Error_Code eb_wide_alt_start (EB_Book *<var>app</var>, int *<var>start</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_narrow_alt_start()</code> は、<var>app</var> が選択中の副本
|
||
における半角外字に対する代替文字列の定義範囲を調べ、先頭の文字番号
|
||
(半角外字の文字番号の中で最小のもの) を <var>start</var> の指す領域に
|
||
書き込みます。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、関数は <code>EB_SUCCESS</code> を返します。
|
||
失敗すると、原因を示すエラーコードを返します。
|
||
</p>
|
||
|
||
<p>
|
||
あらかじめ、<var>app</var> は副本を選択していなくてはなりません。
|
||
選択していない場合は、<code>EB_ERR_NO_CUR_APPSUB</code> を返します。
|
||
副本が半角外字に対する代替文字列を定義していない場合は、
|
||
<code>EB_ERR_NO_ALT</code> を返します。
|
||
</p>
|
||
|
||
<p>
|
||
関数 <code>eb_wide_font_start()</code> は、半角外字ではなく全角外字に
|
||
ついて調べるという点を除いて、<code>eb_narrow_font_start()</code> と同じ
|
||
です。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:narrow_alt_end"><code>EB_Error_Code eb_narrow_alt_end (EB_Book *<var>app</var>, int *<var>end</var>)</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:wide_alt_end"><code>EB_Error_Code eb_wide_alt_end (EB_Book *<var>app</var>, int *<var>end</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_narrow_alt_end()</code> は、<var>app</var> が選択中の副本
|
||
における半角外字に対する代替文字列の定義範囲を調べ、最後の文字番号
|
||
(半角外字の文字番号の中で最大のもの) を <var>start</var> の指す領域に
|
||
書き込みます。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、関数は <code>EB_SUCCESS</code> を返します。
|
||
失敗すると、原因を示すエラーコードを返します。
|
||
</p>
|
||
|
||
<p>
|
||
あらかじめ、<var>app</var> は副本を選択していなくてはなりません。
|
||
選択していない場合は、<code>EB_ERR_NO_CUR_APPSUB</code> を返します。
|
||
副本が半角外字に対する代替文字列を定義していない場合は、
|
||
<code>EB_ERR_NO_ALT</code> を返します。
|
||
</p>
|
||
|
||
<p>
|
||
関数 <code>eb_wide_font_start()</code> は、半角外字ではなく全角外字に
|
||
ついて調べるという点を除いて、<code>eb_narrow_font_start()</code> と同じ
|
||
です。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:narrow_alt_character_text"><code>EB_Error_Code eb_narrow_alt_character_text (EB_Book *<var>app</var>, int <code>character_number</code>, char *<var>text</var>)</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:wide_alt_character_text"><code>EB_Error_Code eb_wide_alt_character_text (EB_Book *<var>app</var>, int <code>character_number</code>, char *<var>text</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_narrow_alt_character_text()</code> は、<var>book</var> が
|
||
選択中の副本で定義している、半角外字の代替文字列を取り出します。
|
||
外字の文字番号を、<var>character_number</var> で指定します。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、関数は代替文字列を <var>text</var> の指す領域に書き込み、
|
||
<code>EB_SUCCESS</code> を返します。
|
||
失敗すると、<var>text</var> の指す領域に空文字列を書き込み、原因を示す
|
||
エラーコードを返します。
|
||
</p>
|
||
|
||
<p>
|
||
代替文字列は最長で <code>EB_MAX_ALTERNATION_TEXT_LENGTH</code> バイト
|
||
(= 31 バイト) です。
|
||
ただし、この長さにはナル文字の分は含んでいないので、<var>text</var> の
|
||
領域にはもう 1 バイト分必要です。
|
||
</p>
|
||
|
||
<p>
|
||
代替文字列がどの文字コードで書かれているかは、appendix の中には
|
||
記録されていません。
|
||
しかし、appendix は必ず特定の書籍に対応して作成されるものなので、書籍の
|
||
文字コードから次のように判断すれば、問題ないでしょう。
|
||
</p>
|
||
|
||
<ul>
|
||
<li>書籍が ISO 8859-1 で書かれている場合は、代替文字列も ISO 8859-1
|
||
<li>それ以外の場合、代替文字列は日本語 EUC
|
||
</ul>
|
||
|
||
<p>
|
||
あらかじめ、<var>app</var> は副本を選択していなくてはなりません。
|
||
選択していない場合は、<code>EB_ERR_NO_CUR_APPSUB</code> を返します。
|
||
文字番号 <var>character_number</var> が外字の定義範囲外にある場合は、
|
||
<code>EB_ERR_NO_SUCH_CHAR_TEXT</code> を返します。
|
||
</p>
|
||
|
||
<p>
|
||
副本が半角外字に対する代替文字列を (<var>character_number</var> に限らず
|
||
まったく) 定義していない場合は、<code>EB_ERR_NO_ALT</code> を返します。
|
||
そうではなく、一部の文字番号については半角外字に対する代替文字列を
|
||
定義しているものの、<var>character_number</var> に対する代替文字列は
|
||
存在しない場合、関数は <code>EB_SUCCESS</code> を返し、<var>text</var>
|
||
の指す領域には空文字列が書き込まれます。
|
||
</p>
|
||
|
||
<p>
|
||
関数 <code>eb_wide_alt_character_text()</code> は、半角外字ではなく
|
||
全角外字に対する代替文字列を取り出すという点を除いて、
|
||
<code>eb_narrow_alt_character_text()</code> と同じです。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:backward_narrow_alt_character"><code>EB_Error_Code eb_backward_narrow_alt_character (EB_Book *<var>book</var>, int <var>n</var>, int *<var>character_number</var>)</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:backward_wide_alt_character"><code>EB_Error_Code eb_backward_wide_alt_character (EB_Book *<var>book</var>, int <var>n</var>, int *<var>character_number</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_forward_narrow_alt_character()</code> は、<var>app</var>
|
||
が選択中の副本において定義されている、半角外字に対する代替文字列の
|
||
文字番号 <var>character_number</var> の <var>n</var> 個後ろに位置する
|
||
文字の文字番号を取得します。
|
||
</p>
|
||
|
||
<p>
|
||
まず、関数を呼び出す際に、<var>character_number</var> の指す領域に
|
||
文字番号を書き込んでおきます。
|
||
関数の処理が成功すると、戻ったときに <var>n</var> 個分だけ後方の文字番号
|
||
に書き換わっています。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、関数は <code>EB_SUCCESS</code> を返します。
|
||
失敗すると、原因を示すエラーコードを返します。
|
||
</p>
|
||
|
||
<p>
|
||
あらかじめ、<var>app</var> は副本を選択していなくてはなりません。
|
||
選択していない場合は、<code>EB_ERR_NO_CUR_APPSUB</code> を返します。
|
||
副本が半角外字に対する代替文字列を定義していない場合は、
|
||
<code>EB_ERR_NO_ALT</code> を返します。
|
||
</p>
|
||
|
||
<p>
|
||
<var>n</var> 個後ろにもう外字がない場合や、呼び出した際に
|
||
<var>character_number</var> の指す領域に書き込んであった文字番号が外字の
|
||
定義範囲外にある場合は <code>EB_ERR_NO_SUCH_CHAR_TEXT</code> を返します。
|
||
</p>
|
||
|
||
<p>
|
||
<var>n</var> には負の数を指定することもできます。
|
||
この場合、次の呼び出しと等価になります。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
/* n < 0 とする */
|
||
eb_backward_narrow_font_character (book, -n, character_number);
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
関数 <code>eb_forward_wide_alt_character()</code> は、半角外字ではなく
|
||
全角外字について操作するという点を除いて、
|
||
<code>eb_forward_narrow_alt_character()</code> と同じです。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="appendix-sample">サンプルプログラム</a></h3>
|
||
|
||
<!-- #include "eb-sample-appendix.html" -->
|
||
|
||
<!-- ================================================================ -->
|
||
<h2><a name="book-list-on-server">サーバ上の書籍一覧</a></h2>
|
||
|
||
<p>
|
||
EBNET サーバから遠隔アクセスを行う際、サーバがそのクライアントに対して
|
||
アクセスを許可している書籍や appendix データの一覧を取得することが
|
||
できます。
|
||
</p>
|
||
|
||
<p>
|
||
このとき、EBNET サーバを指定する遠隔アクセス記述子には、特定の書籍や
|
||
appendix データに対するアクセスとは異なり、書籍名は指定しません。
|
||
すなわち、一般形は次のようになります。
|
||
</p>
|
||
|
||
<blockquote>
|
||
<pre>
|
||
ebnet://<var>ホスト</var>:<var>ポート</var>/
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
末尾の `/' はなくても構いません。
|
||
<samp>:</samp> とそれに続くポート番号は省略可能で、その場合は
|
||
22010 番ポートを利用することを意味します。
|
||
</p>
|
||
|
||
<p>
|
||
ebinfo コマンドの --book-list オプション指定時の挙動は、EB ライブラリ
|
||
のこの機能によって実装されています。
|
||
(ebinfo についての詳細は、
|
||
@pxref{Book list on EBNET server, , EBNET サーバの書籍一覧, ebinfo-ja, ebinfo-ja}。)
|
||
</p>
|
||
|
||
<blockquote>
|
||
<pre>
|
||
% ebinfo --book-list ebnet://localhost
|
||
名前 題名
|
||
encycl ブラウンコンサイス百科事典
|
||
encycl.app ブラウンコンサイス百科事典 (appendix)
|
||
crossword クロスワードパズル辞典
|
||
travel ワールドトラベルガイド
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
名前の末尾が <samp>.app</samp> になっているものは appendix データで、
|
||
その他は書籍本体です。
|
||
この例の書籍 <samp>encycl</samp> に対してアクセスするなら、
|
||
遠隔アクセス識別子は <code>ebnet://localhost/encycl</code> になります。
|
||
</p>
|
||
|
||
<p>
|
||
なお、クライアントに対してアクセスを許可していない書籍や appendix データ
|
||
は、サーが側で一覧から除外されます。
|
||
</p>
|
||
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="eb_booklist-object"><code>EB_BookList</code> オブジェクト</a></h3>
|
||
|
||
<p>
|
||
EBNET サーバの提供する書籍および appendix データの一覧を取得するには、
|
||
まず <code>EB_BookList</code> 型のオブジェクトを用意する必要があります。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
EB_BookList bl;
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
オブジェクトの領域は、<code>malloc()</code> で確保しても構いません。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
EB_BookList *bl_pointer;
|
||
|
||
bl_pointer = (EB_BookList *) malloc(sizeof(EB_BookList));
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
<code>EB_Book</code> オブジェクトと同様に、<code>EB_BookList</code>
|
||
オブジェクトも使う前に中身を初期化する必要があります。
|
||
これは、<code>eb_initialize_booklist()</code> という関数で行います。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
eb_initialize_booklist(&bl);
|
||
eb_initialize_booklist(bl_pointer);
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
初期化が完了したら、特定のサーバとオブジェクトを結びつけます。
|
||
たとえば、<code>ebnet://localhost</code> で表されるサーバに対して、
|
||
オブジェクトを結びつけるには次のようにします。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
if (eb_bind_booklist(&bl, "ebnet://localhost") != EB_SUCCESS) {
|
||
printf("eb_bind_booklist() failed\n");
|
||
return;
|
||
}
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
これはちょうど、<code>EB_Book</code> オブジェクトに対して
|
||
<code>eb_bind()</code> を呼ぶのと同じです。
|
||
</p>
|
||
|
||
<p>
|
||
こうして、ようやく書籍一覧の情報を取り出すことができます。
|
||
これには <code>eb_booklist_book_count()</code>,
|
||
<code>eb_booklist_book_name()</code>, <code>eb_booklist_book_title()</code>
|
||
という 3 つの関数を使用します。
|
||
これらの関数はそれぞれ、クライアントがアクセス可能な書籍の数、各書籍
|
||
および appendix データの名称 (アクセス識別子として指定する名前)、各書籍
|
||
と appendix データの題名を得ることができます。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
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);
|
||
}
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
<code>EB_BookList</code> オブジェクトを使い終わったら、必ず後始末を
|
||
行います。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
eb_finalize_booklist(&bl);
|
||
eb_finalize_booklist(bl_pointer);
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<p>
|
||
オブジェクトの領域を <code>malloc()</code> で確保した場合は、
|
||
<code>eb_finalize_booklist()</code> を呼んだ後ならば、オブジェクトの領域
|
||
を安全に解放することができます。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
free(bl_pointer);
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="booklist-data">データ型の詳細</a></h3>
|
||
|
||
<p>
|
||
この節で説明しているデータ型を使うには、次のようにヘッダファイルを
|
||
読み込んで下さい。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
#include <eb/booklist.h>
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="type:BookList"><code>EB_BookList</code> 型</a></h4>
|
||
|
||
<p>
|
||
<code>EB_BookList</code> 型は、EBNET サーバ上が使っている書籍および
|
||
appendix の一覧を取得する際に用いるオクジェクトの型です。
|
||
</p>
|
||
|
||
<p>
|
||
<code>EB_BookList</code> オブジェクトを使用する際は、まずそのオブジェクト
|
||
に対して <code>eb_initialize_booklist()</code> を呼んで初期化する必要が
|
||
あります。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="booklist-functions">関数の詳細</a></h3>
|
||
|
||
<p>
|
||
この節で説明している関数を使うには、次のようにヘッダファイルを読み込んで
|
||
下さい。
|
||
</p>
|
||
|
||
<blockquote class="program">
|
||
<pre>
|
||
#include <eb/booklist.h>
|
||
</pre>
|
||
</blockquote>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:initialize_booklist"><code>void eb_initialize_booklist (EB_BookList *<var>bl</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_initialize_booklist()</code> は、<var>bl</var> の指す
|
||
<code>EB_BookList</code> オブジェクトを初期化します。
|
||
<code>EB_BookList</code> オブジェクトに対して EB ライブラリの他の関数を
|
||
呼ぶ前に、必ずそのオブジェクトを初期化しなくてはなりません。
|
||
初期化していないオブジェクトに対して、EB ライブラリの他の関数を呼んだ
|
||
場合の動作は未定義です。
|
||
また、すでに初期化したオブジェクトに対して、
|
||
再度 <code>eb_initialize_booklist()</code> を呼んではいけません。
|
||
呼んだ場合の動作は未定義です。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:bind_booklist"><code>EB_Error_Code eb_bind_booklist (EB_BookList *<var>bl</var>, const char *<var>path</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_bind_booklist()</code> は、<var>app</var> の指す
|
||
<code>EB_BookList</code> オブジェクトを、遠隔アクセス記述子 <var>path</var>
|
||
で指定された EBNET サーバに結び付けます。
|
||
</p>
|
||
|
||
<p>
|
||
オブジェクトがすでにサーバに結び付いていた場合、そのサーバとの結び付き
|
||
を解いてから、<var>path</var> にあるサーバに結び付けます。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、関数は <code>EB_SUCCESS</code> を返します。
|
||
失敗すると、オブジェクトをサーバとの結び付きを解かれた状態にして、原因
|
||
を示すエラーコードを返します。
|
||
</p>
|
||
|
||
<p>
|
||
<var>path</var> は、<code>EB_MAX_PATH_LENGTH</code> バイトに収まて
|
||
いなくてはなりません。
|
||
これを超えると、<code>EB_ERR_TOO_LONG_FILE_NAME</code> を返します。
|
||
また、書籍名を指定していない遠隔アクセス記述子でなければなりません。
|
||
それ以外の形式だと、<code>EB_ERR_BAD_FILE_NAME</code> を返します。
|
||
</p>
|
||
|
||
<p>
|
||
使用している EB ライブラリのバイナリが、遠隔アクセスに非対応のもので
|
||
ある場合、<code>EB_ERR_EBNET_UNSUPPORTED</code> が返ります。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:finalize_booklist"><code>void eb_finalize_booklist (EB_BookList *<var>bl</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_finalize_booklist()</code> は、<var>bl</var> が指す
|
||
<code>EB_BookList</code> オブジェクトの後始末を行います。
|
||
</p>
|
||
|
||
<p>
|
||
オブジェクトが割り当てて管理していたメモリはすべて解放され、
|
||
ファイルディスクリプタもすべて閉じられます。
|
||
オブジェクトが EBNET サーバと結び付いていた場合は、結び付きが解かれます。
|
||
</p>
|
||
|
||
<p>
|
||
後始末をしたオブジェクトに対して <code>eb_bind_booklist()</code> を呼ぶ
|
||
ことで、オブジェクトを再利用することができます。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:booklist_book_count"><code>int eb_booklist_book_count (EB_BookList *<var>bl</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_booklist_book_count()</code> は、EBNET サーバがこの
|
||
クライアントに対してアクセスを許可している書籍および appendix データの数
|
||
を取得します。
|
||
</p>
|
||
|
||
<p>
|
||
オブジェクト <var>bl</var> の指す <code>EB_BookList</code> オブジェクトは、
|
||
あらかじめ EBNET サーバに結びついている必要があります。
|
||
結びついていない場合は、<code>EB_ERR_UNBOUND_BOOKLIST</code> を返します。
|
||
</p>
|
||
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:booklist_book_name"><code>EB_Error_Code eb_booklist_book_name (EB_BookList *<var>bl</var>, int <var>i</var>, char **<var>name</var>)</code></a></h4>
|
||
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
|
||
<h4><a name="func:booklist_book_title"><code>EB_Error_Code eb_booklist_book_title (EB_BookList *<var>bl</var>, int <var>i</var>, char **<var>title</var>)</code></a></h4>
|
||
|
||
<p>
|
||
関数 <code>eb_booklist_book_name()</code> は、EBNET サーバの書籍や
|
||
appendix データの名称を取得します。
|
||
ここで言う「名称」とは、遠隔アクセス識別子で指定する書籍名のことです。
|
||
つまり、<samp>ebnet://localhost/dict</samp> の <samp>dict</samp> の部分
|
||
を指します。
|
||
同様に、関数 <code>eb_booklist_book_title()</code> は、書籍や appendix
|
||
の題名を取得します。
|
||
</p>
|
||
|
||
<p>
|
||
いずれの関数も、EBNET サーバ上の何番目の書籍もしくは appendix の情報を
|
||
取得するのかを、引数 <var>i</var> で指定します。
|
||
先頭は 1 番目ではなく 0 番目になります。
|
||
</p>
|
||
|
||
<p>
|
||
成功すると、関数は書籍の名称、題名へのポインタを *<var>name</var>,
|
||
*<var>title</var> に書き込み、<code>EB_SUCCESS</code> を返します。
|
||
なお、このポインタ値は オブジェクト <code>bl</code> が保持している
|
||
文字列を指すようになっています。
|
||
<code>bl</code> に対して <code>eb_finalize_booklist()</code> を呼んで
|
||
しまうと、この文字列も参照不可能になってしまいますので、注意して下さい。
|
||
</p>
|
||
|
||
<p>
|
||
オブジェクト <var>bl</var> の指す <code>EB_BookList</code> オブジェクト
|
||
は、あらかじめ EBNET サーバに結びついている必要があります。
|
||
結びついていない場合は、<code>EB_ERR_UNBOUND_BOOKLIST</code> を返します。
|
||
また、<var>i</var> は 0 以上かつサーバが提供している書籍および appendix
|
||
の総数未満でなければなりません。
|
||
これ以外の値のときは、<code>EB_ERR_NO_SUCH_BOOK</code> が返ります。
|
||
</p>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="booklist-sample">サンプルプログラム</a></h3>
|
||
|
||
<!-- #include "eb-sample-booklist.html" -->
|
||
|
||
<!-- ================================================================ -->
|
||
<h2><a name="indice">索引</a></h2>
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="data-type-index">データ型の索引</a></h3>
|
||
|
||
<p>
|
||
型名の先頭の <code>EB_</code> は省略しています。
|
||
</p>
|
||
|
||
<!-- #include "eb-index-type.html" -->
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="function-index">関数の索引</a></h3>
|
||
|
||
<p>
|
||
関数名の先頭の <code>eb_</code> は省略しています。
|
||
</p>
|
||
|
||
<!-- #include "eb-index-func.html" -->
|
||
|
||
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
|
||
<h3><a name="const-index">定数の索引</a></h3>
|
||
|
||
<p>
|
||
定数名の先頭の <code>EB_</code> は省略しています。
|
||
</p>
|
||
|
||
<!-- #include "eb-index-const.html" -->
|
||
|
||
</body>
|
||
</html>
|