File.h
Go to the documentation of this file.
1 /****
2  * File.h
3  *
4  * Copyright 2019 mikee47 <mike@sillyhouse.net>
5  *
6  * This file is part of the IFS Library
7  *
8  * This library is free software: you can redistribute it and/or modify it under the terms of the
9  * GNU General Public License as published by the Free Software Foundation, version 3 or later.
10  *
11  * This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
12  * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
13  * See the GNU General Public License for more details.
14  *
15  * You should have received a copy of the GNU General Public License along with this library.
16  * If not, see <https://www.gnu.org/licenses/>.
17  *
18  ****/
19 
20 #pragma once
21 
22 #include "FsBase.h"
23 
24 namespace IFS
25 {
29 class File : public FsBase
30 {
31 public:
32  using FsBase::FsBase;
33 
38  static constexpr OpenFlags ReadOnly{OpenFlag::Read};
39  static constexpr OpenFlags WriteOnly{OpenFlag::Write};
40  static constexpr OpenFlags ReadWrite{OpenFlag::Read | OpenFlag::Write};
41  static constexpr OpenFlags Create{OpenFlag::Create};
42  static constexpr OpenFlags Append{OpenFlag::Append};
43  static constexpr OpenFlags Truncate{OpenFlag::Truncate};
44  static constexpr OpenFlags CreateNewAlways{OpenFlag::Create |
45  OpenFlag::Truncate};
46 
48  ~File()
49  {
50  close();
51  }
52 
53  explicit operator bool() const
54  {
55  return handle >= 0;
56  }
57 
63  bool stat(Stat& stat)
64  {
65  GET_FS(false);
66  return check(fs->fstat(handle, &stat));
67  }
68 
80  int control(ControlCode code, void* buffer, size_t bufSize)
81  {
83  int res = fs->fcontrol(handle, code, buffer, bufSize);
84  check(res);
85  return res;
86  }
87 
94  template <typename T> bool open(const T& path, OpenFlags flags = OpenFlag::Read)
95  {
96  GET_FS(false);
97  fs->close(handle);
98  handle = fs->open(path, flags);
99  return check(handle);
100  }
101 
106  bool close()
107  {
108  if(handle < 0) {
109  return true;
110  }
111  GET_FS(false);
112  int res = fs->close(handle);
113  handle = -1;
114  return check(res);
115  }
116 
123  int read(void* data, size_t size)
124  {
125  GET_FS(lastError);
126  int res = fs->read(handle, data, size);
127  check(res);
128  return res;
129  }
130 
137  int write(const void* data, size_t size)
138  {
139  GET_FS(lastError);
140  int res = fs->write(handle, data, size);
141  check(res);
142  return res;
143  }
144 
145  bool write(const String& s)
146  {
147  size_t len = s.length();
148  return write(s.c_str(), len) == int(len);
149  }
150 
158  {
159  GET_FS(lastError);
160  auto res = fs->lseek(handle, offset, origin);
161  check(res);
162  return res;
163  }
164 
169  bool eof()
170  {
171  auto fs = getFileSystem();
172  if(fs == nullptr) {
173  return true;
174  }
175  int res = fs->eof(handle);
176  check(res);
177  return res != FS_OK;
178  }
179 
185  {
186  GET_FS(lastError);
187  auto res = fs->tell(handle);
188  check(res);
189  return res;
190  }
191 
197  bool truncate(file_size_t new_size)
198  {
199  GET_FS(lastError);
200  int res = fs->ftruncate(handle, new_size);
201  return check(res);
202  }
203 
208  bool truncate()
209  {
210  GET_FS(lastError);
211  int res = fs->ftruncate(handle);
212  return check(res);
213  }
214 
219  bool flush()
220  {
221  GET_FS(false);
222  return check(fs->flush(handle));
223  }
224 
230  bool setacl(const ACL& acl)
231  {
232  GET_FS(false);
233  return check(fs->setacl(handle, acl));
234  }
235 
241  bool settime(time_t mtime)
242  {
243  GET_FS(false);
244  return check(fs->settime(handle, mtime));
245  }
246 
252  bool setcompression(const Compression& compression)
253  {
254  GET_FS(false);
255  return check(fs->setcompression(handle, compression));
256  }
257 
258  template <typename... ParamTypes> bool setAttribute(AttributeTag tag, ParamTypes... params)
259  {
260  GET_FS(false);
261  return check(fs->setAttribute(handle, tag, params...));
262  }
263 
264  template <typename... ParamTypes> int getAttribute(AttributeTag tag, ParamTypes... params)
265  {
266  GET_FS(lastError);
267  return check(fs->getAttribute(handle, tag, params...));
268  }
269 
270  template <typename... ParamTypes> bool setUserAttribute(uint8_t tagValue, ParamTypes... params)
271  {
272  GET_FS(false);
273  return check(fs->setAttribute(handle, getUserAttributeTag(tagValue), params...));
274  }
275 
276  template <typename... ParamTypes> int getUserAttribute(uint8_t tagValue, ParamTypes... params)
277  {
278  GET_FS(lastError);
279  return check(fs->getUserAttribute(handle, tagValue, params...));
280  }
281 
283  {
284  GET_FS(nullptr);
285  return fs->getUserAttribute(handle, tagValue);
286  }
287 
288  bool removeUserAttribute(uint8_t tagValue)
289  {
290  GET_FS(false);
291  return check(fs->removeUserAttribute(handle, tagValue));
292  }
293 
294  int enumAttributes(AttributeEnumCallback callback, void* buffer, size_t bufsize)
295  {
296  GET_FS(lastError);
297  int res = fs->fenumxattr(handle, callback, buffer, bufsize);
298  check(res);
299  return res;
300  }
301 
306  bool remove()
307  {
308  GET_FS(false);
309  int res = fs->fremove(handle);
310  if(!check(res)) {
311  return false;
312  }
313  fs->close(handle);
314  handle = -1;
315  return true;
316  }
317 
323  {
324  GET_FS(lastError);
325  return fs->getSize(handle);
326  }
327 
329 
336  file_offset_t readContent(size_t size, ReadContentCallback callback)
337  {
338  GET_FS(lastError);
339  auto res = fs->readContent(handle, size, callback);
340  check(res);
341  return res;
342  }
343 
350  {
351  GET_FS(lastError);
352  auto res = fs->readContent(handle, callback);
353  check(res);
354  return res;
355  }
356 
365  {
366  String s;
367  auto len = getSize();
368  if(!s.setLength(len)) {
369  return nullptr;
370  }
371 
372  if(read(s.begin(), len) != int(len)) {
373  return nullptr;
374  }
375 
376  return s;
377  }
378 
383  {
384  auto res = handle;
385  handle = -1;
386  return res;
387  }
388 
389  int getExtents(Storage::Partition* part, Extent* list, uint16_t extcount)
390  {
391  GET_FS(lastError);
392  int res = fs->fgetextents(handle, part, list, extcount);
393  check(res);
394  return res;
395  }
396 
397 private:
398  FileHandle handle{-1};
399 };
400 
401 }; // namespace IFS
Represents a flash partition.
Definition: Partition.h:85
bool eof()
determine if current file position is at end of file
Definition: File.h:203
bool flush()
flush any buffered data to physical media
Definition: File.h:253
bool open(const T &path, OpenFlags flags=OpenFlag::Read)
open a file by name/path
Definition: File.h:128
static constexpr OpenFlags Truncate
Truncate existing file to zero length.
Definition: File.h:77
bool setacl(const ACL &acl)
Set access control information for file.
Definition: File.h:264
int getExtents(Storage::Partition *part, Extent *list, uint16_t extcount)
Definition: File.h:423
Wraps up all file access methods.
Definition: File.h:46
int write(const void *data, size_t size)
write content to a file at current position and advance cursor
Definition: File.h:171
static constexpr OpenFlags ReadWrite
Read + Write.
Definition: File.h:74
char * begin()
Get a modifiable pointer to String content.
Definition: WString.h:625
The String class.
Definition: WString.h:136
FileSystem * getFileSystem() const
Definition: FsBase.h:81
int getUserAttribute(uint8_t tagValue, ParamTypes... params)
Definition: File.h:310
constexpr ErrorCode FS_OK
Definition: Components/IFS/src/include/IFS/Error.h:130
static constexpr OpenFlags WriteOnly
Write-only.
Definition: File.h:73
Defines the location of a contiguous run of file data.
Definition: Extent.h:57
bool setcompression(const Compression &compression)
Set file compression information.
Definition: File.h:286
bool check(int64_t res)
Check file operation result and note error code.
Definition: FsBase.h:101
bool setLength(size_t length)
set the string length accordingly, expanding if necessary
static constexpr OpenFlags Append
Append to existing file.
Definition: File.h:76
BitSet< uint8_t, OpenFlag, size_t(OpenFlag::MAX)> OpenFlags
Definition: OpenFlags.h:69
bool truncate()
Truncate an open file at the current cursor position.
Definition: File.h:242
bool close()
close an open file
Definition: File.h:140
AttributeTag getUserAttributeTag(uint8_t value)
Definition: Attribute.h:104
int16_t FileHandle
File handle.
Definition: Stat.h:59
Definition: DirectoryTemplate.h:36
static constexpr OpenFlags ReadOnly
Read-only.
Definition: File.h:72
ControlCode
See IFS::IFileSystem::fcontrol
Definition: Components/IFS/src/include/IFS/Control.h:48
int read(void *data, size_t size)
read content from a file and advance cursor
Definition: File.h:157
FileHandle release()
Return current file handle and release ownership.
Definition: File.h:416
Delegate< int(const char *buffer, size_t size)> ReadContentCallback
Callback for readContent method.
Definition: Components/IFS/src/include/IFS/FileSystem.h:305
int32_t file_offset_t
Definition: Components/IFS/src/include/IFS/Types.h:51
bool stat(Stat &stat)
get file information
Definition: File.h:97
Manage a set of bit values using enumeration.
Definition: BitSet.h:44
FileSystem::ReadContentCallback ReadContentCallback
Definition: File.h:362
String getContent()
Read content of the file, from current position.
Definition: File.h:398
int getAttribute(AttributeTag tag, ParamTypes... params)
Definition: File.h:298
const char * c_str() const
Get a constant (un-modifiable) pointer to String content.
Definition: WString.h:616
int lastError
Definition: FsBase.h:112
#define GET_FS(failure)
Definition: FsBase.h:45
int enumAttributes(AttributeEnumCallback callback, void *buffer, size_t bufsize)
Definition: File.h:328
~File()
Definition: File.h:82
file_offset_t tell()
get current file position
Definition: File.h:218
AttributeTag
Identifies a specific attribute.
Definition: Attribute.h:64
file_size_t getSize()
Get size of file.
Definition: File.h:356
FsBase(IFileSystem *filesys=nullptr)
Definition: FsBase.h:54
IFS::FileHandle FileHandle
Definition: Core/FileSystem.h:24
bool removeUserAttribute(uint8_t tagValue)
Definition: File.h:322
SeekOrigin
Stream/file seek origins.
Definition: SeekOrigin.h:18
A compression descriptor.
Definition: Compression.h:57
bool settime(time_t mtime)
Set modification time for file.
Definition: File.h:275
bool setUserAttribute(uint8_t tagValue, ParamTypes... params)
Definition: File.h:304
bool setAttribute(AttributeTag tag, ParamTypes... params)
Definition: File.h:292
static constexpr OpenFlags Create
Create file if it doesn't exist.
Definition: File.h:75
file_offset_t seek(file_offset_t offset, SeekOrigin origin)
change file read/write position
Definition: File.h:191
Definition: Delegate.h:20
bool remove()
remove (delete) an open file (and close it)
Definition: File.h:340
int control(ControlCode code, void *buffer, size_t bufSize)
Low-level and non-standard file control operations.
Definition: File.h:114
size_t length(void) const
Obtain the String length in characters, excluding NUL terminator.
Definition: WString.h:243
file_offset_t readContent(size_t size, ReadContentCallback callback)
Read from current file position and invoke callback for each block read.
Definition: File.h:370
uint32_t file_size_t
Definition: Components/IFS/src/include/IFS/Types.h:50
static constexpr OpenFlags CreateNewAlways
Create new file or overwrite file if it exists.
Definition: File.h:78