src/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> must 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     NOT_A_FILE,
  26     NOT_EMPTY,
  27     INVALID_URL,
  28     IO
  29   };
  30
  31   // Mode of opening a file. Used by <code>onOpenFileRequested</code>.
  32   enum OpenFileMode {
  33     READ,
  34     WRITE
  35   };
  36
  37   // Represents metadata of a file or a directory.
  38   dictionary EntryMetadata {
  39     // True if it is a directory.
  40     boolean isDirectory;
  41
  42     // Name of this entry (not full path name).
  43     DOMString name;
  44
  45     // File size in bytes.
  46     double size;
  47
  48     // The last modified time of this entry.
  49     [instanceOf=Date] object modificationTime;
  50
  51     // Mime type for the entry.
  52     DOMString? mimeType;
  53
  54     // Thumbnail image as a data URI in either PNG, JPEG or WEBP format, at most
  55     // 32 KB in size. Optional, but can be provided only when explicitly
  56     // requested by the <code>onGetMetadataRequested</code> event.
  57     DOMString? thumbnail;
  58   };
  59
  60   // Represents a mounted file system.
  61   dictionary FileSystemInfo {
  62     // The identifier of the file system.
  63     DOMString fileSystemId;
  64
  65     // A human-readable name for the file system.
  66     DOMString displayName;
  67
  68     // Whether the file system supports operations which may change contents
  69     // of the file system (such as creating, deleting or writing to files).
  70     boolean writable;
  71   };
  72
  73   // Options for the <code>mount()</code> method.
  74   dictionary MountOptions {
  75     // The string indentifier of the file system. Must be unique per each
  76     // extension.
  77     DOMString fileSystemId;
  78
  79     // A human-readable name for the file system.
  80     DOMString displayName;
  81
  82     // Whether the file system supports operations which may change contents
  83     // of the file system (such as creating, deleting or writing to files).
  84     boolean? writable;
  85   };
  86
  87   // Options for the <code>unmount()</code> method.
  88   dictionary UnmountOptions {
  89     // The identifier of the file system to be unmounted.
  90     DOMString fileSystemId;
  91   };
  92
  93   // Options for the <code>onUnmountRequested()</code> event.
  94   dictionary UnmountRequestedOptions {
  95     // The identifier of the file system to be unmounted.
  96     DOMString fileSystemId;
  97     long requestId;
  98   };
  99
 100   // Options for the <code>onGetMetadataRequested()</code> event.
 101   dictionary GetMetadataRequestedOptions {
 102     // The identifier of the file system related to this operation.
 103     DOMString fileSystemId;
 104
 105     // The unique identifier of this request.
 106     long requestId;
 107
 108     // The path of the entry to fetch metadata about.
 109     DOMString entryPath;
 110
 111     // Set to <code>true</code> if the thumbnail is requested.
 112     boolean thumbnail;
 113   };
 114
 115   // Options for the <code>onReadDirectoryRequested()</code> event.
 116   dictionary ReadDirectoryRequestedOptions {
 117     // The identifier of the file system related to this operation.
 118     DOMString fileSystemId;
 119
 120     // The unique identifier of this request.
 121     long requestId;
 122
 123     // The path of the directory which contents are requested.
 124     DOMString directoryPath;
 125   };
 126
 127   // Options for the <code>onOpenFileRequested()</code> event.
 128   dictionary OpenFileRequestedOptions {
 129     // The identifier of the file system related to this operation.
 130     DOMString fileSystemId;
 131
 132     // A request ID which will be used by consecutive read/write and close
 133     // requests.
 134     long requestId;
 135
 136     // The path of the file to be opened.
 137     DOMString filePath;
 138
 139     // Whether the file will be used for reading or writing.
 140     OpenFileMode mode;
 141   };
 142
 143   // Options for the <code>onCloseFileRequested()</code> event.
 144   dictionary CloseFileRequestedOptions {
 145     // The identifier of the file system related to this operation.
 146     DOMString fileSystemId;
 147
 148     // The unique identifier of this request.
 149     long requestId;
 150
 151     // A request ID used to open the file.
 152     long openRequestId;
 153   };
 154
 155   // Options for the <code>onReadFileRequested()</code> event.
 156   dictionary ReadFileRequestedOptions {
 157     // The identifier of the file system related to this operation.
 158     DOMString fileSystemId;
 159
 160     // The unique identifier of this request.
 161     long requestId;
 162
 163     // A request ID used to open the file.
 164     long openRequestId;
 165
 166     // Position in the file (in bytes) to start reading from.
 167     double offset;
 168
 169     // Number of bytes to be returned.
 170     double length;
 171   };
 172
 173   // Options for the <code>onCreateDirectoryRequested()</code> event.
 174   dictionary CreateDirectoryRequestedOptions {
 175     // The identifier of the file system related to this operation.
 176     DOMString fileSystemId;
 177
 178     // The unique identifier of this request.
 179     long requestId;
 180
 181     // The path of the directory to be created.
 182     DOMString directoryPath;
 183
 184     // Whether the operation is recursive (for directories only).
 185     boolean recursive;
 186   };
 187
 188   // Options for the <code>onDeleteEntryRequested()</code> event.
 189   dictionary DeleteEntryRequestedOptions {
 190     // The identifier of the file system related to this operation.
 191     DOMString fileSystemId;
 192
 193     // The unique identifier of this request.
 194     long requestId;
 195
 196     // The path of the entry to be deleted.
 197     DOMString entryPath;
 198
 199     // Whether the operation is recursive (for directories only).
 200     boolean recursive;
 201   };
 202
 203   // Options for the <code>onCreateFileRequested()</code> event.
 204   dictionary CreateFileRequestedOptions {
 205     // The identifier of the file system related to this operation.
 206     DOMString fileSystemId;
 207
 208     // The unique identifier of this request.
 209     long requestId;
 210
 211     // The path of the file to be created.
 212     DOMString filePath;
 213   };
 214
 215   // Options for the <code>onCopyEntryRequested()</code> event.
 216   dictionary CopyEntryRequestedOptions {
 217     // The identifier of the file system related to this operation.
 218     DOMString fileSystemId;
 219
 220     // The unique identifier of this request.
 221     long requestId;
 222
 223     // The source path of the entry to be copied.
 224     DOMString sourcePath;
 225
 226     // The destination path for the copy operation.
 227     DOMString targetPath;
 228   };
 229
 230   // Options for the <code>onMoveEntryRequested()</code> event.
 231   dictionary MoveEntryRequestedOptions {
 232     // The identifier of the file system related to this operation.
 233     DOMString fileSystemId;
 234
 235     // The unique identifier of this request.
 236     long requestId;
 237
 238     // The source path of the entry to be moved into a new place.
 239     DOMString sourcePath;
 240
 241     // The destination path for the copy operation.
 242     DOMString targetPath;
 243   };
 244
 245   // Options for the <code>onTruncateRequested()</code> event.
 246   dictionary TruncateRequestedOptions {
 247     // The identifier of the file system related to this operation.
 248     DOMString fileSystemId;
 249
 250     // The unique identifier of this request.
 251     long requestId;
 252
 253     // The path of the file to be truncated.
 254     DOMString filePath;
 255
 256     // Number of bytes to be retained after the operation completes.
 257     double length;
 258   };
 259
 260   // Options for the <code>onWriteFileRequested()</code> event.
 261   dictionary WriteFileRequestedOptions {
 262     // The identifier of the file system related to this operation.
 263     DOMString fileSystemId;
 264
 265     // The unique identifier of this request.
 266     long requestId;
 267
 268     // A request ID used to open the file.
 269     long openRequestId;
 270
 271     // Position in the file (in bytes) to start writing the bytes from.
 272     double offset;
 273
 274     // Buffer of bytes to be written to the file.
 275     ArrayBuffer data;
 276   };
 277
 278   // Options for the <code>onAbortRequested()</code> event.
 279   dictionary AbortRequestedOptions {
 280     // The identifier of the file system related to this operation.
 281     DOMString fileSystemId;
 282
 283     // The unique identifier of this request.
 284     long requestId;
 285
 286     // An ID of the request to be aborted.
 287     long operationRequestId;
 288   };
 289
 290   // Callback to receive the result of mount() function.
 291   callback MountCallback = void([nodoc, instanceOf=DOMError] object error);
 292
 293   // Callback to receive the result of unmount() function.
 294   callback UnmountCallback = void([nodoc, instanceOf=DOMError] object error);
 295
 296   // Callback to receive the result of getAll() function.
 297   callback GetAllCallback = void(FileSystemInfo[] fileSystems);
 298
 299   // Callback to handle an error raised from the browser.
 300   [nocompile] callback ErrorCallback = void([instanceOf=DOMError] object error);
 301
 302   // Callback to be called by the providing extension in case of a success.
 303   [nocompile] callback ProviderSuccessCallback = void();
 304
 305   // Callback to be called by the providing extension in case of an error.
 306   [nocompile] callback ProviderErrorCallback = void(ProviderError error);
 307
 308   // Success callback for the <code>onGetMetadataRequested</code> event.
 309   [nocompile] callback MetadataCallback = void(
 310       EntryMetadata metadata);
 311
 312   // Success callback for the <code>onReadDirectoryRequested</code> event. If
 313   // more entries will be returned, then <code>hasMore</code> must be true, and
 314   // it has to be called again with additional entries. If no more entries are
 315   // available, then <code>hasMore</code> must be set to false.
 316   [nocompile] callback EntriesCallback = void(
 317       EntryMetadata[] entries, boolean hasMore);
 318
 319   // Success callback for the <code>onReadFileRequested</code> event. If more
 320   // data will be returned, then <code>hasMore</code> must be true, and it
 321   // has to be called again with additional entries. If no more data is
 322   // available, then <code>hasMore</code> must be set to false.
 323   [nocompile] callback FileDataCallback = void(
 324       ArrayBuffer data, boolean hasMore);
 325
 326   interface Functions {
 327     // Mounts a file system with the given <code>fileSystemId</code> and <code>
 328     // displayName</code>. <code>displayName</code> will be shown in the left
 329     // panel of Files.app. <code>displayName</code> can contain any characters
 330     // including '/', but cannot be an empty string. <code>displayName</code>
 331     // must be descriptive but doesn't have to be unique. Duplicate display
 332     // names are uniquified by adding suffix like "(1)" in the Files app UI.
 333     //
 334     // If a file system with the passed <code>fileSystemId</code> is already
 335     // mounted by this extension, then <code>errorCallback</code> will be called
 336     // with <code>ProviderError.EXISTS</code> value. The <code>fileSystemId
 337     // </code> must not be an empty string.
 338     static void mount(MountOptions options,
 339                       MountCallback successCallback,
 340                       [nocompile] ErrorCallback errorCallback);
 341
 342     // Unmounts a file system with the given <code>fileSystemId</code>. It
 343     // must be called after <code>onUnmountRequested</code> is invoked. Also,
 344     // the providing extension can decide to perform unmounting if not requested
 345     // (eg. in case of lost connection, or a file error). If there is no file
 346     // system with the requested id, or unmounting fails, then the
 347     // <code>errorCallback</code> will be called.
 348     static void unmount(UnmountOptions options,
 349                         UnmountCallback successCallback,
 350                         [nocompile] ErrorCallback errorCallback);
 351
 352     // Returns all file systems mounted by the extension.
 353     static void getAll(GetAllCallback callback);
 354   };
 355
 356   interface Events {
 357     // Raised when unmounting for the file system with the <code>fileSystemId
 358     // </code> identifier is requested. In the response, the <code>unmount
 359     // </code> API method must be called together with <code>successCallback
 360     // </code>. If unmounting is not possible (eg. due to a pending operation),
 361     // then <code>errorCallback</code> must be called.
 362     [maxListeners=1] static void onUnmountRequested(
 363         UnmountRequestedOptions options,
 364         ProviderSuccessCallback successCallback,
 365         ProviderErrorCallback errorCallback);
 366
 367     // Raised when metadata of a file or a directory at <code>entryPath</code>
 368     // is requested. The metadata must be returned with the <code>
 369     // successCallback</code> call. In case of an error, <code>errorCallback
 370     // </code> must be called.
 371     [maxListeners=1] static void onGetMetadataRequested(
 372         GetMetadataRequestedOptions options,
 373         MetadataCallback successCallback,
 374         ProviderErrorCallback errorCallback);
 375
 376     // Raised when contents of a directory at <code>directoryPath</code> are
 377     // requested. The results must be returned in chunks by calling the <code>
 378     // successCallback</code> several times. In case of an error, <code>
 379     // errorCallback</code> must be called.
 380     [maxListeners=1] static void onReadDirectoryRequested(
 381         ReadDirectoryRequestedOptions options,
 382         EntriesCallback successCallback,
 383         ProviderErrorCallback errorCallback);
 384
 385     // Raised when opening a file at <code>filePath</code> is requested. If the
 386     // file does not exist, then the operation must fail.
 387     [maxListeners=1] static void onOpenFileRequested(
 388         OpenFileRequestedOptions options,
 389         ProviderSuccessCallback successCallback,
 390         ProviderErrorCallback errorCallback);
 391
 392     // Raised when opening a file previously opened with <code>openRequestId
 393     // </code> is requested to be closed.
 394     [maxListeners=1] static void onCloseFileRequested(
 395         CloseFileRequestedOptions options,
 396         ProviderSuccessCallback successCallback,
 397         ProviderErrorCallback errorCallback);
 398
 399     // Raised when reading contents of a file opened previously with <code>
 400     // openRequestId</code> is requested. The results must be returned in
 401     // chunks by calling <code>successCallback</code> several times. In case of
 402     // an error, <code>errorCallback</code> must be called.
 403     [maxListeners=1] static void onReadFileRequested(
 404         ReadFileRequestedOptions options,
 405         FileDataCallback successCallback,
 406         ProviderErrorCallback errorCallback);
 407
 408     // Raised when creating a directory is requested. The operation must fail
 409     // with the EXISTS error if the target directory already exists.
 410     // If <code>recursive</code> is true, then all of the missing directories
 411     // on the directory path must be created.
 412     [maxListeners=1] static void onCreateDirectoryRequested(
 413         CreateDirectoryRequestedOptions options,
 414         ProviderSuccessCallback successCallback,
 415         ProviderErrorCallback errorCallback);
 416
 417     // Raised when deleting an entry is requested. If <code>recursive</code> is
 418     // true, and the entry is a directory, then all of the entries inside
 419     // must be recursively deleted as well.
 420     [maxListeners=1] static void onDeleteEntryRequested(
 421         DeleteEntryRequestedOptions options,
 422         ProviderSuccessCallback successCallback,
 423         ProviderErrorCallback errorCallback);
 424
 425     // Raised when creating a file is requested. If the file already exists,
 426     // then <code>errorCallback</code> must be called with the <code>EXISTS
 427     // </code> error code.
 428     [maxListeners=1] static void onCreateFileRequested(
 429         CreateFileRequestedOptions options,
 430         ProviderSuccessCallback successCallback,
 431         ProviderErrorCallback errorCallback);
 432
 433     // Raised when copying an entry (recursively if a directory) is requested.
 434     // If an error occurs, then <code>errorCallback</code> must be called.
 435     [maxListeners=1] static void onCopyEntryRequested(
 436         CopyEntryRequestedOptions options,
 437         ProviderSuccessCallback successCallback,
 438         ProviderErrorCallback errorCallback);
 439
 440     // Raised when moving an entry (recursively if a directory) is requested.
 441     // If an error occurs, then <code>errorCallback</code> must be called.
 442     [maxListeners=1] static void onMoveEntryRequested(
 443         MoveEntryRequestedOptions options,
 444         ProviderSuccessCallback successCallback,
 445         ProviderErrorCallback errorCallback);
 446
 447     // Raised when truncating a file to a desired length is requested.
 448     // If an error occurs, then <code>errorCallback</code> must be called.
 449     [maxListeners=1] static void onTruncateRequested(
 450         TruncateRequestedOptions options,
 451         ProviderSuccessCallback successCallback,
 452         ProviderErrorCallback errorCallback);
 453
 454     // Raised when writing contents to a file opened previously with <code>
 455     // openRequestId</code> is requested.
 456     [maxListeners=1] static void onWriteFileRequested(
 457         WriteFileRequestedOptions options,
 458         ProviderSuccessCallback successCallback,
 459         ProviderErrorCallback errorCallback);
 460
 461     // Raised when aborting an operation with <code>operationRequestId</code>
 462     // is requested. The operation executed with <code>operationRequestId</code>
 463     // must be immediately stopped and <code>successCallback</code> of this
 464     // abort request executed. If aborting fails, then <code>errorCallback
 465     // </code> must be called. Note, that callbacks of the aborted operation
 466     // must not be called, as they will be ignored. Despite calling <code>
 467     // errorCallback</code>, the request may be forcibly aborted.
 468     [maxListeners=1] static void onAbortRequested(
 469         AbortRequestedOptions options,
 470         ProviderSuccessCallback successCallback,
 471         ProviderErrorCallback errorCallback);
 472   };
 473 };
 474