hashirama/ebclient
1
0
Fork 0
Code Issues Pull requests Actions Projects Releases Wiki Activity
ebclient/lib/ebu/doc/eb-05.html
Jacques De SAGAN 03de9e18bb first import
2024-04-07 11:52:06 +08:00

562 lines
17 KiB
HTML
Raw Permalink Blame History

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<!-- #file "eb.html" -->
<html lang="ja">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=euc-jp">
<link rel="stylesheet" type="text/css" href="eb.css">
<link rev="made" href="mailto:m-kasahr@sra.co.jp">
<title>EB ライブラリ</title>
</head>
<body>
<p>
[<a href="eb-04.html">前へ</a>] [<a href="eb-06.html">次へ</a>] [<a href="eb.html#toc">目次</a>]
</p>
<hr>
<h2><a name="eb_book">CD-ROM 書籍と <code>EB_Book</code> オブジェクト</a></h2>
<p>
EB ライブラリでは、CD-ROM 書籍へのアクセスは、すべて <code>EB_Book</code> 型
のオブジェクトを介して行います。
したがって、ほとんどのアプリケーションプログラムは、本章で記述している
処理を必要とするはずです。
</p>
<p>
本章では <code>EB_Book</code> オブジェクトの初期化、後始末といった基本的な
取り扱い方について説明します。
</p>
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
<h3><a name="eb_book-explanation"><code>EB_Book</code> オブジェクト</a></h3>
<p>
CD-ROM 書籍へアクセスするには、まず <code>EB_Book</code> 型のオブジェクトを
用意します。
同時に複数の CD-ROM 書籍にアクセスするなら、書籍一冊毎にオブジェクトを
作る必要があります。
</p>
<blockquote class="program">
<pre>
EB_Book book;
</pre>
</blockquote>
<p>
もちろん、オブジェクトの領域は、<code>malloc()</code> で確保しても
構いません。
</p>
<blockquote class="program">
<pre>
EB_Book *book_pointer;
book_pointer = (EB_Book *) malloc(sizeof(EB_Book));
</pre>
</blockquote>
<p>
<code>EB_Book</code> オブジェクトの中身 (変数 <code>book</code> の中身
および <code>book_pointer</code> の指す領域) はまだ初期化されていませんので、
次の要領でオブジェクトを初期化します。
</p>
<blockquote class="program">
<pre>
eb_initialize_book(&amp;book);
eb_initialize_book(book_pointer);
</pre>
</blockquote>
<p>
<code>eb_initialize()</code> へ渡す引数は <code>EB_Book</code> オブジェクト
へのポインタであって、<code>EB_Book</code> オブジェクトそのものでは
ないことに注意して下さい。
(EB ライブラリの他の関数も、すべてオブジェクトをポインタで渡します。)
</p>
<p>
CD-ROM 書籍を使うには、続いて <code>EB_Book</code> オブジェクトを
CD-ROM 書籍の実体に結び付けます。
これは、関数 <code>eb_bind()</code> によって行います。
</p>
<blockquote>
<pre>
ＥＢ＿Ｂｏｏｋ　　　　　　　　　　　　ＣＤ－ＲＯＭ書籍
オブジェクト　　　　　　　　　　┌────────────┐
┌───┐　　　　　　　　　　　│　　　　　　　　　　　　│
│　　　┝━━━━━━━━━━━┥　／ｍｎｔ／ｃｄｒｏｍ　│
└───┘　ｅｂ＿ｂｉｎｄ（）　│　　　　　　　　　　　　│
　　　　　　　　　　　　　　　　└────────────┘
</pre>
</blockquote>
<p>
実際のプログラムでは、次のようにします。
</p>
<blockquote class="program">
<pre>
if (eb_bind(&amp;book, "/mnt/cdrom") != EB_SUCCESS) {
printf("eb_bind() failed\n");
return;
}
</pre>
</blockquote>
<p>
<code>eb_bind()</code> に渡す書籍のパス (この例では <code>/mnt/cdrom</code>)
は書籍のトップディレクトリ、つまり <code>catalog</code> または
<code>catalogs</code> ファイルのあるディレクトリを指定します。
</p>
<p>
<code>EB_Book</code> オブジェクトを使い終わったら、
<code>eb_finalize_book()</code> を呼んで後始末をします。
オブジェクトは書籍との結び付きを解かれた状態に戻り、内部で割り当てられた
メモリは解放され、開いていたファイルもすべて閉じられます。
</p>
<blockquote class="program">
<pre>
eb_finalize_book(&amp;book);
eb_finalize_book(book_pointer);
</pre>
</blockquote>
<p>
オブジェクトの領域を <code>malloc()</code> で確保した場合は、
<code>eb_finalize_book()</code> を呼んだ後ならば、オブジェクトの領域を
安全に解放することができます。
</p>
<blockquote class="program">
<pre>
free(book_pointer);
</pre>
</blockquote>
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
<h3><a name="eb_bind-to-remote-host">遠隔ホストへの <code>eb_bind()</code></a></h3>
<p>
前節で説明した <code>eb_bind()</code> を用いて、<code>EB_Book</code>
オブジェクトを遠隔ホストの書籍に結びつけることができます。
これには、書籍のパスの代わりに、遠隔アクセス用の識別子を指定します。
識別子は、次のような形式をとります。
</p>
<blockquote>
<pre>
ebnet://<var>ホスト</var>:<var>ポート</var>/<var>書籍名</var>
</pre>
</blockquote>
<p>
<var>ホスト</var> は遠隔ホストの IP アドレスもしくはホスト名です。
ただし、IPv6 アドレスを指定する場合は、アドレスを <code>[</code> と
<code>]</code> で囲む必要があります。
<var>ポート</var> は、そのホストが待ち受けているポートの番号です。
ホストが待ち受けているポートが標準の 22010 番であれば、<var>:ポート</var>
の部分は省略可能です。
</p>
<p>
以下に <code>eb_bind()</code> のコード例を記します。
</p>
<blockquote class="program">
<pre>
if (eb_bind(&amp;book, "ebnet://localhost/cdrom") != EB_SUCCESS) {
printf("eb_bind() failed\n");
return;
}
</pre>
</blockquote>
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
<h3><a name="eb_book-sample">サンプルプログラム</a></h3>
<p>
このサンプルプログラムでは、CD-ROM 書籍の種類を調べるために、
<code>eb_disc_code()</code> という関数を使用しています。
この関数については、<a href="eb-05.html#eb_book-functions">「関数の詳細」</a> を参照のこと。
</p>
<blockquote>
<pre>
/* -*- 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 &lt;book-path&gt;
* 例:
* disctype /cdrom
* 説明:
* &lt;book-path&gt; で指定された CD-ROM 書籍の種類が、EB か EPWING か
* を調べて表示します。
*/
#include &lt;stdio.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;eb/eb.h&gt;
#include &lt;eb/error.h&gt;
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(&amp;book);
/* `book' を書籍に結び付ける。失敗したら終了。*/
error_code = eb_bind(&amp;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(&amp;book, &amp;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(&amp;book);
eb_finalize_library();
exit(0);
/* エラー発生で終了するときの処理。*/
die:
eb_finalize_book(&amp;book);
eb_finalize_library();
exit(1);
}
</pre>
</blockquote>
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
<h3><a name="eb_book-data-types">データ型の詳細</a></h3>
<p>
この節で説明しているデータ型を使うには、次のようにヘッダファイルを
読み込んで下さい。
</p>
<blockquote class="program">
<pre>
#include &lt;eb/eb.h&gt;
</pre>
</blockquote>
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<h4><a name="type:Book"><code>EB_Book</code> 型</a></h4>
<p>
<code>EB_Book</code> 型は、一冊の CD-ROM 書籍を表します。
CD-ROM 書籍へのアクセスは、すべてこの型のオブジェクトを介して行います。
同時に複数の CD-ROM 書籍にアクセスする際は、書籍一冊毎にオブジェクトを
作る必要があります。
</p>
<p>
<code>EB_Book</code> オブジェクトの操作は、すべて EB ライブラリが用意
している関数で行います。
アプリケーションプログラムは、直接 <code>EB_Book</code> オブジェクトの
メンバを参照したり、セットしたりすべきではありません。
</p>
<p>
<code>EB_Book</code> オブジェクトを使用する際は、まずそのオブジェクトに
対して <code>eb_initialize_book()</code> を呼んで初期化しなくては
なりません。
</p>
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<h4><a name="type:Disc_Code"><code>EB_Disc_Code</code> 型</a></h4>
<p>
データ型 <code>EB_Disc_Code</code> は、CD-ROM 書籍の形式コードを表します。
現在のところ、次の値が定義されています。
</p>
<dl>
<dt><code>EB_DISC_EB</code></dt>
<dd>
電子ブック (EB, EBG, EBXA, EBXA-C, S-EBXA) であることを表します。
<dt><code>EB_DISC_EPWING</code></dt>
<dd>
EPWING であることを表します。
<dt><code>EB_DISC_INVALID</code></dt>
<dd>
不正な形式コード値を表します。
</dl>
<p>
この型は符合付き整数型の別名として定義されていますので、2 つのコードを
2 項演算子 <code>==</code> と <code>!=</code> で一致比較することができます。
</p>
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<h4><a name="type:EB_Character_Code"><code>EB_Character_Code</code> 型</a></h4>
<p>
データ型 <code>EB_Character_Code</code> は、CD-ROM 書籍で使用される
文字コードを表します。
現在のところ、次の値が定義されています。
</p>
<dl>
<dt><code>EB_CHARCODE_ISO8859_1</code></dt>
<dd>
ISO 8859-1 (ラテン文字 1) を使用していることを表します。
電子ブックの EBG はこれです。
<dt><code>EB_CHARCODE_JISX0208</code></dt>
<dd>
JIS X 0208 (日本語のかな漢字) を使用していることを表します。
EBG, EBXA-C 以外の電子ブック、および EPWING はすべてこれです。
<dt><code>EB_CHARCODE_JISX0208_GB2312</code></dt>
<dd>
JIS X 0208 (日本語のかな漢字) と GB 2312 (中国語の簡体字) を併用している
ことを表します。
電子ブックの EBXA-C はこれです。
<dt><code>EB_CHARCODE_INVALID</code></dt>
<dd>
不正な文字コード値を表します。
</dl>
<p>
この型は符合付き整数型の別名として定義されていますので、2 つのコードを
2 項演算子 <code>==</code> と <code>!=</code> で一致比較することができます。
</p>
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = -->
<h3><a name="eb_book-functions">関数の詳細</a></h3>
<p>
この節で説明している関数を使うには、次のようにヘッダファイルを読み込んで
下さい。
</p>
<blockquote class="program">
<pre>
#include &lt;eb/eb.h&gt;
</pre>
</blockquote>
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<h4><a name="func:initialize_book"><code>void eb_initialize_book (EB_Book *<var>book</var>)</code></a></h4>
<p>
関数 <code>eb_initialize_book()</code> は、<var>book</var> の指す
<code>EB_Book</code> オブジェクトを初期化します。
<code>EB_Book</code> オブジェクトに対して EB ライブラリの他の関数を呼ぶ前に、
必ずそのオブジェクトを初期化しなくてはなりません。
初期化していないオブジェクトに対して、EB ライブラリの他の関数を呼んだ
場合の動作は未定義です。
また、すでに初期化したオブジェクトに対して、再度
<code>eb_initialize_book()</code> を呼んではいけません。
呼んだ場合の動作は未定義です。
</p>
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<h4><a name="func:bind"><code>EB_Error_Code eb_bind (EB_Book *<var>book</var>, const char *<var>path</var>)</code></a></h4>
<p>
関数 <code>eb_bind()</code> は、<var>book</var> の指す <code>EB_Book</code>
オブジェクトを、パス <var>path</var> にある CD-ROM 書籍に結び付けます。
パスには、書籍のトップディレクトリか遠隔アクセス識別子を指定します。
書籍のトップディレクトリとは、<code>catalog</code> あるいは
<code>catalogs</code> ファイルの存在するディレクトリを指します。
</p>
<p>
オブジェクトがすでに書籍に結び付いていた場合、その書籍との結び付きを
解いてから、<var>path</var> にある書籍に結び付けます。
</p>
<p>
成功すると、関数は <code>EB_SUCCESS</code> を返します。
このとき、副本は未選択の状態になります。
失敗すると、オブジェクトを書籍との結び付きを解かれた状態にして、原因
を示すエラーコードを返します。
</p>
<p>
<var>path</var> は、<code>EB_MAX_PATH_LENGTH</code> バイトに収まていなくては
なりません。
さらに、<var>path</var> が相対パスのときは、絶対パスに変換した結果がこの長さ
に収まっていなくてはなりません。
これを超えると、<code>EB_ERR_TOO_LONG_FILE_NAME</code> を返します。
</p>
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<h4><a name="func:finalize_book"><code>void eb_finalize_book (EB_Book *<var>book</var>)</code></a></h4>
<p>
関数 <code>eb_finalize_book()</code> は、<var>book</var> が指す
<code>EB_Book</code> オブジェクトの後始末を行います。
</p>
<p>
オブジェクトが割り当てて管理していたメモリはすべて解放され、
ファイルディスクリプタもすべて閉じられます。
オブジェクトが書籍と結び付いていた場合は、結び付きが解かれます。
</p>
<p>
後始末をしたオブジェクトに対して <code>eb_bind()</code> を呼ぶことで、
オブジェクトを再利用することができます。
</p>
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<h4><a name="func:is_bound"><code>int eb_is_bound (EB_Book *<var>book</var>)</code></a></h4>
<p>
関数 <code>eb_is_bound()</code> は、<var>book</var> が書籍に結び付いているか
どうかを調べます。
結び付いていれば 1 を返し、そうでなければ 0 を返します。
</p>
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<h4><a name="func:path"><code>EB_Error_Code eb_path (EB_Book *<var>book</var> const char *<var>path</var>)</code></a></h4>
<p>
関数 <code>eb_path()</code> は、<var>book</var> に結び付いている書籍のパス
もしくは遠隔アクセス識別子を、<var>path</var> の指す領域に書き込みます。
</p>
<p>
成功すると、関数は <code>EB_SUCCESS</code> を返します。
失敗すると、<var>path</var> の指す領域に空文字列を書き込み、原因を示す
エラーコードを返します。
</p>
<p>
<var>book</var> は、あらかじめ書籍に結び付いている必要があります。
結びついていない場合は、<code>EB_ERR_UNBOUND_BOOK</code> を返します。
</p>
<p>
<var>path</var> に書き込むパス名のバイト数は、最長で
<code>EB_MAX_PATH_LENGTH</code> になります。
この長さは、末尾のナル文字を含みません。
関数が返すパスは正規化された形になっているので、<code>eb_bind()</code> に
渡したときのものと同じとは限りません。
たとえば、相対パスだった場合は、絶対パスに変換されます。
</p>
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<h4><a name="func:disc_type"><code>EB_Error_Code eb_disc_type (EB_Book *<var>book</var>, EB_Disc_Code *<var>disc_code</var>)</code></a></h4>
<p>
関数 <code>eb_disc_type()</code> は、<var>book</var> のディスクの形式を
<var>disc_code</var> の指す領域に書き込みます。
書き込むディスクの形式の値は、<code>EB_Disc_Code</code> 型
(<a href="eb-05.html#eb_book-data-types">「[CD-ROM 書籍と <code>EB_Book</code> オブジェクト] データ型の詳細」</a> を参照のこと)
のいずれかの定数値です。
</p>
<p>
成功すると、関数は <code>EB_SUCCESS</code> を返します。
失敗すると、<var>disc_code</var> の指す領域に <code>EB_DISC_INVALID</code>
を書き込み、原因を示すエラーコードを返します。
</p>
<p>
<var>book</var> は、あらかじめ書籍に結び付いていなければなりません。
結びついていない場合は、<code>EB_ERR_UNBOUND_BOOK</code> を返します。
</p>
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<h4><a name="func:character_code"><code>EB_Error_Code eb_character_code (EB_Book *<var>book</var>, EB_Character_Code *<var>character_code</var>)</code></a></h4>
<p>
関数 <code>eb_character_code()</code> は、<var>book</var> が書かれている
文字コードを <var>character_code</var> の指す領域に書き込みます。
書き込む文字コードの値は、<code>EB_Character_Code</code> 型
(<a href="eb-05.html#eb_book-data-types">「[CD-ROM 書籍と <code>EB_Book</code> オブジェクト] データ型の詳細」</a> を参照のこと)
のいずれかの定数値です。
</p>
<p>
成功すると、関数は <code>EB_SUCCESS</code> を返します。
失敗すると、<var>character_code</var> の指す領域に
<code>EB_CHARCODE_INVALID</code> を書き込み、原因を示すエラーコードを
返します。
</p>
<p>
<var>book</var> は、あらかじめ書籍に結び付いていなければなりません。
結びついていない場合は、<code>EB_ERR_UNBOUND_BOOK</code> を返します。
</p>
<!-- ================================================================ -->
<hr>
<p>
[<a href="eb-04.html">前へ</a>] [<a href="eb-06.html">次へ</a>] [<a href="eb.html#toc">目次</a>]
</p>
</body>
</html>
Reference in a new issue View git blame Copy permalink