michael@0: /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
michael@0:  * You can obtain one at http://mozilla.org/MPL/2.0/.
michael@0:  */
michael@0: 
michael@0: interface File;
michael@0: 
michael@0: /*
michael@0:  * All functions on Directory that accept DOMString arguments for file or
michael@0:  * directory names only allow relative path to current directory itself. The
michael@0:  * path should be a descendent path like "path/to/file.txt" and not contain a
michael@0:  * segment of ".." or ".". So the paths aren't allowed to walk up the directory
michael@0:  * tree. For example, paths like "../foo", "..", "/foo/bar" or "foo/../bar" are
michael@0:  * not allowed.
michael@0:  */
michael@0: [NoInterfaceObject]
michael@0: interface Directory {
michael@0:   /*
michael@0:    * The leaf name of the directory.
michael@0:    */
michael@0:   readonly attribute DOMString name;
michael@0: 
michael@0:   /*
michael@0:    * Creates a new file or replaces an existing file with given data. The file
michael@0:    * should be a descendent of current directory.
michael@0:    *
michael@0:    * @param path The relative path of the new file to current directory.
michael@0:    * @param options It has two optional properties, 'ifExists' and 'data'.
michael@0:    * If 'ifExists' is 'fail' and the path already exists, createFile must fail;
michael@0:    * If 'ifExists' is 'replace', the path already exists, and is a file, create
michael@0:    * a new file to replace the existing one;
michael@0:    * If 'ifExists' is 'replace', the path already exists, but is a directory,
michael@0:    * createFile must fail.
michael@0:    * Otherwise, if no other error occurs, createFile will create a new file.
michael@0:    * The 'data' property contains the new file's content.
michael@0:    * @return If succeeds, the promise is resolved with the new created
michael@0:    * File object. Otherwise, rejected with a DOM error.
michael@0:    */
michael@0:   [NewObject]
michael@0:   // Promise<File>
michael@0:   Promise createFile(DOMString path, optional CreateFileOptions options);
michael@0: 
michael@0:   /*
michael@0:    * Creates a descendent directory. This method will create any intermediate
michael@0:    * directories specified by the path segments.
michael@0:    *
michael@0:    * @param path The relative path of the new directory to current directory.
michael@0:    * If path exists, createDirectory must fail.
michael@0:    * @return If succeeds, the promise is resolved with the new created
michael@0:    * Directory object. Otherwise, rejected with a DOM error.
michael@0:    */
michael@0:   [NewObject]
michael@0:   // Promise<Directory>
michael@0:   Promise createDirectory(DOMString path);
michael@0: 
michael@0:   /*
michael@0:    * Gets a descendent file or directory with the given path.
michael@0:    *
michael@0:    * @param path The descendent entry's relative path to current directory.
michael@0:    * @return If the path exists and no error occurs, the promise is resolved
michael@0:    * with a File or Directory object, depending on the entry's type. Otherwise,
michael@0:    * rejected with a DOM error.
michael@0:    */
michael@0:   [NewObject]
michael@0:   // Promise<(File or Directory)>
michael@0:   Promise get(DOMString path);
michael@0: 
michael@0:   /*
michael@0:    * Deletes a file or an empty directory. The target must be a descendent of
michael@0:    * current directory.
michael@0:    * @param path If a DOM string is passed, it is the relative path of the
michael@0:    * target. Otherwise, the File or Directory object of the target should be
michael@0:    * passed.
michael@0:    * @return If the target is a non-empty directory, or if deleting the target
michael@0:    * fails, the promise is rejected with a DOM error. If the target did not
michael@0:    * exist, the promise is resolved with boolean false. If the target did exist
michael@0:    * and was successfully deleted, the promise is resolved with boolean true.
michael@0:    */
michael@0:   [NewObject]
michael@0:   // Promise<boolean>
michael@0:   Promise remove((DOMString or File or Directory) path);
michael@0: 
michael@0:   /*
michael@0:    * Deletes a file or a directory recursively. The target should be a
michael@0:    * descendent of current directory.
michael@0:    * @param path If a DOM string is passed, it is the relative path of the
michael@0:    * target. Otherwise, the File or Directory object of the target should be
michael@0:    * passed.
michael@0:    * @return If the target exists, but deleting the target fails, the promise is
michael@0:    * rejected with a DOM error. If the target did not exist, the promise is
michael@0:    * resolved with boolean false. If the target did exist and was successfully
michael@0:    * deleted, the promise is resolved with boolean true.
michael@0:    */
michael@0:   [NewObject]
michael@0:   // Promise<boolean>
michael@0:   Promise removeDeep((DOMString or File or Directory) path);
michael@0: };
michael@0: 
michael@0: enum CreateIfExistsMode { "replace", "fail" };
michael@0: 
michael@0: dictionary CreateFileOptions {
michael@0:   CreateIfExistsMode ifExists = "fail";
michael@0:   (DOMString or Blob or ArrayBuffer or ArrayBufferView) data;
michael@0: };