// Copyright (c) 2012 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

namespace fileSystem {
  dictionary AcceptOption {
    // This is the optional text description for this option. If not present,
    // a description will be automatically generated; typically containing an
    // expanded list of valid extensions (e.g. "text/html" may expand to
    // "*.html, *.htm").
    DOMString? description;

    // Mime-types to accept, e.g. "image/jpeg" or "audio/*". One of mimeTypes or
    // extensions must contain at least one valid element.
    DOMString[]? mimeTypes;

    // Extensions to accept, e.g. "jpg", "gif", "crx".
    DOMString[]? extensions;
  };

  enum ChooseEntryType {

    // Prompts the user to open an existing file and returns a read-only
    // FileEntry on success.
    openFile,

    // Prompts the user to open an existing file and returns a writable
    // FileEntry on success. Calls using this type will fail unless the
    // application has the 'write' permission under 'fileSystem'.
    openWritableFile,

    // Prompts the user to open an existing file or a new file and returns a
    // writable FileEntry on success. Calls using this type will fail unless the
    // application has the 'write' permission under 'fileSystem'.
    saveFile
  };

  dictionary ChooseEntryOptions {
    // Type of the prompt to show. The default is 'openFile'.
    ChooseEntryType? type;

    // The suggested file name that will be presented to the user as the
    // default name to read or write. This is optional.
    DOMString? suggestedName;

    // The optional list of accept options for this file opener. Each option
    // will be presented as a unique group to the end-user.
    AcceptOption[]? accepts;

    // Whether to accept all file types, in addition to the options specified
    // in the accepts argument. The default is true. If the accepts field is
    // unset or contains no valid entries, this will always be reset to true.
    boolean? acceptsAllTypes;
  };
  callback GetDisplayPathCallback = void (DOMString displayPath);
  callback FileEntryCallback = void ([instanceOf=FileEntry] object fileEntry);
  callback IsWritableCallback = void (boolean isWritable);
  callback IsRestorableCallback = void (boolean isRestorable);

  interface Functions {
    // Get the display path of a FileEntry object. The display path is based on
    // the full path of the file on the local file system, but may be made more
    // readable for display purposes.
    static void getDisplayPath([instanceOf=FileEntry] object fileEntry,
                               GetDisplayPathCallback callback);

    // Get a writable FileEntry from another FileEntry. This call will fail if
    // the application does not have the 'write' permission under 'fileSystem'.
    static void getWritableEntry([instanceOf=FileEntry] object fileEntry,
                                 FileEntryCallback callback);

    // Gets whether this FileEntry is writable or not.
    static void isWritableEntry([instanceOf=FileEntry] object fileEntry,
                                IsWritableCallback callback);

    // Ask the user to choose a file.
    static void chooseEntry(optional ChooseEntryOptions options,
                            FileEntryCallback callback);

    // Returns the file entry with the given id if it can be restored. This call
    // will fail otherwise.
    static void restoreEntry(DOMString id, FileEntryCallback callback);

    // Returns whether a file entry for the given id can be restored, i.e.
    // whether restoreEntry would succeed with this id now.
    static void isRestorable(DOMString id, IsRestorableCallback callback);

    // Returns an id that can be passed to restoreEntry to regain access to a
    // given file entry. Only the 500 most recently used entries are retained,
    // where calls to retainEntry and restoreEntry count as use.
    static DOMString retainEntry([instanceOf=FileEntry] object fileEntry);
  };
};