Copyright © 2015 W3C® (MIT, ERCIM, Keio, Beihang), All Rights Reserved. W3C liability, trademark and document use rules apply.
This document specifies an API that allows web applications to request a wake lock. A wake lock prevents some aspect of the device from entering a power-saving state (e.g., preventing the system from turning off the screen).
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
Implementors need to be aware that this specification is extremely unstable. Implementors who are not taking part in the discussions will find the specification changing out from under them in incompatible ways. Vendors interested in implementing this specification before it eventually reaches the Candidate Recommendation phase should subscribe to the repository on GitHub and take part in the discussions.
This document was published by the Device APIs Working Group as a First Public Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-device-apis@w3.org (subscribe, archives). All comments are welcome.
Publication as a First Public Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This document is governed by the 1 August 2014 W3C Process Document.
This section is non-normative.
//request to keep the display awake when the recipe is showing: document.keepScreenAwake = true; //stop keeping the display awake: document.keepScreenAwake = false;
A wake lock prevents some aspect of the device or operating system from entering a power-saving state.
This specification deals specifically with the screen wake lock which prevents the screen(s) of the device from entering a power-saving state.
Each Document
has a request flag for the
wake lock. The request flag is unset when the
Document
is created. Request flags are used by
user agent to track if a particular Document
is requesting the lock (for the purpose of
acquiring or releasing the
corresponding operating system lock).
A Document
requests wake lock
by setting its lock request flag. This means that the
Document
indicates to the user agent a
preference that the underlying operating system apply wake lock, i.e.
keep the screen on.
A Document
can successfully request wake lock
regardless of whether the actual lock can be applied by the user
agent and/or the underlying operating system at the time when the
request is made.
Conversely, a Document
cancels wake lock request by resetting its lock request flag
. This means that the Document
indicates to the
user agent that it no longer prefers that the underlying system
apply the wake lock.
Lock request flag merely indicates a preference of the
Document
to have the wake lock applied. Requesting
the lock or cancelling wake lock request does not entail synchronous
acquisition or release of the corresponding operating system lock, and
can only result in an error when the document is explicitly prohibited
form executing those operations by some security mechanism.
No Document
"owns" the operating system lock and
the state of operating system lock does not affect the state of the
lock request flag for any Document
.
Instead, user agent is responsible for mapping the state of request
flags for all Document
s to the state the operating
system lock.
User agent acquires the wake lock by requesting the undrelying operating system to apply the lock. The lock is considered acquired only when the request to the operating system succeeds.
Conversely, user agent releases wake lock by requesting the underlying operating system to no longer apply the wake lock. The lock is considered released only when the request to the operating system succeeds.
A Document
is relevant to the wake lock
if:
Document
is fully active.
Document
's browsing context is in
position to interact with the user, i.e. it is in an active tab
and the browser window is focused.
Document
's wake lock request flag is
set.
Document
does not have a
browsing context, it is not relevant to the wake lock.
The wake lock is applicable if the state of the operating system permits application of the lock (e.g. there is sufficient battery charge and wake locking is not disabled by a user setting).
User agent MUST acquire the wake lock when all of the following conditions become true:
Document
that is
relevant to the wake lock.
User agent MUST release the wake lock when any of the conditions above become false.
From the user's perspective, a Document
which has
requested the wake lock will no longer cause the lock to be applied if
one of the following happens:
Should the tab and/or browser window once again become focused, the lock will be applied again if it is still requested and the state of operating system permits its application.
Document
interfacepartial interface Document {
attribute boolean keepScreenAwake;
};
keepScreenAwake
of type boolean, true
to
request wake lock or to false
to
cancel wake lock request.
The lock request and management mechanism presented in this document can
be extended to support additional types of locks by adding new lock
request flags to Document
interface. E.g. a "system"
wake lock could be introduced which would prevent the device's cpu,
radio(s), and other system services from entering a power-saving state
while allowing the screen to switch off.
The following concepts and interfaces are defined in [HTML]:
This section is non-normative.
The use cases and requirements are documented in [WAKE-LOCK-USE-CASES].
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key word MUST is to be interpreted as described in [RFC2119].
This specification defines conformance criteria for a single product: a user agent that implements the interfaces that it contains.
A user agent MUST implement the APIs defined in this specification in a manner that conforms to the ECMAScript Bindings defined in [WEBIDL].
This section is non-normative.
We would like to offer my sincere thanks to Mounir Lamouri, Sergey Konstantinov and Matvey Larionov for their contributions to this work.