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


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() によって行います。

EB_Book            CD−ROM書籍
オブジェクト          ┌────────────┐
┌───┐           │            │
│   ┝━━━━━━━━━━━┥ /mnt/cdrom │
└───┘ 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 を返します。


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