/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this file,
 * You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"
#include "nsIVolumeStat.idl"

[scriptable, uuid(EE752CB8-8FD7-11E4-A602-70221D5D46B0)]
interface nsIVolume : nsISupports
{
  // These MUST match the states from android's system/vold/Volume.h header
  // Note: Changes made to the STATE_xxx names should also be reflected in the
  //       NS_VolumeStateStr function found in Volume.cpp
  const long STATE_INIT        = -1;
  const long STATE_NOMEDIA     = 0;
  const long STATE_IDLE        = 1;
  const long STATE_PENDING     = 2;
  const long STATE_CHECKING    = 3;
  const long STATE_MOUNTED     = 4;
  const long STATE_UNMOUNTING  = 5;
  const long STATE_FORMATTING  = 6;
  const long STATE_SHARED      = 7;
  const long STATE_SHAREDMNT   = 8;
  const long STATE_CHECKMNT    = 100;
  const long STATE_MOUNT_FAIL  = 101;

  // The name of the volume. Often there is only one volume, called sdcard.
  // But some phones support multiple volumes.
  readonly attribute DOMString name;

  // The mount point is the path on the system where the volume is mounted
  // and is only valid when state == STATE_MOUNTED.
  readonly attribute DOMString mountPoint;

  // Reflects the current state of the volume, using STATE_xxx constants
  // from above.
  readonly attribute long state;

  // mountGeneration is a unique number which is used distinguish between
  // periods of time that a volume is in the mounted state. Each time a
  // volume transitions to the mounted state, the mountGeneration will
  // be different from the last time it transitioned to the mounted state.
  readonly attribute long mountGeneration;

  // While a volume is mounted, it can be locked, preventing it from being
  // shared with the PC. To lock a volume, acquire an MozWakeLock
  // using the name of this attribute. Note that mountLockName changes
  // every time the mountGeneration changes, so you'll need to reacquire
  // the wakelock every time the volume becomes mounted.
  readonly attribute DOMString mountLockName;

  // Determines if a mountlock is currently being held against this volume.
  readonly attribute boolean isMountLocked;

  // Determines if media is actually present or not. Note, that when an sdcard
  // is ejected, it may go through several tranistory states before finally
  // arriving at STATE_NOMEDIA. So isMediaPresent may be false even when the
  // current state isn't STATE_NOMEDIA.
  readonly attribute boolean isMediaPresent;

  // Determines if the volume is currently being shared. This covers off
  // more than just state == STATE_SHARED. isSharing will return true from the
  // time that the volume leaves the mounted state, until it gets back to
  // mounted, nomedia, or formatting states. This attribute is to allow
  // device storage to suppress unwanted 'unavailable' status when
  // transitioning from mounted to sharing and back again.
  readonly attribute boolean isSharing;

  // Determines if the volume is currently formatting. This sets true once 
  // mFormatRequest == true and mState == STATE_MOUNTED, and sets false
  // once the volume has been formatted and mounted again.
  readonly attribute boolean isFormatting;

  readonly attribute boolean isUnmounting;

  nsIVolumeStat getStats();

  // Formats the volume in IO thread, if the volume is ready to be formatted.
  // Automounter will unmount it, format it and then mount it again.
  void format();

  // Mounts the volume in IO thread, if the volume is already unmounted.
  // Automounter will mount it. Otherwise Automounter will skip this.
  void mount();

  // Unmounts the volume in IO thread, if the volume is already mounted.
  // Automounter will unmount it. Otherwise Automounter will skip this.
  void unmount();

  // Whether this is a fake volume.
  readonly attribute boolean isFake;

  // Whether this is a removable volume
  readonly attribute boolean isRemovable;

  // Whether this is a hot-swappable volume
  readonly attribute boolean isHotSwappable;

};

%{C++
// For use with the ObserverService
#define NS_VOLUME_STATE_CHANGED  "volume-state-changed"
#define NS_VOLUME_REMOVED        "volume-removed"

namespace mozilla {
namespace system {

// Convert a state into a loggable/printable string.
const char* NS_VolumeStateStr(int32_t aState);

} // system
} // mozilla
%}