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 as well
  11   // as in case of errors when calling methods of the API. For success, <code>
  12   // OK</code> must be used.
  13   enum ProviderError {
  14     OK,
  15     FAILED,
  16     IN_USE,
  17     EXISTS,
  18     NOT_FOUND,
  19     ACCESS_DENIED,
  20     TOO_MANY_OPENED,
  21     NO_MEMORY,
  22     NO_SPACE,
  23     NOT_A_DIRECTORY,
  24     INVALID_OPERATION,
  25     SECURITY,
  26     ABORT,
  27     NOT_A_FILE,
  28     NOT_EMPTY,
  29     INVALID_URL,
  30     IO
  31   };
  32
  33   // Mode of opening a file. Used by <code>onOpenFileRequested</code>.
  34   enum OpenFileMode {
  35     READ,
  36     WRITE
  37   };
  38
  39   // Type of a change detected on the observed directory.
  40   enum ChangeType {
  41     CHANGED,
  42     DELETED
  43   };
  44
  45   // Represents metadata of a file or a directory.
  46   dictionary EntryMetadata {
  47     // True if it is a directory.
  48     boolean isDirectory;
  49
  50     // Name of this entry (not full path name).
  51     DOMString name;
  52
  53     // File size in bytes.
  54     double size;
  55
  56     // The last modified time of this entry.
  57     [instanceOf=Date] object modificationTime;
  58
  59     // Mime type for the entry.
  60     DOMString? mimeType;
  61
  62     // Thumbnail image as a data URI in either PNG, JPEG or WEBP format, at most
  63     // 32 KB in size. Optional, but can be provided only when explicitly
  64     // requested by the <code>onGetMetadataRequested</code> event.
  65     DOMString? thumbnail;
  66   };
  67
  68   // Represents a watcher.
  69   dictionary Watcher {
  70     // The path of the entry being observed.
  71     DOMString entryPath;
  72
  73     // Whether watching should include all child entries recursively. It can be
  74     // true for directories only.
  75     boolean recursive;
  76
  77     // Tag used by the last notification for the watcher.
  78     DOMString? lastTag;
  79   };
  80
  81   // Represents a mounted file system.
  82   dictionary FileSystemInfo {
  83     // The identifier of the file system.
  84     DOMString fileSystemId;
  85
  86     // A human-readable name for the file system.
  87     DOMString displayName;
  88
  89     // Whether the file system supports operations which may change contents
  90     // of the file system (such as creating, deleting or writing to files).
  91     boolean writable;
  92
  93     // Whether the file system supports the <code>tag</code> field for observing
  94     // directories.
  95     [nodoc] boolean? supportsNotifyTag;
  96
  97     // List of watchers.
  98     [nodoc] Watcher[] watchers;
  99   };
 100
 101   // Options for the <code>mount()</code> method.
 102   dictionary MountOptions {
 103     // The string indentifier of the file system. Must be unique per each
 104     // extension.
 105     DOMString fileSystemId;
 106
 107     // A human-readable name for the file system.
 108     DOMString displayName;
 109
 110     // Whether the file system supports operations which may change contents
 111     // of the file system (such as creating, deleting or writing to files).
 112     boolean? writable;
 113
 114     // Whether the file system supports the <code>tag</code> field for observed
 115     // directories. Required in order to enable the internal cache.
 116     [nodoc] boolean? supportsNotifyTag;
 117   };
 118
 119   // Options for the <code>unmount()</code> method.
 120   dictionary UnmountOptions {
 121     // The identifier of the file system to be unmounted.
 122     DOMString fileSystemId;
 123   };
 124
 125   // Options for the <code>onUnmountRequested()</code> event.
 126   dictionary UnmountRequestedOptions {
 127     // The identifier of the file system to be unmounted.
 128     DOMString fileSystemId;
 129     long requestId;
 130   };
 131
 132   // Options for the <code>onGetMetadataRequested()</code> event.
 133   dictionary GetMetadataRequestedOptions {
 134     // The identifier of the file system related to this operation.
 135     DOMString fileSystemId;
 136
 137     // The unique identifier of this request.
 138     long requestId;
 139
 140     // The path of the entry to fetch metadata about.
 141     DOMString entryPath;
 142
 143     // Set to <code>true</code> if the thumbnail is requested.
 144     boolean thumbnail;
 145   };
 146
 147   // Options for the <code>onReadDirectoryRequested()</code> event.
 148   dictionary ReadDirectoryRequestedOptions {
 149     // The identifier of the file system related to this operation.
 150     DOMString fileSystemId;
 151
 152     // The unique identifier of this request.
 153     long requestId;
 154
 155     // The path of the directory which contents are requested.
 156     DOMString directoryPath;
 157   };
 158
 159   // Options for the <code>onOpenFileRequested()</code> event.
 160   dictionary OpenFileRequestedOptions {
 161     // The identifier of the file system related to this operation.
 162     DOMString fileSystemId;
 163
 164     // A request ID which will be used by consecutive read/write and close
 165     // requests.
 166     long requestId;
 167
 168     // The path of the file to be opened.
 169     DOMString filePath;
 170
 171     // Whether the file will be used for reading or writing.
 172     OpenFileMode mode;
 173   };
 174
 175   // Options for the <code>onCloseFileRequested()</code> event.
 176   dictionary CloseFileRequestedOptions {
 177     // The identifier of the file system related to this operation.
 178     DOMString fileSystemId;
 179
 180     // The unique identifier of this request.
 181     long requestId;
 182
 183     // A request ID used to open the file.
 184     long openRequestId;
 185   };
 186
 187   // Options for the <code>onReadFileRequested()</code> event.
 188   dictionary ReadFileRequestedOptions {
 189     // The identifier of the file system related to this operation.
 190     DOMString fileSystemId;
 191
 192     // The unique identifier of this request.
 193     long requestId;
 194
 195     // A request ID used to open the file.
 196     long openRequestId;
 197
 198     // Position in the file (in bytes) to start reading from.
 199     double offset;
 200
 201     // Number of bytes to be returned.
 202     double length;
 203   };
 204
 205   // Options for the <code>onCreateDirectoryRequested()</code> event.
 206   dictionary CreateDirectoryRequestedOptions {
 207     // The identifier of the file system related to this operation.
 208     DOMString fileSystemId;
 209
 210     // The unique identifier of this request.
 211     long requestId;
 212
 213     // The path of the directory to be created.
 214     DOMString directoryPath;
 215
 216     // Whether the operation is recursive (for directories only).
 217     boolean recursive;
 218   };
 219
 220   // Options for the <code>onDeleteEntryRequested()</code> event.
 221   dictionary DeleteEntryRequestedOptions {
 222     // The identifier of the file system related to this operation.
 223     DOMString fileSystemId;
 224
 225     // The unique identifier of this request.
 226     long requestId;
 227
 228     // The path of the entry to be deleted.
 229     DOMString entryPath;
 230
 231     // Whether the operation is recursive (for directories only).
 232     boolean recursive;
 233   };
 234
 235   // Options for the <code>onCreateFileRequested()</code> event.
 236   dictionary CreateFileRequestedOptions {
 237     // The identifier of the file system related to this operation.
 238     DOMString fileSystemId;
 239
 240     // The unique identifier of this request.
 241     long requestId;
 242
 243     // The path of the file to be created.
 244     DOMString filePath;
 245   };
 246
 247   // Options for the <code>onCopyEntryRequested()</code> event.
 248   dictionary CopyEntryRequestedOptions {
 249     // The identifier of the file system related to this operation.
 250     DOMString fileSystemId;
 251
 252     // The unique identifier of this request.
 253     long requestId;
 254
 255     // The source path of the entry to be copied.
 256     DOMString sourcePath;
 257
 258     // The destination path for the copy operation.
 259     DOMString targetPath;
 260   };
 261
 262   // Options for the <code>onMoveEntryRequested()</code> event.
 263   dictionary MoveEntryRequestedOptions {
 264     // The identifier of the file system related to this operation.
 265     DOMString fileSystemId;
 266
 267     // The unique identifier of this request.
 268     long requestId;
 269
 270     // The source path of the entry to be moved into a new place.
 271     DOMString sourcePath;
 272
 273     // The destination path for the copy operation.
 274     DOMString targetPath;
 275   };
 276
 277   // Options for the <code>onTruncateRequested()</code> event.
 278   dictionary TruncateRequestedOptions {
 279     // The identifier of the file system related to this operation.
 280     DOMString fileSystemId;
 281
 282     // The unique identifier of this request.
 283     long requestId;
 284
 285     // The path of the file to be truncated.
 286     DOMString filePath;
 287
 288     // Number of bytes to be retained after the operation completes.
 289     double length;
 290   };
 291
 292   // Options for the <code>onWriteFileRequested()</code> event.
 293   dictionary WriteFileRequestedOptions {
 294     // The identifier of the file system related to this operation.
 295     DOMString fileSystemId;
 296
 297     // The unique identifier of this request.
 298     long requestId;
 299
 300     // A request ID used to open the file.
 301     long openRequestId;
 302
 303     // Position in the file (in bytes) to start writing the bytes from.
 304     double offset;
 305
 306     // Buffer of bytes to be written to the file.
 307     ArrayBuffer data;
 308   };
 309
 310   // Options for the <code>onAbortRequested()</code> event.
 311   dictionary AbortRequestedOptions {
 312     // The identifier of the file system related to this operation.
 313     DOMString fileSystemId;
 314
 315     // The unique identifier of this request.
 316     long requestId;
 317
 318     // An ID of the request to be aborted.
 319     long operationRequestId;
 320   };
 321
 322   // Options for the <code>onAddWatcherRequested()</code> event.
 323   dictionary AddWatcherRequestedOptions {
 324     // The identifier of the file system related to this operation.
 325     DOMString fileSystemId;
 326
 327     // The unique identifier of this request.
 328     long requestId;
 329
 330     // The path of the entry to be observed.
 331     DOMString entryPath;
 332
 333     // Whether observing should include all child entries recursively. It can be
 334     // true for directories only.
 335     boolean recursive;
 336   };
 337
 338   // Options for the <code>onRemoveWatcherRequested()</code> event.
 339   dictionary RemoveWatcherRequestedOptions {
 340     // The identifier of the file system related to this operation.
 341     DOMString fileSystemId;
 342
 343     // The unique identifier of this request.
 344     long requestId;
 345
 346     // The path of the watched entry.
 347     DOMString entryPath;
 348
 349     // Mode of the watcher.
 350     boolean recursive;
 351   };
 352
 353   // Information about a change happened to an entry within the observed
 354   // directory (including the entry itself).
 355   dictionary Change {
 356     // The path of the changed entry.
 357     DOMString entryPath;
 358
 359     // The type of the change which happened to the entry.
 360     ChangeType changeType;
 361   };
 362
 363   // Options for the <code>Notify()</code> method.
 364   dictionary NotifyOptions {
 365     // The identifier of the file system related to this change.
 366     DOMString fileSystemId;
 367
 368     // The path of the observed entry.
 369     DOMString observedPath;
 370
 371     // Mode of the observed entry.
 372     boolean recursive;
 373
 374     // The type of the change which happened to the observed entry. If it is
 375     // DELETED, then the observed entry will be automatically removed from the
 376     // list of observed entries.
 377     ChangeType changeType;
 378
 379     // List of changes to entries within the observed directory (including the
 380     // entry itself)
 381     Change[]? changes;
 382
 383     // Tag for the notification. Required if the file system was mounted with
 384     // the <code>supportsNotifyTag</code> option. Note, that this flag is
 385     // necessary to provide notifications about changes which changed even
 386     // when the system was shutdown.
 387     DOMString? tag;
 388   };
 389
 390   // Callback to receive the result of getAll() function.
 391   callback GetAllCallback = void(FileSystemInfo[] fileSystems);
 392
 393   // Callback to be called by the providing extension in case of a success.
 394   [nocompile] callback ProviderSuccessCallback = void();
 395
 396   // Callback to be called by the providing extension in case of an error.
 397   [nocompile] callback ProviderErrorCallback = void(ProviderError error);
 398
 399   // Success callback for the <code>onGetMetadataRequested</code> event.
 400   [nocompile] callback MetadataCallback = void(
 401       EntryMetadata metadata);
 402
 403   // Success callback for the <code>onReadDirectoryRequested</code> event. If
 404   // more entries will be returned, then <code>hasMore</code> must be true, and
 405   // it has to be called again with additional entries. If no more entries are
 406   // available, then <code>hasMore</code> must be set to false.
 407   [nocompile] callback EntriesCallback = void(
 408       EntryMetadata[] entries, boolean hasMore);
 409
 410   // Success callback for the <code>onReadFileRequested</code> event. If more
 411   // data will be returned, then <code>hasMore</code> must be true, and it
 412   // has to be called again with additional entries. If no more data is
 413   // available, then <code>hasMore</code> must be set to false.
 414   [nocompile] callback FileDataCallback = void(
 415       ArrayBuffer data, boolean hasMore);
 416
 417   // A generic result callback to indicate success or failure.
 418   callback ResultCallback = void();
 419
 420   interface Functions {
 421     // Mounts a file system with the given <code>fileSystemId</code> and <code>
 422     // displayName</code>. <code>displayName</code> will be shown in the left
 423     // panel of Files.app. <code>displayName</code> can contain any characters
 424     // including '/', but cannot be an empty string. <code>displayName</code>
 425     // must be descriptive but doesn't have to be unique. The <code>fileSystemId
 426     // </code> must not be an empty string.
 427     //
 428     // In case of an error, <code>chrome.runtime.lastError</code> will be set
 429     // will a corresponding error code.
 430     static void mount(MountOptions options,
 431                       optional ResultCallback callback);
 432
 433     // Unmounts a file system with the given <code>fileSystemId</code>. It
 434     // must be called after <code>onUnmountRequested</code> is invoked. Also,
 435     // the providing extension can decide to perform unmounting if not requested
 436     // (eg. in case of lost connection, or a file error).
 437     //
 438     // In case of an error, <code>chrome.runtime.lastError</code> will be set
 439     // will a corresponding error code.
 440     static void unmount(UnmountOptions options,
 441                         optional ResultCallback callback);
 442
 443     // Returns all file systems mounted by the extension.
 444     static void getAll(GetAllCallback callback);
 445
 446     // Notifies about changes in the watched directory at <code>
 447     // observedPath</code> in <code>recursive</code mode. If the file system is
 448     // mounted with <code>supportsNofityTag</code>, then <code>tag</code> must
 449     // be provided, and all changes since the last notification always reported,
 450     // even if the system was shutdown. The last tag can be obtained with <code>
 451     // getAll()</code>. Note, that <code>tag</code> is required in order to
 452     // enable the internal cache.
 453     //
 454     // Value of <code>tag</code> can be any string which is unique per call,
 455     // so it's possible to identify the last registered notification. Eg. if
 456     // the providing extension starts after a reboot, and the last registered
 457     // notification's tag is equal to "123", then it should call notify() for
 458     // all changes which happened since the change tagged as "123". It cannot
 459     // be an empty string.
 460     //
 461     // Not all providers are able to provide a tag, but if the file system has
 462     // a changelog, then the tag can be eg. a change number, or a revision
 463     // number.
 464     //
 465     // Note that if a parent directory is removed, then all descendant entries
 466     // are also removed, and if they are watched, then the API must be notified
 467     // about the fact. Also, if a directory is renamed, then all descendant
 468     // entries are in fact removed, as there is no entry under their original
 469     // paths anymore.
 470     //
 471     // In case of an error, <code>chrome.runtime.lastError</code> will be set
 472     // will a corresponding error code.
 473     [nodoc] static void notify(NotifyOptions options,
 474                                optional ResultCallback callback);
 475   };
 476
 477   interface Events {
 478     // Raised when unmounting for the file system with the <code>fileSystemId
 479     // </code> identifier is requested. In the response, the <code>unmount
 480     // </code> API method must be called together with <code>successCallback
 481     // </code>. If unmounting is not possible (eg. due to a pending operation),
 482     // then <code>errorCallback</code> must be called.
 483     [maxListeners=1] static void onUnmountRequested(
 484         UnmountRequestedOptions options,
 485         ProviderSuccessCallback successCallback,
 486         ProviderErrorCallback errorCallback);
 487
 488     // Raised when metadata of a file or a directory at <code>entryPath</code>
 489     // is requested. The metadata must be returned with the <code>
 490     // successCallback</code> call. In case of an error, <code>errorCallback
 491     // </code> must be called.
 492     [maxListeners=1] static void onGetMetadataRequested(
 493         GetMetadataRequestedOptions options,
 494         MetadataCallback successCallback,
 495         ProviderErrorCallback errorCallback);
 496
 497     // Raised when contents of a directory at <code>directoryPath</code> are
 498     // requested. The results must be returned in chunks by calling the <code>
 499     // successCallback</code> several times. In case of an error, <code>
 500     // errorCallback</code> must be called.
 501     [maxListeners=1] static void onReadDirectoryRequested(
 502         ReadDirectoryRequestedOptions options,
 503         EntriesCallback successCallback,
 504         ProviderErrorCallback errorCallback);
 505
 506     // Raised when opening a file at <code>filePath</code> is requested. If the
 507     // file does not exist, then the operation must fail.
 508     [maxListeners=1] static void onOpenFileRequested(
 509         OpenFileRequestedOptions options,
 510         ProviderSuccessCallback successCallback,
 511         ProviderErrorCallback errorCallback);
 512
 513     // Raised when opening a file previously opened with <code>openRequestId
 514     // </code> is requested to be closed.
 515     [maxListeners=1] static void onCloseFileRequested(
 516         CloseFileRequestedOptions options,
 517         ProviderSuccessCallback successCallback,
 518         ProviderErrorCallback errorCallback);
 519
 520     // Raised when reading contents of a file opened previously with <code>
 521     // openRequestId</code> is requested. The results must be returned in
 522     // chunks by calling <code>successCallback</code> several times. In case of
 523     // an error, <code>errorCallback</code> must be called.
 524     [maxListeners=1] static void onReadFileRequested(
 525         ReadFileRequestedOptions options,
 526         FileDataCallback successCallback,
 527         ProviderErrorCallback errorCallback);
 528
 529     // Raised when creating a directory is requested. The operation must fail
 530     // with the EXISTS error if the target directory already exists.
 531     // If <code>recursive</code> is true, then all of the missing directories
 532     // on the directory path must be created.
 533     [maxListeners=1] static void onCreateDirectoryRequested(
 534         CreateDirectoryRequestedOptions options,
 535         ProviderSuccessCallback successCallback,
 536         ProviderErrorCallback errorCallback);
 537
 538     // Raised when deleting an entry is requested. If <code>recursive</code> is
 539     // true, and the entry is a directory, then all of the entries inside
 540     // must be recursively deleted as well.
 541     [maxListeners=1] static void onDeleteEntryRequested(
 542         DeleteEntryRequestedOptions options,
 543         ProviderSuccessCallback successCallback,
 544         ProviderErrorCallback errorCallback);
 545
 546     // Raised when creating a file is requested. If the file already exists,
 547     // then <code>errorCallback</code> must be called with the <code>EXISTS
 548     // </code> error code.
 549     [maxListeners=1] static void onCreateFileRequested(
 550         CreateFileRequestedOptions options,
 551         ProviderSuccessCallback successCallback,
 552         ProviderErrorCallback errorCallback);
 553
 554     // Raised when copying an entry (recursively if a directory) is requested.
 555     // If an error occurs, then <code>errorCallback</code> must be called.
 556     [maxListeners=1] static void onCopyEntryRequested(
 557         CopyEntryRequestedOptions options,
 558         ProviderSuccessCallback successCallback,
 559         ProviderErrorCallback errorCallback);
 560
 561     // Raised when moving an entry (recursively if a directory) is requested.
 562     // If an error occurs, then <code>errorCallback</code> must be called.
 563     [maxListeners=1] static void onMoveEntryRequested(
 564         MoveEntryRequestedOptions options,
 565         ProviderSuccessCallback successCallback,
 566         ProviderErrorCallback errorCallback);
 567
 568     // Raised when truncating a file to a desired length is requested.
 569     // If an error occurs, then <code>errorCallback</code> must be called.
 570     [maxListeners=1] static void onTruncateRequested(
 571         TruncateRequestedOptions options,
 572         ProviderSuccessCallback successCallback,
 573         ProviderErrorCallback errorCallback);
 574
 575     // Raised when writing contents to a file opened previously with <code>
 576     // openRequestId</code> is requested.
 577     [maxListeners=1] static void onWriteFileRequested(
 578         WriteFileRequestedOptions options,
 579         ProviderSuccessCallback successCallback,
 580         ProviderErrorCallback errorCallback);
 581
 582     // Raised when aborting an operation with <code>operationRequestId</code>
 583     // is requested. The operation executed with <code>operationRequestId</code>
 584     // must be immediately stopped and <code>successCallback</code> of this
 585     // abort request executed. If aborting fails, then <code>errorCallback
 586     // </code> must be called. Note, that callbacks of the aborted operation
 587     // must not be called, as they will be ignored. Despite calling <code>
 588     // errorCallback</code>, the request may be forcibly aborted.
 589     [maxListeners=1] static void onAbortRequested(
 590         AbortRequestedOptions options,
 591         ProviderSuccessCallback successCallback,
 592         ProviderErrorCallback errorCallback);
 593
 594     // Raised when setting a new directory watcher is requested. If an error
 595     // occurs, then <code>errorCallback</code> must be called.
 596     [maxListeners=1, nodoc] static void onAddWatcherRequested(
 597       AddWatcherRequestedOptions options,
 598       ProviderSuccessCallback successCallback,
 599       ProviderErrorCallback errorCallback);
 600
 601     // Raised when the watcher should be removed. If an error occurs, then
 602     // <code>errorCallback</code> must be called.
 603     [maxListeners=1, nodoc] static void onRemoveWatcherRequested(
 604       RemoveWatcherRequestedOptions options,
 605       ProviderSuccessCallback successCallback,
 606       ProviderErrorCallback errorCallback);
 607   };
 608 };
 609