|
eaarl-io
1.0.1+71abbd4
EAARL Input/Output Library (Public API)
|
Stream interface. More...
#include <stream.h>
Data Fields | |
| eaarlio_error(* | close )(struct eaarlio_stream *self) |
| Close the stream. More... | |
| eaarlio_error(* | read )(struct eaarlio_stream *self, uint64_t len, unsigned char *buffer) |
| Read bytes from a stream and place them in a buffer. More... | |
| eaarlio_error(* | write )(struct eaarlio_stream *self, uint64_t len, unsigned char const *buffer) |
| Writes bytes from a buffer to a stream. More... | |
| eaarlio_error(* | seek )(struct eaarlio_stream *self, int64_t offset, int whence) |
| Set the current position for the stream. More... | |
| eaarlio_error(* | tell )(struct eaarlio_stream *self, int64_t *position) |
| Retrieve the current position in the stream. More... | |
| void * | data |
| Internal data pointer. More... | |
Stream interface.
This interface generalizes the operations needed to read from and write to a file. The intent is to make it possible to read from streams other than a "normal" file: for example, a compressed file.
Each function accepts as its first parameter a pointer to the eaarlio_stream. This gives the functions access to the stream's data field, which is a pointer to whatever the implementation may need for internal state.
All functions return an eaarlio_error and should use EAARLIO_SUCCESS to represet a successful outcome. If it is not plausible to provide an implementation for a given function, then it should return EAARLIO_STREAM_NOT_IMPL. Each function is documented with some suggested error codes for other failing conditions, but you are not restricted to those listed. You can return any valid eaarlio_error value as needed.
This interface is intended to support random-access reads and writes. Not all streams are suitable for random-access. In such cases, your stream should pretend to be random-access as much as is possible. For example, requests to seek should succeed if they're to a current position; requests to seek for a future position should simply discard data to that point. If possible, consider implementing random read access to permit backtracking by restarting the stream from the beginning as a last resort. Except where noted, library functions operate sequentially so backtracking shouldn't cause a significant performance penalty internally.
| eaarlio_error(* eaarlio_stream::close) (struct eaarlio_stream *self) |
Close the stream.
| [in,out] | self | A pointer to the stream |
| EAARLIO_SUCCESS | on success |
| EAARLIO_NULL | if provided a NULL pointer |
| EAARLIO_STREAM_INVALID | if stream is not valid |
| EAARLIO_STREAM_CLOSE_ERROR | if an error is encountered while closing |
| EAARLIO_STREAM_NOT_IMPL | if this function isn't implemented |
NULL. | void* eaarlio_stream::data |
Internal data pointer.
This is not used by calling code directly. It provides a means for the functions in the structure to maintain internal state.
| eaarlio_error(* eaarlio_stream::read) (struct eaarlio_stream *self, uint64_t len, unsigned char *buffer) |
Read bytes from a stream and place them in a buffer.
| [in] | self | A pointer to the stream |
| [in] | len | The number of bytes to read |
| [out] | buffer | The destination for the bytes read |
| EAARLIO_SUCCESS | on success |
| EAARLIO_NULL | if provided a NULL pointer |
| EAARLIO_STREAM_INVALID | if stream is not valid |
| EAARLIO_STREAM_READ_SHORT | if the read request returned fewer bytes than requested (this is generally interpreted as being at the end of the file) |
| EAARLIO_STREAM_READ_ERROR | if an error is encountered during the read |
| EAARLIO_STREAM_NOT_IMPL | if this function isn't implemented |
| eaarlio_error( * eaarlio_stream::seek) (struct eaarlio_stream *self, int64_t offset, int whence) |
Set the current position for the stream.
The position in the stream will be set based on the given values for offset and whence, possibly relative to the current stream position. The position is set based on the value of whence, using the same meaning as for the C standard library function fseek:
| whence | Interpretation |
|---|---|
SEEK_SET | offset is from the start of the file |
SEEK_CUR | offset is relative to the current position |
SEEK_END | offset is from the end of the file |
SEEK_SET and SEEK_CUR. Your implementation can respond to SEEK_END with EAARLIO_STREAM_SEEK_INVALID if appropriate.| [in] | self | A pointer to the stream |
| [in] | offset | Offset to apply, as indicated by whence |
| [in] | whence | How to apply offset to the current position. This should be one of SEEK_SET, SEEK_CUR, or SEEK_END. |
| EAARLIO_SUCCESS | on success |
| EAARLIO_NULL | if provided a NULL pointer |
| EAARLIO_STREAM_INVALID | if stream is not valid |
| EAARLIO_STREAM_SEEK_INVALID | if an invalid value is provided for whence |
| EAARLIO_STREAM_SEEK_ERROR | if an error is encountered during the seek |
| EAARLIO_STREAM_NOT_IMPL | if this function isn't implemented |
| eaarlio_error(* eaarlio_stream::tell) (struct eaarlio_stream *self, int64_t *position) |
Retrieve the current position in the stream.
| [in] | self | A pointer to the stream |
| [out] | position | Pointer to single position value to be populated |
| EAARLIO_SUCCESS | on success |
| EAARLIO_NULL | if provided a NULL pointer |
| EAARLIO_STREAM_INVALID | if stream is not valid |
| EAARLIO_STREAM_TELL_ERROR | if an error is encountered during the tell |
| EAARLIO_STREAM_NOT_IMPL | if this function isn't implemented |
| eaarlio_error(* eaarlio_stream::write) (struct eaarlio_stream *self, uint64_t len, unsigned char const *buffer) |
Writes bytes from a buffer to a stream.
| [in] | self | A pointer to the stream |
| [in] | len | The number of bytes to write |
| [in] | buffer | The data to write |
| EAARLIO_SUCCESS | on success |
| EAARLIO_NULL | if provided a NULL pointer |
| EAARLIO_STREAM_INVALID | if stream is not valid |
| EAARLIO_STREAM_WRITE_SHORT | if the write request wrote fewer bytes than requested |
| EAARLIO_STREAM_WRITE_ERROR | if an error is encountered during the write |
| EAARLIO_STREAM_NOT_IMPL | if this function isn't implemented |
1.8.13