Add documentation, expand error handling, implement file and buffer io

include/bh/io.h

@@ -1,10 +1,24 @@
-#ifndef BHLIB_IO_H
-#define BHLIB_IO_H
+#ifndef BH_IO_H
+#define BH_IO_H
 
 #include "bh.h"
 
-#define BH_IO_ERROR (1 << 0)
-#define BH_IO_EOF   (1 << 1)
+#define BH_IO_ERROR         0x0001
+#define BH_IO_EOF           0x0002
+
+#define BH_IO_READ          0x0001
+#define BH_IO_WRITE         0x0002
+#define BH_IO_READ_WRITE    (BH_IO_READ | BH_IO_WRITE)
+#define BH_IO_OPEN          0x0000
+#define BH_IO_CREATE        0x0100
+#define BH_IO_APPEND        0x0200
+#define BH_IO_TRUNCATE      0x0300
+#define BH_IO_MASK          0xFF00
+
+
+#define BH_IO_SET           0x0000
+#define BH_IO_CURRENT       0x0001
+#define BH_IO_END           0x0002
 
 #define BH_IO_CAST(x) \
     ((bh_io_t *)(x))
@@ -13,6 +27,13 @@ struct bh_io_s;
 
 typedef struct bh_io_table_s
 {
+    int (*open)(struct bh_io_s *io,
+                int mode);
+
+    void (*close)(struct bh_io_s *io);
+
+    int (*is_open)(struct bh_io_s *io);
+
     size_t (*read)(struct bh_io_s *io,
                    char *data,
                    size_t size);
@@ -23,9 +44,11 @@ typedef struct bh_io_table_s
 
     void (*flush)(struct bh_io_s *io);
 
-    void (*seek)(struct bh_io_s *io,
-                 bh_off_t offset,
-                 int dir);
+    int (*seek)(struct bh_io_s *io,
+                bh_off_t offset,
+                int dir);
+
+    bh_off_t (*size)(struct bh_io_s *io);
 
     bh_off_t (*tell)(struct bh_io_s *io);
 
@@ -38,145 +61,49 @@ typedef struct bh_io_table_s
 
 typedef struct bh_io_s
 {
-    bh_io_table_t *table;
+    const bh_io_table_t *table;
     int flags;
 } bh_io_t;
 
-/**
- * @brief   Create new IO object.
- *
- * @param   table   Valid pointer to the IO table.
- * @param   size    Size of the IO object.
- *
- * @return  If the function succeeds, the return value is a pointer to the
- *          new, semi-initalized, IO object.
- * @return  If the function fails, the return value is NULL.
- *
- * @warning This function should be used in context of implementing child
- *          IO objects (files, sockets, streaming compression, etc).
- *
- * @sa      bh_io_free
- */
 bh_io_t *bh_io_new(bh_io_table_t *table,
                    size_t size);
 
-/**
- * @brief   Free IO object.
- *
- * @param   io      Valid pointer to the IO object.
- */
 void bh_io_free(bh_io_t *io);
 
-/**
- * @brief   Read data from IO.
- *
- * @param   io      Valid pointer to the IO object.
- * @param   data    Valid pointer to the buffer.
- * @param   size    Size of the buffer.
- *
- * @return  If the function succeeds, the return value is the amount
- *          of bytes read from the IO object.
- * @return  If the function fails, the return value is zero and error
- *          flag is set.
- *
- * @sa      bh_io_write, bh_io_eof, bh_io_error
- */
+int bh_io_open(bh_io_t *io,
+               int mode);
+
+void bh_io_close(bh_io_t *io);
+
+int bh_io_is_open(bh_io_t *io);
+
 size_t bh_io_read(bh_io_t *io,
                   char *data,
                   size_t size);
 
-/**
- * @brief   Write data to IO.
- *
- * @param   io      Valid pointer to the IO object.
- * @param   data    Valid pointer to the buffer.
- * @param   size    Size of the buffer.
- *
- * @return  If the function succeeds, the return value is the amount
- *          of bytes written to the IO object.
- * @return  If the function fails, the return value is zero and error
- *          flag is set.
- *
- * @sa      bh_io_read, bh_io_error, bh_io_flush
- */
+
 size_t bh_io_write(bh_io_t *io,
                    const char* data,
                    size_t size);
 
-/**
- * @brief   Writes any uncommited changes (if possible).
- *
- * @param   io      Valid pointer to the IO object.
- */
 void bh_io_flush(bh_io_t *io);
 
-/**
- * @brief   Seeks IO object to the specified position (if possible).
- *
- * @param   io      Valid pointer to the IO object.
- * @param   offset  Position
- * @param   dir     Direction
- *
- * @sa      bh_io_tell
- */
-void bh_io_seek(bh_io_t *io,
-                bh_off_t offset,
-                int dir);
 
-/**
- * @brief   Return current position in IO.
- *
- * @param   io      Valid pointer to the IO object.
- *
- * @return  If the function succeeds, the return value is current 
- *          position in the IO.
- * @return  If the function fails, the return value is -1.
- * 
- * @sa      bh_io_seek
- */
+int bh_io_seek(bh_io_t *io,
+               bh_off_t offset,
+               int dir);
+
+bh_off_t bh_io_size(bh_io_t *io);
+
 bh_off_t bh_io_tell(bh_io_t *io);
 
-/**
- * @brief   Return available bytes in the IO.
- *
- * @param   io      Valid pointer to the IO object.
- *
- * @return  If the function succeeds, the return value is the amount
- *          of the available bytes for reading.
- * @return  If the function fails, the return value is zero.
- */
+
 bh_off_t bh_io_available(bh_io_t *io);
 
-/**
- * @brief   Return error flag of the IO.
- *
- * @param   io      Valid pointer to the IO object.
- * 
- * @return  The return value is error flag.
- *
- * @sa      bh_io_eof, bh_io_clear
- */
 int bh_io_error(bh_io_t *io);
 
-/**
- * @brief   Return end-of-file flag of the IO.
- *
- * @param   io      Valid pointer to the IO object.
- *
- * @return  The return value is end-of-file flag.
- *
- * @sa      bh_io_error, bh_io_clear
- */
 int bh_io_eof(bh_io_t *io);
 
-/**
- * @brief   Crear IO object state.
- *
- * @param   io      Valid pointer to the IO object.
- *
- * @sa      bh_io_error, bh_io_eof
- */
 void bh_io_clear(bh_io_t *io);
 
-
-#endif /* BHLIB_IO_H */
+#endif /* BH_IO_H */