diff options
Diffstat (limited to '')
| -rw-r--r-- | dom/chrome-webidl/IOUtils.webidl | 766 |
1 files changed, 766 insertions, 0 deletions
diff --git a/dom/chrome-webidl/IOUtils.webidl b/dom/chrome-webidl/IOUtils.webidl new file mode 100644 index 0000000000..e1b67a53bd --- /dev/null +++ b/dom/chrome-webidl/IOUtils.webidl @@ -0,0 +1,766 @@ +/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ +/* This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this file, + * You can obtain one at http://mozilla.org/MPL/2.0/. + */ + +interface nsIFile; + +/** + * IOUtils is a simple, efficient interface for performing file I/O from a + * privileged chrome-only context. All asynchronous I/O tasks are run on + * a background thread. + * + * Pending I/O tasks will block shutdown at the |profileBeforeChange| phase. + * During this shutdown phase, no additional I/O tasks will be accepted -- + * method calls to this interface will reject once shutdown has entered this + * phase. + * + * IOUtils methods may reject for any number of reasons. Reasonable attempts + * have been made to map each common operating system error to a |DOMException|. + * Most often, a caller only needs to check if a given file wasn't found by + * catching the rejected error and checking if |ex.name === 'NotFoundError'|. + * In other cases, it is likely sufficient to allow the error to be caught and + * reported elsewhere. + */ +[ChromeOnly, Exposed=(Window, Worker)] +namespace IOUtils { + /** + * Reads up to |opts.maxBytes| of the file at |path| according to |opts|. + * + * NB: The maximum file size that can be read is UINT32_MAX. + * + * @param path An absolute file path. + * + * @return Resolves with an array of unsigned byte values read from disk, + * otherwise rejects with a DOMException. + */ + [NewObject] + Promise<Uint8Array> read(DOMString path, optional ReadOptions opts = {}); + /** + * Reads the UTF-8 text file located at |path| and returns the decoded + * contents as a |DOMString|. + * + * NB: The maximum file size that can be read is UINT32_MAX. + * + * @param path An absolute file path. + * + * @return Resolves with the file contents encoded as a string, otherwise + * rejects with a DOMException. + */ + [NewObject] + Promise<UTF8String> readUTF8(DOMString path, optional ReadUTF8Options opts = {}); + /** + * Read the UTF-8 text file located at |path| and return the contents + * parsed as JSON into a JS value. + * + * NB: The maximum file size that can be read is UINT32_MAX. + * + * @param path An absolute path. + * + * @return Resolves with the contents of the file parsed as JSON. + */ + [NewObject] + Promise<any> readJSON(DOMString path, optional ReadUTF8Options opts = {}); + /** + * Attempts to safely write |data| to a file at |path|. + * + * This operation can be made atomic by specifying the |tmpPath| option. If + * specified, then this method ensures that the destination file is not + * modified until the data is entirely written to the temporary file, after + * which point the |tmpPath| is moved to the specified |path|. + * + * The target file can also be backed up to a |backupFile| before any writes + * are performed to prevent data loss in case of corruption. + * + * @param path An absolute file path. + * @param data Data to write to the file at path. + * + * @return Resolves with the number of bytes successfully written to the file, + * otherwise rejects with a DOMException. + */ + [NewObject] + Promise<unsigned long long> write(DOMString path, Uint8Array data, optional WriteOptions options = {}); + /** + * Attempts to encode |string| to UTF-8, then safely write the result to a + * file at |path|. Works exactly like |write|. + * + * @param path An absolute file path. + * @param string A string to write to the file at path. + * @param options Options for writing the file. + * + * @return Resolves with the number of bytes successfully written to the file, + * otherwise rejects with a DOMException. + */ + [NewObject] + Promise<unsigned long long> writeUTF8(DOMString path, UTF8String string, optional WriteOptions options = {}); + /** + * Attempts to serialize |value| into a JSON string and encode it as into a + * UTF-8 string, then safely write the result to a file at |path|. Works + * exactly like |write|. + * + * @param path An absolute file path + * @param value The value to be serialized. + * @param options Options for writing the file. The "append" mode is not supported. + * + * @return Resolves with the number of bytes successfully written to the file, + * otherwise rejects with a DOMException. + */ + [NewObject] + Promise<unsigned long long> writeJSON(DOMString path, any value, optional WriteOptions options = {}); + /** + * Moves the file from |sourcePath| to |destPath|, creating necessary parents. + * If |destPath| is a directory, then the source file will be moved into the + * destination directory. + * + * @param sourcePath An absolute file path identifying the file or directory + * to move. + * @param destPath An absolute file path identifying the destination + * directory and/or file name. + * + * @return Resolves if the file is moved successfully, otherwise rejects with + * a DOMException. + */ + [NewObject] + Promise<undefined> move(DOMString sourcePath, DOMString destPath, optional MoveOptions options = {}); + /** + * Removes a file or directory at |path| according to |options|. + * + * @param path An absolute file path identifying the file or directory to + * remove. + * + * @return Resolves if the file is removed successfully, otherwise rejects + * with a DOMException. + */ + [NewObject] + Promise<undefined> remove(DOMString path, optional RemoveOptions options = {}); + /** + * Creates a new directory at |path| according to |options|. + * + * @param path An absolute file path identifying the directory to create. + * + * @return Resolves if the directory is created successfully, otherwise + * rejects with a DOMException. + */ + [NewObject] + Promise<undefined> makeDirectory(DOMString path, optional MakeDirectoryOptions options = {}); + /** + * Obtains information about a file, such as size, modification dates, etc. + * + * @param path An absolute file path identifying the file or directory to + * inspect. + * + * @return Resolves with a |FileInfo| object for the file at path, otherwise + * rejects with a DOMException. + * + * @see FileInfo + */ + [NewObject] + Promise<FileInfo> stat(DOMString path); + /** + * Copies a file or directory from |sourcePath| to |destPath| according to + * |options|. + * + * @param sourcePath An absolute file path identifying the source file to be + * copied. + * @param destPath An absolute file path identifying the location for the + * copy. + * + * @return Resolves if the file was copied successfully, otherwise rejects + * with a DOMException. + */ + [NewObject] + Promise<undefined> copy(DOMString sourcePath, DOMString destPath, optional CopyOptions options = {}); + /** + * Updates the access time for the file at |path|. + * + * @param path An absolute file path identifying the file whose + * modification time is to be set. This file must exist + * and will not be created. + * @param modification An optional access time for the file expressed in + * milliseconds since the Unix epoch + * (1970-01-01T00:00:00Z). The current system time is used + * if this parameter is not provided. + * + * @return Resolves with the updated access time time expressed in + * milliseconds since the Unix epoch, otherwise rejects with a + * DOMException. + */ + [NewObject] + Promise<long long> setAccessTime(DOMString path, optional long long access); + /** + * Updates the modification time for the file at |path|. + * + * @param path An absolute file path identifying the file whose + * modification time is to be set. This file must exist + * and will not be created. + * @param modification An optional modification time for the file expressed in + * milliseconds since the Unix epoch + * (1970-01-01T00:00:00Z). The current system time is used + * if this parameter is not provided. + * + * @return Resolves with the updated modification time expressed in + * milliseconds since the Unix epoch, otherwise rejects with a + * DOMException. + */ + [NewObject] + Promise<long long> setModificationTime(DOMString path, optional long long modification); + /** + * Retrieves a (possibly empty) list of immediate children of the directory at + * |path|. + * + * @param path An absolute file path. + * + * @return Resolves with a sequence of absolute file paths representing the + * children of the directory at |path|, otherwise rejects with a + * DOMException. + */ + [NewObject] + Promise<sequence<DOMString>> getChildren(DOMString path, optional GetChildrenOptions options = {}); + /** + * Set the permissions of the file at |path|. + * + * Windows does not make a distinction between user, group, and other + * permissions like UNICES do. If a permission flag is set for any of user, + * group, or other has a permission, then all users will have that + * permission. Additionally, Windows does not support setting the + * "executable" permission. + * + * @param path An absolute file path + * @param permissions The UNIX file mode representing the permissions. + * @param honorUmask If omitted or true, any UNIX file mode value is + * modified by the process umask. If false, the exact value + * of UNIX file mode will be applied. This value has no effect + * on Windows. + * + * @return Resolves if the permissions were set successfully, otherwise + * rejects with a DOMException. + */ + [NewObject] + Promise<undefined> setPermissions(DOMString path, unsigned long permissions, optional boolean honorUmask = true); + /** + * Return whether or not the file exists at the given path. + * + * @param path An absolute file path. + * + * @return A promise that resolves to whether or not the given file exists. + */ + [NewObject] + Promise<boolean> exists(DOMString path); + + /** + * Create a file with a unique name and return its path. + * + * @param parent An absolute path to the directory where the file is to be + * created. + * @param prefix A prefix for the filename. + * + * @return A promise that resolves to a unique filename. + */ + [NewObject] + Promise<DOMString> createUniqueFile(DOMString parent, DOMString prefix, optional unsigned long permissions = 0644); + + /** + * Create a directory with a unique name and return its path. + * + * @param parent An absolute path to the directory where the file is to be + * created. + * @param prefix A prefix for the directory name. + * + * @return A promise that resolves to a unique directory name. + */ + [NewObject] + Promise<DOMString> createUniqueDirectory(DOMString parent, DOMString prefix, optional unsigned long permissions = 0755); + + /** + * Compute the hash of a file as a hex digest. + * + * @param path The absolute path of the file to hash. + * @param method The hashing method to use. + * + * @return A promise that resolves to the hex digest of the file's hash in lowercase. + */ + [NewObject] + Promise<UTF8String> computeHexDigest(DOMString path, HashAlgorithm method); + +#if defined(XP_WIN) + /** + * Return the Windows-specific file attributes of the file at the given path. + * + * @param path An absolute file path. + * + * @return A promise that resolves to the Windows-specific file attributes. + */ + [NewObject] + Promise<WindowsFileAttributes> getWindowsAttributes(DOMString path); + + /** + * Set the Windows-specific file attributes of the file at the given path. + * + * @param path An absolute file path. + * @param attrs The attributes to set. Attributes will only be set if they are + * |true| or |false| (i.e., |undefined| attributes are not + * changed). + * + * @return A promise that resolves is the attributes were set successfully. + */ + [NewObject] + Promise<undefined> setWindowsAttributes(DOMString path, optional WindowsFileAttributes attrs = {}); +#elif defined(XP_MACOSX) + /** + * Return whether or not the file has a specific extended attribute. + * + * @param path An absolute path. + * @param attr The attribute to check for. + * + * @return A promise that resolves to whether or not the file has an extended + * attribute, or rejects with an error. + */ + [NewObject] + Promise<boolean> hasMacXAttr(DOMString path, UTF8String attr); + /** + * Return the value of an extended attribute for a file. + * + * @param path An absolute path. + * @param attr The attribute to get the value of. + * + * @return A promise that resolves to the value of the extended attribute, or + * rejects with an error. + */ + [NewObject] + Promise<Uint8Array> getMacXAttr(DOMString path, UTF8String attr); + /** + * Set the extended attribute on a file. + * + * @param path An absolute path. + * @param attr The attribute to set. + * @param value The value of the attribute to set. + * + * @return A promise that resolves to whether or not the file has an extended + * attribute, or rejects with an error. + */ + [NewObject] + Promise<undefined> setMacXAttr(DOMString path, UTF8String attr, Uint8Array value); + /** + * Delete the extended attribute on a file. + * + * @param path An absolute path. + * @param attr The attribute to delete. + * + * @return A promise that resolves if the attribute was deleted, or rejects + * with an error. + */ + [NewObject] + Promise<undefined> delMacXAttr(DOMString path, UTF8String attr); +#endif + + /** + * Return a nsIFile whose parent directory exists. The parent directory of the + * file will be created off main thread if it does not already exist. + * + * @param components The path components. The first component must be an + * absolute path. + * + * @return A promise that resolves to an nsIFile for the requested file. + */ + [NewObject] + Promise<nsIFile> getFile(DOMString... components); + + /** + * Return an nsIFile corresponding to a directory. It will be created + * off-main-thread if it does not already exist. + * + * @param components The path components. The first component must be an + * absolute path. + * + * @return A promise that resolves to an nsIFile for the requested directory. + */ + [NewObject] + Promise<nsIFile> getDirectory(DOMString... components); +}; + +[Exposed=Window] +partial namespace IOUtils { + /** + * The async shutdown client for the profile-before-change shutdown phase. + */ + [Throws] + readonly attribute any profileBeforeChange; + + /** + * The async shutdown client for the profile-before-change-telemetry shutdown + * phase. + * + * ONLY telemetry should register blockers on this client. + */ + [Throws] + readonly attribute any sendTelemetry; +}; + +[Exposed=Worker] +partial namespace IOUtils { + /** + * Synchronously opens the file at |path|. This API is only available in workers. + * + * @param path An absolute file path. + * + * @return A |SyncReadFile| object for the file. + */ + [Throws] + SyncReadFile openFileForSyncReading(DOMString path); + +#ifdef XP_UNIX + /** + * Launch a child process; uses `base::LaunchApp` from IPC. (This WebIDL + * binding is currently Unix-only; it could also be supported on Windows + * but it would use u16-based strings, so it would basically be a separate + * copy of the bindings.) + * + * This interface was added for use by `Subprocess.sys.jsm`; other would-be + * callers may want to just use Subprocess instead of calling this directly. + * + * @param argv The command to run and its arguments. + * @param options Various parameters about how the child process is launched + * and its initial environment. + * + * @return The process ID. Note that various errors (e.g., the + * executable to be launched doesn't exist) may not be + * encountered until after the process is created, so a + * successful return doesn't necessarily imply a successful + * launch. + */ + [Throws] + unsigned long launchProcess(sequence<UnixString> argv, LaunchOptions options); +#endif +}; + +/** + * An object representing an open file, allowing parts of the file contents to be + * read synchronously. Only available in workers. + */ +[ChromeOnly, Exposed=Worker] +interface SyncReadFile { + /** + * The file size, in bytes. + */ + readonly attribute long long size; + + /** + * Synchronously read |dest.length| bytes at offset |offset| into |dest|. + * Throws if the file has been closed already or if the read would be out-of-bounds. + * + * @param dest A Uint8Array whose entire contents will be overwritten with + * bytes read from the file. + * @param offset The file offset at which the read range begins. (The length of the + * range is given by |dest.length|.) + */ + [Throws] + undefined readBytesInto(Uint8Array dest, long long offset); + + /** + * Close the file. Subsequent calls to readBytesInto will throw. + * If the file is not closed manually, it will be closed once this object is GC'ed. + */ + undefined close(); +}; + +/** + * Options to be passed to the |IOUtils.readUTF8| method. + */ +dictionary ReadUTF8Options { + /** + * If true, this option indicates that the file to be read is compressed with + * LZ4-encoding, and should be decompressed before the data is returned to + * the caller. + */ + boolean decompress = false; +}; + +/** + * Options to be passed to the |IOUtils.read| method. + */ +dictionary ReadOptions : ReadUTF8Options { + /** + * The offset into the file to read from. If unspecified, the file will be read + * from the start. + */ + unsigned long long offset = 0; + + /** + * The max bytes to read from the file at path. If unspecified, the entire + * file will be read. This option is incompatible with |decompress|. + */ + unsigned long? maxBytes = null; +}; + +/** + * Modes for writing to a file. + */ +enum WriteMode { + /** + * Overwrite the contents of the file. + * + * The file will be created if it does not exist. + */ + "overwrite", + /** + * Append to the end of the file. + * + * This mode will refuse to create the file if it does not exist. + */ + "append", + /** + * Append to the end of the file, or create it if it does not exist. + */ + "appendOrCreate", + /** + * Create a new file. + * + * This mode will refuse to overwrite an existing file. + */ + "create", +}; + +/** + * Options to be passed to the |IOUtils.write| and |writeUTF8| + * methods. + */ +dictionary WriteOptions { + /** + * If specified, backup the destination file to this path before writing. + */ + DOMString backupFile; + /** + * If specified, write the data to a file at |tmpPath| instead of directly to + * the destination. Once the write is complete, the destination will be + * overwritten by a move. Specifying this option will make the write a little + * slower, but also safer. + */ + DOMString tmpPath; + /** + * The mode used to write to the file. + */ + WriteMode mode = "overwrite"; + /** + * If true, force the OS to write its internal buffers to the disk. + * This is considerably slower for the whole system, but safer in case of + * an improper system shutdown (e.g. due to a kernel panic) or device + * disconnection before the buffers are flushed. + */ + boolean flush = false; + /** + * If true, compress the data with LZ4-encoding before writing to the file. + */ + boolean compress = false; +}; + +/** + * Options to be passed to the |IOUtils.move| method. + */ +dictionary MoveOptions { + /** + * If true, fail if the destination already exists. + */ + boolean noOverwrite = false; +}; + +/** + * Options to be passed to the |IOUtils.remove| method. + */ +dictionary RemoveOptions { + /** + * If true, no error will be reported if the target file is missing. + */ + boolean ignoreAbsent = true; + /** + * If true, and the target is a directory, recursively remove files. + */ + boolean recursive = false; +}; + +/** + * Options to be passed to the |IOUtils.makeDirectory| method. + */ +dictionary MakeDirectoryOptions { + /** + * If true, create the directory and all necessary ancestors if they do not + * already exist. If false and any ancestor directories do not exist, + * |makeDirectory| will reject with an error. + */ + boolean createAncestors = true; + /** + * If true, succeed even if the directory already exists (default behavior). + * Otherwise, fail if the directory already exists. + */ + boolean ignoreExisting = true; + /** + * The file mode to create the directory with. + * + * This is ignored on Windows. + */ + unsigned long permissions = 0755; + +}; + +/** + * Options to be passed to the |IOUtils.copy| method. + */ +dictionary CopyOptions { + /** + * If true, fail if the destination already exists. + */ + boolean noOverwrite = false; + /** + * If true, copy the source recursively. + */ + boolean recursive = false; +}; + +/** + * Options to be passed to the |IOUtils.getChildren| method. + */ +dictionary GetChildrenOptions { + /** + * If true, no error will be reported if the target file is missing. + */ + boolean ignoreAbsent = false; +}; + +/** + * Types of files that are recognized by the |IOUtils.stat| method. + */ +enum FileType { "regular", "directory", "other" }; + +/** + * Basic metadata about a file. + */ +dictionary FileInfo { + /** + * The absolute path to the file on disk, as known when this file info was + * obtained. + */ + DOMString path; + + /** + * Identifies if the file at |path| is a regular file, directory, or something + * something else. + */ + FileType type; + + /** + * If this represents a regular file, the size of the file in bytes. + * Otherwise, -1. + */ + long long size; + + /** + * The timestamp of file creation, represented in milliseconds since Epoch + * (1970-01-01T00:00:00.000Z). + * + * This is only available on MacOS and Windows. + */ + long long creationTime; + + /** + * The timestmp of last file accesss, represented in milliseconds since Epoch + * (1970-01-01T00:00:00.000Z). + */ + long long lastAccessed; + + /** + * The timestamp of the last file modification, represented in milliseconds + * since Epoch (1970-01-01T00:00:00.000Z). + */ + long long lastModified; + + /** + * The permissions of the file, expressed as a UNIX file mode. + * + * NB: Windows does not make a distinction between user, group, and other + * permissions like UNICES do. The user, group, and other parts will always + * be identical on Windows. + */ + unsigned long permissions; +}; + +/** + * The supported hash algorithms for |IOUtils.hashFile|. + */ +enum HashAlgorithm { "sha1", "sha256", "sha384", "sha512" }; + +#ifdef XP_WIN +/** + * Windows-specific file attributes. + */ +dictionary WindowsFileAttributes { + /** + * Whether or not the file is read-only. + */ + boolean readOnly; + /** + * Whether or not the file is hidden. + */ + boolean hidden; + /** + * Whether or not the file is classified as a system file. + */ + boolean system; +}; +#endif + +#ifdef XP_UNIX +/** + * Used where the POSIX API allows an arbitrary byte string but in + * practice it's usually UTF-8, so JS strings are accepted for + * convenience. + */ +typedef (UTF8String or Uint8Array) UnixString; + +/** + * Options for the `launchApp` method. See also `base::LaunchOptions` + * in C++. + */ +dictionary LaunchOptions { + /** + * The environment variables, as a sequence of `NAME=value` strings. + * (The underlying C++ code can also inherit the current environment + * with optional changes; that feature could be added here if needed.) + */ + required sequence<UnixString> environment; + + /** + * The initial current working directory. + */ + UnixString workdir; + + /** + * File descriptors to pass to the child process. Any fds not + * mentioned here, other than stdin/out/err, will not be inherited + * even if they aren't marked close-on-exec. + */ + sequence<FdMapping> fdMap; + + /** + * On macOS 10.14+, disclaims responsibility for the child process + * with respect to privacy/security permission prompts and + * decisions. Ignored if not supported by the OS. + */ + boolean disclaim = false; +}; + +/** + * Describes a file descriptor to give to the child process. + */ +dictionary FdMapping { + /** + * The fd in the parent process to pass. This must remain open during + * the call to `launchApp` but can be closed after it returns (or throws). + */ + required unsigned long src; + + /** + * The fd number to map it to in the child process. + */ + required unsigned long dst; +}; +#endif |