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:
以下の振る舞いも想定している

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は次のような振る舞いを想定している。

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