mirrors/unleashed-firmware
1
Fork 0
mirror of https://github.com/DarkFlippers/unleashed-firmware.git synced 2025-12-12 20:49:49 +04:00
Code Issues Activity

Documentation: new doc on Storage module and JS cleanup (#4161)

Browse Source 
- Add new doc on Storage module
- Improve formatting in the JS section for better readability
This commit is contained in:
knrn64
2025-03-26 17:29:26 +03:00
committed by GitHub
parent 02dedd60f3
commit 54adc38b3a
17 changed files with 898 additions and 298 deletions
Download Patch File Download Diff File Expand all files Collapse all files

445
documentation/js/js_storage.md Normal file
View File

@@ -0,0 +1,445 @@
# Storage module {#js_storage}
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:
```js
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
<br>
## FileInfo
File information structure.
**Fields**
- path: Full path (e.g. "/ext/test", returned by `stat`) or file name (e.g. "test", returned by `readDirectory`)
- isDirectory: Returns `true` if 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.
<br>
### 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.
<br>
### isOpen()
**Returns**
`true` if file is currently opened, `false` otherwise.
<br>
### 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 `string` decoded from ASCII data (`"ascii"`), or an `ArrayBuf` (`"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.
<br>
### 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.
<br>
### 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.
<br>
### 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.
<br>
### tell()
Gets the absolute position of the R/W pointer in bytes.
**Returns**
The absolute current position in the file.
<br>
### 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.
<br>
### size()
**Returns**
The total size of the file in bytes.
<br>
### eof()
Detects whether the R/W pointer has reached the end of the file.
**Returns**
`true` if end of file reached, `false` otherwise.
<br>
### 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.
<br>
## 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.
<br>
## 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**
```js
if (storage.fileOrDirExists("/ext/test_dir")) {
print("Test directory exists");
}
```
<br>
## 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**
```js
let fsinfo = storage.fsInfo("/ext");
if (fsinfo === undefined) {
print("Filesystem access error");
} else {
print("Free space on the /ext filesystem:", fsinfo.freeSpace);
}
```
<br>
## 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**
```js
let finfo = storage.stat("/ext/test_file.txt");
if (finfo === undefined) {
print("File not found");
} else {
print("File size:", finfo.size);
}
```
<br>
## directoryExists()
Detects whether a directory exists.
**Parameters**
- path: The path to the directory
**Returns**
`true` if directory exists, `false` otherwise.
<br>
## makeDirectory()
Creates an empty directory.
**Parameters**
- path: The path to the new directory
**Returns**
`true` on success, `false` on failure.
<br>
## 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.
<br>
## 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.
<br>
## 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**
```js
if (storage.copy("/ext/src_file.txt", "/ext/dst_file.txt")) {
print("File copied");
}
```
<br>
## 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**
```js
if (storage.rename("/ext/src_file.txt", "/ext/dst_file.txt")) {
print("File moved");
}
```
<br>
## 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**
```js
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");
}
```
<br>
## 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**
```js
let path = "/ext/test_dir";
if (storage.rmrf(path)) {
print("Directory removed");
}
```