EB ライブラリ

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

## 副本

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

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

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

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

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

### 副本コード

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

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

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

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

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

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

>     char title[EB_MAX_TITLE_LENGTH + 1];

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

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

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

### 選択中の副本

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

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

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

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

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

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

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

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

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

>     /*                                                            -*- 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 が書籍に結び付いていないか、副本が選択されていない場合は、 何もしません。

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