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};
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 
282  String getUserAttribute(uint8_t tagValue)
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(const 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, const 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
int32_t file_offset_t
Definition: Components/IFS/src/include/IFS/Types.h:51
uint32_t file_size_t
Definition: Components/IFS/src/include/IFS/Types.h:50
#define GET_FS(failure)
Definition: FsBase.h:27
SeekOrigin
Stream/file seek origins.
Definition: SeekOrigin.h:18
Manage a set of bit values using enumeration.
Definition: BitSet.h:45
Definition: Delegate.h:20
Delegate< int(const char *buffer, size_t size)> ReadContentCallback
Callback for readContent method.
Definition: Components/IFS/src/include/IFS/FileSystem.h:305
Wraps up all file access methods.
Definition: File.h:30
static constexpr OpenFlags ReadOnly
Read-only.
Definition: File.h:38
bool removeUserAttribute(uint8_t tagValue)
Definition: File.h:288
bool eof()
determine if current file position is at end of file
Definition: File.h:169
static constexpr OpenFlags Append
Append to existing file.
Definition: File.h:42
int getUserAttribute(uint8_t tagValue, ParamTypes... params)
Definition: File.h:276
bool truncate()
Truncate an open file at the current cursor position.
Definition: File.h:208
~File()
Definition: File.h:48
bool close()
close an open file
Definition: File.h:106
bool setUserAttribute(uint8_t tagValue, ParamTypes... params)
Definition: File.h:270
FileHandle release()
Return current file handle and release ownership.
Definition: File.h:382
file_offset_t seek(file_offset_t offset, SeekOrigin origin)
change file read/write position
Definition: File.h:157
int getAttribute(AttributeTag tag, ParamTypes... params)
Definition: File.h:264
bool stat(Stat &stat)
get file information
Definition: File.h:63
static constexpr OpenFlags ReadWrite
Read + Write.
Definition: File.h:40
bool setAttribute(AttributeTag tag, ParamTypes... params)
Definition: File.h:258
bool flush()
flush any buffered data to physical media
Definition: File.h:219
String getUserAttribute(uint8_t tagValue)
Definition: File.h:282
static constexpr OpenFlags Create
Create file if it doesn't exist.
Definition: File.h:41
static constexpr OpenFlags Truncate
Truncate existing file to zero length.
Definition: File.h:43
bool write(const String &s)
Definition: File.h:145
int write(const void *data, size_t size)
write content to a file at current position and advance cursor
Definition: File.h:137
bool setcompression(const Compression &compression)
Set file compression information.
Definition: File.h:252
int getExtents(Storage::Partition *part, Extent *list, uint16_t extcount)
Definition: File.h:389
file_offset_t tell()
get current file position
Definition: File.h:184
static constexpr OpenFlags WriteOnly
Write-only.
Definition: File.h:39
bool remove()
remove (delete) an open file (and close it)
Definition: File.h:306
bool settime(time_t mtime)
Set modification time for file.
Definition: File.h:241
file_offset_t readContent(size_t size, const ReadContentCallback &callback)
Read from current file position and invoke callback for each block read.
Definition: File.h:336
file_size_t getSize()
Get size of file.
Definition: File.h:322
int enumAttributes(const AttributeEnumCallback &callback, void *buffer, size_t bufsize)
Definition: File.h:294
int read(void *data, size_t size)
read content from a file and advance cursor
Definition: File.h:123
String getContent()
Read content of the file, from current position.
Definition: File.h:364
bool open(const T &path, OpenFlags flags=OpenFlag::Read)
open a file by name/path
Definition: File.h:94
file_offset_t readContent(const ReadContentCallback &callback)
Read from current file position to end of file and invoke callback for each block read.
Definition: File.h:349
int control(ControlCode code, void *buffer, size_t bufSize)
Low-level and non-standard file control operations.
Definition: File.h:80
bool setacl(const ACL &acl)
Set access control information for file.
Definition: File.h:230
bool truncate(file_size_t new_size)
Truncate (reduce) the size of an open file.
Definition: File.h:197
static constexpr OpenFlags CreateNewAlways
Create new file or overwrite file if it exists.
Definition: File.h:44
Definition: FsBase.h:34
FsBase(IFileSystem *filesys=nullptr)
Definition: FsBase.h:36
bool check(int64_t res)
Check file operation result and note error code.
Definition: FsBase.h:83
int lastError
Definition: FsBase.h:94
FileSystem * getFileSystem() const
Definition: FsBase.h:63
Represents a flash partition.
Definition: Partition.h:86
The String class.
Definition: WString.h:137
const char * c_str() const
Get a constant (un-modifiable) pointer to String content.
Definition: WString.h:617
bool setLength(size_t length)
set the string length accordingly, expanding if necessary
char * begin()
Get a modifiable pointer to String content.
Definition: WString.h:626
size_t length(void) const
Obtain the String length in characters, excluding NUL terminator.
Definition: WString.h:244
constexpr ErrorCode FS_OK
Definition: Components/IFS/src/include/IFS/Error.h:130
Definition: DirectoryTemplate.h:37
ControlCode
See IFS::IFileSystem::fcontrol
Definition: Components/IFS/src/include/IFS/Control.h:31
AttributeTag
Identifies a specific attribute.
Definition: Attribute.h:45
AttributeTag getUserAttributeTag(uint8_t value)
Definition: Attribute.h:85
int16_t FileHandle
File handle.
Definition: Stat.h:40
Definition: Access.h:34
A compression descriptor.
Definition: Compression.h:38
Defines the location of a contiguous run of file data.
Definition: Extent.h:40
File Status structure.
Definition: Stat.h:52