// 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.
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 transient ID that uniquely identifies the storage device.
    // This ID will be persistent within the same run of a single application.
    // It will not be a persistent identifier between different runs of an
    // application, or between different applications.
    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 StorageAvailableCapacityInfo {
    // A copied |id| of getAvailableCapacity function parameter |id|.
    DOMString id;
    // The available capacity of the storage device, in bytes.
    double availableCapacity;
  };

  [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 EjectDeviceCallback = void (EjectDeviceResultCode result);

  callback StorageInfoCallback = void (StorageUnitInfo[] info);

  callback GetAvailableCapacityCallback = void (
      StorageAvailableCapacityInfo 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.
    static void ejectDevice(DOMString id, EjectDeviceCallback callback);

    // Get the available capacity of a specified |id| storage device.
    // The |id| is the transient device ID from StorageUnitInfo.
    static void getAvailableCapacity(DOMString id,
                                     GetAvailableCapacityCallback callback);
  };

  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);
  };

};