1. 序論
この文書は、 ~Web~platform上で`強力な特能$を利用する許可を要請するための機能を指定する。 ◎ This document specifies a function to request permission to use powerful features on the Web platform.
開発者が~Web~APIを利用する意図を通達する仕方は、 ~APIごとに まちまちである： ◎ Different Web APIs have disparate ways to signal a developer’s intent to use them:
- `notifications$r ~APIは、［ 許可を要請すること，許可~状態sを明示的に検査すること ］を開発者に許容する。 ◎ The [notifications] API allows developers to request a permission and check the permission status explicitly.
- `geolocation-API$r は、 許可~要請を所在~要請に伴わせる。 ◎ The [geolocation-API] conflates the permission request with a location request.
開発者にとっては、 すべての`強力な特能$が従うべき単独の~patternがあった方が， 自身の［ 許可に関係する~code ］を設計することは もっと容易になる。 ◎ It’s easier for developers to design their permission-related code if they have a single pattern to follow for all powerful features.
2. 要請~API
partial interface `Permissions$I {
`Promise$<`PermissionStatus$I> `request$m(`object$ %permissionDesc);
};
`request(permissionDesc)@m ~method手続きは： ◎ When the request(permissionDesc) method is invoked, the user agent MUST run the following algorithm, passing the parameter permissionDesc:
- %記述子~obj ~LET %permissionDesc が指す【~JS】~obj ◎ ↓
-
%根~記述子 ~LET `~IDL値に変換する$( %記述子~obj, `PermissionDescriptor$I )
例外が投出されたときは、 ~catchして ⇒ ~RET `却下される~promise$( その例外 )
◎ Let rootDesc be the object permissionDesc refers to, converted to an IDL value of type PermissionDescriptor. If this throws an exception, return a promise rejected with that exception and abort these steps. - %特能 ~LET %根~記述子 で`識別される特能$
-
%有型~記述子 ~LET `~IDL値に変換する$( %記述子~obj, %特能 の`許可~記述子~型$ )
例外が投出されたときは、 ~catchして ⇒ ~RET `却下される~promise$( その例外 )
◎ Let typedDescriptor be the object permissionDesc refers to, converted to an IDL value of rootDesc.name’s permission descriptor type. If this throws an exception, return a promise rejected with that exception and abort these steps. - %~promise ~LET `新たな~promise$ ◎ Let promise be a newly-created Promise.
-
この段は`並列的$に遂行する： ◎ Return promise and continue the following steps asynchronously.
- %状態s ~LET `許可~状態sを作成する$( %有型~記述子 ) ◎ Run the steps to create a PermissionStatus for typedDescriptor, and let status be the result.
-
%特能 用の`許可~要請~algo$( %有型~記述子, %状態s ) ◎ Run the permission request algorithm of the feature named typedDescriptor.name with typedDescriptor and status as arguments.
例外が投出されたときは、 ~catchして ⇒＃ `~promiseを却下する$( %~promise, その例外 )； ~RET ◎ If the previous step threw an exception, reject promise with that exception.
- `~promiseを解決する$( %~promise, %状態s ) ◎ Otherwise resolve promise with status.
- ~RET %~promise ◎ ↑
3. 許可~registry内の追加的な~field
`許可~registry$を成す各`強力な特能$は、 `許可~要請~algo@ を追加的に定義してもヨイ — それは： ◎ Powerful features in the Permission Registry additionally define a permission request algorithm:
- ( `許可~記述子~型$を成す~instance %記述子, `許可~結果型$の~instance %結果 ) を入力にとるとする。 ~call元は、 %結果 に新たな~instanceを与えるとする。 【必要なら。この~algoは %結果 を改変し得るので。】 ◎ Input • An instance of the permission descriptor type • A newly-created instance of the permission result type.
- 次のように挙動するとする ⇒ %記述子 を`利用する許可を要請する$【！~PERMISSIONS#requesting-more-permission$】ことにより，もっと許可を増やすよう試行するために必要yな~promptを利用者に示した上で、 その結果に合致するよう %結果 を更新する ◎ Behavior • Uses the algorithms in Requesting more permission to show the user any necessary prompt to try to increase permissions, and updates the instance of the permission result type to match.
- 値を返さないとするが、 当の要請が例外的に失敗し得る場合には，例外を投出してもヨイ （単に許可が否認されるだけでは、 例外的とは言えない）。 ◎ Returns • Nothing, but may throw an exception if the request can fail exceptionally. (Merely being denied permission is not exceptional.) ◎ ↓↓ Example callers • Permissions.request(permissionDesc)
- 未指定な場合の既定は、 `既定の許可~要請~algo$になるとする。 ◎ Default • If unspecified, this defaults to the default permission request algorithm.
`許可~要請~algo$は、 例えば， `Permissions$I の `request()$m ~methodから~callされる。 ◎ ↑↑
3.1. 既定の要請~algo
`既定の許可~要請~algo@ は、 所与の ( `PermissionDescriptor$I %許可~記述子, `PermissionStatus$I %状態s ) に対し， 次の手続きを走らす： ◎ The default permission request algorithm, given a PermissionDescriptor permissionDesc and a PermissionStatus status, runs the following steps:
- `既定の許可を~queryする~algo$( %許可~記述子, %状態s ) ◎ Run the default permission query algorithm on permissionDesc and status.
- ~IF［ %状態s[ "`state^c" ] ~NEQ `prompt$l ］ ⇒ ~RET ◎ If status.state is not "prompt", abort these steps.
- `利用する許可を要請する$( %許可~記述子 ) ◎ Request permission to use permissionDesc.
-
`既定の許可を~queryする~algo$( %許可~記述子, %状態s ) ◎ Run the default permission query algorithm again on permissionDesc and status.
許可を`環境~設定群~obj$の中に持続的に格納しない~browser上では， これは常に `prompt$l を返すことになるが、 それでも，利用者に不必要な~promptを示す。 それは，適切な~obj能力を決して返せないので、［ どの許可も`既定の許可~要請~algo$を利用するべきでない ］ことを意味するであろう。 ◎ On browsers that don’t store permissions persistently within an environment settings object, this will always return "prompt", but still show the user an unnecessary prompt. That may mean that no permissions should use the default permission request algorithm, since it can never return an appropriate object-capability.
4. ~securityの考慮点
~securityの考慮点として識別されたものは無い。 ◎ No security considerations have been identified.
5. ~privacyの考慮点
~privacyの考慮点として識別されたものは無い。 ◎ No privacy considerations have been identified.