Define and document IsoStream interface.

This commit is contained in:
Vreixo Formoso 2007-11-27 00:27:57 +01:00
parent 100919a5cb
commit b9152421f3

View File

@ -11,7 +11,7 @@
/*
* Definitions of streams.
*/
/*
* Some functions here will be moved to libisofs.h when we expose
* Streams.
@ -19,27 +19,76 @@
typedef struct Iso_Stream IsoStream;
struct Iso_Stream
struct Iso_Stream
{
/**
* Opens the stream.
* @return 1 on success, < 0 on error
*/
int (*open)(IsoStream *stream);
/**
* Close the Stream.
/**
* Opens the stream.
*
* @return
* 1 on success, < 0 on error, 2 file is smaller than expect,
* 3 file is larger than expected (2 and 3 are not errors, they're
* handled by read_block, see there. Moreover, IsooStream
* implementations doesn't need to check that)
*/
int (*open)(IsoStream *stream);
/**
* Close the Stream.
* @return 1 on success, < 0 on error
*/
int (*close)(IsoStream *stream);
// Stream should read in 2k blocks!
//...
int refcount;
void *data;
*/
int (*close)(IsoStream *stream);
/**
* Get the size (in bytes) of the stream. This function must return
* always the same size, even if the underlying source file has changed.
*/
off_t (*get_size)(IsoStream *stream);
/**
* Read a block (2048 bytes) from the stream.
*
* This function should always read the full 2048 bytes, blocking if
* needed. When it reaches EOF, the buf is filled with 0's, if needed.
* Note that the EOF is not reported in that call, but in the next call.
* I.e., when the EOF is reported you can be sure that the function
* has not written anything to the buffer. If the file size is a multiple
* of block size, i.e N*2048, the read_block reports the EOF just when
* reading the N+1 block.
*
* Note that EOF refers to the original size as reported by get_size.
* If the underlying source size has changed, this function should take
* care of this, truncating the file, or filling the buffer with 0s. I.e.
* this function return 0 (EOF) only when get_size() bytes have been
* readed.
*
* On an I/O error, or a file smaller than the expected size, this
* function returns a [specific error code], and the buffer is filled
* with 0s. Subsequent calls will still return an error code and fill
* buffer with 0's, until EOF (as defined above) is reached, and then
* the function will return 0.
*
* Note that if the current size is larger than expected, you don't get
* any error on reading.
*
* @param buf
* Buffer where data fill be copied, with at least 2048 bytes.
* @return
* 1 sucess, 0 EOF, < 0 error (buf is filled with 0's)
*/
int (*read_block)(IsoStream *stream, void *buf);
/**
* Whether this Stram can be read several times, with the same results.
* For example, a regular file is repeatable, you can read it as many
* times as you want. However, a pipe isn't.
*
* This function doesn't take into account if the file has been modified
* between the two reads.
*/
int (*is_repeatable)(IsoStream *stream);
int refcount;
void *data;
}
#endif /*STREAM_H_*/