Home | History | Annotate | Download | only in api 
      1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
      2 // Use of this source code is governed by a BSD-style license that can be
      3 // found in the LICENSE file.
      4 
      5 // Use the <code>chrome.fileSystem</code> API to create, read, navigate,
      6 // and write to a sandboxed section of the user's local file system. With this
      7 // API, packaged apps can read and write to a user-selected location. For
      8 // example, a text editor app can use the API to read and write local documents.
      9 namespace fileSystem {
     10   dictionary AcceptOption {
     11     // This is the optional text description for this option. If not present,
     12     // a description will be automatically generated; typically containing an
     13     // expanded list of valid extensions (e.g. "text/html" may expand to
     14     // "*.html, *.htm").
     15     DOMString? description;
     16 
     17     // Mime-types to accept, e.g. "image/jpeg" or "audio/*". One of mimeTypes or
     18     // extensions must contain at least one valid element.
     19     DOMString[]? mimeTypes;
     20 
     21     // Extensions to accept, e.g. "jpg", "gif", "crx".
     22     DOMString[]? extensions;
     23   };
     24 
     25   enum ChooseEntryType {
     26 
     27     // Prompts the user to open an existing file and returns a read-only
     28     // FileEntry on success.
     29     openFile,
     30 
     31     // Prompts the user to open an existing file and returns a writable
     32     // FileEntry on success. Calls using this type will fail unless the
     33     // application has the 'write' permission under 'fileSystem'.
     34     openWritableFile,
     35 
     36     // Prompts the user to open an existing file or a new file and returns a
     37     // writable FileEntry on success. Calls using this type will fail unless the
     38     // application has the 'write' permission under 'fileSystem'.
     39     saveFile
     40   };
     41 
     42   dictionary ChooseEntryOptions {
     43     // Type of the prompt to show. The default is 'openFile'.
     44     ChooseEntryType? type;
     45 
     46     // The suggested file name that will be presented to the user as the
     47     // default name to read or write. This is optional.
     48     DOMString? suggestedName;
     49 
     50     // The optional list of accept options for this file opener. Each option
     51     // will be presented as a unique group to the end-user.
     52     AcceptOption[]? accepts;
     53 
     54     // Whether to accept all file types, in addition to the options specified
     55     // in the accepts argument. The default is true. If the accepts field is
     56     // unset or contains no valid entries, this will always be reset to true.
     57     boolean? acceptsAllTypes;
     58 
     59     // Whether to accept multiple files. This is only supported for openFile and
     60     // openWritableFile. The callback to chooseEntry will be called with a list
     61     // of entries if this is set to true. Otherwise it will be called with a
     62     // single Entry.
     63     boolean? acceptsMultiple;
     64   };
     65   callback GetDisplayPathCallback = void (DOMString displayPath);
     66   callback FileEntryCallback = void ([instanceOf=FileEntry] object fileEntry);
     67   callback FileEntriesCallback = void (
     68       [instanceOf=FileEntry] optional object fileEntry,
     69       [instanceOf=FileEntry] optional object[] fileEntries);
     70   callback IsWritableCallback = void (boolean isWritable);
     71   callback IsRestorableCallback = void (boolean isRestorable);
     72 
     73   interface Functions {
     74     // Get the display path of a FileEntry object. The display path is based on
     75     // the full path of the file on the local file system, but may be made more
     76     // readable for display purposes.
     77     static void getDisplayPath([instanceOf=FileEntry] object fileEntry,
     78                                GetDisplayPathCallback callback);
     79 
     80     // Get a writable FileEntry from another FileEntry. This call will fail if
     81     // the application does not have the 'write' permission under 'fileSystem'.
     82     static void getWritableEntry([instanceOf=FileEntry] object fileEntry,
     83                                  FileEntryCallback callback);
     84 
     85     // Gets whether this FileEntry is writable or not.
     86     static void isWritableEntry([instanceOf=FileEntry] object fileEntry,
     87                                 IsWritableCallback callback);
     88 
     89     // Ask the user to choose a file.
     90     static void chooseEntry(optional ChooseEntryOptions options,
     91                             FileEntriesCallback callback);
     92 
     93     // Returns the file entry with the given id if it can be restored. This call
     94     // will fail otherwise.
     95     static void restoreEntry(DOMString id, FileEntryCallback callback);
     96 
     97     // Returns whether a file entry for the given id can be restored, i.e.
     98     // whether restoreEntry would succeed with this id now.
     99     static void isRestorable(DOMString id, IsRestorableCallback callback);
    100 
    101     // Returns an id that can be passed to restoreEntry to regain access to a
    102     // given file entry. Only the 500 most recently used entries are retained,
    103     // where calls to retainEntry and restoreEntry count as use. If the app has
    104     // the 'retainEntries' permission under 'fileSystem', entries are retained
    105     // indefinitely. Otherwise, entries are retained only while the app is
    106     // running and across restarts.
    107     static DOMString retainEntry([instanceOf=FileEntry] object fileEntry);
    108   };
    109 };
    110