// 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.
[platforms=("chromeos"),
 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. For
  // success, <code>OK</code> should 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
  };

  // 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).
    DOMString name;

    // File size in bytes.
    double size;

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

  // Options for the <code>mount()</code> method.
  dictionary MountOptions {
    DOMString fileSystemId;
    DOMString displayName;
  };

  // Options for the <code>unmount()</code> method.
  dictionary UnmountOptions {
    DOMString fileSystemId;
  };

  // Options for the <code>onUnmountRequested()</code> event.
  dictionary UnmountRequestedOptions {
    DOMString fileSystemId;
    long requestId;
  };

  // Options for the <code>onGetMetadataRequested()</code> event.
  dictionary GetMetadataRequestedOptions {
    DOMString fileSystemId;
    long requestId;
    DOMString entryPath;
  };

  // Options for the <code>onReadDirectoryRequested()</code> event.
  dictionary ReadDirectoryRequestedOptions {
    DOMString fileSystemId;
    long requestId;
    DOMString directoryPath;
  };

  // Options for the <code>onOpenFileRequested()</code> event.
  dictionary OpenFileRequestedOptions {
    DOMString fileSystemId;
    long requestId;
    DOMString filePath;
    OpenFileMode mode;
    boolean create;
  };

  // Options for the <code>onCloseFileRequested()</code> event.
  dictionary CloseFileRequestedOptions {
    DOMString fileSystemId;
    long requestId;
    long openRequestId;
  };

  // Options for the <code>onReadFileRequested()</code> event.
  dictionary ReadFileRequestedOptions {
    DOMString fileSystemId;
    long requestId;
    long openRequestId;
    double offset;
    double length;
  };

  // Callback to receive the result of mount() function.
  callback MountCallback = void([nodoc, instanceOf=DOMError] object error);

  // Callback to receive the result of unmount() function.
  callback UnmountCallback = void([nodoc, instanceOf=DOMError] object error);

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

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

  // Callback to handle an error raised from the browser.
  [nocompile] callback ErrorCallback = void([instanceOf=DOMError] object error);

  // Success callback for the <code>onGetMetadataRequested</code> event.
  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.
  callback EntriesCallback = void(ResourceEntry[] entries, bool 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.
  callback FileDataCallback = void(ArrayBuffer data, bool hasMore);

  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>
    // should be descriptive but doesn't have to be unique. Duplicate display
    // names are uniquified by adding suffix like "(1)" in the Files app UI.
    //
    // If a file system with the passed <code>fileSystemId</code> is already
    // mounted by this extension, then <code>errorCallback</code> will be called
    // with <code>ProviderError.EXISTS</code> value. The <code>fileSystemId
    // </code> must not be an empty string.
    static void mount(MountOptions options,
                      MountCallback successCallback,
                      [nocompile] ErrorCallback errorCallback);

    // Unmounts a file system with the given <code>fileSystemId</code>. It
    // should 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). If there is no file
    // system with the requested id, or unmounting fails, then the
    // <code>errorCallback</code> will be called.
    static void unmount(UnmountOptions options,
                        UnmountCallback successCallback,
                        [nocompile] ErrorCallback errorCallback);
  };

  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 should 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 should 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 should 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 <code>create</code> is set to <code>true</code> and the file does not
    // exist, then it should be created.
    [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 contents of a file opened previously with <code>openRequestId
    // </code>. The results should 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);
  };
};