Screen Wake Lock API

1. 序論

現代の~OSは、 より長い~battery寿命を達成するために， 積極的な電力~管理を実装する — それは、 次により，電力~利用度をアリな限り制限することを意味する ⇒ ~host機器は、 利用者-活動が一定時間無いときは，次のいずれかを行ってヨイとする ⇒＃ ~screenの明るさを下げる／ ~screenを~offにする／ ~CPUを休眠~状態になれるようにする ◎ Modern operating systems achieve longer battery life by implementing aggressive power management, meaning that shortly after the lack of user activity, a host device may lower the screen brightness, turn the screen off and even let the CPU go into a deep power state, limiting power usage as much as possible.

これは，~battery寿命を引延ばすことに関しては申し分ないが、 一部の利用事例を邪魔するときもある — 例： ~barcodeを走査している, 電子本を読んでいる, ~recipeを目で追っている, 視聴者に呈示している, 等々。 `~wake~lock：利用事例＠~TR/wake-lock-use-cases/$cite も見よ。 ◎ Though this is great for prolonged battery life, it can sometime hinder some use cases such as scanning a barcode, reading an ebook, following a recipe, presenting to an audience, and so on. See also Wake Lock: Use cases.

~wake~lockは，一般に何かが起こることを防止するが、 ~UA（および下層の~OS）は， 所与の~battery状態s （例：［ コンセントに接続されている／ 放電-中にある／ ~battery残量が少ない ］かどうか） の下で~wake~lockを時間~制限してもヨイ — 電力~節約~modeが作動化された事例では、 ~wake~lockを許容しないことにしてもヨイ。 ◎ A wake lock will generally prevent something from happening, but UAs (and the underlying OS) may time limit a wake lock given the battery status (wall power connected, discharging, low battery level), or even disallow wake locks in the case a power saving mode is activated.

2. ~wake~lock

この仕様は、 次に挙げる `~wake~lock種別@ を定義する： ◎ This specification defines the following wake lock type:

• `~screen~wake~lock@i ⇒ ~screenが~offにすることを防止する。 ~screen~wake~lockを獲得し得るのは、 可視な文書に限られる。

  【 これは、 ~dataとしては，それを表現する文字列 `screen$l と同一視される。 】

  ◎ A screen wake lock prevents the screen from turning off. Only visible documents can acquire the screen wake lock.

この~APIにおいては、 `~wake~lock種別$は，`WakeLockType$I 列挙~値により表現される。 ◎ In the API, the wake lock types are represented by the WakeLockType enum values.

注記： 他の仕様は、 異なる~wake~lock種別を定義し得る。 ◎ Note Other specifications might define different wake lock types.

3. 施策~制御

`~screen~wake~lock~API^cite は、 文字列 `screen-wake-lock^l により識別される`施策により制御される特能$を定義する。 その`既定の許容list$は `'self'^l とする。 ◎ The Screen Wake Lock API defines a policy-controlled feature identified by the string "screen-wake-lock". Its default allowlist is 'self'.

<iframe src="https://third-party.com" allow="screen-wake-lock"></iframe>

Permissions-Policy: screen-wake-lock=()

4. 許可と利用者~prompt

`許可~API^cite `PERMISSIONS$r は、 ~web~site用に［ 利用者からの許可を要請する ］ため, および［ 当の~web~siteが どの許可を有するか~queryする ］ための一様な仕方を供する。 ◎ The [PERMISSIONS] API provides a uniform way for websites to request permissions from users and query which permissions they have.

`~UA$は、 実装に特有な理由 — ~platform設定や利用者~選好など — により， 特定0の `Document$I 用に特定0の`~wake~lock種別$の `~wake~lockを否認-@ できる。 ◎ A user agent can deny a wake lock of a particular wake lock type for a particular Document by any implementation-specific reason, such as platform setting or user preference.

~UAには、 次を行うことが推奨される： ◎ It is RECOMMENDED that a user agent＼

• 何らかの形を成す控えめな通知 — ~wake~lockが作動中になったとき，そのことを利用者に伝える通知 — を示す。 ◎ show some form of unobtrusive notification that informs the user when a wake lock is active,＼
• 次を行う手段を利用者に供する ⇒ 進行中な演算を`阻む＠#dfn-screen-wake-lock-permission-revocation-algorithm$か， 単純に当の通知を退ける ◎ as well as provides the user with the means to block the ongoing operation, or simply dismiss the notification.

5. 各種~概念

この仕様~内で言及される`~task$用の`~task~source$は、 `~screen~wake~lock~task~source@ である。 ◎ The task source for the tasks mentioned in this specification is the screen wake lock task source.

用語 `~platform~wake~lock@ は、 ~UAが，ある~wake~lock［ の状態を~queryする／を獲得する／を解放する ］ためにヤリトリする~platform~interfaceを指す。 ◎ The term platform wake lock refers to platform interfaces with which the user agent interacts to query state and acquire and release a wake lock.

`~platform~wake~lock$は、 下層の~platformにより定義されることもあれば （例：~native~wake~lock~frameworkにおいて）， ~UAにより定義されることも — ~UAが直な~hardware制御を有する場合には — ある。 ◎ A platform wake lock can be defined by the underlying platform (e.g. in a native wake lock framework) or by the user agent, if it has direct hardware control.

6. `Document^I ~interfaceに対する拡張

各 `Document$I ~instanceは、 次に挙げる`内部~slot$を伴って作成される： ◎ 6.1. Internal slots

7. `Navigator^I ~interfaceに対する拡張

[`SecureContext$]
partial interface `Navigator$I {
  [`SameObject$] readonly attribute `WakeLock$I `wakeLock@m;
};

8. `WakeLock^I ~interface

`WakeLock$I ~interfaceは、［ 文書が `~screen~wake~lock$i を獲得する ］ことを許容する。 ◎ The WakeLock interface allows a document to acquire a screen wake lock.

[`SecureContext$, `Exposed$=(Window)]
interface `WakeLock@I {
  `Promise$<`WakeLockSentinel$I> `request$m(optional `WakeLockType$I %type = "screen");
};

9. `WakeLockSentinel^I ~interface

[`SecureContext$, `Exposed$=(Window)]
interface `WakeLockSentinel@I : `EventTarget$I {
  readonly attribute `boolean$ `released$m;
  readonly attribute `WakeLockType$I `type$m;
  `Promise$<`undefined$> `release$m();
  attribute `EventHandler$I `onrelease$m;
};

`WakeLockSentinel$I ~obj %~obj は、 その `type$m 属性が指示する`~wake~lock種別$ %種別 用の下層の`~platform~wake~lock$ %~lock への~handle %~handle を供する： ◎ A WakeLockSentinel object provides a handle to a platform wake lock,＼

• %~handle は、［ %~obj が `release()$m により手動で解放されるか %~lock が解放される ］まで %~obj に保持される。 ◎ and it holds on to it until it is either manually released or until the underlying platform wake lock is released.＼
• %~lock は、 %~handle が存在し続ける限り，作動中に保たれる。 ◎ Its existence keeps a platform wake lock for a given wake lock type active,＼
• %種別 用の `WakeLockSentinel$I ~instanceすべてを解放すると、 %~lock は，解放されるようになる。 ◎ and releasing all WakeLockSentinel instances of a given wake lock type will cause the underlying platform wake lock to be released.

注記： 所与の~wake~lockを`~UA$が どの状況下で解放し得るかについては、 次に挙げる各節を見よ ⇒＃ `§ ~wake~lockの自動的な解放-法＠#auto-releasing-wake-locks$, `§ 全部的に作動中でなくなった文書の取扱い＠#handling-document-loss-of-full-activity$, `§ 可視でなくなった文書の取扱い＠#handling-document-loss-of-visibility$ ◎ Note See auto-releasing wake locks, handling document loss of full activity and handling document loss of visibility for circumstances under which a given wake lock may be released by the user agent.

各 `WakeLockSentinel$I ~instanceは、 次に挙げる`内部~slot$を伴って作成される： ◎ 9.1. Internal slots ◎ WakeLockSentinel instances are created with the following internal slots:

`onrelease@m 属性は、 名前 `onrelease^l を伴う`~event~handler$用の`~event~handler~IDL属性$である — 対応する`~event~handler~event型$は、 `release@et である。 ◎ 9.5. The onrelease attribute ◎ The onrelease attribute is an event handler IDL attribute for the "onrelease" event handler, whose event handler event type is "release".

`onrelease$m は、 次を~scriptに通知するために利用される ⇒ この `WakeLockSentinel$I ~objの~handleが［ `release()$m ~methodが~callされた／ 当の~wake~lockが`~UA$により解放された ］ことに因り解放された。 ◎ It is used to notify scripts that a given WakeLockSentinel object's handle has been released, either due to the release() method being called or because the wake lock was released by the user agent.

注記： `WakeLockSentinel$I ~objの~handleが解放されたとしても、 所与の`~wake~lock種別$用の`~platform~wake~lock$が解放されたことを意味するとは限らない 【まだ解放されてない `WakeLockSentinel^I ~objが他にもあり得るので】。 それは、 `~platform~wake~lock$の `ActiveLocks$sl 内部~slotに依存する。 `~wake~lockを解放する$を見よ。 ◎ Note A WakeLockSentinel object's handle being released does not necessarily mean the platform wake lock for a given wake lock type was released. That depends on the platform wake lock's [[ActiveLocks]] internal slot. See release a wake lock.

注記： `onrelease$m ~event~handlerを`利用する方法の例＠#onrelease-example$も見よ。 ◎ Note Example 2 contains an example of how to use the onrelease event handler.

10. `WakeLockType^I 列挙

この仕様は、 各`~wake~lock種別$を述べる目的で， それらを表現する次の列挙を定義する： ◎ For the purpose of wake lock type description, this specification defines the following enumeration to represent wake lock types:

enum `WakeLockType@I { `screen$l };

`screen@l は、 種別 `~screen~wake~lock$i を表現する。 ◎ screen • Screen wake lock type.

11. ~wake~lockの管理-法

この節は、 各`~wake~lock種別$に等しくかつ独立に適用される — 特定0の`~wake~lock種別$が明示的に言及されない限り。 ◎ This section applies to each wake lock type equally and independently, unless a particular wake lock type is explicitly mentioned.

`~UA$は、 所与の`~wake~lock種別$用の `~wake~lockを適用するよう下層の~OSに要請する@ ことにより，当の~wake~lockを獲得する。 `~UA$は、 そのような要請の返り値を検査しない — 言い換えれば、 `~UA$は，~wake~lockの獲得を助言的に限られるものとして扱うモノトスル。 ◎ The user agent acquires the wake lock by requesting the underlying operating system to apply the lock. A possible return value of the request to the underlying operating system is not checked. In other words, user agents MUST treat wake lock acquisition as advisory-only.

逆に，`~UA$は、 所与の`~wake~lock種別$用の `~wake~lockをもはや適用しないよう下層の~OSに要請する@ ことにより，当の~wake~lockを解放する。 当の~lockは、 そのような要請が成功したときに限り，解放されたものと見なされる。 ◎ Conversely, the user agent releases the 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.

~wake~lockが `適用-可能@ であるとは、 次が満たされることをいう ⇒ ~OSは、 当の~lockの適用を許可する状態にある （例：~batteryは不足なく充電されている）。 ◎ The wake lock is applicable if the state of the operating system permits application of the lock (e.g. there is sufficient battery charge).

`~screen~wake~lock$i は、 ~screenが利用者により手動で~offに切替えられた場合には， 再び~onに切替えられるまで，`適用-可能$でないモノトスル。 ◎ The screen wake lock MUST NOT be applicable after the screen is manually switched off by the user until it is switched on again.

注記： ~wake~lockが適用-可能かどうかは、 一過な条件である — 例：~battery残量が少なく，充電し直されたとき。 可視性~要件と同様に，これは、 自動的な~wake~lock管理の一部を成すものであり， ~wake~lockを許容するか否認するか裁定する処理nの一部を成すものではない。 ◎ Note Whether the wake lock is applicable is a transient condition, e.g. when the battery charge is low but then the battery is recharged. So like the visibility requirement, this is part of automatic wake lock management and not part of the decision process whether to allow or deny the wake lock.

12. ~security／~privacy の考慮点

~screen~wake~lockは、 様々な機器~component — 特に~display — を，~lockされない場合より高い電力で運用させ得る。 これは、 望ましくない効果へ至らせ得る — 機器が自身を自動的に~lockすることを防止して，~batteryの消耗が速くなるなど。 それは、 近くに可用な電源が無いことが多い~mobile機器において特に懸念される。 予期されない時点に~batteryが完全に消耗すると、 利用者は，通話や~network~service（緊急~call~serviceも含む）を利用-不能になる。 ◎ Screen wake locks can cause various device components - particularly the display - to operate at higher power levels than they otherwise would. This can lead to undesirable effects, such as preventing the device from automatically locking itself and faster battery depletion. Faster battery depletion is of particular concern for mobile devices, which often don't have a stationary power source readily available. Complete battery depletion at an unexpected time can lead to inability of the user to make or receive calls and use network services, including the emergency call service.

実装は、 例えば［ ~battery容量が少ない場合／ 利用者が自身の機器を電力~節約~modeに置いた場合 ］には，~screen~wake~lock用の要請を無視してもヨイ。 ◎ Implementations MAY ignore requests for screen wake lock if, for example, the battery capacity is low, or the user has put their device in a power-saving mode.

~UAには、［ ~screen~wake~lockがいつ作動中になったか，利用者が知ることを許容する ］よう，何らかの~UIや指示子を供することが推奨される。 そのような~UIを供することは、 末端-利用者が［ 特定0の~web~appが，機器の消費電力に負な影響iがある ］ことを識別する助けにもなり、 それでも欲される場合には，そのための動作をとることも彼らに許容する。 ◎ It is RECOMMENDED that a user agent provide some UI or indicator that allows the user to know when a screen wake lock is active. Providing such a UI could help end users to identify if a particular web application is having a negative energy impact on the device, and allow them to take action if so desired.

13. 例

function tryKeepScreenAlive(%minutes) {
  navigator.wakeLock.request("screen").then(%lock => {
    setTimeout(() => %lock.release(), %minutes * 60 * 1000);
  });
}

tryKeepScreenAlive(10);

const %checkbox = document.createElement("input");
%checkbox.setAttribute("type", "checkbox");
document.body.appendChild(%checkbox);

const %sentinel = await navigator.wakeLock.request("screen");
%checkbox.checked = !%sentinel.released;
%sentinel.onrelease = () => %checkbox.checked = !%sentinel.released;

let %lock1 = await navigator.wakeLock.request("screen");
let %lock2 = await navigator.wakeLock.request("screen");

%lock1.release();
%lock2.release();

謝辞

次に挙げる方々による，この作業に対する貢献に感謝したい ⇒ `Mounir Lamouri, Sergey Konstantinov, Matvey Larionov, Dominique Hazael-Massieux, Domenic Denicola, Thomas Steiner, Anne van Kesteren^en ◎ We would like to offer our sincere thanks to Mounir Lamouri, Sergey Konstantinov, Matvey Larionov, Dominique Hazael-Massieux, Domenic Denicola, Thomas Steiner, Anne van Kesteren for their contributions to this work.

変更点

この節は、 以前の公表からの変更点を文書化する。 ◎ This section documents the changes since previous publications.

2017年 12月 14日 勧告候補からの変更点 ◎ B.1. Changes since the 14 December 2017 CR

この文書【における~screen~wake種別】を~screen~wake~lockだけに絞って， ~system~lockを新たな仕様へ移動した。 ◎ Convert the document to purely screen wake lock, and move system lock to a new specification.

利用者~可視~APIを書き直した。 ◎ Rewrite user-visible API.

可視でなくなった文書を処するため、 `WakeLock.request()^c に `中止されたとき＠~INFRA#if-aborted$の段を追加した。 【この変更に該当する箇所は、この仕様には無い（他の仕様に移動されたと思われる）】 ◎ Add an if aborted step to WakeLock.request() to deal with hidden documents.

~IDL索引を追加した。 ◎ Add an IDL Index.

重複な規範的な言明を除去した。 ◎ Remove duplicate normative statements.

各~例を現代化した。 ◎ Modernize the examples.

注釈文に代えて内部~slotを利用するようにした。 ◎ Use internal slots instead of prose.

~UAが いつ`~wake~lockを解放-＠#dfn-release-a-wake-lock$してもヨイとされるかに関する情報を追加した。 ◎ Add info on when the user agent may release a wake lock.

文書の可視性を取扱うようにした。 ◎ Handle document visibility.

`ScreenWakeLock^I を構築-可能にした。 ◎ Make ScreenWakeLock constructable.

任意選択な許可~prompt法を統合した。 ◎ Integrate optional permission prompting.

［ 全部的に作動中でなくなった文書, ~worker内で走っている場合 ］を取扱うようにした。 【が、~workerに関する記述は，この仕様~内には無い】 ◎ Handle loss of full activity, as well as running in workers.

§ 序論を書き直した。 ◎ Rewrite the introduction section.

`Feature Policy^en（特能~施策）を `Permissions Policy^en（許可~施策）に改称した。 ◎ Rename Feature Policy to Permissions Policy.

`WakeLockSentinel.released^c を追加した。 ◎ Add WakeLockSentinel.released.

この仕様における~task用の~task~sourceを定義した。 ◎ Define a task source for tasks in this specification.