@signageos/front-applet 7.2.0 → 8.0.1

package/es6/FrontApplet/FileSystem/FileSystem.d.ts

@@ -2,32 +2,187 @@ import IPostMessage from '../IPostMessage';
 import { IStorageUnit, IFilePath, IFile, IHeaders, ICopyFileOptions, IMoveFileOptions } from './types';
 import StorageUnitsChangedMessage from './StorageUnitsChangedMessage';
 import IFileSystem from './IFileSystem';
+import { HashAlgorithm } from './HashAlgorithm';
+/**
+ * The `sos.fileSystem` API groups together methods for low-level access to the file system. The File System API supports both internal and
+ * external storage.
+ *
+ * :::warning
+ *
+ * File System directory structure is **PERSISTENT** and is **NOT** automatically deleted through `Applet Reload` power action!
+ * Applet Reload only deletes `/data` directory which is reserved for simplified [Offline Cache API](./offline). Use
+ * `deleteFile()` to clear the device storage file system.
+ *
+ * :::
+ */
 export default class FileSystem implements IFileSystem {
     private messagePrefix;
     private postMessage;
     static MESSAGE_PREFIX: string;
     private eventEmitter;
+    /** @internal */
     constructor(messagePrefix: string, postMessage: IPostMessage<any>);
+    /**
+     * The `listStorageUnits()` method lists all available storage units. All devices always have one internal storage device (with
+     * `removable: false`) and zero or more external devices. The capacity values are in bytes.
+     */
     listStorageUnits(): Promise<IStorageUnit[]>;
+    /**
+     * A shorthand method for listing only the internal storage units (i.e. those with the `removable: false`). The capacity values are in bytes.
+     */
+    listInternalStorageUnits(): Promise<IStorageUnit[]>;
+    /**
+     * The `onStorageUnitsChanged()` method sets up a listener, which is called whenever the list of storage units changes.
+     */
     onStorageUnitsChanged(listener: () => void): void;
+    /**
+     * The `removeStorageUnitsChangedListener()` method removes a listener, previously added by `onStorageUnitsChanged()`
+     */
     removeStorageUnitsChangedListener(listener: () => void): void;
+    /**
+     * The `removeAllListeners()` method removes all listeners, previously added by `removeAllListeners()`
+     */
     removeAllListeners(): void;
+    /**
+     * The `listFiles()` method lists all files and directories in the specified path (nested files are not included).
+     *
+     * @throws If the path does not exist or it is a file.
+     */
     listFiles(directoryPath: IFilePath): Promise<IFilePath[]>;
+    /**
+     * The `exists()` method checks whether a file or directory exists.
+     */
     exists(filePath: IFilePath): Promise<boolean>;
+    /**
+     * The `getFile()` method returns runtime information about a file path, such as local url, last modified date or size.
+     */
     getFile(filePath: IFilePath): Promise<IFile | null>;
+    /**
+     * The `writeFile()` method writes string content to the file specified by `filePath`. If the file does exist, it is created. If the directory
+     * does not exist, an error is thrown.
+     *
+     * @throws If the parent directory does not exist or the `filePath` is a directory.
+     */
     writeFile(filePath: IFilePath, contents: string): Promise<void>;
+    /**
+     * The `writeFile()` method appends string content to the file specified by `filePath`. If the file does exist, it is created. If the directory
+     * does not exist, an error is thrown.
+     *
+     * @throws If the parent directory does not exist or the `filePath` is a directory.
+     */
     appendFile(filePath: IFilePath, contents: string): Promise<void>;
+    /**
+     * The `readFile()` method returns content of the file specified by `filePath`. The file has to be a text file, otherwise the content will be
+     * mangled.
+     *
+     * @throws If the file does not exist.
+     */
     readFile(filePath: IFilePath): Promise<string>;
+    /**
+     * The `copyFile()` method creates a copy of file at `sourceFilePath` to `destinationFilePath`.
+     *
+     * @param options.overwrite If not set or set to `false`, an error will be thrown if `destinationFilePath` already exists.
+     *
+     * @throws If the source file does not exists or parent of the destination file path does not exists. It also throws if the
+     * `options.overwrite` is not set and the destination file path already exists.
+     */
     copyFile(sourceFilePath: IFilePath, destinationFilePath: IFilePath, options?: ICopyFileOptions): Promise<void>;
+    /**
+     * The `moveFile()` method moves a file from `sourceFilePath` to `destinationFilePath`.
+     *
+     * @throws If the source file does not exists or parent of the destination file path does not exists. It also throws if the
+     * `options.overwrite` is not set and the destination file path already exists.
+     */
     moveFile(sourceFilePath: IFilePath, destinationFilePath: IFilePath, options?: IMoveFileOptions): Promise<void>;
+    /**
+     * The `deleteFile()` method deletes the file specified by `filePath`. To remove a directory set `recursive` to `true`.
+     *
+     * @throws If the file does not exists or if `recursive` is set to false and the file path is a directory.
+     */
     deleteFile(filePath: IFilePath, recursive: boolean): Promise<void>;
+    /**
+     * The `downloadFile()` method download a file from `sourceUri` and saves it to the specified path. If the file already exists it is
+     * overwritten. Optionally, headers for the download request may be specified. A HEAD request is always sent first to get `content-length`
+     * of the downloaded file.
+     *
+     * :::warning
+     * - For every download request, our app makes HEAD request for `content-length` header on that downloaded file.
+     * - Windows platform can download only files smaller then 4GB.
+     * :::
+     *
+     * #### Encoding
+     *
+     * All downloads respect a standard of `Encoding` with optional compression of files. See [Mozilla standard Accept Encoding](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding) and [Content Encoding](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding).
+     *
+     * Download file method is always sending optional following headers:
+     * ```
+     * Accept-Encoding: gzip
+     * Accept-Encoding: compress
+     * Accept-Encoding: deflate
+     * Accept-Encoding: br
+     * Accept-Encoding: identity
+     * Accept-Encoding: *
+     * ```
+     *
+     * If the server understands the `Encoding` standard, it compresses files using `gzip` algorithm before the files are sent to the client. If so, the response will contain the following headers:
+     * ```
+     * Content-Encoding: gzip
+     * Content-Encoding: compress
+     * Content-Encoding: deflate
+     * Content-Encoding: br
+     * ```
+     * So the data communication is compressed under the hood. The client will automatically decompress data before it's saved to a specified location path. So from JS API point of view, there is no requirement to decompress data by itself.
+     *
+     * The standard is supported on all following platforms:
+     *
+     * - WebOS 3+
+     * - Tizen 2.4+
+     * - Brightsign
+     * - Raspberry Pi
+     * - Windows
+     *
+     * @throws If the network request fails, parent directory does not exist, or the file path is a directory.
+     */
     downloadFile(filePath: IFilePath, sourceUri: string, headers?: IHeaders): Promise<void>;
+    /**
+     * The `decompressFile()` method decompresses the file at `archiveFilePath` into a new file specified by `destinationDirectoryPath`.
+     *
+     * @throws If the archive file path does not exist, it is not a valid archive file or the destination directory does not exist.
+     */
     extractFile(archiveFilePath: IFilePath, destinationDirectoryPath: IFilePath, method: string): Promise<void>;
+    /**
+     * The `createArchive()` method creates an arch file at `archiveFilePath` from `archiveEntries` files.
+     *
+     * :::warning
+     *
+     * This function is available only on Tizen devices.
+     *
+     * :::
+     */
     createArchive(archiveFilePath: IFilePath, archiveEntries: IFilePath[]): Promise<void>;
-    getFileChecksum(filePath: IFilePath, hashType: string): Promise<string>;
+    /**
+     * The `getChecksumFile()` method computes a checksum of the file specified by `filePath`.
+     *
+     * @throws If the file does not exist or it is a directory.
+     */
+    getFileChecksum(filePath: IFilePath, hashType: HashAlgorithm): Promise<string>;
+    /**
+     * The `createDirectory()` method create a new directory at specified path.
+     *
+     * @throws If the directory already exists or its parent directory does not exist.
+     */
     createDirectory(directoryPath: IFilePath): Promise<void>;
+    /**
+     * The `isDirectory()` method checks whether the file path points to a directory.
+     *
+     * @throws If the file path does not exist.
+     */
     isDirectory(filePath: IFilePath): Promise<boolean>;
+    /**
+     * The `link()` method creates a symbolic link to `sourceFilePath` (existing path) from `destinationFilePath` (new path).
+     */
     link(sourceFilePath: IFilePath, destinationFilePath: IFilePath): Promise<void>;
+    /** @internal */
     handleMessageData(data: StorageUnitsChangedMessage): void;
     private getMessage;
 }