chrome/common/extensions/api/file_system.idl

   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 the user's local file system. With this API, Chrome Apps can
   7 // read and write to a user-selected location. For example, a text editor app
   8 // can use the API to read and write local documents. All failures are notified
   9 // via chrome.runtime.lastError.
  10 namespace fileSystem {
  11   dictionary AcceptOption {
  12     // This is the optional text description for this option. If not present,
  13     // a description will be automatically generated; typically containing an
  14     // expanded list of valid extensions (e.g. "text/html" may expand to
  15     // "*.html, *.htm").
  16     DOMString? description;
  17
  18     // Mime-types to accept, e.g. "image/jpeg" or "audio/*". One of mimeTypes or
  19     // extensions must contain at least one valid element.
  20     DOMString[]? mimeTypes;
  21
  22     // Extensions to accept, e.g. "jpg", "gif", "crx".
  23     DOMString[]? extensions;
  24   };
  25
  26   enum ChooseEntryType {
  27
  28     // Prompts the user to open an existing file and returns a FileEntry on
  29     // success. From Chrome 31 onwards, the FileEntry will be writable if the
  30     // application has the 'write' permission under 'fileSystem'; otherwise, the
  31     // FileEntry will be read-only.
  32     openFile,
  33
  34     // Prompts the user to open an existing file and returns a writable
  35     // FileEntry on success. Calls using this type will fail with a runtime
  36     // error if the application doesn't have the 'write' permission under
  37     // 'fileSystem'.
  38     openWritableFile,
  39
  40     // Prompts the user to open an existing file or a new file and returns a
  41     // writable FileEntry on success. Calls using this type will fail with a
  42     // runtime error if the application doesn't have the 'write' permission
  43     // under 'fileSystem'.
  44     saveFile,
  45
  46     // Prompts the user to open a directory and returns a DirectoryEntry on
  47     // success. Calls using this type will fail with a runtime error if the
  48     // application doesn't have the 'directory' permission under 'fileSystem'.
  49     // If the application has the 'write' permission under 'fileSystem', the
  50     // returned DirectoryEntry will be writable; otherwise it will be read-only.
  51     // New in Chrome 31.
  52     openDirectory
  53   };
  54
  55   // Type of a change happened to a child entry within a tracked directory.
  56   enum ChildChangeType {
  57     created,
  58     removed,
  59     changed
  60   };
  61
  62   dictionary ChooseEntryOptions {
  63     // Type of the prompt to show. The default is 'openFile'.
  64     ChooseEntryType? type;
  65
  66     // The suggested file name that will be presented to the user as the
  67     // default name to read or write. This is optional.
  68     DOMString? suggestedName;
  69
  70     // The optional list of accept options for this file opener. Each option
  71     // will be presented as a unique group to the end-user.
  72     AcceptOption[]? accepts;
  73
  74     // Whether to accept all file types, in addition to the options specified
  75     // in the accepts argument. The default is true. If the accepts field is
  76     // unset or contains no valid entries, this will always be reset to true.
  77     boolean? acceptsAllTypes;
  78
  79     // Whether to accept multiple files. This is only supported for openFile and
  80     // openWritableFile. The callback to chooseEntry will be called with a list
  81     // of entries if this is set to true. Otherwise it will be called with a
  82     // single Entry.
  83     boolean? acceptsMultiple;
  84   };
  85
  86   dictionary RequestFileSystemOptions {
  87     // The ID of the requested volume.
  88     DOMString volumeId;
  89
  90     // Whether the requested file system should be writeable, or read-only.
  91     // By default read-only.
  92     boolean? writable;
  93   };
  94
  95   // Represents a mounted volume, which can be accessed via <code>chrome.
  96   // fileSystem.requestFileSystem</code>.
  97   dictionary Volume {
  98     DOMString volumeId;
  99     boolean writable;
 100   };
 101
 102   // Change to an entry within a tracked directory.
 103   [nodoc] dictionary ChildChange {
 104     [instanceOf=Entry] object entry;
 105     ChildChangeType type;
 106   };
 107
 108   // Event notifying about an inserted or a removed volume from the system.
 109   dictionary VolumeListChangedEvent {
 110     Volume[] volumes;
 111   };
 112
 113   // Event notifying about a change in a file or a directory, including its
 114   // contents.
 115   [nodoc] dictionary EntryChangedEvent {
 116     // Tracked entry.
 117     [instanceOf=Entry] object target;
 118
 119     // List of changed entries within the tracked directory in order they
 120     // happened. May not be available for some types of file systems.
 121     ChildChange[]? childChanges;
 122   };
 123
 124   // Event notifying about a tracked file or a directory being removed.
 125   [nodoc] dictionary EntryRemovedEvent {
 126     [instanceOf=Entry] object target;
 127   };
 128
 129   callback GetDisplayPathCallback = void (DOMString displayPath);
 130   callback EntryCallback = void ([instanceOf=Entry] object entry);
 131   callback EntriesCallback = void (
 132       [instanceOf=Entry] optional object entry,
 133       [instanceOf=FileEntry] optional object[] fileEntries);
 134   callback IsWritableCallback = void (boolean isWritable);
 135   callback IsRestorableCallback = void (boolean isRestorable);
 136   [nodoc] callback GetObservedEntriesCallback = void (
 137       [instanceOf=Entry] object[] entries);
 138   callback RequestFileSystemCallback = void(
 139       [instanceOf=FileSystem] optional object fileSystem);
 140   callback GetVolumeListCallback = void(optional Volume[] volumes);
 141
 142   interface Functions {
 143     // Get the display path of an Entry object. The display path is based on
 144     // the full path of the file or directory on the local file system, but may
 145     // be made more readable for display purposes.
 146     static void getDisplayPath([instanceOf=Entry] object entry,
 147                                GetDisplayPathCallback callback);
 148
 149     // Get a writable Entry from another Entry. This call will fail with a
 150     // runtime error if the application does not have the 'write' permission
 151     // under 'fileSystem'. If entry is a DirectoryEntry, this call will fail if
 152     // the application does not have the 'directory' permission under
 153     // 'fileSystem'.
 154     static void getWritableEntry([instanceOf=Entry] object entry,
 155                                  EntryCallback callback);
 156
 157     // Gets whether this Entry is writable or not.
 158     static void isWritableEntry([instanceOf=Entry] object entry,
 159                                 IsWritableCallback callback);
 160
 161     // Ask the user to choose a file or directory.
 162     static void chooseEntry(optional ChooseEntryOptions options,
 163                             EntriesCallback callback);
 164
 165     // Returns the file entry with the given id if it can be restored. This call
 166     // will fail with a runtime error otherwise.
 167     static void restoreEntry(DOMString id, EntryCallback callback);
 168
 169     // Returns whether the app has permission to restore the entry with the
 170     // given id.
 171     static void isRestorable(DOMString id, IsRestorableCallback callback);
 172
 173     // Returns an id that can be passed to restoreEntry to regain access to a
 174     // given file entry. Only the 500 most recently used entries are retained,
 175     // where calls to retainEntry and restoreEntry count as use. If the app has
 176     // the 'retainEntries' permission under 'fileSystem', entries are retained
 177     // indefinitely. Otherwise, entries are retained only while the app is
 178     // running and across restarts.
 179     static DOMString retainEntry([instanceOf=Entry] object entry);
 180
 181     // Requests access to a file system for a volume represented by <code>
 182     // options.volumeId</code>. If <code>options.writable</code> is set to true,
 183     // then the file system will be writable. Otherwise, it will be read-only.
 184     // The <code>writable</code> option requires the <code>
 185     // "fileSystem": {"write"}</code> permission in the manifest. Available to
 186     // kiosk apps running in kiosk session only. For manual-launch kiosk mode, a
 187     // confirmation dialog will be shown on top of the active app window.
 188     // In case of an error, <code>fileSystem</code> will be undefined, and
 189     // <code>chrome.runtime.lastError</code> will be set.
 190     static void requestFileSystem(RequestFileSystemOptions options,
 191                                   RequestFileSystemCallback callback);
 192
 193     // Returns a list of volumes available for <code>requestFileSystem()</code>.
 194     // The <code>"fileSystem": {"requestFileSystem"}</code> manifest permission
 195     // is required. Available to kiosk apps running in the kiosk session only.
 196     // In case of an error, <code>volumes</code> will be undefined, and <code>
 197     // chrome.runtime.lastError</code> will be set.
 198     static void getVolumeList(GetVolumeListCallback callback);
 199
 200     // Observes a directory entry. Emits an event if the tracked directory is
 201     // changed (including the list of files on it), or removed. If <code>
 202     // recursive</code> is set to true, then also all accessible subdirectories
 203     // will be tracked. Observers are automatically removed once the extension
 204     // is closed or suspended, unless <code>entry</code> is retained using
 205     // <code>chrome.fileSystem.retainEntry</code>.
 206     //
 207     // In such case of retained entries, the observer stays active across
 208     // restarts until <code>unobserveEntry</code> is explicitly called. Note,
 209     // that once the <code>entry</code> is not retained anymore, the observer
 210     // will be removed automatically. Observed entries are also automatically
 211     // restored when either <code>getObservers</code> is called, or an observing
 212     // event for it is invoked.
 213     [nodoc] static void observeDirectory(
 214         [instanceOf=DirectoryEntry] object entry,
 215         optional boolean recursive);
 216
 217     // Unobserves a previously observed either a file or a directory.
 218     [nodoc] static void unobserveEntry([instanceOf=Entry] object entry);
 219
 220     // Lists all observed entries.
 221     [nodoc] static void getObservedEntries(GetObservedEntriesCallback callback);
 222   };
 223
 224   interface Events {
 225     // Called when a list of available volumes is changed.
 226     static void onVolumeListChanged(VolumeListChangedEvent event);
 227
 228     // Called when an observed entry is changed.
 229     [nodoc] static void onEntryChanged(EntryChangedEvent event);
 230
 231     // Called when an observed entry is removed.
 232     [nodoc] static void onEntryRemoved(EntryRemovedEvent event);
 233   };
 234 };