// 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.system.storage</code> API to query storage device
// information and be notified when a removable storage device is attached and
// detached or the available capacity changes.
namespace system.storage {

  enum StorageUnitType {
    // The storage has fixed media, e.g. hard disk or SSD.
    fixed,
    // The storage is removable, e.g. USB flash drive.
    removable,
    // The storage type is unknown.
    unknown
  };

  dictionary StorageUnitInfo {
    // The unique storage id. It will use the transient ID.
    DOMString id;
    // The name of the storage unit.
    DOMString name;
    // The media type of the storage unit.
    StorageUnitType type;
    // The total amount of the storage space, in bytes.
    double capacity;
  };

  dictionary StorageFreeSpaceChangeInfo {
    // The transient id of the storage unit already changed.
    DOMString id;
    // The new value of the available capacity.
    double availableCapacity;
  };

  // A dictionary that describes the add particular storage device watch
  // request results.
  dictionary AddAvailableCapacityWatchResult {
    DOMString id;
    boolean success;
  };

  [inline_doc] enum EjectDeviceResultCode {
    // The ejection command is successful -- the application can prompt the user
    // to remove the device.
    success,
    // The device is in use by another application. The ejection did not
    // succeed; the user should not remove the device until the other
    // application is done with the device.
    in_use,
    // There is no such device known.
    no_such_device,
    // The ejection command failed.
    failure
  };

  callback AddAvailableCapacityWatchCallback = void (
      AddAvailableCapacityWatchResult info);

  callback GetAllAvailableCapacityWatchesCallback = void (
      DOMString[] storageIds);

  callback EjectDeviceCallback = void (EjectDeviceResultCode result);

  callback StorageInfoCallback = void (StorageUnitInfo[] info);

  interface Functions {
    // Get the storage information from the system. The argument passed to the
    // callback is an array of StorageUnitInfo objects.
    static void getInfo(StorageInfoCallback callback);

    // Ejects a removable storage device.
    // Note: We plan to move this function into a namespace that indicates it
    // that modifies the state of the system rather than just gathering
    // information.
    static void ejectDevice(DOMString id, EjectDeviceCallback callback);

    // Monitor a particular storage device available change capacity.
    static void addAvailableCapacityWatch(
        DOMString id,
        AddAvailableCapacityWatchCallback callback);

    // Remove the monitor of a particular device.
    static void removeAvailableCapacityWatch(DOMString id);

    // Get all the watched storage devices.
    static void getAllAvailableCapacityWatches(
        GetAllAvailableCapacityWatchesCallback callback);

    // Remove all the storage devices monitors.
    static void removeAllAvailableCapacityWatches();
  };

  interface Events {
    // Fired when a new removable storage is attached to the system.
    static void onAttached(StorageUnitInfo info);

    // Fired when a removable storage is detached from the system.
    static void onDetached(DOMString id);

    // Fired when the storage device available capacity is changed.
    // |info|: The changed information for the specified storage unit.
    static void onAvailableCapacityChanged(StorageFreeSpaceChangeInfo info);
  };

};