-
Notifications
You must be signed in to change notification settings - Fork 502
/
FatFile.h
1032 lines (1024 loc) · 35.2 KB
/
FatFile.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/**
* Copyright (c) 2011-2018 Bill Greiman
* This file is part of the SdFat library for SD memory cards.
*
* MIT License
*
* Permission is hereby granted, free of charge, to any person obtaining a
* copy of this software and associated documentation files (the "Software"),
* to deal in the Software without restriction, including without limitation
* the rights to use, copy, modify, merge, publish, distribute, sublicense,
* and/or sell copies of the Software, and to permit persons to whom the
* Software is furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included
* in all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
* OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
* DEALINGS IN THE SOFTWARE.
*/
#ifndef FatFile_h
#define FatFile_h
/**
* \file
* \brief FatFile class
*/
// #include <ctype.h>
#include <string.h>
#include <stddef.h>
#include <limits.h>
#include "FatLibConfig.h"
#include "FatApiConstants.h"
#include "FatStructs.h"
#include "FatVolume.h"
class FatFileSystem;
//------------------------------------------------------------------------------
// Stuff to store strings in AVR flash.
#ifdef __AVR__
#include <avr/pgmspace.h>
#else // __AVR__
#ifndef PSTR
/** store literal string in flash for ARM */
#define PSTR(x) (x)
#endif // PSTR
#ifndef pgm_read_byte
/** read 8-bits from flash for ARM */
#define pgm_read_byte(addr) (*(const unsigned char*)(addr))
#endif // pgm_read_byte
#ifndef pgm_read_word
/** read 16-bits from flash for ARM */
#define pgm_read_word(addr) (*(const uint16_t*)(addr))
#endif // pgm_read_word
#ifndef PROGMEM
/** store in flash for ARM */
#define PROGMEM
#endif // PROGMEM
#endif // __AVR__
//------------------------------------------------------------------------------
/**
* \struct FatPos_t
* \brief Internal type for file position - do not use in user apps.
*/
struct FatPos_t {
/** stream position */
uint32_t position;
/** cluster for position */
uint32_t cluster;
FatPos_t() : position(0), cluster(0) {}
};
//------------------------------------------------------------------------------
/** Expression for path name separator. */
#define isDirSeparator(c) ((c) == '/')
//------------------------------------------------------------------------------
/**
* \struct fname_t
* \brief Internal type for Short File Name - do not use in user apps.
*/
struct fname_t {
/** Flags for base and extension character case and LFN. */
uint8_t flags;
/** length of Long File Name */
size_t len;
/** Long File Name start. */
const char* lfn;
/** position for sequence number */
uint8_t seqPos;
/** Short File Name */
uint8_t sfn[11];
};
/** Derived from a LFN with loss or conversion of characters. */
const uint8_t FNAME_FLAG_LOST_CHARS = 0X01;
/** Base-name or extension has mixed case. */
const uint8_t FNAME_FLAG_MIXED_CASE = 0X02;
/** LFN entries are required for file name. */
const uint8_t FNAME_FLAG_NEED_LFN =
FNAME_FLAG_LOST_CHARS | FNAME_FLAG_MIXED_CASE;
/** Filename base-name is all lower case */
const uint8_t FNAME_FLAG_LC_BASE = DIR_NT_LC_BASE;
/** Filename extension is all lower case. */
const uint8_t FNAME_FLAG_LC_EXT = DIR_NT_LC_EXT;
//==============================================================================
/**
* \class FatFile
* \brief Basic file class.
*/
class FatFile {
public:
/** Create an instance. */
FatFile() : m_attr(FILE_ATTR_CLOSED), m_error(0) {}
/** Create a file object and open it in the current working directory.
*
* \param[in] path A path with a valid 8.3 DOS name for a file to be opened.
*
* \param[in] oflag Values for \a oflag are constructed by a bitwise-inclusive
* OR of open flags. see FatFile::open(FatFile*, const char*, oflag_t).
*/
FatFile(const char* path, oflag_t oflag) {
m_attr = FILE_ATTR_CLOSED;
m_error = 0;
open(path, oflag);
}
#if DESTRUCTOR_CLOSES_FILE
~FatFile() {
if (isOpen()) {
close();
}
}
#endif // DESTRUCTOR_CLOSES_FILE
#if ENABLE_ARDUINO_FEATURES
/** List directory contents.
*
* \param[in] flags The inclusive OR of
*
* LS_DATE - %Print file modification date
*
* LS_SIZE - %Print file size.
*
* LS_R - Recursive list of subdirectories.
*
* \return true for success or false if an error occurred.
*/
bool ls(uint8_t flags = 0) {
return ls(&Serial, flags);
}
/** %Print a directory date field.
*
* Format is yyyy-mm-dd.
*
* \param[in] fatDate The date field from a directory entry.
*/
static void printFatDate(uint16_t fatDate) {
printFatDate(&Serial, fatDate);
}
/** %Print a directory time field.
*
* Format is hh:mm:ss.
*
* \param[in] fatTime The time field from a directory entry.
*/
static void printFatTime(uint16_t fatTime) {
printFatTime(&Serial, fatTime);
}
/** Print a file's name.
*
* \return The value true is returned for success and
* the value false is returned for failure.
*/
size_t printName() {
return FatFile::printName(&Serial);
}
#endif // ENABLE_ARDUINO_FEATURES
/** \return value of writeError */
bool getWriteError() {
return m_error & WRITE_ERROR;
}
/** Set writeError to zero */
void clearWriteError() {
m_error &= ~WRITE_ERROR;
}
/** Clear all error bits. */
void clearError() {
m_error = 0;
}
/** \return All error bits. */
uint8_t getError() {
return m_error;
}
/** get position for streams
* \param[out] pos struct to receive position
*/
void getpos(FatPos_t* pos);
/** set position for streams
* \param[out] pos struct with value for new position
*/
void setpos(FatPos_t* pos);
/** \return The number of bytes available from the current position
* to EOF for normal files. Zero is returned for directory files.
*/
uint32_t available() {
return isFile() ? fileSize() - curPosition() : 0;
}
/** Close a file and force cached data and directory information
* to be written to the storage device.
*
* \return The value true is returned for success and
* the value false is returned for failure.
*/
bool close();
/** Check for contiguous file and return its raw block range.
*
* \param[out] bgnBlock the first block address for the file.
* \param[out] endBlock the last block address for the file.
*
* \return The value true is returned for success and
* the value false is returned for failure.
*/
bool contiguousRange(uint32_t* bgnBlock, uint32_t* endBlock);
/** Create and open a new contiguous file of a specified size.
*
* \param[in] dirFile The directory where the file will be created.
* \param[in] path A path with a valid file name.
* \param[in] size The desired file size.
* \param[in] startCluster The desired startCluster.
*
* \return The value true is returned for success and
* the value false, is returned for failure.
*/
bool createContiguous(FatFile* dirFile, const char* path,
uint32_t size, uint32_t startCluster = 0);
/** Create and open a new contiguous file of a specified size.
*
* \param[in] path A path with a valid file name.
* \param[in] size The desired file size.
* \param[in] startCluster The desired startCluster.
*
* \return The value true is returned for success and
* the value false, is returned for failure.
*/
bool createContiguous(const char* path,
uint32_t size, uint32_t startCluster = 0) {
return createContiguous(m_cwd, path, size, startCluster);
}
/** \return The current cluster number for a file or directory. */
uint32_t curCluster() const {
return m_curCluster;
}
/** \return The current position for a file or directory. */
uint32_t curPosition() const {
return m_curPosition;
}
/** \return Current working directory */
static FatFile* cwd() {
return m_cwd;
}
/** Set the date/time callback function
*
* \param[in] dateTime The user's call back function. The callback
* function is of the form:
*
* \code
* void dateTime(uint16_t* date, uint16_t* time) {
* uint16_t year;
* uint8_t month, day, hour, minute, second;
*
* // User gets date and time from GPS or real-time clock here
*
* // return date using FAT_DATE macro to format fields
* *date = FAT_DATE(year, month, day);
*
* // return time using FAT_TIME macro to format fields
* *time = FAT_TIME(hour, minute, second);
* }
* \endcode
*
* Sets the function that is called when a file is created or when
* a file's directory entry is modified by sync(). All timestamps,
* access, creation, and modify, are set when a file is created.
* sync() maintains the last access date and last modify date/time.
*
* See the timestamp() function.
*/
static void dateTimeCallback(
void (*dateTime)(uint16_t* date, uint16_t* time)) {
m_dateTime = dateTime;
}
/** Cancel the date/time callback function. */
static void dateTimeCallbackCancel() {
m_dateTime = 0;
}
/** Return a file's directory entry.
*
* \param[out] dir Location for return of the file's directory entry.
*
* \return The value true is returned for success and
* the value false is returned for failure.
*/
bool dirEntry(dir_t* dir);
/**
* \return The index of this file in it's directory.
*/
uint16_t dirIndex() {
return m_dirIndex;
}
/** Format the name field of \a dir into the 13 byte array
* \a name in standard 8.3 short name format.
*
* \param[in] dir The directory structure containing the name.
* \param[out] name A 13 byte char array for the formatted name.
* \return length of the name.
*/
static uint8_t dirName(const dir_t* dir, char* name);
/** \return The number of bytes allocated to a directory or zero
* if an error occurs.
*/
uint32_t dirSize();
/** Dump file in Hex
* \param[in] pr Print stream for list.
* \param[in] pos Start position in file.
* \param[in] n number of locations to dump.
*/
void dmpFile(print_t* pr, uint32_t pos, size_t n);
/** Test for the existence of a file in a directory
*
* \param[in] path Path of the file to be tested for.
*
* The calling instance must be an open directory file.
*
* dirFile.exists("TOFIND.TXT") searches for "TOFIND.TXT" in the directory
* dirFile.
*
* \return true if the file exists else false.
*/
bool exists(const char* path) {
FatFile file;
return file.open(this, path, O_RDONLY);
}
/**
* Get a string from a file.
*
* fgets() reads bytes from a file into the array pointed to by \a str, until
* \a num - 1 bytes are read, or a delimiter is read and transferred to \a str,
* or end-of-file is encountered. The string is then terminated
* with a null byte.
*
* fgets() deletes CR, '\\r', from the string. This insures only a '\\n'
* terminates the string for Windows text files which use CRLF for newline.
*
* \param[out] str Pointer to the array where the string is stored.
* \param[in] num Maximum number of characters to be read
* (including the final null byte). Usually the length
* of the array \a str is used.
* \param[in] delim Optional set of delimiters. The default is "\n".
*
* \return For success fgets() returns the length of the string in \a str.
* If no data is read, fgets() returns zero for EOF or -1 if an error occurred.
*/
int16_t fgets(char* str, int16_t num, char* delim = 0);
/** \return The total number of bytes in a file. */
uint32_t fileSize() const {
return m_fileSize;
}
/** \return The first cluster number for a file or directory. */
uint32_t firstCluster() const {
return m_firstCluster;
}
/**
* Get a file's name followed by a zero byte.
*
* \param[out] name An array of characters for the file's name.
* \param[in] size The size of the array in bytes. The array
* must be at least 13 bytes long. The file's name will be
* truncated if the file's name is too long.
* \return The value true, is returned for success and
* the value false, is returned for failure.
*/
bool getName(char* name, size_t size);
/**
* Get a file's Short File Name followed by a zero byte.
*
* \param[out] name An array of characters for the file's name.
* The array must be at least 13 bytes long.
* \return The value true, is returned for success and
* the value false, is returned for failure.
*/
bool getSFN(char* name);
/** \return True if this is a directory else false. */
bool isDir() const {
return m_attr & FILE_ATTR_DIR;
}
/** \return True if this is a normal file else false. */
bool isFile() const {
return m_attr & FILE_ATTR_FILE;
}
/** \return True if this is a hidden file else false. */
bool isHidden() const {
return m_attr & FILE_ATTR_HIDDEN;
}
/** \return true if this file has a Long File Name. */
bool isLFN() const {
return m_lfnOrd;
}
/** \return True if this is an open file/directory else false. */
bool isOpen() const {
return m_attr;
}
/** \return True if this is the root directory. */
bool isRoot() const {
return m_attr & FILE_ATTR_ROOT;
}
/** \return True if this is the FAT32 root directory. */
bool isRoot32() const {
return m_attr & FILE_ATTR_ROOT32;
}
/** \return True if this is the FAT12 of FAT16 root directory. */
bool isRootFixed() const {
return m_attr & FILE_ATTR_ROOT_FIXED;
}
/** \return True if file is read-only */
bool isReadOnly() const {
return m_attr & FILE_ATTR_READ_ONLY;
}
/** \return True if this is a subdirectory else false. */
bool isSubDir() const {
return m_attr & FILE_ATTR_SUBDIR;
}
/** \return True if this is a system file else false. */
bool isSystem() const {
return m_attr & FILE_ATTR_SYSTEM;
}
/** Check for a legal 8.3 character.
* \param[in] c Character to be checked.
* \return true for a legal 8.3 character else false.
*/
static bool legal83Char(uint8_t c) {
if (c == '"' || c == '|') {
return false;
}
// *+,./
if (0X2A <= c && c <= 0X2F && c != 0X2D) {
return false;
}
// :;<=>?
if (0X3A <= c && c <= 0X3F) {
return false;
}
// [\]
if (0X5B <= c && c <= 0X5D) {
return false;
}
return 0X20 < c && c < 0X7F;
}
/** List directory contents.
*
* \param[in] pr Print stream for list.
*
* \param[in] flags The inclusive OR of
*
* LS_DATE - %Print file modification date
*
* LS_SIZE - %Print file size.
*
* LS_R - Recursive list of subdirectories.
*
* \param[in] indent Amount of space before file name. Used for recursive
* list to indicate subdirectory level.
*
* \return true for success or false if an error occurred.
*/
bool ls(print_t* pr, uint8_t flags = 0, uint8_t indent = 0);
/** Make a new directory.
*
* \param[in] dir An open FatFile instance for the directory that will
* contain the new directory.
*
* \param[in] path A path with a valid 8.3 DOS name for the new directory.
*
* \param[in] pFlag Create missing parent directories if true.
*
* \return The value true is returned for success and
* the value false is returned for failure.
*/
bool mkdir(FatFile* dir, const char* path, bool pFlag = true);
/** Open a file in the volume working directory of a FatFileSystem.
*
* \param[in] fs File System where the file is located.
*
* \param[in] path with a valid 8.3 DOS name for a file to be opened.
*
* \param[in] oflag bitwise-inclusive OR of open mode flags.
* See see FatFile::open(FatFile*, const char*, oflag_t).
*
* \return The value true is returned for success and
* the value false is returned for failure.
*/
bool open(FatFileSystem* fs, const char* path, oflag_t oflag);
/** Open a file by index.
*
* \param[in] dirFile An open FatFile instance for the directory.
*
* \param[in] index The \a index of the directory entry for the file to be
* opened. The value for \a index is (directory file position)/32.
*
* \param[in] oflag bitwise-inclusive OR of open mode flags.
* See see FatFile::open(FatFile*, const char*, oflag_t).
*
* See open() by path for definition of flags.
* \return true for success or false for failure.
*/
bool open(FatFile* dirFile, uint16_t index, oflag_t oflag);
/** Open a file or directory by name.
*
* \param[in] dirFile An open FatFile instance for the directory containing
* the file to be opened.
*
* \param[in] path A path with a valid 8.3 DOS name for a file to be opened.
*
* \param[in] oflag Values for \a oflag are constructed by a
* bitwise-inclusive OR of flags from the following list
*
* O_RDONLY - Open for reading.
*
* O_READ - Same as O_RDONLY (GNU).
*
* O_WRONLY - Open for writing.
*
* O_WRITE - Same as O_WRONLY (GNU).
*
* O_RDWR - Open for reading and writing.
*
* O_APPEND - If set, the file offset shall be set to the end of the
* file prior to each write.
*
* O_AT_END - Set the initial position at the end of the file.
*
* O_CREAT - If the file exists, this flag has no effect except as noted
* under O_EXCL below. Otherwise, the file shall be created
*
* O_EXCL - If O_CREAT and O_EXCL are set, open() shall fail if the file exists.
*
* O_SYNC - Call sync() after each write. This flag should not be used with
* write(uint8_t) or any functions do character at a time writes since sync()
* will be called after each byte.
*
* O_TRUNC - If the file exists and is a regular file, and the file is
* successfully opened and is not read only, its length shall be truncated to 0.
*
* WARNING: A given file must not be opened by more than one FatFile object
* or file corruption may occur.
*
* \note Directory files must be opened read only. Write and truncation is
* not allowed for directory files.
*
* \return The value true is returned for success and
* the value false is returned for failure.
*/
bool open(FatFile* dirFile, const char* path, oflag_t oflag);
/** Open a file in the current working directory.
*
* \param[in] path A path with a valid 8.3 DOS name for a file to be opened.
*
* \param[in] oflag bitwise-inclusive OR of open mode flags.
* See see FatFile::open(FatFile*, const char*, oflag_t).
*
* \return The value true is returned for success and
* the value false is returned for failure.
*/
bool open(const char* path, oflag_t oflag = O_RDONLY) {
return open(m_cwd, path, oflag);
}
/** Open current working directory.
*
* \return true for success or false for failure.
*/
bool openCwd();
/** Open the next file or subdirectory in a directory.
*
* \param[in] dirFile An open FatFile instance for the directory
* containing the file to be opened.
*
* \param[in] oflag bitwise-inclusive OR of open mode flags.
* See see FatFile::open(FatFile*, const char*, oflag_t).
*
* \return true for success or false for failure.
*/
bool openNext(FatFile* dirFile, oflag_t oflag = O_RDONLY);
/** Open a volume's root directory.
*
* \param[in] vol The FAT volume containing the root directory to be opened.
*
* \return The value true is returned for success and
* the value false is returned for failure.
*/
bool openRoot(FatVolume* vol);
/** Return the next available byte without consuming it.
*
* \return The byte if no error and not at eof else -1;
*/
int peek();
/** Print a file's creation date and time
*
* \param[in] pr Print stream for output.
*
* \return The value true is returned for success and
* the value false is returned for failure.
*/
bool printCreateDateTime(print_t* pr);
/** %Print a directory date field.
*
* Format is yyyy-mm-dd.
*
* \param[in] pr Print stream for output.
* \param[in] fatDate The date field from a directory entry.
*/
static void printFatDate(print_t* pr, uint16_t fatDate);
/** %Print a directory time field.
*
* Format is hh:mm:ss.
*
* \param[in] pr Print stream for output.
* \param[in] fatTime The time field from a directory entry.
*/
static void printFatTime(print_t* pr, uint16_t fatTime);
/** Print a number followed by a field terminator.
* \param[in] value The number to be printed.
* \param[in] term The field terminator. Use '\\n' for CR LF.
* \param[in] prec Number of digits after decimal point.
* \return The number of bytes written or -1 if an error occurs.
*/
int printField(float value, char term, uint8_t prec = 2);
/** Print a number followed by a field terminator.
* \param[in] value The number to be printed.
* \param[in] term The field terminator. Use '\\n' for CR LF.
* \return The number of bytes written or -1 if an error occurs.
*/
int printField(int16_t value, char term);
/** Print a number followed by a field terminator.
* \param[in] value The number to be printed.
* \param[in] term The field terminator. Use '\\n' for CR LF.
* \return The number of bytes written or -1 if an error occurs.
*/
int printField(uint16_t value, char term);
/** Print a number followed by a field terminator.
* \param[in] value The number to be printed.
* \param[in] term The field terminator. Use '\\n' for CR LF.
* \return The number of bytes written or -1 if an error occurs.
*/
int printField(int32_t value, char term);
/** Print a number followed by a field terminator.
* \param[in] value The number to be printed.
* \param[in] term The field terminator. Use '\\n' for CR LF.
* \return The number of bytes written or -1 if an error occurs.
*/
int printField(uint32_t value, char term);
/** Print a file's modify date and time
*
* \param[in] pr Print stream for output.
*
* \return The value true is returned for success and
* the value false is returned for failure.
*/
bool printModifyDateTime(print_t* pr);
/** Print a file's name
*
* \param[in] pr Print stream for output.
*
* \return The value true is returned for success and
* the value false is returned for failure.
*/
size_t printName(print_t* pr);
/** Print a file's size.
*
* \param[in] pr Print stream for output.
*
* \return The number of characters printed is returned
* for success and zero is returned for failure.
*/
size_t printFileSize(print_t* pr);
/** Print a file's Short File Name.
*
* \param[in] pr Print stream for output.
*
* \return The number of characters printed is returned
* for success and zero is returned for failure.
*/
size_t printSFN(print_t* pr);
/** Read the next byte from a file.
*
* \return For success read returns the next byte in the file as an int.
* If an error occurs or end of file is reached -1 is returned.
*/
int read() {
uint8_t b;
return read(&b, 1) == 1 ? b : -1;
}
/** Read data from a file starting at the current position.
*
* \param[out] buf Pointer to the location that will receive the data.
*
* \param[in] nbyte Maximum number of bytes to read.
*
* \return For success read() returns the number of bytes read.
* A value less than \a nbyte, including zero, will be returned
* if end of file is reached.
* If an error occurs, read() returns -1. Possible errors include
* read() called before a file has been opened, corrupt file system
* or an I/O error occurred.
*/
int read(void* buf, size_t nbyte);
/** Read the next directory entry from a directory file.
*
* \param[out] dir The dir_t struct that will receive the data.
*
* \return For success readDir() returns the number of bytes read.
* A value of zero will be returned if end of file is reached.
* If an error occurs, readDir() returns -1. Possible errors include
* readDir() called before a directory has been opened, this is not
* a directory file or an I/O error occurred.
*/
int8_t readDir(dir_t* dir);
/** Remove a file.
*
* The directory entry and all data for the file are deleted.
*
* \note This function should not be used to delete the 8.3 version of a
* file that has a long name. For example if a file has the long name
* "New Text Document.txt" you should not delete the 8.3 name "NEWTEX~1.TXT".
*
* \return The value true is returned for success and
* the value false is returned for failure.
*/
bool remove();
/** Remove a file.
*
* The directory entry and all data for the file are deleted.
*
* \param[in] dirFile The directory that contains the file.
* \param[in] path Path for the file to be removed.
*
* \note This function should not be used to delete the 8.3 version of a
* file that has a long name. For example if a file has the long name
* "New Text Document.txt" you should not delete the 8.3 name "NEWTEX~1.TXT".
*
* \return The value true is returned for success and
* the value false is returned for failure.
*/
static bool remove(FatFile* dirFile, const char* path);
/** Set the file's current position to zero. */
void rewind() {
seekSet(0);
}
/** Rename a file or subdirectory.
*
* \note the file will be moved to the current working directory.
*
* \param[in] newPath New path name for the file/directory.
*
* \return The value true is returned for success and
* the value false is returned for failure.
*/
bool rename(const char* newPath) {
return rename(cwd(), newPath);
}
/** Rename a file or subdirectory.
*
* \param[in] dirFile Directory for the new path.
* \param[in] newPath New path name for the file/directory.
*
* \return The value true is returned for success and
* the value false is returned for failure.
*/
bool rename(FatFile* dirFile, const char* newPath);
/** Remove a directory file.
*
* The directory file will be removed only if it is empty and is not the
* root directory. rmdir() follows DOS and Windows and ignores the
* read-only attribute for the directory.
*
* \note This function should not be used to delete the 8.3 version of a
* directory that has a long name. For example if a directory has the
* long name "New folder" you should not delete the 8.3 name "NEWFOL~1".
*
* \return The value true is returned for success and
* the value false is returned for failure.
*/
bool rmdir();
/** Recursively delete a directory and all contained files.
*
* This is like the Unix/Linux 'rm -rf *' if called with the root directory
* hence the name.
*
* Warning - This will remove all contents of the directory including
* subdirectories. The directory will then be removed if it is not root.
* The read-only attribute for files will be ignored.
*
* \note This function should not be used to delete the 8.3 version of
* a directory that has a long name. See remove() and rmdir().
*
* \return The value true is returned for success and
* the value false is returned for failure.
*/
bool rmRfStar();
/** Set the files position to current position + \a pos. See seekSet().
* \param[in] offset The new position in bytes from the current position.
* \return true for success or false for failure.
*/
bool seekCur(int32_t offset) {
return seekSet(m_curPosition + offset);
}
/** Set the files position to end-of-file + \a offset. See seekSet().
* Can't be used for directory files since file size is not defined.
* \param[in] offset The new position in bytes from end-of-file.
* \return true for success or false for failure.
*/
bool seekEnd(int32_t offset = 0) {
return isFile() ? seekSet(m_fileSize + offset) : false;
}
/** Sets a file's position.
*
* \param[in] pos The new position in bytes from the beginning of the file.
*
* \return The value true is returned for success and
* the value false is returned for failure.
*/
bool seekSet(uint32_t pos);
/** Set the current working directory.
*
* \param[in] dir New current working directory.
*
* \return true for success else false.
*/
static bool setCwd(FatFile* dir) {
if (!dir->isDir()) {
return false;
}
m_cwd = dir;
return true;
}
/** \return first block of file or zero for empty file. */
uint32_t firstBlock() {
if (m_firstCluster) {
return m_vol->clusterFirstBlock(m_firstCluster);
}
return 0;
}
/** The sync() call causes all modified data and directory fields
* to be written to the storage device.
*
* \return The value true is returned for success and
* the value false is returned for failure.
*/
bool sync();
/** Copy a file's timestamps
*
* \param[in] file File to copy timestamps from.
*
* \note
* Modify and access timestamps may be overwritten if a date time callback
* function has been set by dateTimeCallback().
*
* \return The value true is returned for success and
* the value false is returned for failure.
*/
bool timestamp(FatFile* file);
/** Set a file's timestamps in its directory entry.
*
* \param[in] flags Values for \a flags are constructed by a bitwise-inclusive
* OR of flags from the following list
*
* T_ACCESS - Set the file's last access date.
*
* T_CREATE - Set the file's creation date and time.
*
* T_WRITE - Set the file's last write/modification date and time.
*
* \param[in] year Valid range 1980 - 2107 inclusive.
*
* \param[in] month Valid range 1 - 12 inclusive.
*
* \param[in] day Valid range 1 - 31 inclusive.
*
* \param[in] hour Valid range 0 - 23 inclusive.
*
* \param[in] minute Valid range 0 - 59 inclusive.
*
* \param[in] second Valid range 0 - 59 inclusive
*
* \note It is possible to set an invalid date since there is no check for
* the number of days in a month.
*
* \note
* Modify and access timestamps may be overwritten if a date time callback
* function has been set by dateTimeCallback().
*
* \return The value true is returned for success and
* the value false is returned for failure.
*/
bool timestamp(uint8_t flags, uint16_t year, uint8_t month, uint8_t day,
uint8_t hour, uint8_t minute, uint8_t second);
/** Type of file. You should use isFile() or isDir() instead of fileType()
* if possible.
*
* \return The file or directory type.
*/
uint8_t fileAttr() const {
return m_attr;
}
/** Truncate a file to a specified length. The current file position
* will be maintained if it is less than or equal to \a length otherwise
* it will be set to end of file.
*
* \param[in] length The desired length for the file.
*
* \return The value true is returned for success and
* the value false is returned for failure.
*/
bool truncate(uint32_t length);
/** \return FatVolume that contains this file. */
FatVolume* volume() const {
return m_vol;
}
/** Write a string to a file. Used by the Arduino Print class.
* \param[in] str Pointer to the string.
* Use getWriteError to check for errors.
* \return count of characters written for success or -1 for failure.
*/
int write(const char* str) {
return write(str, strlen(str));
}
/** Write a single byte.
* \param[in] b The byte to be written.
* \return +1 for success or -1 for failure.
*/
int write(uint8_t b) {
return write(&b, 1);
}
/** Write data to an open file.
*
* \note Data is moved to the cache but may not be written to the
* storage device until sync() is called.
*
* \param[in] buf Pointer to the location of the data to be written.
*
* \param[in] nbyte Number of bytes to write.
*
* \return For success write() returns the number of bytes written, always
* \a nbyte. If an error occurs, write() returns -1. Possible errors
* include write() is called before a file has been opened, write is called
* for a read-only file, device is full, a corrupt file system or an I/O error.
*
*/
int write(const void* buf, size_t nbyte);
//------------------------------------------------------------------------------
private:
/** This file has not been opened. */
static const uint8_t FILE_ATTR_CLOSED = 0;
/** File is read-only. */
static const uint8_t FILE_ATTR_READ_ONLY = DIR_ATT_READ_ONLY;
/** File should be hidden in directory listings. */
static const uint8_t FILE_ATTR_HIDDEN = DIR_ATT_HIDDEN;
/** Entry is for a system file. */
static const uint8_t FILE_ATTR_SYSTEM = DIR_ATT_SYSTEM;
/** Entry for normal data file */
static const uint8_t FILE_ATTR_FILE = 0X08;
/** Entry is for a subdirectory */
static const uint8_t FILE_ATTR_SUBDIR = DIR_ATT_DIRECTORY;
/** A FAT12 or FAT16 root directory */
static const uint8_t FILE_ATTR_ROOT_FIXED = 0X20;
/** A FAT32 root directory */
static const uint8_t FILE_ATTR_ROOT32 = 0X40;
/** Entry is for root. */
static const uint8_t FILE_ATTR_ROOT = FILE_ATTR_ROOT_FIXED | FILE_ATTR_ROOT32;
/** Directory type bits */
static const uint8_t FILE_ATTR_DIR = FILE_ATTR_SUBDIR | FILE_ATTR_ROOT;
/** Attributes to copy from directory entry */
static const uint8_t FILE_ATTR_COPY = DIR_ATT_READ_ONLY | DIR_ATT_HIDDEN |
DIR_ATT_SYSTEM | DIR_ATT_DIRECTORY;
/** experimental don't use */
bool openParent(FatFile* dir);
// private functions
bool addCluster();
bool addDirCluster();
dir_t* cacheDirEntry(uint8_t action);
static uint8_t lfnChecksum(uint8_t* name);
bool lfnUniqueSfn(fname_t* fname);
bool openCluster(FatFile* file);
static bool parsePathName(const char* str, fname_t* fname, const char** ptr);
bool mkdir(FatFile* parent, fname_t* fname);
bool open(FatFile* dirFile, fname_t* fname, oflag_t oflag);
bool openCachedEntry(FatFile* dirFile, uint16_t cacheIndex, oflag_t oflag,
uint8_t lfnOrd);
bool readLBN(uint32_t* lbn);