chrome/common/extensions/api/file_system_provider.idl

   1 // Copyright 2013 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.fileSystemProvider</code> API to create file systems,
   6 // that can be accessible from the file manager on Chrome OS.
   7 [platforms=("chromeos"),
   8  implemented_in="chrome/browser/chromeos/extensions/file_system_provider/file_system_provider_api.h"]
   9 namespace fileSystemProvider {
  10   // Error codes used by providing extensions in response to requests. For
  11   // success, <code>OK</code> should be used.
  12   enum ProviderError {
  13     OK,
  14     FAILED,
  15     IN_USE,
  16     EXISTS,
  17     NOT_FOUND,
  18     ACCESS_DENIED,
  19     TOO_MANY_OPENED,
  20     NO_MEMORY,
  21     NO_SPACE,
  22     NOT_A_DIRECTORY,
  23     INVALID_OPERATION,
  24     SECURITY,
  25     ABORT,
  26     NOT_A_FILE,
  27     NOT_EMPTY,
  28     INVALID_URL,
  29     IO
  30   };
  31
  32   // Mode of opening a file. Used by <code>onOpenFileRequested</code>.
  33   enum OpenFileMode {
  34     READ,
  35     WRITE
  36   };
  37
  38   // Represents metadata of a file or a directory.
  39   dictionary EntryMetadata {
  40     // True if it is a directory.
  41     boolean isDirectory;
  42
  43     // Name of this entry (not full path name).
  44     DOMString name;
  45
  46     // File size in bytes.
  47     double size;
  48
  49     // The last modified time of this entry.
  50     [instanceOf=Date] object modificationTime;
  51   };
  52
  53   // Callback to receive the result of mount() function.
  54   callback MountCallback = void([nodoc, instanceOf=DOMError] object error);
  55
  56
  57   // Callback to receive the result of unmount() function.
  58   callback UnmountCallback = void([nodoc, instanceOf=DOMError] object error);
  59
  60   // Callback to be called by the providing extension in case of a success.
  61   callback ProviderSuccessCallback = void();
  62
  63   // Callback to be called by the providing extension in case of an error.
  64   callback ProviderErrorCallback = void(ProviderError error);
  65
  66   // Callback to handle an error raised from the browser.
  67   [nocompile] callback ErrorCallback = void([instanceOf=DOMError] object error);
  68
  69   // Success callback for the <code>onGetMetadataRequested</code> event.
  70   callback MetadataCallback = void(EntryMetadata metadata);
  71
  72   // Success callback for the <code>onReadDirectoryRequested</code> event. If
  73   // more entries will be returned, then <code>hasMore</code> must be true, and
  74   // it has to be called again with additional entries. If no more entries are
  75   // available, then <code>hasMore</code> must be set to false.
  76   callback EntriesCallback = void(ResourceEntry[] entries, bool hasMore);
  77
  78   // Success callback for the <code>onReadFileRequested</code> event. If more
  79   // data will be returned, then <code>hasMore</code> must be true, and it
  80   // has to be called again with additional entries. If no more data is
  81   // available, then <code>hasMore</code> must be set to false.
  82   callback FileDataCallback = void(ArrayBuffer data, bool hasMore);
  83
  84   interface Functions {
  85     // Mounts a file system with the given <code>fileSystemId</code> and <code>
  86     // displayName</code>. <code>displayName</code> will be shown in the left
  87     // panel of Files.app. <code>displayName</code> can contain any characters
  88     // including '/', but cannot be an empty string. <code>displayName</code>
  89     // should be descriptive but doesn't have to be unique. Duplicate display
  90     // names are uniquified by adding suffix like "(1)" in the Files app UI.
  91     //
  92     // If a file system with the passed <code>fileSystemId</code> is already
  93     // mounted by this extension, then <code>errorCallback</code> will be called
  94     // with <code>ProviderError.EXISTS</code> value. The <code>fileSystemId
  95     // </code> must not be an empty string.
  96     static void mount(DOMString fileSystemId,
  97                       DOMString displayName,
  98                       MountCallback successCallback,
  99                       [nocompile] ErrorCallback errorCallback);
 100
 101     // Unmounts a file system with the given <code>fileSystemId</code>. It
 102     // should be called after <code>onUnmountRequested</code> is invoked. Also,
 103     // the providing extension can decide to perform unmounting if not requested
 104     // (eg. in case of lost connection, or a file error). If there is no file
 105     // system with the requested id, or unmounting fails, then the
 106     // <code>errorCallback</code> will be called.
 107     static void unmount(DOMString fileSystemId,
 108                         UnmountCallback successCallback,
 109                         [nocompile] ErrorCallback errorCallback);
 110   };
 111
 112   interface Events {
 113     // Raised when unmounting for the file system with the <code>fileSystemId
 114     // </code> identifier is requested. In the response, the <code>unmount
 115     // </code> API method should be called together with <code>successCallback
 116     // </code>. If unmounting is not possible (eg. due to a pending operation),
 117     // then <code>errorCallback</code> must be called.
 118     [maxListeners=1] static void onUnmountRequested(
 119         DOMString fileSystemId,
 120         ProviderSuccessCallback successCallback,
 121         ProviderErrorCallback errorCallback);
 122
 123     // Raised when metadata of a file or a directory at <code>entryPath</code>
 124     // is requested. The metadata should be returned with the <code>
 125     // successCallback</code> call. In case of an error, <code>errorCallback
 126     // </code> must be called.
 127     [maxListeners=1] static void onGetMetadataRequested(
 128         DOMString fileSystemId,
 129         DOMString entryPath,
 130         MetadataCallback successCallback,
 131         ProviderErrorCallback errorCallback);
 132
 133     // Raised when contents of a directory at <code>directoryPath</code> are
 134     // requested. The results should be returned in chunks by calling the <code>
 135     // successCallback</code> several times. In case of an error, <code>
 136     // errorCallback</code> must be called.
 137     [maxListeners=1] static void onReadDirectoryRequested(
 138         DOMString fileSystemId,
 139         DOMString directoryPath,
 140         EntriesCallback successCallback,
 141         ProviderErrorCallback errorCallback);
 142
 143     // Raised when opening a file at <code>filePath</code> is requested.
 144     // If <code>create</code> is set to <code>true</code> and the file does not
 145     // exist, then it should be created.
 146     [maxListeners=1] static void onOpenFileRequested(
 147         DOMString fileSystemId,
 148         long requestId,
 149         DOMString filePath,
 150         OpenFileMode mode,
 151         boolean create,
 152         ProviderSuccessCallback successCallback,
 153         ProviderErrorCallback errorCallback);
 154
 155     // Raised when opening a file previously opened with <code>openRequestId
 156     // </code> is requested to be closed.
 157     [maxListeners=1] static void onCloseFileRequested(
 158         DOMString fileSystemId,
 159         long openRequestId,
 160         ProviderSuccessCallback successCallback,
 161         ProviderErrorCallback errorCallback);
 162
 163     // Raised when contents of a file opened previously with <code>openRequestId
 164     // </code>. The results should be returned in chunks by calling <code>
 165     // successCallback</code> several times. In case of an error, <code>
 166     // errorCallback</code> must be called.
 167     [maxListeners=1] static void onReadFileRequested(
 168         DOMString fileSystemId,
 169         long openRequestId,
 170         double offset,
 171         double length,
 172         FileDataCallback successCallback,
 173         ProviderErrorCallback errorCallback);
 174   };
 175 };
 176