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 を返します。

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