// Copyright 2015 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.

module device.mojom;

enum WakeLockType {
    // Prevent the application from being suspended. On some platforms, apps may
    // be suspended when they are not visible to the user. This type of block
    // requests that the app continue to run in that case, and on all platforms
    // prevents the system from sleeping.
    // Example use cases: downloading a file, playing audio.
    kPreventAppSuspension = 0,

    // Prevent the display from going to sleep. This also has the side effect of
    // preventing the system from sleeping, but does not necessarily prevent the
    // app from being suspended on some platforms if the user hides it.
    // Example use case: playing video.
    kPreventDisplaySleep = 1,

    // Like kPreventDisplaySleep, but permits the display to dim while remaining
    // on. On some platforms, this may be treated identically to
    // PreventDisplaySleep.
    kPreventDisplaySleepAllowDimming = 2,
};

enum WakeLockReason {
    // Audio is being played.
    kAudioPlayback = 0,
    // Video is being played.
    kVideoPlayback = 1,
    // WakeLock for some other reason.
    kOther = 2,
};

// WakeLock receives wake lock preferences from its client.
interface WakeLock {
  // Requests that a wake lock be applied on behalf of this client. Has no
  // effect if the client has previously called this method without
  // subsequently calling CancelWakeLock().
  RequestWakeLock();

  // Cancels all outstanding wake lock requests from this client. If there are
  // no more outstanding requests from any clients, the active wake lock (if
  // there is one) will be turned off.
  CancelWakeLock();

  // Adds a client to this WakeLock instance. Clients are grouped on a
  // per-WakeLock instance basis: that is, a given WakeLock instance turns
  // on its wake lock whenever *any* of its clients make a request to do so
  // and turns off its wake lock only when *all* its clients that had
  // previously called RequestWakelock() cancel their requests.
  AddClient(WakeLock& wake_lock);

  // Change the wake lock type. Has no effect if the current wakelock is shared
  // by more than one client (by AddClient()). Has no effect on Android.
  // If the wake lock is in "active" state (by RequestWakeLock()), it requests
  // a wakelock with new type first before cancels the old one to ensure that
  // there isn't a brief period where the old wake lock is cancelled while the
  // new wake lock is not requested. If the wake lock is in "non-active" state,
  // it only changes the type.
  // Returns true if the wake lock type is successfully changed.
  ChangeType(WakeLockType type) => (bool result);

  // Test-only method that returns whether a wake lock is currently active.
  HasWakeLockForTests() => (bool result);
};