Re-wrote API.

Now File and Directory are just integers, and they are joined by Volume. All the info is stored inside the volume manager.

The upside is you no longer have to pass the right volume along with your file handle! It also becomes much easier to implement a Drop trait on File if you want (although we don't for the reasons explained in the comments).

The downside is the File object no longer has any methods. The upside is that it's much easier to store files.

Author: thejpster

README.md

@@ -23,36 +23,35 @@ let mut volume_mgr = embedded_sdmmc::VolumeManager::new(sdcard, time_source);
 // It doesn't hold a reference to the Volume Manager and so must be passed back
 // to every Volume Manager API call. This makes it easier to handle multiple
 // volumes in parallel.
-let mut volume0 = volume_mgr.get_volume(embedded_sdmmc::VolumeIdx(0))?;
+let volume0 = volume_mgr.get_volume(embedded_sdmmc::VolumeIdx(0))?;
 println!("Volume 0: {:?}", volume0);
 // Open the root directory (passing in the volume we're using).
 let root_dir = volume_mgr.open_root_dir(&volume0)?;
 // Open a file called "MY_FILE.TXT" in the root directory
-let mut my_file = volume_mgr.open_file_in_dir(
-    &mut volume0,
-    &root_dir,
+let my_file = volume_mgr.open_file_in_dir(
+    root_dir,
     "MY_FILE.TXT",
     embedded_sdmmc::Mode::ReadOnly,
 )?;
 // Print the contents of the file
-while !my_file.eof() {
+while !volume_manager.file_eof(my_file).unwrap() {
     let mut buffer = [0u8; 32];
     let num_read = volume_mgr.read(&volume0, &mut my_file, &mut buffer)?;
     for b in &buffer[0..num_read] {
         print!("{}", *b as char);
     }
 }
-volume_mgr.close_file(&volume0, my_file)?;
-volume_mgr.close_dir(&volume0, root_dir);
+volume_mgr.close_file(my_file)?;
+volume_mgr.close_dir(root_dir)?;
 ```
 
 ### Open directories and files
 
-By default the `VolumeManager` will initialize with a maximum number of `4` open directories and files. This can be customized by specifying the `MAX_DIR` and `MAX_FILES` generic consts of the `VolumeManager`:
+By default the `VolumeManager` will initialize with a maximum number of `4` open directories, files and volumes. This can be customized by specifying the `MAX_DIR`, `MAX_FILES` and `MAX_VOLUMES` generic consts of the `VolumeManager`:
 
 ```rust
-// Create a volume manager with a maximum of 6 open directories and 12 open files
-let mut cont: VolumeManager<_, _, 6, 12> = VolumeManager::new_with_limits(block, time_source);
+// Create a volume manager with a maximum of 6 open directories, 12 open files, and 4 volumes (or partitions)
+let mut cont: VolumeManager<_, _, 6, 12, 4> = VolumeManager::new_with_limits(block, time_source);
 ```
 
 ## Supported features

examples/create_test.rs

@@ -118,34 +118,30 @@ fn main() {
         .map_err(Error::DeviceError)
         .unwrap();
     println!("lbd: {:?}", lbd);
-    let mut volume_mgr = VolumeManager::new(lbd, Clock);
+    let mut volume_mgr: VolumeManager<LinuxBlockDevice, Clock, 8, 8, 4> =
+        VolumeManager::new_with_limits(lbd, Clock, 0xAA00_0000);
     for volume_idx in 0..=3 {
-        let volume = volume_mgr.get_volume(VolumeIdx(volume_idx));
+        let volume = volume_mgr.open_volume(VolumeIdx(volume_idx));
         println!("volume {}: {:#?}", volume_idx, volume);
-        if let Ok(mut volume) = volume {
-            let root_dir = volume_mgr.open_root_dir(&volume).unwrap();
+        if let Ok(volume) = volume {
+            let root_dir = volume_mgr.open_root_dir(volume).unwrap();
             println!("\tListing root directory:");
             volume_mgr
-                .iterate_dir(&volume, &root_dir, |x| {
+                .iterate_dir(root_dir, |x| {
                     println!("\t\tFound: {:?}", x);
                 })
                 .unwrap();
             println!("\nCreating file {}...", FILE_TO_CREATE);
             // This will panic if the file already exists, use ReadWriteCreateOrAppend or
             // ReadWriteCreateOrTruncate instead
-            let mut f = volume_mgr
-                .open_file_in_dir(
-                    &mut volume,
-                    &root_dir,
-                    FILE_TO_CREATE,
-                    Mode::ReadWriteCreate,
-                )
+            let f = volume_mgr
+                .open_file_in_dir(root_dir, FILE_TO_CREATE, Mode::ReadWriteCreate)
                 .unwrap();
             println!("\nReading from file");
             println!("FILE STARTS:");
-            while !f.eof() {
+            while !volume_mgr.file_eof(f).unwrap() {
                 let mut buffer = [0u8; 32];
-                let num_read = volume_mgr.read(&volume, &mut f, &mut buffer).unwrap();
+                let num_read = volume_mgr.read(f, &mut buffer).unwrap();
                 for b in &buffer[0..num_read] {
                     if *b == 10 {
                         print!("\\n");
@@ -162,32 +158,27 @@ fn main() {
                 buffer.push(b'\n');
             }
             println!("\nAppending to file");
-            let num_written1 = volume_mgr.write(&mut volume, &mut f, &buffer1[..]).unwrap();
-            let num_written = volume_mgr.write(&mut volume, &mut f, &buffer[..]).unwrap();
+            let num_written1 = volume_mgr.write(f, &buffer1[..]).unwrap();
+            let num_written = volume_mgr.write(f, &buffer[..]).unwrap();
             println!("Number of bytes written: {}\n", num_written + num_written1);
-            volume_mgr.close_file(&mut volume, f).unwrap();
+            volume_mgr.close_file(f).unwrap();
 
-            let mut f = volume_mgr
-                .open_file_in_dir(
-                    &mut volume,
-                    &root_dir,
-                    FILE_TO_CREATE,
-                    Mode::ReadWriteCreateOrAppend,
-                )
+            let f = volume_mgr
+                .open_file_in_dir(root_dir, FILE_TO_CREATE, Mode::ReadWriteCreateOrAppend)
                 .unwrap();
-            f.seek_from_start(0).unwrap();
+            volume_mgr.file_seek_from_start(f, 0).unwrap();
 
             println!("\tFinding {}...", FILE_TO_CREATE);
             println!(
                 "\tFound {}?: {:?}",
                 FILE_TO_CREATE,
-                volume_mgr.find_directory_entry(&volume, &root_dir, FILE_TO_CREATE)
+                volume_mgr.find_directory_entry(root_dir, FILE_TO_CREATE)
             );
             println!("\nReading from file");
             println!("FILE STARTS:");
-            while !f.eof() {
+            while !volume_mgr.file_eof(f).unwrap() {
                 let mut buffer = [0u8; 32];
-                let num_read = volume_mgr.read(&volume, &mut f, &mut buffer).unwrap();
+                let num_read = volume_mgr.read(f, &mut buffer).unwrap();
                 for b in &buffer[0..num_read] {
                     if *b == 10 {
                         print!("\\n");
@@ -196,7 +187,7 @@ fn main() {
                 }
             }
             println!("EOF");
-            volume_mgr.close_file(&mut volume, f).unwrap();
+            volume_mgr.close_file(f).unwrap();
         }
     }
 }

examples/delete_test.rs

@@ -118,53 +118,49 @@ fn main() {
         .map_err(Error::DeviceError)
         .unwrap();
     println!("lbd: {:?}", lbd);
-    let mut volume_mgr = VolumeManager::new(lbd, Clock);
+    let mut volume_mgr: VolumeManager<LinuxBlockDevice, Clock, 8, 8, 4> =
+        VolumeManager::new_with_limits(lbd, Clock, 0xAA00_0000);
     for volume_idx in 0..=3 {
-        let volume = volume_mgr.get_volume(VolumeIdx(volume_idx));
+        let volume = volume_mgr.open_volume(VolumeIdx(volume_idx));
         println!("volume {}: {:#?}", volume_idx, volume);
-        if let Ok(mut volume) = volume {
-            let root_dir = volume_mgr.open_root_dir(&volume).unwrap();
+        if let Ok(volume) = volume {
+            let root_dir = volume_mgr.open_root_dir(volume).unwrap();
             println!("\tListing root directory:");
             volume_mgr
-                .iterate_dir(&volume, &root_dir, |x| {
+                .iterate_dir(root_dir, |x| {
                     println!("\t\tFound: {:?}", x);
                 })
                 .unwrap();
             println!("\nCreating file {}...", FILE_TO_DELETE);
             // This will panic if the file already exists, use ReadWriteCreateOrAppend or
             // ReadWriteCreateOrTruncate instead
             let f = volume_mgr
-                .open_file_in_dir(
-                    &mut volume,
-                    &root_dir,
-                    FILE_TO_DELETE,
-                    Mode::ReadWriteCreate,
-                )
+                .open_file_in_dir(root_dir, FILE_TO_DELETE, Mode::ReadWriteCreate)
                 .unwrap();
 
             println!("\tFinding {}...", FILE_TO_DELETE);
             println!(
                 "\tFound {}?: {:?}",
                 FILE_TO_DELETE,
-                volume_mgr.find_directory_entry(&volume, &root_dir, FILE_TO_DELETE)
+                volume_mgr.find_directory_entry(root_dir, FILE_TO_DELETE)
             );
 
-            match volume_mgr.delete_file_in_dir(&volume, &root_dir, FILE_TO_DELETE) {
+            match volume_mgr.delete_file_in_dir(root_dir, FILE_TO_DELETE) {
                 Ok(()) => (),
                 Err(error) => println!("\tCannot delete file: {:?}", error),
             }
             println!("\tClosing {}...", FILE_TO_DELETE);
-            volume_mgr.close_file(&mut volume, f).unwrap();
+            volume_mgr.close_file(f).unwrap();
 
-            match volume_mgr.delete_file_in_dir(&volume, &root_dir, FILE_TO_DELETE) {
+            match volume_mgr.delete_file_in_dir(root_dir, FILE_TO_DELETE) {
                 Ok(()) => println!("\tDeleted {}.", FILE_TO_DELETE),
                 Err(error) => println!("\tCannot delete {}: {:?}", FILE_TO_DELETE, error),
             }
             println!("\tFinding {}...", FILE_TO_DELETE);
             println!(
                 "\tFound {}?: {:?}",
                 FILE_TO_DELETE,
-                volume_mgr.find_directory_entry(&volume, &root_dir, FILE_TO_DELETE)
+                volume_mgr.find_directory_entry(root_dir, FILE_TO_DELETE)
             );
         }
     }

examples/readme_test.rs

@@ -90,26 +90,22 @@ fn main() -> Result<(), Error> {
     // It doesn't hold a reference to the Volume Manager and so must be passed back
     // to every Volume Manager API call. This makes it easier to handle multiple
     // volumes in parallel.
-    let mut volume0 = volume_mgr.get_volume(embedded_sdmmc::VolumeIdx(0))?;
+    let volume0 = volume_mgr.open_volume(embedded_sdmmc::VolumeIdx(0))?;
     println!("Volume 0: {:?}", volume0);
     // Open the root directory (passing in the volume we're using).
-    let root_dir = volume_mgr.open_root_dir(&volume0)?;
+    let root_dir = volume_mgr.open_root_dir(volume0)?;
     // Open a file called "MY_FILE.TXT" in the root directory
-    let mut my_file = volume_mgr.open_file_in_dir(
-        &mut volume0,
-        &root_dir,
-        "MY_FILE.TXT",
-        embedded_sdmmc::Mode::ReadOnly,
-    )?;
+    let my_file =
+        volume_mgr.open_file_in_dir(root_dir, "MY_FILE.TXT", embedded_sdmmc::Mode::ReadOnly)?;
     // Print the contents of the file
-    while !my_file.eof() {
+    while !volume_mgr.file_eof(my_file).unwrap() {
         let mut buffer = [0u8; 32];
-        let num_read = volume_mgr.read(&volume0, &mut my_file, &mut buffer)?;
+        let num_read = volume_mgr.read(my_file, &mut buffer)?;
         for b in &buffer[0..num_read] {
             print!("{}", *b as char);
         }
     }
-    volume_mgr.close_file(&mut volume0, my_file)?;
-    volume_mgr.close_dir(&volume0, root_dir);
+    volume_mgr.close_file(my_file)?;
+    volume_mgr.close_dir(root_dir)?;
     Ok(())
 }

examples/test_mount.rs

@@ -121,31 +121,32 @@ fn main() {
         .map_err(Error::DeviceError)
         .unwrap();
     println!("lbd: {:?}", lbd);
-    let mut volume_mgr = VolumeManager::new(lbd, Clock);
+    let mut volume_mgr: VolumeManager<LinuxBlockDevice, Clock, 8, 8, 4> =
+        VolumeManager::new_with_limits(lbd, Clock, 0xAA00_0000);
     for i in 0..=3 {
-        let volume = volume_mgr.get_volume(VolumeIdx(i));
+        let volume = volume_mgr.open_volume(VolumeIdx(i));
         println!("volume {}: {:#?}", i, volume);
-        if let Ok(mut volume) = volume {
-            let root_dir = volume_mgr.open_root_dir(&volume).unwrap();
+        if let Ok(volume) = volume {
+            let root_dir = volume_mgr.open_root_dir(volume).unwrap();
             println!("\tListing root directory:");
             volume_mgr
-                .iterate_dir(&volume, &root_dir, |x| {
+                .iterate_dir(root_dir, |x| {
                     println!("\t\tFound: {:?}", x);
                 })
                 .unwrap();
             println!("\tFinding {}...", FILE_TO_PRINT);
             println!(
                 "\tFound {}?: {:?}",
                 FILE_TO_PRINT,
-                volume_mgr.find_directory_entry(&volume, &root_dir, FILE_TO_PRINT)
+                volume_mgr.find_directory_entry(root_dir, FILE_TO_PRINT)
             );
-            let mut f = volume_mgr
-                .open_file_in_dir(&mut volume, &root_dir, FILE_TO_PRINT, Mode::ReadOnly)
+            let f = volume_mgr
+                .open_file_in_dir(root_dir, FILE_TO_PRINT, Mode::ReadOnly)
                 .unwrap();
             println!("FILE STARTS:");
-            while !f.eof() {
+            while !volume_mgr.file_eof(f).unwrap() {
                 let mut buffer = [0u8; 32];
-                let num_read = volume_mgr.read(&volume, &mut f, &mut buffer).unwrap();
+                let num_read = volume_mgr.read(f, &mut buffer).unwrap();
                 for b in &buffer[0..num_read] {
                     if *b == 10 {
                         print!("\\n");
@@ -156,42 +157,52 @@ fn main() {
             println!("EOF");
             // Can't open file twice
             assert!(volume_mgr
-                .open_file_in_dir(&mut volume, &root_dir, FILE_TO_PRINT, Mode::ReadOnly)
+                .open_file_in_dir(root_dir, FILE_TO_PRINT, Mode::ReadOnly)
                 .is_err());
-            volume_mgr.close_file(&mut volume, f).unwrap();
+            volume_mgr.close_file(f).unwrap();
 
-            let test_dir = volume_mgr.open_dir(&volume, &root_dir, "TEST").unwrap();
+            let test_dir = volume_mgr.open_dir(root_dir, "TEST").unwrap();
             // Check we can't open it twice
-            assert!(volume_mgr.open_dir(&volume, &root_dir, "TEST").is_err());
+            assert!(volume_mgr.open_dir(root_dir, "TEST").is_err());
             // Print the contents
             println!("\tListing TEST directory:");
             volume_mgr
-                .iterate_dir(&volume, &test_dir, |x| {
+                .iterate_dir(test_dir, |x| {
                     println!("\t\tFound: {:?}", x);
                 })
                 .unwrap();
-            volume_mgr.close_dir(&volume, test_dir);
+            volume_mgr.close_dir(test_dir).unwrap();
 
             // Checksum example file. We just sum the bytes, as a quick and dirty checksum.
             // We also read in a weird block size, just to exercise the offset calculation code.
-            let mut f = volume_mgr
-                .open_file_in_dir(&mut volume, &root_dir, FILE_TO_CHECKSUM, Mode::ReadOnly)
+            let f = volume_mgr
+                .open_file_in_dir(root_dir, FILE_TO_CHECKSUM, Mode::ReadOnly)
                 .unwrap();
-            println!("Checksuming {} bytes of {}", f.length(), FILE_TO_CHECKSUM);
+            println!(
+                "Checksuming {} bytes of {}",
+                volume_mgr.file_length(f).unwrap(),
+                FILE_TO_CHECKSUM
+            );
             let mut csum = 0u32;
-            while !f.eof() {
+            while !volume_mgr.file_eof(f).unwrap() {
                 let mut buffer = [0u8; 2047];
-                let num_read = volume_mgr.read(&volume, &mut f, &mut buffer).unwrap();
+                let num_read = volume_mgr.read(f, &mut buffer).unwrap();
                 for b in &buffer[0..num_read] {
                     csum += u32::from(*b);
                 }
             }
-            println!("Checksum over {} bytes: {}", f.length(), csum);
-            volume_mgr.close_file(&mut volume, f).unwrap();
+            println!(
+                "\nChecksum over {} bytes: {}",
+                volume_mgr.file_length(f).unwrap(),
+                csum
+            );
+            // Should be all zero bytes
+            assert_eq!(csum, 0);
+            volume_mgr.close_file(f).unwrap();
 
-            assert!(volume_mgr.open_root_dir(&volume).is_err());
-            volume_mgr.close_dir(&volume, root_dir);
-            assert!(volume_mgr.open_root_dir(&volume).is_ok());
+            assert!(volume_mgr.open_root_dir(volume).is_err());
+            assert!(volume_mgr.close_dir(root_dir).is_ok());
+            assert!(volume_mgr.open_root_dir(volume).is_ok());
         }
     }
 }