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