embedded_fat/filesystem/
files.rs

Help
1use crate::filesystem::{ClusterId, DirEntry, SearchId};
2
3/// Represents an open file on disk.
4///
5/// Do NOT drop this object! It doesn't hold a reference to the Volume Manager
6/// it was created from and cannot update the directory entry if you drop it.
7/// Additionally, the VolumeManager will think you still have the file open if
8/// you just drop it, and it won't let you open the file again.
9///
10/// Instead you must pass it to [`crate::VolumeManager::close_file`] to close it
11/// cleanly.
12///
13/// If you want your files to close themselves on drop, create your own File
14/// type that wraps this one and also holds a `VolumeManager` reference. You'll
15/// then also need to put your `VolumeManager` in some kind of Mutex or RefCell,
16/// and deal with the fact you can't put them both in the same struct any more
17/// because one refers to the other. Basically, it's complicated and there's a
18/// reason we did it this way.
19#[cfg_attr(feature = "defmt-log", derive(defmt::Format))]
20#[derive(Debug, Copy, Clone, PartialEq, Eq)]
21pub struct File(pub(crate) SearchId);
22
23/// Internal metadata about an open file
24#[cfg_attr(feature = "defmt-log", derive(defmt::Format))]
25#[derive(Debug, Clone)]
26pub(crate) struct FileInfo {
27    /// Unique ID for this file
28    pub(crate) file_id: File,
29    /// The current cluster, and how many bytes that short-cuts us
30    pub(crate) current_cluster: (u32, ClusterId),
31    /// How far through the file we've read (in bytes).
32    pub(crate) current_offset: u32,
33    /// What mode the file was opened in
34    pub(crate) mode: Mode,
35    /// DirEntry of this file
36    pub(crate) entry: DirEntry,
37    /// Did we write to this file?
38    pub(crate) dirty: bool,
39}
40
41/// Errors related to file operations
42#[cfg_attr(feature = "defmt-log", derive(defmt::Format))]
43#[derive(Debug, Clone, Copy, PartialEq, Eq)]
44pub enum FileError {
45    /// Tried to use an invalid offset.
46    InvalidOffset,
47}
48
49/// The different ways we can open a file.
50#[cfg_attr(feature = "defmt-log", derive(defmt::Format))]
51#[derive(Debug, PartialEq, Eq, Copy, Clone)]
52pub enum Mode {
53    /// Open a file for reading, if it exists.
54    ReadOnly,
55    /// Open a file for appending (writing to the end of the existing file), if it exists.
56    ReadWriteAppend,
57    /// Open a file and remove all contents, before writing to the start of the existing file, if it exists.
58    ReadWriteTruncate,
59    /// Create a new empty file. Fail if it exists.
60    ReadWriteCreate,
61    /// Create a new empty file, or truncate an existing file.
62    ReadWriteCreateOrTruncate,
63    /// Create a new empty file, or append to an existing file.
64    ReadWriteCreateOrAppend,
65}
66
67impl FileInfo {
68    /// Are we at the end of the file?
69    pub fn eof(&self) -> bool {
70        self.current_offset == self.entry.size
71    }
72
73    /// How long is the file?
74    pub fn length(&self) -> u32 {
75        self.entry.size
76    }
77
78    /// Seek to a new position in the file, relative to the start of the file.
79    pub fn seek_from_start(&mut self, offset: u32) -> Result<(), FileError> {
80        if offset <= self.entry.size {
81            self.current_offset = offset;
82            if offset < self.current_cluster.0 {
83                // Back to start
84                self.current_cluster = (0, self.entry.cluster);
85            }
86            Ok(())
87        } else {
88            Err(FileError::InvalidOffset)
89        }
90    }
91
92    /// Seek to a new position in the file, relative to the end of the file.
93    pub fn seek_from_end(&mut self, offset: u32) -> Result<(), FileError> {
94        if offset <= self.entry.size {
95            self.current_offset = self.entry.size - offset;
96            if offset < self.current_cluster.0 {
97                // Back to start
98                self.current_cluster = (0, self.entry.cluster);
99            }
100            Ok(())
101        } else {
102            Err(FileError::InvalidOffset)
103        }
104    }
105
106    /// Seek to a new position in the file, relative to the current position.
107    pub fn seek_from_current(&mut self, offset: i32) -> Result<(), FileError> {
108        let new_offset = i64::from(self.current_offset) + i64::from(offset);
109        if new_offset >= 0 && new_offset <= i64::from(self.entry.size) {
110            self.current_offset = new_offset as u32;
111            Ok(())
112        } else {
113            Err(FileError::InvalidOffset)
114        }
115    }
116
117    /// Amount of file left to read.
118    pub fn left(&self) -> u32 {
119        self.entry.size - self.current_offset
120    }
121
122    /// Update the file's length.
123    pub(crate) fn update_length(&mut self, new: u32) {
124        self.entry.size = new;
125        self.entry.size = new;
126    }
127}
embedded_fat/filesystem/files.rs

embedded_fat/filesystem/
files.rs
