Define and document IsoStream interface.

src/stream.h

@@ -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_*/