path: root/src/io.c

#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)
{
    bh_io_t *result;

    result = malloc(size);
    if (result)
        bh_io_init(result, 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,
                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)
{
    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)
{
    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);
}

/**
 * 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)
{
    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;
}

/**
 * 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;
}

/**
 * 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);
}

/**
 * \}
 */