EB ライブラリ

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

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

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

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

### `EB_Book` オブジェクト

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

>     EB_Book book;

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

>     EB_Book *book_pointer;

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

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

>     eb_initialize_book(&book);
>     eb_initialize_book(book_pointer);

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

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

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

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

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

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

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

>     eb_finalize_book(&book);
>     eb_finalize_book(book_pointer);

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

>     free(book_pointer);

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

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

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

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

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

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

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

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

>     /*                                                            -*- 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.
>      */

>     /*
>      * 使用方法:
>      *     disctype <book-path>
>      * 例:
>      *     disctype /cdrom
>      * 説明:
>      *     <book-path> で指定された CD-ROM 書籍の種類が、EB か EPWING か
>      *     を調べて表示します。
>      */
>     #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_Disc_Code disc_code;

>         /* コマンド行引数をチェック。*/
>         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_disc_type(&book, &disc_code);
>         if (error_code != EB_SUCCESS) {
>             fprintf(stderr, "%s: failed to get disc type, %s: %s\n",
>                 argv[0], eb_error_message(error_code), argv[1]);
>             goto die;
>         }

>         if (disc_code == EB_DISC_EB) {
>             fputs("EB\n", stdout);
>         } else if (disc_code == EB_DISC_EPWING) {
>             fputs("EPWING\n", stdout);
>         } else {
>             fputs("unknown\n", stdout);
>         }

>         /* 書籍と 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_Book` 型

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

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

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

#### `EB_Disc_Code` 型

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

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

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

#### `EB_Character_Code` 型

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

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

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

### 関数の詳細

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

>     #include <eb/eb.h>

#### `void eb_initialize_book (EB_Book *book)`

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

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

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

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

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

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

#### `void eb_finalize_book (EB_Book *book)`

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

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

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

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

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

#### `EB_Error_Code eb_path (EB_Book *book const char *path)`

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

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

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

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

#### `EB_Error_Code eb_disc_type (EB_Book *book, EB_Disc_Code *disc_code)`

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

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

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

#### `EB_Error_Code eb_character_code (EB_Book *book, EB_Character_Code *character_code)`

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

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

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

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