diff options
Diffstat (limited to 'src/io.c')
| -rw-r--r-- | src/io.c | 186 |
1 files changed, 179 insertions, 7 deletions
@@ -1,6 +1,25 @@ #include <bh/internal/io.h> #include <stdlib.h> +/** + * \defgroup io Input/Output + * + * Input/output device abstraction layer. + * \{ + */ + +/** + * Creates the new io object with specified \a table and \a size. + * + * \param table Pointer to the io table + * \param size Size of the io object + * + * \return On success, returns new semi-initialized io object. + * \return On failure, returns null pointer. + * + * \warning This function should be used in context of implementing child + * io objects (files, sockets, streaming compression, etc). + */ bh_io_t *bh_io_new(bh_io_table_t *table, size_t size) { @@ -13,24 +32,91 @@ bh_io_t *bh_io_new(bh_io_table_t *table, return result; } +/** + * Frees the \a io object. + * + * \param io Pointer to the io object to be freed + */ void bh_io_free(bh_io_t *io) { bh_io_destroy(io); free(io); } +/** + * Initializes the \a io object with specified \a table. + * + * \param io Pointer to the io object to be initialized + * \param table Pointer to the io table + */ void bh_io_init(bh_io_t *io, - bh_io_table_t *table) + const bh_io_table_t *table) { io->table = table; io->flags = 0; } +/** + * Destroys the \a io object. + * + * \param io Pointer to the io object to be destroyed + */ void bh_io_destroy(bh_io_t *io) { io->table->destroy(io); } +/** + * Opens the \a io object for specified \a mode of operation. + * + * \param io Pointer to the io object + * \param mode Bitmask determining access mode + * + * \return On success, returns zero. + * \return On failure, returns error code. + */ +int bh_io_open(bh_io_t *io, + int mode) +{ + return io->table->open(io, mode); +} + +/** + * Closes the \a io object. + * + * \param io Pointer to the io object + */ +void bh_io_close(bh_io_t *io) +{ + io->table->close(io); +} + +/** + * Checks if the \a io is open. + * + * \param io Pointer to the io object + * + * \return If io object is open - returns non-zero. + * \return If io object is closed - returns zero. + */ +int bh_io_is_open(bh_io_t *io) +{ + return io->table->is_open(io); +} + +/** + * Reads up to \a size amount of bytes from the \a io object into memory buffer + * pointed by \a data pointer. + * + * \param io Pointer to the io object + * \param data Pointer to the memory buffer + * \param size Maximum number of bytes to be read + * + * \return On success, returns number of bytes successfuly read. + * \return On failure, returns zero. + * + * \note To check for end-of-file or error see bh_io_eof and bh_io_error. + */ size_t bh_io_read(bh_io_t *io, char *data, size_t size) @@ -38,6 +124,19 @@ size_t bh_io_read(bh_io_t *io, return io->table->read(io, data, size); } +/** + * Writes up to \a size amount of bytes to the \a io object from memory buffer + * pointed by \a data pointer. + * + * \param io Pointer to the io object + * \param data Pointer to the memory buffer + * \param size Maximum number of bytes to be read + * + * \return On success, returns number of bytes successfuly written. + * \return On failure, returns zero. + * + * \note To check for error see bh_io_error. + */ size_t bh_io_write(bh_io_t *io, const char* data, size_t size) @@ -45,39 +144,112 @@ size_t bh_io_write(bh_io_t *io, return io->table->write(io, data, size); } +/** + * Synchronizes the \a io object (if possible). + * + * In most cases, this function causes any unwritten/buffered data to be + * written. + * + * \param io Pointer to the io object + */ void bh_io_flush(bh_io_t *io) { io->table->flush(io); } -void bh_io_seek(bh_io_t *io, - bh_off_t offset, - int dir) +/** + * Seeks the \a io object in the specified direction \a dir and \a offset (if + * possible). + * + * \param io Pointer to the io object + * \param offset Number of bytes to seek in specified direciton + * \param dir Seeking direction + * + * \return On success, returns zero. + * \return On failure, returns error code. + */ +int bh_io_seek(bh_io_t *io, + bh_off_t offset, + int dir) { - io->table->seek(io, offset, dir); + return io->table->seek(io, offset, dir); } +/** + * Returns total size of the \a io object (if possible) + * + * \param io Pointer to the io object + * + * \return On success, returns total size of the io object. + * \return On failure, returns -1. + */ +bh_off_t bh_io_size(bh_io_t *io) +{ + return io->table->size(io); +} + +/** + * Returns current position in the \a io object (if possible). + * + * \param io Pointer to the io object + * + * \return On success, returns current position in the io object. + * \return On failure, returns -1. + */ bh_off_t bh_io_tell(bh_io_t *io) { return io->table->tell(io); } +/** + * Returns available number of bytes to be read from the \a io object. + * + * \param io Pointer to the io object + * + * \return On success, returns number of available bytes to be read. + * \return On failure, returns zero. + */ bh_off_t bh_io_available(bh_io_t *io) { return io->table->available(io); } +/** + * Checks error flag of the \a io object. + * + * \param io Pointer to the io object + * + * \return If error flag is set, returns non-zero. + * \return If error flag is not set, returns zero. + */ int bh_io_error(bh_io_t *io) { - return (io->flags & BH_IO_ERROR) > 0; + return (io->flags & BH_IO_ERROR) != 0; } +/** + * Checks end-of-file flag of the \a io object. + * + * \param io Pointer to the io object + * + * \return If end-of-file flag is set, returns non-zero. + * \return If end-of-file flag is not set, returns zero. + */ int bh_io_eof(bh_io_t *io) { - return (io->flags & BH_IO_EOF) > 0; + return (io->flags & BH_IO_EOF) != 0; } +/** + * Clears error of the \a io object. + * + * \param io Pointer to the io object + */ void bh_io_clear(bh_io_t *io) { io->table->clear(io); } + +/** + * \} + */ |