Merge pull request #149 from rust-embedded-community/rename-searchid

Rename SearchId to Handle.

Author: thejpster

src/filesystem/directory.rs

@@ -2,7 +2,7 @@ use core::convert::TryFrom;
 
 use crate::blockdevice::BlockIdx;
 use crate::fat::{FatType, OnDiskDirEntry};
-use crate::filesystem::{Attributes, ClusterId, SearchId, ShortFileName, Timestamp};
+use crate::filesystem::{Attributes, ClusterId, Handle, ShortFileName, Timestamp};
 use crate::{Error, RawVolume, VolumeManager};
 
 use super::ToShortFileName;
@@ -47,7 +47,7 @@ pub struct DirEntry {
 /// and there's a reason we did it this way.
 #[cfg_attr(feature = "defmt-log", derive(defmt::Format))]
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
-pub struct RawDirectory(pub(crate) SearchId);
+pub struct RawDirectory(pub(crate) Handle);
 
 impl RawDirectory {
     /// Convert a raw directory into a droppable [`Directory`]
@@ -240,9 +240,9 @@ where
 #[cfg_attr(feature = "defmt-log", derive(defmt::Format))]
 #[derive(Debug, Clone)]
 pub(crate) struct DirectoryInfo {
-    /// Unique ID for this directory.
+    /// The handle for this directory.
     pub(crate) directory_id: RawDirectory,
-    /// The unique ID for the volume this directory is on
+    /// The handle for the volume this directory is on
     pub(crate) volume_id: RawVolume,
     /// The starting point of the directory listing.
     pub(crate) cluster: ClusterId,

src/filesystem/files.rs

@@ -1,6 +1,6 @@
 use super::TimeSource;
 use crate::{
-    filesystem::{ClusterId, DirEntry, SearchId},
+    filesystem::{ClusterId, DirEntry, Handle},
     BlockDevice, Error, RawVolume, VolumeManager,
 };
 use embedded_io::{ErrorType, Read, Seek, SeekFrom, Write};
@@ -23,7 +23,7 @@ use embedded_io::{ErrorType, Read, Seek, SeekFrom, Write};
 /// reason we did it this way.
 #[cfg_attr(feature = "defmt-log", derive(defmt::Format))]
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
-pub struct RawFile(pub(crate) SearchId);
+pub struct RawFile(pub(crate) Handle);
 
 impl RawFile {
     /// Convert a raw file into a droppable [`File`]
@@ -283,10 +283,10 @@ pub enum Mode {
 #[cfg_attr(feature = "defmt-log", derive(defmt::Format))]
 #[derive(Debug, Clone)]
 pub(crate) struct FileInfo {
-    /// Unique ID for this file
-    pub(crate) file_id: RawFile,
-    /// The unique ID for the volume this directory is on
-    pub(crate) volume_id: RawVolume,
+    /// Handle for this file
+    pub(crate) raw_file: RawFile,
+    /// The handle for the volume this directory is on
+    pub(crate) raw_volume: RawVolume,
     /// The last cluster we accessed, and how many bytes that short-cuts us.
     ///
     /// This saves us walking from the very start of the FAT chain when we move

src/filesystem/search_id.rs renamed to src/filesystem/handles.rs

@@ -1,35 +1,43 @@
+//! Contains the Handles and the HandleGenerator.
+
 use core::num::Wrapping;
 
-#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+#[derive(Clone, Copy, PartialEq, Eq)]
 #[cfg_attr(feature = "defmt-log", derive(defmt::Format))]
-/// Unique ID used to search for files and directories in the open Volume/File/Directory lists
-pub struct SearchId(pub(crate) u32);
+/// Unique ID used to identify things in the open Volume/File/Directory lists
+pub struct Handle(pub(crate) u32);
+
+impl core::fmt::Debug for Handle {
+    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        write!(f, "{:#08x}", self.0)
+    }
+}
 
-/// A Search ID generator.
+/// A Handle Generator.
 ///
 /// This object will always return a different ID.
 ///
 /// Well, it will wrap after `2**32` IDs. But most systems won't open that many
 /// files, and if they do, they are unlikely to hold one file open and then
 /// open/close `2**32 - 1` others.
 #[derive(Debug)]
-pub struct SearchIdGenerator {
+pub struct HandleGenerator {
     next_id: Wrapping<u32>,
 }
 
-impl SearchIdGenerator {
-    /// Create a new generator of Search IDs.
+impl HandleGenerator {
+    /// Create a new generator of Handles.
     pub const fn new(offset: u32) -> Self {
         Self {
             next_id: Wrapping(offset),
         }
     }
 
-    /// Generate a new, unique [`SearchId`].
-    pub fn get(&mut self) -> SearchId {
+    /// Generate a new, unique [`Handle`].
+    pub fn generate(&mut self) -> Handle {
         let id = self.next_id;
         self.next_id += 1;
-        SearchId(id.0)
+        Handle(id.0)
     }
 }
 

src/filesystem/mod.rs

@@ -11,15 +11,15 @@ mod cluster;
 mod directory;
 mod filename;
 mod files;
-mod search_id;
+mod handles;
 mod timestamp;
 
 pub use self::attributes::Attributes;
 pub use self::cluster::ClusterId;
 pub use self::directory::{DirEntry, Directory, RawDirectory};
 pub use self::filename::{FilenameError, ShortFileName, ToShortFileName};
 pub use self::files::{File, FileError, Mode, RawFile};
-pub use self::search_id::{SearchId, SearchIdGenerator};
+pub use self::handles::{Handle, HandleGenerator};
 pub use self::timestamp::{TimeSource, Timestamp};
 
 pub(crate) use self::directory::DirectoryInfo;

src/lib.rs

@@ -75,7 +75,7 @@ pub mod sdcard;
 
 use core::fmt::Debug;
 use embedded_io::ErrorKind;
-use filesystem::SearchId;
+use filesystem::Handle;
 
 #[doc(inline)]
 pub use crate::blockdevice::{Block, BlockCount, BlockDevice, BlockIdx};
@@ -247,10 +247,19 @@ where
     }
 }
 
-/// A partition with a filesystem within it.
+/// A handle to a volume.
+///
+/// A volume is a partition with a filesystem within it.
+///
+/// Do NOT drop this object! It doesn't hold a reference to the Volume Manager
+/// it was created from and the VolumeManager will think you still have the
+/// volume open if you just drop it, and it won't let you open the file again.
+///
+/// Instead you must pass it to [`crate::VolumeManager::close_volume`] to close
+/// it cleanly.
 #[cfg_attr(feature = "defmt-log", derive(defmt::Format))]
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
-pub struct RawVolume(SearchId);
+pub struct RawVolume(Handle);
 
 impl RawVolume {
     /// Convert a raw volume into a droppable [`Volume`]
@@ -272,7 +281,7 @@ impl RawVolume {
     }
 }
 
-/// An open volume on disk, which closes on drop.
+/// A handle for an open volume on disk, which closes on drop.
 ///
 /// In contrast to a `RawVolume`, a `Volume` holds a mutable reference to its
 /// parent `VolumeManager`, which restricts which operations you can perform.
@@ -373,9 +382,9 @@ where
 #[cfg_attr(feature = "defmt-log", derive(defmt::Format))]
 #[derive(Debug, PartialEq, Eq)]
 pub(crate) struct VolumeInfo {
-    /// Search ID for this volume.
-    volume_id: RawVolume,
-    /// TODO: some kind of index
+    /// Handle for this volume.
+    raw_volume: RawVolume,
+    /// Which volume (i.e. partition) we opened on the disk
     idx: VolumeIdx,
     /// What kind of volume this is
     volume_type: VolumeType,