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_DISC_EPWING
EB_DISC_INVALID
この型は符合付き整数型の別名として定義されていますので、2 つのコードを
2 項演算子 ==
と !=
で一致比較することができます。
EB_Character_Code
型
データ型 EB_Character_Code
は、CD-ROM 書籍で使用される
文字コードを表します。
現在のところ、次の値が定義されています。
EB_CHARCODE_ISO8859_1
EB_CHARCODE_JISX0208
EB_CHARCODE_JISX0208_GB2312
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
を返します。