1// Copyright 2015 The Chromium Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5module device.mojom;
6
7enum WakeLockType {
8    // Prevent the application from being suspended. On some platforms, apps may
9    // be suspended when they are not visible to the user. This type of block
10    // requests that the app continue to run in that case, and on all platforms
11    // prevents the system from sleeping.
12    // Example use cases: downloading a file, playing audio.
13    kPreventAppSuspension = 0,
14
15    // Prevent the display from going to sleep. This also has the side effect of
16    // preventing the system from sleeping, but does not necessarily prevent the
17    // app from being suspended on some platforms if the user hides it.
18    // Example use case: playing video.
19    kPreventDisplaySleep = 1,
20
21    // Like kPreventDisplaySleep, but permits the display to dim while remaining
22    // on. On some platforms, this may be treated identically to
23    // PreventDisplaySleep.
24    kPreventDisplaySleepAllowDimming = 2,
25};
26
27enum WakeLockReason {
28    // Audio is being played.
29    kAudioPlayback = 0,
30    // Video is being played.
31    kVideoPlayback = 1,
32    // WakeLock for some other reason.
33    kOther = 2,
34};
35
36// WakeLock receives wake lock preferences from its client.
37interface WakeLock {
38  // Requests that a wake lock be applied on behalf of this client. Has no
39  // effect if the client has previously called this method without
40  // subsequently calling CancelWakeLock().
41  RequestWakeLock();
42
43  // Cancels all outstanding wake lock requests from this client. If there are
44  // no more outstanding requests from any clients, the active wake lock (if
45  // there is one) will be turned off.
46  CancelWakeLock();
47
48  // Adds a client to this WakeLock instance. Clients are grouped on a
49  // per-WakeLock instance basis: that is, a given WakeLock instance turns
50  // on its wake lock whenever *any* of its clients make a request to do so
51  // and turns off its wake lock only when *all* its clients that had
52  // previously called RequestWakelock() cancel their requests.
53  AddClient(pending_receiver<WakeLock> wake_lock);
54
55  // Change the wake lock type. Has no effect if the current wakelock is shared
56  // by more than one client (by AddClient()). Has no effect on Android.
57  // If the wake lock is in "active" state (by RequestWakeLock()), it requests
58  // a wakelock with new type first before cancels the old one to ensure that
59  // there isn't a brief period where the old wake lock is cancelled while the
60  // new wake lock is not requested. If the wake lock is in "non-active" state,
61  // it only changes the type.
62  // Returns true if the wake lock type is successfully changed.
63  ChangeType(WakeLockType type) => (bool result);
64
65  // Test-only method that returns whether a wake lock is currently active.
66  HasWakeLockForTests() => (bool result);
67};
68