紙に印刷された本では別々の書籍になっているものでも、電子ブックや EPWING では 1 枚の CD-ROM にまとめることができます。
たとえば、ある CD-ROM 書籍は、国語辞書、英々辞典、百科事典という 3 つ の (印刷された本で言うところの) 「書籍」を持っていることもあり得ます。 紛らわしさを避けるために、EB ライブラリではここで言う「書籍」のことを 副本 (subbook) と呼んでいます。
CD−ROM書籍 ┌─────────────┐ │ 副本0: [国語辞典] │ │ 副本1: [英々辞典] │ │ 副本2: [百科事典] │ └─────────────┘
CD-ROM 書籍では、それぞれの副本はそれ自体が独立した書籍になっています。 また、副本のデータも、副本毎に別々のファイルに収められています。 したがって、EB ライブラリでも、アプリケーションプログラムの主要な処理 である単語の検索や本文データの取得などは、すべて副本単位で行うように なっています。
本章では、EB ライブラリでの副本の扱い方について説明します。
EB ライブラリでは、それぞれの副本に対して 副本コード (subbook code) を割り当てます。 このコードは EB ライブラリが副本を識別するために用いますので、個々の 副本コードは、書籍内で同じものがないようになっています。
以下のソースコードは、eb_subbook_list()
という関数の
使用例です。
この関数は、書籍内のすべての副本の副本コードを取得することができます。
/*book
がEB_Book
のオブジェクトで、すでに * 書籍に結び付けられていると仮定しています。*/ EB_Subbook_Code sub_codes[EB_MAX_SUBBOOKS]; int sub_count; if (eb_subbook_list(&book, sub_codes, &sub_count) != EB_SUCCESS) { printf("eb_subbook_list() failed\n"); return; }
eb_subbook_list()
が成功すると、書籍内のすべての副本コードが
配列 sub_codes[]
に格納されます。
配列の先頭の副本コードは sub_codes[0]
と表され、次の
コードは sub_codes[1]
、という具合になります。
副本の個数は、sub_count
に格納されます。
個々の副本には、必ず題名が付けられています。
先頭の副本 (sub_codes[0]
) の題名は、次のようにして
得ることができます。
char title[EB_MAX_TITLE_LENGTH + 1]; if (eb_subbook_title2(&book, sub_codes[0], title) != EB_SUCCESS) { printf("eb_subbook_title2() failed\n"); return; }
eb_subbook_title2()
の呼び出しが成功すると、
title
に題名を表す文字列が格納されます。
蛇足ですが、(副本ではなく) CD-ROM の題名を取得する関数はありません。 なぜなら、題名を示すデータが CD-ROM の中には何処にもないからです。
EB_Book
オブジェクトは、結びつけられた CD-ROM 書籍の中の
任意の副本から一つ選んで、選択中の副本 (current subbook)
として指定することができます。
複数の副本を、同時に選択することはできません。
単語の検索や、本文データの取得など、ほとんどの操作は、選択中の副本に
対してだけ行えます。
eb_bind()
で EB_Book
オブジェクトを書籍に
結び付けた直後は、いずれの副本も選択されていない状態になっています。
EB_Book CD−ROM書籍 オブジェクト ┌────┐ ┌─────────────┐ │選択中 │ │ 副本0: [国語辞典] │ │の副本 │ │ 副本1: [英々辞典] │ │<なし>│ │ 副本2: [百科事典] │ └────┘ └─────────────┘
副本の選択を行うには、関数 eb_set_subbook()
を使用します。
eb_set_subbook()
は、引数として渡された副本コードに
したがって副本を選択します。
以下は、先頭の副本 (sub_codes[0]
) を選択する場合の例です。
/*book
がEB_Book
のオブジェクトで、すでに * 書籍に結び付けられていると仮定しています。*/ EB_Subbook_Code sub_codes[EB_MAX_SUBBOOKS]; int sub_count; if (eb_subbook_list(&book, sub_codes, &sub_count) != EB_SUCCESS) { printf("eb_subbook_list() failed\n"); return; } if (eb_set_subbook(&book, sub_codes[0]) != EB_SUCCESS) { printf("eb_subbook_list() failed\n"); return; }
成功すると、次のように副本が選択された状態になります。
EB_Book CD−ROM書籍 オブジェクト ┌────┐ ┌─────────────┐ │選択中 │ ┏━━━━┿━副本0: [国語辞典] │ │の副本 │ ┃ │ 副本1: [英々辞典] │ │ *━━┿━━┛ │ 副本2: [百科事典] │ └────┘ └─────────────┘
/* -*- C -*- * Copyright (c) 1999-2006 Motoyuki Kasahara * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * 1. Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * 2. Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in the * documentation and/or other materials provided with the distribution. * 3. Neither the name of the project nor the names of its contributors * may be used to endorse or promote products derived from this software * without specific prior written permission. * * THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE * ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF * SUCH DAMAGE. */ /* * 使用方法: * subbook <book-path> * 例: * subbook /cdrom * 説明: * <boook-path> で指定され CD-ROM 書籍に含まれているすべての副本の * 題名を表示します。 */ #include <stdio.h> #include <stdlib.h> #include <eb/eb.h> #include <eb/error.h> int main(int argc, char *argv[]) { EB_Error_Code error_code; EB_Book book; EB_Subbook_Code subbook_list[EB_MAX_SUBBOOKS]; int subbook_count; char title[EB_MAX_TITLE_LENGTH + 1]; int i; /* コマンド行引数をチェック。*/ if (argc != 2) { fprintf(stderr, "Usage: %s book-path\n", argv[0]); exit(1); } /* EB ライブラリと `book' を初期化。*/ error_code = eb_initialize_library(); if (error_code != EB_SUCCESS) { fprintf(stderr, "%s: failed to initialize EB Library, %s: %s\n", argv[0], eb_error_message(error_code), argv[1]); goto die; } eb_initialize_book(&book); /* 書籍を `book' に結び付ける。*/ error_code = eb_bind(&book, argv[1]); if (error_code != EB_SUCCESS) { fprintf(stderr, "%s: failed to bind the book, %s: %s\n", argv[0], eb_error_message(error_code), argv[1]); goto die; } /* 副本の一覧を取得。*/ error_code = eb_subbook_list(&book, subbook_list, &subbook_count); if (error_code != EB_SUCCESS) { fprintf(stderr, "%s: failed to get the subbbook list, %s\n", argv[0], eb_error_message(error_code)); goto die; } /* 書籍に含まれている副本の題名を出力。*/ for (i = 0; i < subbook_count; i++) { error_code = eb_subbook_title2(&book, subbook_list[i], title); if (error_code != EB_SUCCESS) { fprintf(stderr, "%s: failed to get the title, %s\n", argv[0], eb_error_message(error_code)); continue; } printf("%d: %s\n", i, title); } /* 書籍と EB ライブラリの利用を終了。*/ eb_finalize_book(&book); eb_finalize_library(); exit(0); /* エラー発生で終了するときの処理。*/ die: eb_finalize_book(&book); eb_finalize_library(); exit(1); }
この節で説明しているデータ型を使うには、次のようにヘッダファイルを 読み込んで下さい。
#include <eb/eb.h>
EB_Subbook_Code
型
データ型 EB_Subbook_Code
は副本コードを表します。
一冊の書籍の中の副本は、それぞれ一意の副本コードを持っています。
この型は符合付き整数型の別名として定義されていますので、2 つのコードを
2 項演算子 ==
と !=
で一致比較することが
できます。
また、不正な副本コード値を表す EB_SUBBOOK_INVALID
という
特別な副本コードが定義されています。
利用可能な副本に対して、この副本コードが割り当てられることはありません。
この節で説明している関数を使うには、次のようにヘッダファイルを読み込んで 下さい。
#include <eb/eb.h>
EB_Error_Code eb_load_all_subbooks (EB_Book *book)
関数 eb_load_all_subbooks()
は、book 内のすべての
副本を初期化します。
通常、副本の初期化は、その副本が初めて選択されたときに自動的に行われますが、
この関数は初期化を前倒しで行います。
初期化の対象となるのは、この関数を呼び出した時点でまだ初期化していない
すべての副本です。
この関数は、スタンドアロンで動作するサーバアプリケーションなどで有効です。
クライアントからの接続を受ける前にこの関数を呼ぶことで、副本の初期化の
ためにクライアントを待たせなくて済みます。
初期化の対象となったすべての副本の初期化に成功すれば、関数は
EB_SUCCESS
を返します。
一冊でも初期化に失敗した場合は、残りの副本の初期化を諦め、原因を示す
エラーコードを返します。
book は、あらかじめ書籍に結び付けられていなくてはなりません。
結びついていない場合は、EB_ERR_UNBOUND_BOOK
を返します。
この関数を呼び出すと、book は、副本を選択していない状態になります。
EB_Error_Code eb_subbook_list (EB_Book *book, EB_Subbook_Code *subbook_list, int *subbook_count)
関数 eb_subbook_list()
は、book 内のすべて副本の
副本コードを EB_Subbook_Code
型の配列にして、
subbook_list の指す領域に書き込みます。
配列は、最大で EB_MAX_SUBBOOKS
個の要素を持ちます。
加えて、書籍が収録している副本の個数を subbook_count の指す
領域に書き込みます。
成功すると、関数は EB_SUCCESS
を返します。
失敗すると、subbook_count の指す領域に 0 を書き込み、原因を
示すエラーコードを返します。
book は、あらかじめ書籍に結び付けられていなくてはなりません。
結びついていない場合は、EB_ERR_UNBOUND_BOOK
を返します。
EB_Error_Code eb_subbook (EB_Book *book, EB_Subbook_Code *subbook_code)
関数 eb_subbook()
は、book が選択中の副本の
副本コードを subbook_code の指す領域に書き込みます。
成功すると、関数は EB_SUCCESS
を返します。
失敗すると、subbook_code の指す領域に
EB_SUBBOOK_INVALID
を書き込み、原因を示すエラーコードを
返します。
あらかじめ、book はいずれかの副本を選択していなくてはなりません。
選択していない場合は、EB_ERR_NO_CUR_SUB
を返します。
EB_Error_Code eb_subbook_title (EB_Book *book, char *title)
関数 eb_subbook_title()
は、book が選択中の副本の
題名を title の指す領域に文字列として書き込みます。
題名の文字列の長さは、最長で EB_MAX_TITLE_LENGTH
バイトです。
この長さは、末尾のナル文字を含みません。
書籍の文字コード
(「[CD-ROM 書籍と EB_Book
オブジェクト] データ型の詳細」 を参照のこと)
が EB_CHARCODE_ISO8859_1
なら、題名を表す文字列は ISO 8859-1
になり、それ以外の文字コードなら日本語 EUC になります。
成功すると、関数は EB_SUCCESS
を返します。
失敗すると、title の指す領域に空文字列を書き込み、原因を示す
エラーコードを返します。
あらかじめ、book 内のいずれかの副本が選択されていなくては
なりません。
選択していない場合は、EB_ERR_NO_CUR_SUB
を返します。
EB_Error_Code eb_subbook_title2 (EB_Book *book, EB_Subbook_Code subbook_code, char *title)
eb_subbook_title()
と似ていますが、選択中の副本ではなく、
引数 subbook_code で指定された副本の題名を書き込む点が
異なります。
book は副本を選択していなくても構いませんが、あらかじめ書籍
に結び付けられていなければなりません。
結びついていない場合は、EB_ERR_UNBOUND_BOOK
を返します。
EB_Error_Code eb_subbook_directory (EB_Book *book, char *directory)
関数 eb_subbook_directory()
は、book 内で現在
選択中の副本のデータファイルを収めたディレクトリ名を、directory
の指す領域に書き込みます。
ディレクトリ名の文字列の長さは、最長で
EB_MAX_DIRECTORY_NAME_LENGTH
バイトです。
この長さに、末尾のナル文字は含みません。
ディレクトリ名は ASCII の数字、英小文字、アンダースコアで構成されます。
成功すると、関数は EB_SUCCESS
を返します。
失敗すると、directory の指す領域に空文字列を書き込み、原因に
を示すエラーコードを返します。
あらかじめ、book 内のいずれかの副本が選択されていなくては
なりません。
選択していない場合は、EB_ERR_NO_CUR_SUB
を返します。
EB_Error_Code eb_subbook_directory2 (EB_Book *book, EB_Subbook_Code subbook_code, char *directory)
eb_subbook_directory()
と似ていますが、選択中の副本ではなく、
引数 subbook_code で指定された副本のディレクトリ名を書き込む点
が異なります。
book は副本を選択していなくても構いませんが、あらかじめ
書籍に結び付けられていなければなりません。
結びついていない場合は、EB_ERR_UNBOUND_BOOK
を返します。
EB_Error_Code eb_set_subbook (EB_Book *book, EB_Subbook_Code code)
関数 eb_set_subbook()
は、book の副本
code を選択します。
すでに副本を選択していた場合は、いったん未選択の状態にしてから副本
subbook_code を選択します。
成功すると、関数は EB_SUCCESS
を返します。
このとき、外字は未選択の状態となり、検索、テキストデータの読み込み、
バイナリデータの読み込みについての状態記録は、すべてリセットされます。
失敗すると、副本を未選択の状態にして、原因を示すエラーコードを返します。
あらかじめ、book は書籍に結び付けられていなければなりません。
結びついていない場合は、EB_ERR_UNBOUND_BOOK
を返します。
void eb_unset_subbook (EB_Book *book)
関数 eb_unset_subbook()
は、book が選択している
副本を未選択の状態にします。
book が書籍に結び付いていないか、副本が選択されていない場合は、
何もしません。