Diff: mfs.h

Revision:

3:1cbc15648de1

Parent:

0:cbf45dde2b49

Child:

4:c77812997c9c

--- a/mfs.h	Mon Feb 21 07:40:15 2011 +0000
+++ b/mfs.h	Mon Feb 21 09:51:05 2011 +0000
@@ -21,6 +21,7 @@
 *
 * VERSION DATE       WHO             DETAIL
 * 0.1     2011-02-21 Olli Vanhoja    Initial release version
+* 0.2     2011-02-21 Olli Vanhoja    Documentational comments added
 *
 *H*/
 
@@ -37,22 +38,102 @@
 
 typedef unsigned short int uint16;
 
+/** mFS File System class
+ * 
+ * This class is used as a handle for the fs in use.
+ */
 class mfs {
 private:
     i2c_eeprom *mem; // Only 512 kB I2C EEPROM is supported ATM
 public:
+    /** Create a new file system object
+    *
+    * @param xi2c_address a Physical I2C address of the EEPROM chip  
+    */
     mfs(int i2c_address);
-    char read(char *data, char block, unsigned int byteOffset, unsigned int n); // Read bytes from block
-    char write(char *data, char block, unsigned int byteOffset, unsigned int n); // write bytes to block
-    char getNextFreeBlock(char *blockOut); // Reserve next free block from begining
+    /** Reads data from specified fs block
+    *
+    * @param *data Pointer for readed data
+    * @param block Block number.
+    * @param byte Selected byte.
+    * @param n Bytes to be read.
+    * @returns Error code. 0 = OK, 1 = Incorrect input
+    */
+    char read(char *data, char block, unsigned int byte, unsigned int n); // Read bytes from block
+    /** Writes data to specified fs block
+    *
+    * @param *data Pointer for readed data
+    * @param block Block number.
+    * @param byte Selected byte.
+    * @param n Bytes to be read.
+    * @returns Error code. 0 = OK, 1 = Incorrect input
+    */
+    char write(char *data, char block, unsigned int byte, unsigned int n); // write bytes to block
+    /** Locate next free block
+    *
+    * @param *blockOut Returns next free block from begining of the fs.
+    * @returns Error code. 0 = OK, 1 = Out of space
+    */
+    char getNextFreeBlock(char *blockOut);
+    /** Locates next starting file from parameter block
+    *
+    * @param block Start scanning from this block.
+    * @param *filenameOut Return name of the file found.
+    * @returns Block number of the file found or 0xFFFF to indicate empty file system.
+    */
     unsigned int findNextFile(unsigned int block, char *filenameOut); // Returns block number
+    /** Get number of the first block of the given file. (FBOF flag)
+    *
+    * @param filename[20] Filename input.
+    * @returns Block number of the file or 0xFFFF to indicate that file not found.
+    */
     uint16 getFirstBlockOfFile(char filename[20]);
+    /** Create new empty file
+    *
+    * Reserves one block for the file created.
+    *
+    * @param filename[20] Filename input.
+    * @returns Error code. 0 = OK, 1 = File exists already, 2 = Out of space
+    */
     char createFile(char filename[20]);
+    /** Remove file from file system
+    *
+    * @param filename[20] Filename input.
+    * @returns Error code. 0 = OK, 1 = File doesn't exists
+    */
     char removeFile(char filename[20]);
+    /** Set user modifiable flags.
+    *
+    * desc RO|HIDDEN|LOCK
+    * bit  3    2       1
+    *
+    * @param *flags Flag input
+    * @param filename[20] Filename input.
+    * @returns Error code. 0 = OK, 1 = File doesn't exists, 2 = File system is corrupted
+    */
     char setFileFlags(char *flags, char filename[20]);
+    /** Read user modifiable flags.
+    *
+    * desc RO|HIDDEN|LOCK
+    * bit  3    2       1
+    *
+    * @param *flags Flag output
+    * @param filename[20] Filename input.
+    * @returns Error code. 0 = OK, 1 = File doesn't exists
+    */
     char getFileFlags(char *flags, char filename[20]);
+    /** Get number of free blocks
+    *
+    * @returns Number of free blocks.
+    */
     uint16 free();
-    char mkfs(char);
+    /** Format new file system
+    *
+    *
+    * @param createLabel Create volume label at the begining of the file system. (there is no specified use for volume labels atm).
+    * @returns Number of bad block headers. Keep in mind that only first byte is checked and if it's broken the who file system is useless.
+    */
+    char mkfs(char createLabel);
 };
 
 class file {
@@ -66,14 +147,53 @@
     unsigned int blockPos; // "head" position on the current block
     void needsFlush(); // check if flush is needed before read operation
 public:
-    file(mfs *fs_ref, char filename[20], char operation); // Open file handle
+    /** Open new file handle
+    *
+    * File must be created before it can be opened!
+    *
+    * @param filename[20] Filename input.
+    * @param operation 0 = read only, 1 = read and write. If read only file is opened in rw mode system will trip to error().
+    */
+    file(mfs *fs_ref, char filename[20], char operation);
+    /** Close file handle
+    *
+    * Flushes the file and closes the handle.
+    */
     ~file(); // Close file handle and flush
-    void rewind(); // Rewind to start postion of the file
-    char forward(); // Forward one block
+    /** Rewind to the start postion of the file
+    */
+    void rewind();
+    /** Forward one block
+    */
+    char forward();
     //char seek(unsigned int byte); // seek to the byte
+    /** Reads a string of bytes
+    *
+    * Always places '\0' at the end of string.
+    *
+    * @param data Output buffer.
+    * @param n Number of bytes to be read.
+    @returns Error code. 0 = OK, 1 = Last block of the file
+    */
     void read(char *data, unsigned int n);
+    /** Reads a binary array of bytes
+    *
+    * Doesn't add '\0' at the end of data array and doesn't respect mEOF byte.
+    *
+    * @param data Output buffer.
+    * @param n Number of bytes to be read.
+    */
     void readBin(char *data, unsigned int n);
-    char write(char *data, unsigned int n); // Write byte array
+    /** Write byte array to a file (buffer)
+    *
+    * @param data Input data.
+    * @param n Number of bytes to be read.
+    * @returns Error code. 0 = OK, 1 = Flush failed.
+    */
+    char write(char *data, unsigned int n);
+    /** Flush file buffer
+    * Writes buffer to the EEPROM chip in use.
+    */
     char flush();
 };