54adc38b3a
- Add new doc on Storage module - Improve formatting in the JS section for better readability
8.0 KiB
Storage module
The module allows you to access files and directories on the Flipper Zero filesystems. Call the require function to load the module before first using its methods:
let storage = require("storage");
Paths
To work with files and folders, you'll need to specify paths to them. File paths have the following structure:
/ext/example_subdir_1/example_subdir_2/example_file.txt
\____________________________________/ \__________/ \_/
dirPath fileName fileExt
- dirPath — directory path starting with
/int/(small storage in the MCU's flash memory) or/ext/(microSD card storage). Specify the sub-directories containing the file using/as a separator between directory names. - fileName — file name.
- fileExt — file extension (separated from the file name by a period).
Structures
FsInfo
Filesystem information structure.
Fields
- totalSpace: Total size of the filesystem, in bytes
- freeSpace: Free space in the filesystem, in bytes
FileInfo
File information structure.
Fields
- path: Full path (e.g. "/ext/test", returned by
stat) or file name (e.g. "test", returned byreadDirectory) - isDirectory: Returns
trueif path leads to a directory (not a file) - size: File size in bytes, or 0 in the case of directories
- accessTime: Time of last access as a UNIX timestamp
Classes
File
This class implements methods for working with file. To get an object of the File class, use the OpenFile method.
close()
Closes the file. After this method is called, all other operations related to this file become unavailable.
Returns
true on success, false on failure.
isOpen()
Returns
true if file is currently opened, false otherwise.
read()
Reads bytes from a file opened in read-only or read-write mode.
Parameters
- mode: The data type to interpret the bytes as: a
stringdecoded from ASCII data ("ascii"), or anArrayBuf("binary") - bytes: How many bytes to read from the file
Returns
An ArrayBuf if the mode is "binary", a string if the mode is ascii. The number of bytes that was actually read may be fewer than requested.
write()
Writes bytes to a file opened in write-only or read-write mode.
Parameters
- data: The data to write: a string that will be ASCII-encoded, or an ArrayBuf
Returns
The amount of bytes that was actually written.
seekRelative()
Moves the R/W pointer forward.
Parameters
- bytes: How many bytes to move the pointer forward by
Returns
true on success, false on failure.
seekAbsolute()
Moves the R/W pointer to an absolute position inside the file.
Parameters
- bytes: The position inside the file
Returns
true on success, false on failure.
tell()
Gets the absolute position of the R/W pointer in bytes.
Returns
The absolute current position in the file.
truncate()
Discards the data after the current position of the R/W pointer in a file opened in either write-only or read-write mode.
Returns
true on success, false on failure.
size()
Returns
The total size of the file in bytes.
eof()
Detects whether the R/W pointer has reached the end of the file.
Returns
true if end of file reached, false otherwise.
copyTo()
Copies bytes from the R/W pointer in the current file to the R/W pointer in another file.
Parameters
- dest: The file to copy the bytes into
- bytes: The number of bytes to copy
Returns
true on success, false on failure.
Methods
arePathsEqual()
Determines whether the two paths are equivalent. Respects filesystem-defined path equivalence rules.
Parameters
- path1: The first path for comparison
- path2: The second path for comparison
Returns
true if path1 and path2 are equals, false otherwise.
isSubpathOf()
Determines whether a path is a subpath of another path. Respects filesystem-defined path equivalence rules.
Parameters
- parentPath: The parent path
- childPath: The child path
Returns
true if path1 and path2 are equals, false otherwise.
fileOrDirExists()
Detects whether a file or a directory exists.
Parameters
- path: The path to the file or directory
Returns
true if file/directory exists, false otherwise.
Example
if (storage.fileOrDirExists("/ext/test_dir")) {
print("Test directory exists");
}
fsInfo()
Fetches generic information about a filesystem.
Parameters
- filesystem: The path to the filesystem (e.g.
"/ext"or"/int")
Returns
A fsInfo structure or undefined on failure.
Example
let fsinfo = storage.fsInfo("/ext");
if (fsinfo === undefined) {
print("Filesystem access error");
} else {
print("Free space on the /ext filesystem:", fsinfo.freeSpace);
}
stat()
Acquires metadata about a file or directory.
Parameters
- path: The path to the file or directory
Returns
A FileInfo structure or undefined on failure.
Example
let finfo = storage.stat("/ext/test_file.txt");
if (finfo === undefined) {
print("File not found");
} else {
print("File size:", finfo.size);
}
directoryExists()
Detects whether a directory exists.
Parameters
- path: The path to the directory
Returns
true if directory exists, false otherwise.
makeDirectory()
Creates an empty directory.
Parameters
- path: The path to the new directory
Returns
true on success, false on failure.
readDirectory()
Reads the list of files in a directory.
Parameters
- path: The path to the directory
Returns
Array of FileInfo structures with directory entries, or undefined on failure.
nextAvailableFilename()
Chooses the next available filename with a numeric suffix in a directory.
/ext/example_dir/example_file123.txt
\______________/ \__________/\_/ \_/
dirPath fileName | |
| +--- fileExt
+------- suffix selected by this function
Parameters
- dirPath: The directory to look in
- fileName: The base of the filename (the part before the numeric suffix)
- fileExt: The extension of the filename (the part after the numeric suffix)
- maxLen: The maximum length of the filename with the numeric suffix
Returns
The base of the filename with the next available numeric suffix, without the extension or the base directory.
copy()
Copies a file or recursively copies a possibly non-empty directory.
Parameters
- oldPath: The original path to the file or directory
- newPath: The new path that the copy of the file or directory will be accessible under
Returns
true on success, false on failure.
Example
if (storage.copy("/ext/src_file.txt", "/ext/dst_file.txt")) {
print("File copied");
}
rename()
Renames or moves a file or directory.
Parameters
- oldPath: The old path to the file or directory
- newPath: The new path that the file or directory will become accessible
Returns
true on success, false on failure.
Example
if (storage.rename("/ext/src_file.txt", "/ext/dst_file.txt")) {
print("File moved");
}
remove()
Removes a file or an empty directory.
Parameters
- path: The path to the file or directory
Returns
true on success, false on failure.
Example
let path = "/ext/test_file.txt";
file = storage.openFile(path, "w", "create_always");
file.write("Test");
file.close();
print("File created");
if (storage.remove(path)) {
print("File removed");
}
rmrf()
Removes a file or recursively removes a possibly non-empty directory.
Parameters
- path: The path to the file or directory
Returns
true on success, false on failure.
Example
let path = "/ext/test_dir";
if (storage.rmrf(path)) {
print("Directory removed");
}