Vorbisfile documentation |
libVorbisfile version 1.65 - 20020702 |
Callbacks and non-stdio I/O
Although stdio is convenient and nearly universally implemented as per
ANSI C, it is not suited to all or even most potential uses of Vorbis.
For additional flexibility, embedded applications may provide their
own I/O functions for use with Vorbisfile when stdio is unavailable or not
suitable. One common example is decoding a Vorbis stream from a
memory buffer.
stdioが便利でANSI Cとして世界的に実装されているとしても、Vorbisの使用に最大限の威力を発揮するわけではない。
追加する柔軟性として、stdioが使用できないか適切でない場合のために、組み込みアプリケーションが独自のI/O機能をVorbisfileに使用させるために提供できる。
1つの一般的な例として、メモリバッファからVorbisストリームをデコードすることがあげられる。
Use custom I/O functions by populating an ov_callbacks structure and calling ov_open_callbacks() or ov_test_callbacks() rather than the
typical ov_open() or ov_test(). Past the open call, use of
libvorbisfile is identical to using it with stdio.
カスタマイズされたI/O関数を ov_callbacks 構造体にセットし、ov_open_callbacks() か ov_test_callbacks() を
ov_open() や ov_test() の変わりに呼び出すことで使用する。
呼び出しの後は、libvrobisfileがstdioと同様に使用する。
Read function
The read-like function provided in the read_func field is
used to fetch the requested amount of data. It expects the fetch
operation to function similar to file-access, that is, a multiple read
operations will retrieve contiguous sequential pieces of data,
advancing a position cursor after each read.
read_func フィールドで提供される読み込み関数は、要求するデータの総量を与えて呼び出される。
ファイルアクセスに似た関数の読み出し処理を、つまり、
複数回の読み込み処理はそれぞれの処理の後に位置を更新し、後続するデータを取り出すことを期待している。
The following behaviors are also expected:
以下の振る舞いも想定している
- a return of '0' indicates end-of-data (if the by-thread errno is unset)
データの終わりでは0を返す(もしスレッドによってerrnoが設定されて無い場合(?))
- short reads mean nothing special (short reads are not treated as error conditions)
短い読み出しは特にない。(短い読み出しはエラーとしは扱わない)
- a return of zero with the by-thread errno set to nonzero indicates a read error
スレッドによってerrnoを0以外に設定し、0を返した場合は読み込みエラーを示す
Seek function
The seek-like function provided in the seek_func field is
used to request non-sequential data access by libvorbisfile, moving
the access cursor to the requested position.
seek_func フィールドで提供される移動関数は連続的でないデータのアクセスをlibvorbisfileが要求するときに、
アクセスカーソルを要求する位置に移動するために使用される。
libvorbisfile expects the following behavior:
libvorbisfileは次のような振る舞いを想定している。
- The seek function must always return -1 (failure) if the given
data abstraction is not seekable. It may choose to always return -1
if the application desires libvorbisfile to treat the Vorbis data
strictly as a stream (which makes for a less expensive open
operation).
与えられたデータ概念が移動不可能であるとき、移動関数は常に -1(失敗) を返さなければならない。
アプリケーションが、LibvorbisにVorbisデータがストリームであるように扱って欲しいとき
(これは開く処理をより少ないコストで行うことができる)、常に -1 を返すこともできる。
- If the seek function initially indicates seekability, it must
always succeed upon being given a valid seek request.
もし移動関数が最初に使用可能であることを示したなら、
有効な移動要求が与えられたときは常に成功しなければならない。
- The seek function must implement all of SEEK_SET, SEEK_CUR and
SEEK_END. The implementation of SEEK_END should set the access cursor
one past the last byte of accessible data, as would stdio
fseek()
移動関数は SEEK_SET 、SEEK_CUR および SEEK_END のすべてを実装しなければならない。
SEEK_END は stdio の fseek() のようにアクセス可能な最後のバイトの1つ先にアクセスカーソルをセットするように実装するべきである。
Close function
The close function should deallocate any access state used by the
passed in instance of the data access abstraction and invalidate the
instance handle. The close function is assumed to succeed.
クローズ関数は渡されたデータアクセスのインスタンスを使って、すべてのデータを解放し、
インスタンスハンドルを無効にすべきである。
クローズ関数は成功することを想定している。
One common use of callbacks and the close function is to change the
behavior of libvorbisfile with respect to file closure for applications
that must fclose data files themselves. By passing
the normal stdio calls as callback functions, but passing a
close_func that does nothing, an application may call ov_clear() and then fclose() the
file originally passed to libvorbisfile.
コールバックの1つの一般的な使用方法では、
クローズ機能はアプリケーションにファイルの閉鎖を伝えるため、libvorbisfile は振る舞いをかえる(彼ら自身でデータファイルを fclose する必要がある)。
通常のstdioをコールバック関数として渡すとき、close_func は何も行わず、
アプリケーションが ov_clear() を呼び、そのとき libvorbisfile へ渡した元のファイルは fclose() される。
Tell function
The tell function is intended to mimic the
behavior of ftell() and must return the byte position of the
next data byte that would be read. If the data access cursor is at
the end of the 'file' (pointing to one past the last byte of data, as
it would be after calling fseek(file,SEEK_END,0)), the tell
function must return the data position (and thus the total file size),
not an error.
位置通知関数は ftell() と同じように振る舞い、次に読むべきデータの位置をバイト単位で返す必要がある。
もしデータアクセスカーソルがファイルの終わりにあるとき(fseek(file,SEEK_END,0) の呼び出しのあとのように最後のバイトの1つ先をさしているとき)、
位置通知関数は必ずエラーではなくデータの位置(つまりファイルの合計サイズ)を返さなければならない
The tell function need not be provided if the data IO abstraction is
not seekable.
位置通知関数は使うIOデータの概念では移動可能でない場合提供する必要は無い。
copyright © 2002 Xiph.org |
Ogg Vorbis |
Vorbisfile documentation |
libVorbisfile version 1.65 - 20020702 |