path: root/chrome/common/extensions/api/file_system_provider.idl

// Copyright 2013 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// Use the <code>chrome.fileSystemProvider</code> API to create file systems,
// that can be accessible from the file manager on Chrome OS.
[implemented_in="chrome/browser/chromeos/extensions/file_system_provider/file_system_provider_api.h"]
namespace fileSystemProvider {
  // Error codes used by providing extensions in response to requests as well
  // as in case of errors when calling methods of the API. For success, <code>
  // OK</code> must be used.
  enum ProviderError {
    OK,
    FAILED,
    IN_USE,
    EXISTS,
    NOT_FOUND,
    ACCESS_DENIED,
    TOO_MANY_OPENED,
    NO_MEMORY,
    NO_SPACE,
    NOT_A_DIRECTORY,
    INVALID_OPERATION,
    SECURITY,
    ABORT,
    NOT_A_FILE,
    NOT_EMPTY,
    INVALID_URL,
    IO
  };

  // Mode of opening a file. Used by <code>onOpenFileRequested</code>.
  enum OpenFileMode {
    READ,
    WRITE
  };

  // Type of a change detected on the observed directory.
  enum ChangeType {
    CHANGED,
    DELETED
  };

  // Source of the file system data.
  enum FileSystemSource {
    // The file system is handling a file, eg. an archive file obtained via the
    // <code>OnLaunched</code> event and the <code>file_handlers</code> manifest
    // entry.
    FILE,

    // The file system contents are fetched from an external device, such as a
    // USB device, but not via <code>file_handlers</code>.
    DEVICE,

    // The file system is network based. The contents are obtained from another
    // server or local network. Eg. cloud services.
    NETWORK
  };

  // Represents metadata of a file or a directory.
  dictionary EntryMetadata {
    // True if it is a directory.
    boolean isDirectory;

    // Name of this entry (not full path name). Must not contain '/'. For root
    // it must be empty.
    DOMString name;

    // File size in bytes.
    double size;

    // The last modified time of this entry.
    [instanceOf=Date] object modificationTime;

    // Mime type for the entry.
    DOMString? mimeType;

    // Thumbnail image as a data URI in either PNG, JPEG or WEBP format, at most
    // 32 KB in size. Optional, but can be provided only when explicitly
    // requested by the <code>onGetMetadataRequested</code> event.
    DOMString? thumbnail;
  };

  // Represents a watcher.
  dictionary Watcher {
    // The path of the entry being observed.
    DOMString entryPath;

    // Whether watching should include all child entries recursively. It can be
    // true for directories only.
    boolean recursive;

    // Tag used by the last notification for the watcher.
    DOMString? lastTag;
  };

  // Represents an opened file.
  dictionary OpenedFile {
    // A request ID to be be used by consecutive read/write and close requests.
    long openRequestId;

    // The path of the opened file.
    DOMString filePath;

    // Whether the file was opened for reading or writing.
    OpenFileMode mode;
  };

  // Represents a mounted file system.
  dictionary FileSystemInfo {
    // The identifier of the file system.
    DOMString fileSystemId;

    // A human-readable name for the file system. 
    DOMString displayName;

    // Whether the file system supports operations which may change contents
    // of the file system (such as creating, deleting or writing to files).
    boolean writable;

    // The maximum number of files that can be opened at once. If 0, then not
    // limited.
    long openedFilesLimit;

    // List of currently opened files.
    OpenedFile[] openedFiles;

    // Source of the file system data.
    FileSystemSource? source;

    // Whether the file system supports the <code>tag</code> field for observing
    // directories.
    [nodoc] boolean? supportsNotifyTag;

    // List of watchers.
    [nodoc] Watcher[] watchers;
  };

  // Options for the <code>mount()</code> method.
  dictionary MountOptions {
    // The string indentifier of the file system. Must be unique per each
    // extension.
    DOMString fileSystemId;

    // A human-readable name for the file system. 
    DOMString displayName;

    // Whether the file system supports operations which may change contents
    // of the file system (such as creating, deleting or writing to files).
    boolean? writable;

    // The maximum number of files that can be opened at once. If not specified,
    // or 0, then not limited.
    long? openedFilesLimit;

    // Source of the file system data.
    FileSystemSource? source;

    // Whether the file system supports the <code>tag</code> field for observed
    // directories. Required in order to enable the internal cache.
    [nodoc] boolean? supportsNotifyTag;
  };

  // Options for the <code>unmount()</code> method.
  dictionary UnmountOptions {
    // The identifier of the file system to be unmounted.
    DOMString fileSystemId;
  };

  // Options for the <code>onUnmountRequested()</code> event.
  dictionary UnmountRequestedOptions {
    // The identifier of the file system to be unmounted.
    DOMString fileSystemId;
    long requestId;
  };

  // Options for the <code>onGetMetadataRequested()</code> event.
  dictionary GetMetadataRequestedOptions {
    // The identifier of the file system related to this operation.
    DOMString fileSystemId;

    // The unique identifier of this request.
    long requestId;

    // The path of the entry to fetch metadata about.
    DOMString entryPath;

    // Set to <code>true</code> if the thumbnail is requested.
    boolean thumbnail;
  };

  // Options for the <code>onReadDirectoryRequested()</code> event.
  dictionary ReadDirectoryRequestedOptions {
    // The identifier of the file system related to this operation.
    DOMString fileSystemId;

    // The unique identifier of this request.
    long requestId;

    // The path of the directory which contents are requested. 
    DOMString directoryPath;
  };

  // Options for the <code>onOpenFileRequested()</code> event.
  dictionary OpenFileRequestedOptions {
    // The identifier of the file system related to this operation.
    DOMString fileSystemId;

    // A request ID which will be used by consecutive read/write and close
    // requests.
    long requestId;

    // The path of the file to be opened.
    DOMString filePath;

    // Whether the file will be used for reading or writing.
    OpenFileMode mode;
  };

  // Options for the <code>onCloseFileRequested()</code> event.
  dictionary CloseFileRequestedOptions {
    // The identifier of the file system related to this operation.
    DOMString fileSystemId;

    // The unique identifier of this request.
    long requestId;

    // A request ID used to open the file.
    long openRequestId;
  };

  // Options for the <code>onReadFileRequested()</code> event.
  dictionary ReadFileRequestedOptions {
    // The identifier of the file system related to this operation.
    DOMString fileSystemId;

    // The unique identifier of this request.
    long requestId;

    // A request ID used to open the file.
    long openRequestId;

    // Position in the file (in bytes) to start reading from.
    double offset;

    // Number of bytes to be returned.
    double length;
  };

  // Options for the <code>onCreateDirectoryRequested()</code> event.
  dictionary CreateDirectoryRequestedOptions {
    // The identifier of the file system related to this operation.
    DOMString fileSystemId;

    // The unique identifier of this request.
    long requestId;

    // The path of the directory to be created.
    DOMString directoryPath;

    // Whether the operation is recursive (for directories only).
    boolean recursive;
  };

  // Options for the <code>onDeleteEntryRequested()</code> event.
  dictionary DeleteEntryRequestedOptions {
    // The identifier of the file system related to this operation.
    DOMString fileSystemId;

    // The unique identifier of this request.
    long requestId;

    // The path of the entry to be deleted.
    DOMString entryPath;

    // Whether the operation is recursive (for directories only).
    boolean recursive;
  };

  // Options for the <code>onCreateFileRequested()</code> event.
  dictionary CreateFileRequestedOptions {
    // The identifier of the file system related to this operation.
    DOMString fileSystemId;

    // The unique identifier of this request.
    long requestId;

    // The path of the file to be created.
    DOMString filePath;
  };

  // Options for the <code>onCopyEntryRequested()</code> event.
  dictionary CopyEntryRequestedOptions {
    // The identifier of the file system related to this operation.
    DOMString fileSystemId;

    // The unique identifier of this request.
    long requestId;

    // The source path of the entry to be copied.
    DOMString sourcePath;

    // The destination path for the copy operation.
    DOMString targetPath;
  };

  // Options for the <code>onMoveEntryRequested()</code> event.
  dictionary MoveEntryRequestedOptions {
    // The identifier of the file system related to this operation.
    DOMString fileSystemId;

    // The unique identifier of this request.
    long requestId;

    // The source path of the entry to be moved into a new place.
    DOMString sourcePath;

    // The destination path for the copy operation.
    DOMString targetPath;
  };

  // Options for the <code>onTruncateRequested()</code> event.
  dictionary TruncateRequestedOptions {
    // The identifier of the file system related to this operation.
    DOMString fileSystemId;

    // The unique identifier of this request.
    long requestId;

    // The path of the file to be truncated.
    DOMString filePath;

    // Number of bytes to be retained after the operation completes.
    double length;
  };

  // Options for the <code>onWriteFileRequested()</code> event.
  dictionary WriteFileRequestedOptions {
    // The identifier of the file system related to this operation.
    DOMString fileSystemId;

    // The unique identifier of this request.
    long requestId;

    // A request ID used to open the file.
    long openRequestId;

    // Position in the file (in bytes) to start writing the bytes from.
    double offset;

    // Buffer of bytes to be written to the file.
    ArrayBuffer data;
  };

  // Options for the <code>onAbortRequested()</code> event.
  dictionary AbortRequestedOptions {
    // The identifier of the file system related to this operation.
    DOMString fileSystemId;

    // The unique identifier of this request.
    long requestId;

    // An ID of the request to be aborted.
    long operationRequestId;
  };

  // Options for the <code>onAddWatcherRequested()</code> event.
  dictionary AddWatcherRequestedOptions {
    // The identifier of the file system related to this operation.
    DOMString fileSystemId;

    // The unique identifier of this request.
    long requestId;

    // The path of the entry to be observed.
    DOMString entryPath;

    // Whether observing should include all child entries recursively. It can be
    // true for directories only.
    boolean recursive;
  };

  // Options for the <code>onRemoveWatcherRequested()</code> event.
  dictionary RemoveWatcherRequestedOptions {
    // The identifier of the file system related to this operation.
    DOMString fileSystemId;

    // The unique identifier of this request.
    long requestId;

    // The path of the watched entry.
    DOMString entryPath;

    // Mode of the watcher.
    boolean recursive;
  };

  // Information about a change happened to an entry within the observed
  // directory (including the entry itself).
  dictionary Change {
    // The path of the changed entry.
    DOMString entryPath;

    // The type of the change which happened to the entry.
    ChangeType changeType;
  };

  // Options for the <code>Notify()</code> method.
  dictionary NotifyOptions {
    // The identifier of the file system related to this change.
    DOMString fileSystemId;

    // The path of the observed entry.
    DOMString observedPath;

    // Mode of the observed entry.
    boolean recursive;

    // The type of the change which happened to the observed entry. If it is
    // DELETED, then the observed entry will be automatically removed from the
    // list of observed entries.
    ChangeType changeType;

    // List of changes to entries within the observed directory (including the
    // entry itself)
    Change[]? changes;

    // Tag for the notification. Required if the file system was mounted with
    // the <code>supportsNotifyTag</code> option. Note, that this flag is
    // necessary to provide notifications about changes which changed even
    // when the system was shutdown.
    DOMString? tag;
  };

  // Callback to receive the result of getAll() function.
  callback GetAllCallback = void(FileSystemInfo[] fileSystems);

  // Callback to receive the result of get() function.
  callback GetCallback = void(FileSystemInfo fileSystem);

  // Callback to be called by the providing extension in case of a success.
  [nocompile] callback ProviderSuccessCallback = void();

  // Callback to be called by the providing extension in case of an error.
  [nocompile] callback ProviderErrorCallback = void(ProviderError error);

  // Success callback for the <code>onGetMetadataRequested</code> event.
  [nocompile] callback MetadataCallback = void(
      EntryMetadata metadata);

  // Success callback for the <code>onReadDirectoryRequested</code> event. If
  // more entries will be returned, then <code>hasMore</code> must be true, and
  // it has to be called again with additional entries. If no more entries are
  // available, then <code>hasMore</code> must be set to false.
  [nocompile] callback EntriesCallback = void(
      EntryMetadata[] entries, boolean hasMore);

  // Success callback for the <code>onReadFileRequested</code> event. If more
  // data will be returned, then <code>hasMore</code> must be true, and it
  // has to be called again with additional entries. If no more data is
  // available, then <code>hasMore</code> must be set to false.
  [nocompile] callback FileDataCallback = void(
      ArrayBuffer data, boolean hasMore);

  // A generic result callback to indicate success or failure.
  callback ResultCallback = void();

  interface Functions {
    // Mounts a file system with the given <code>fileSystemId</code> and <code>
    // displayName</code>. <code>displayName</code> will be shown in the left
    // panel of Files.app. <code>displayName</code> can contain any characters
    // including '/', but cannot be an empty string. <code>displayName</code>
    // must be descriptive but doesn't have to be unique. The <code>fileSystemId
    // </code> must not be an empty string.
    //
    // Depending on the type of the file system being mounted, the <code>source
    // </code> option must be set appropriately.
    //
    // In case of an error, <code>chrome.runtime.lastError</code> will be set
    // will a corresponding error code.
    static void mount(MountOptions options,
                      optional ResultCallback callback);

    // Unmounts a file system with the given <code>fileSystemId</code>. It
    // must be called after <code>onUnmountRequested</code> is invoked. Also,
    // the providing extension can decide to perform unmounting if not requested
    // (eg. in case of lost connection, or a file error).
    //
    // In case of an error, <code>chrome.runtime.lastError</code> will be set
    // will a corresponding error code.
    static void unmount(UnmountOptions options,
                        optional ResultCallback callback);

    // Returns all file systems mounted by the extension.
    static void getAll(GetAllCallback callback);

    // Returns information about a file system with the passed <code>
    // fileSystemId</code>.
    static void get(DOMString fileSystemId, GetCallback callback);

    // Notifies about changes in the watched directory at <code>
    // observedPath</code> in <code>recursive</code mode. If the file system is
    // mounted with <code>supportsNofityTag</code>, then <code>tag</code> must
    // be provided, and all changes since the last notification always reported,
    // even if the system was shutdown. The last tag can be obtained with <code>
    // getAll()</code>. Note, that <code>tag</code> is required in order to
    // enable the internal cache.
    //
    // Value of <code>tag</code> can be any string which is unique per call,
    // so it's possible to identify the last registered notification. Eg. if
    // the providing extension starts after a reboot, and the last registered
    // notification's tag is equal to "123", then it should call notify() for
    // all changes which happened since the change tagged as "123". It cannot
    // be an empty string.
    //
    // Not all providers are able to provide a tag, but if the file system has
    // a changelog, then the tag can be eg. a change number, or a revision
    // number.
    //
    // Note that if a parent directory is removed, then all descendant entries
    // are also removed, and if they are watched, then the API must be notified
    // about the fact. Also, if a directory is renamed, then all descendant
    // entries are in fact removed, as there is no entry under their original
    // paths anymore.
    //
    // In case of an error, <code>chrome.runtime.lastError</code> will be set
    // will a corresponding error code.
    [nodoc] static void notify(NotifyOptions options,
                               optional ResultCallback callback);
  };

  interface Events {
    // Raised when unmounting for the file system with the <code>fileSystemId
    // </code> identifier is requested. In the response, the <code>unmount
    // </code> API method must be called together with <code>successCallback
    // </code>. If unmounting is not possible (eg. due to a pending operation),
    // then <code>errorCallback</code> must be called.
    [maxListeners=1] static void onUnmountRequested(
        UnmountRequestedOptions options,
        ProviderSuccessCallback successCallback,
        ProviderErrorCallback errorCallback);

    // Raised when metadata of a file or a directory at <code>entryPath</code>
    // is requested. The metadata must be returned with the <code>
    // successCallback</code> call. In case of an error, <code>errorCallback
    // </code> must be called.
    [maxListeners=1] static void onGetMetadataRequested(
        GetMetadataRequestedOptions options,
        MetadataCallback successCallback,
        ProviderErrorCallback errorCallback);

    // Raised when contents of a directory at <code>directoryPath</code> are
    // requested. The results must be returned in chunks by calling the <code>
    // successCallback</code> several times. In case of an error, <code>
    // errorCallback</code> must be called.
    [maxListeners=1] static void onReadDirectoryRequested(
        ReadDirectoryRequestedOptions options,
        EntriesCallback successCallback,
        ProviderErrorCallback errorCallback);

    // Raised when opening a file at <code>filePath</code> is requested. If the
    // file does not exist, then the operation must fail. Maximum number of
    // files opened at once can be specified with <code>MountOptions</code>.
    [maxListeners=1] static void onOpenFileRequested(
        OpenFileRequestedOptions options,
        ProviderSuccessCallback successCallback,
        ProviderErrorCallback errorCallback);

    // Raised when opening a file previously opened with <code>openRequestId
    // </code> is requested to be closed.
    [maxListeners=1] static void onCloseFileRequested(
        CloseFileRequestedOptions options,
        ProviderSuccessCallback successCallback,
        ProviderErrorCallback errorCallback);

    // Raised when reading contents of a file opened previously with <code>
    // openRequestId</code> is requested. The results must be returned in
    // chunks by calling <code>successCallback</code> several times. In case of
    // an error, <code>errorCallback</code> must be called.
    [maxListeners=1] static void onReadFileRequested(
        ReadFileRequestedOptions options,
        FileDataCallback successCallback,
        ProviderErrorCallback errorCallback);

    // Raised when creating a directory is requested. The operation must fail
    // with the EXISTS error if the target directory already exists.
    // If <code>recursive</code> is true, then all of the missing directories
    // on the directory path must be created.
    [maxListeners=1] static void onCreateDirectoryRequested(
        CreateDirectoryRequestedOptions options,
        ProviderSuccessCallback successCallback,
        ProviderErrorCallback errorCallback);

    // Raised when deleting an entry is requested. If <code>recursive</code> is
    // true, and the entry is a directory, then all of the entries inside
    // must be recursively deleted as well.
    [maxListeners=1] static void onDeleteEntryRequested(
        DeleteEntryRequestedOptions options,
        ProviderSuccessCallback successCallback,
        ProviderErrorCallback errorCallback);

    // Raised when creating a file is requested. If the file already exists,
    // then <code>errorCallback</code> must be called with the <code>EXISTS
    // </code> error code.
    [maxListeners=1] static void onCreateFileRequested(
        CreateFileRequestedOptions options,
        ProviderSuccessCallback successCallback,
        ProviderErrorCallback errorCallback);

    // Raised when copying an entry (recursively if a directory) is requested.
    // If an error occurs, then <code>errorCallback</code> must be called.
    [maxListeners=1] static void onCopyEntryRequested(
        CopyEntryRequestedOptions options,
        ProviderSuccessCallback successCallback,
        ProviderErrorCallback errorCallback);

    // Raised when moving an entry (recursively if a directory) is requested.
    // If an error occurs, then <code>errorCallback</code> must be called.
    [maxListeners=1] static void onMoveEntryRequested(
        MoveEntryRequestedOptions options,
        ProviderSuccessCallback successCallback,
        ProviderErrorCallback errorCallback);

    // Raised when truncating a file to a desired length is requested.
    // If an error occurs, then <code>errorCallback</code> must be called.
    [maxListeners=1] static void onTruncateRequested(
        TruncateRequestedOptions options,
        ProviderSuccessCallback successCallback,
        ProviderErrorCallback errorCallback);

    // Raised when writing contents to a file opened previously with <code>
    // openRequestId</code> is requested.
    [maxListeners=1] static void onWriteFileRequested(
        WriteFileRequestedOptions options,
        ProviderSuccessCallback successCallback,
        ProviderErrorCallback errorCallback);

    // Raised when aborting an operation with <code>operationRequestId</code>
    // is requested. The operation executed with <code>operationRequestId</code>
    // must be immediately stopped and <code>successCallback</code> of this
    // abort request executed. If aborting fails, then <code>errorCallback
    // </code> must be called. Note, that callbacks of the aborted operation
    // must not be called, as they will be ignored. Despite calling <code>
    // errorCallback</code>, the request may be forcibly aborted. 
    [maxListeners=1] static void onAbortRequested(
        AbortRequestedOptions options,
        ProviderSuccessCallback successCallback,
        ProviderErrorCallback errorCallback);

    // Raised when setting a new directory watcher is requested. If an error
    // occurs, then <code>errorCallback</code> must be called.
    [maxListeners=1, nodoc] static void onAddWatcherRequested(
      AddWatcherRequestedOptions options,
      ProviderSuccessCallback successCallback,
      ProviderErrorCallback errorCallback);

    // Raised when the watcher should be removed. If an error occurs, then
    // <code>errorCallback</code> must be called.
    [maxListeners=1, nodoc] static void onRemoveWatcherRequested(
      RemoveWatcherRequestedOptions options,
      ProviderSuccessCallback successCallback,
      ProviderErrorCallback errorCallback);
  };
};