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