dom/webidl/Directory.webidl

   1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
   4  * You can obtain one at http://mozilla.org/MPL/2.0/.
   5  */
   6
   7 /*
   8  * All functions on Directory that accept DOMString arguments for file or
   9  * directory names only allow relative path to current directory itself. The
  10  * path should be a descendent path like "path/to/file.txt" and not contain a
  11  * segment of ".." or ".". So the paths aren't allowed to walk up the directory
  12  * tree. For example, paths like "../foo", "..", "/foo/bar" or "foo/../bar" are
  13  * not allowed.
  14  */
  15 [NoInterfaceObject]
  16 interface Directory {
  17   /*
  18    * The leaf name of the directory.
  19    */
  20   readonly attribute DOMString name;
  21
  22   /*
  23    * Creates a new file or replaces an existing file with given data. The file
  24    * should be a descendent of current directory.
  25    *
  26    * @param path The relative path of the new file to current directory.
  27    * @param options It has two optional properties, 'ifExists' and 'data'.
  28    * If 'ifExists' is 'fail' and the path already exists, createFile must fail;
  29    * If 'ifExists' is 'replace', the path already exists, and is a file, create
  30    * a new file to replace the existing one;
  31    * If 'ifExists' is 'replace', the path already exists, but is a directory,
  32    * createFile must fail.
  33    * Otherwise, if no other error occurs, createFile will create a new file.
  34    * The 'data' property contains the new file's content.
  35    * @return If succeeds, the promise is resolved with the new created
  36    * File object. Otherwise, rejected with a DOM error.
  37    */
  38   [NewObject]
  39   Promise<File> createFile(DOMString path, optional CreateFileOptions options);
  40
  41   /*
  42    * Creates a descendent directory. This method will create any intermediate
  43    * directories specified by the path segments.
  44    *
  45    * @param path The relative path of the new directory to current directory.
  46    * If path exists, createDirectory must fail.
  47    * @return If succeeds, the promise is resolved with the new created
  48    * Directory object. Otherwise, rejected with a DOM error.
  49    */
  50   [NewObject]
  51   Promise<Directory> createDirectory(DOMString path);
  52
  53   /*
  54    * Gets a descendent file or directory with the given path.
  55    *
  56    * @param path The descendent entry's relative path to current directory.
  57    * @return If the path exists and no error occurs, the promise is resolved
  58    * with a File or Directory object, depending on the entry's type. Otherwise,
  59    * rejected with a DOM error.
  60    */
  61   [NewObject]
  62   Promise<(File or Directory)> get(DOMString path);
  63
  64   /*
  65    * Deletes a file or an empty directory. The target must be a descendent of
  66    * current directory.
  67    * @param path If a DOM string is passed, it is the relative path of the
  68    * target. Otherwise, the File or Directory object of the target should be
  69    * passed.
  70    * @return If the target is a non-empty directory, or if deleting the target
  71    * fails, the promise is rejected with a DOM error. If the target did not
  72    * exist, the promise is resolved with boolean false. If the target did exist
  73    * and was successfully deleted, the promise is resolved with boolean true.
  74    */
  75   [NewObject]
  76   Promise<boolean> remove((DOMString or File or Directory) path);
  77
  78   /*
  79    * Deletes a file or a directory recursively. The target should be a
  80    * descendent of current directory.
  81    * @param path If a DOM string is passed, it is the relative path of the
  82    * target. Otherwise, the File or Directory object of the target should be
  83    * passed.
  84    * @return If the target exists, but deleting the target fails, the promise is
  85    * rejected with a DOM error. If the target did not exist, the promise is
  86    * resolved with boolean false. If the target did exist and was successfully
  87    * deleted, the promise is resolved with boolean true.
  88    */
  89   [NewObject]
  90   Promise<boolean> removeDeep((DOMString or File or Directory) path);
  91 };
  92
  93 enum CreateIfExistsMode { "replace", "fail" };
  94
  95 dictionary CreateFileOptions {
  96   CreateIfExistsMode ifExists = "fail";
  97   (DOMString or Blob or ArrayBuffer or ArrayBufferView) data;
  98 };