diff --git a/index.html b/index.html index 14a1ab6..ec0d1a3 100644 --- a/index.html +++ b/index.html @@ -305,176 +305,6 @@

-
-

- Reading the current permission state -

-

- To get the current - permission state, given a [=powerful feature/name=] |name| and an optional - [=environment settings object=] |settings|: -

-
    -
  1. Let |descriptor:PermissionDescriptor| be a newly-created {{PermissionDescriptor}} - whose {{PermissionDescriptor/name}} is initialized with |name|. -
    2. -
  2. Return the [=permission state=] of |descriptor| and |settings|. -
    3. -
-

- A |descriptor|'s permission state for an - optional environment settings object |settings| is the result of the following - algorithm, which returns one of {{PermissionState/"granted"}}, - {{PermissionState/"prompt"}}, or {{PermissionState/"denied"}}: -

-
    -
  1. If |settings| wasn't passed, set it to the [=current settings object=]. -
    2. -
  2. If |settings| is a non-secure context, return {{PermissionState/"denied"}}. -
    3. -
  3. If there exists a [=policy-controlled feature=] identified by |descriptor|'s - {{PermissionDescriptor/name}} and |settings| has an associated `Document` named - document, run the following step: -
      -
    1. If document is not allowed to use the feature identified by - |descriptor|'s {{PermissionDescriptor/name}} return {{PermissionState/"denied"}}. -
      2. -
    -
    4. -
  4. If there was a previous invocation of this algorithm with the same |descriptor| and - |settings|, returning |previousResult|, and the UA has not received new information - about the user's intent since that invocation, return |previousResult|. -
    5. -
  5. Return whichever of the following options most accurately reflects the user's intent - for the calling algorithm, taking into account any [=powerful feature/permission state - constraints=] for |descriptor|'s {{PermissionDescriptor/name}}: -
    -
    - succeed without prompting the user -
    -
    - {{PermissionState/"granted"}} -
    -
    - show the user a prompt to decide whether to succeed -
    -
    - {{PermissionState/"prompt"}} -
    -
    - fail without prompting the user -
    -
    - {{PermissionState/"denied"}} -
    -
    -
    6. -
- -

- As a shorthand, a {{PermissionName}} |name|'s permission state is the - permission state of a {{PermissionDescriptor}} with its - {{PermissionDescriptor/name}} member set to |name|. -

-
-
-

- Requesting permission to use a powerful feature -

-

- Spec authors, please note that algorithms in this section can wait for user input; so - they shouldn't be used from other algorithms running on the main thread. -

-

- To request permission to use a |descriptor|, the UA must perform the - following steps. This algorithm returns either {{PermissionState/"granted"}} or - {{PermissionState/"denied"}}. -

-
    -
  1. Let current state be the |descriptor|'s permission state. -
    2. -
  2. If current state is not {{PermissionState/"prompt"}}, return current - state and abort these steps. -
    3. -
  3. Ask the user for express permission for the calling algorithm to use the - powerful feature described by |descriptor|. -
    4. -
  4. If the user grants permission, return {{PermissionState/"granted"}}; otherwise return - {{PermissionState/"denied"}}. The user's interaction may provide new information about - the user's intent for this [=global object/realm=] and other [=global object/realms=] - with the same origin. -

    - This is intentionally vague about the details of the permission UI and how the UA - infers user intent. UAs should be able to explore lots of UI within this framework. -

    -
    5. -
-

- As a shorthand, requesting permission to use a {{PermissionName}} |name|, is the - same as requesting permission to use a {{PermissionDescriptor}} with its - {{PermissionDescriptor/name}} member set to |name|. -

-
-
-

- Prompt the user to choose -

-

- To prompt the user to choose one of several |options| associated with a - |descriptor|, the UA must perform the following steps. This algorithm returns either - {{PermissionState/"denied"}} or one of the options. -

-
    -
  1. If |descriptor|'s permission state is {{PermissionState/"denied"}}, return - {{PermissionState/"denied"}} and abort these steps. -
    2. -
  2. If |descriptor|'s permission state is {{PermissionState/"granted"}}, the UA - may return one of |options| and abort these steps. If the UA returns without prompting, - then subsequent prompts for the user to choose - from the same set of options with the same |descriptor| must return the same option, - unless the UA receives new information about the user's intent. -
    3. -
  3. Ask the user to choose one of the options or deny permission, and wait for them to - choose. If the calling algorithm specified extra information to include in the prompt, - include it. -
    4. -
  4. If the user chose an option, return it; otherwise return - {{PermissionState/"denied"}}. If the user's interaction indicates they intend this choice - to apply to other realms, then treat this this as new information about the user's - intent for other [=global object/realms=] with the same origin. -

    - This is intentionally vague about the details of the permission UI and how the UA - infers user intent. UAs should be able to explore lots of UI within this framework. -

    -
    5. -
-

- As a shorthand, prompting the user to choose from options associated with a - {{PermissionName}} |name|, is the same as prompting the user to choose from those - options associated with a {{PermissionDescriptor}} with its {{PermissionDescriptor/name}} - member set to |name|. -

-
-
-

- Reacting to users revoking permission -

-

- When the UA learns that the user no longer intends to grant permission for a [=global - object/realm=] to use a feature, react to the user revoking permission - by: -

-
    -
  1. - Queue a task on the Realm's [=Realm/settings object=]'s [=environment settings - object/responsible event loop=] to run that feature's [=powerful feature/permission - revocation algorithm=]. -
    2. -
-

@@ -675,6 +505,181 @@

of the above types and algorithms defaulted.

+
+

+ Algorithms to interface with permissions +

+
+

+ Reading the current permission state +

+

+ To get the current + permission state, given a [=powerful feature/name=] |name| and an optional + [=environment settings object=] |settings|: +

+
    +
  1. Let |descriptor:PermissionDescriptor| be a newly-created {{PermissionDescriptor}} + whose {{PermissionDescriptor/name}} is initialized with |name|. +
    2. +
  2. Return the [=permission state=] of |descriptor| and |settings|. +
    3. +
+

+ A |descriptor|'s permission state for an + optional environment settings object |settings| is the result of the following + algorithm, which returns one of {{PermissionState/"granted"}}, + {{PermissionState/"prompt"}}, or {{PermissionState/"denied"}}: +

+
    +
  1. If |settings| wasn't passed, set it to the [=current settings object=]. +
    2. +
  2. If |settings| is a non-secure context, return {{PermissionState/"denied"}}. +
    3. +
  3. If there exists a [=policy-controlled feature=] identified by |descriptor|'s + {{PermissionDescriptor/name}} and |settings| has an associated `Document` named + document, run the following step: +
      +
    1. If document is not allowed to use the feature identified by + |descriptor|'s {{PermissionDescriptor/name}} return {{PermissionState/"denied"}}. +
      2. +
    +
    4. +
  4. If there was a previous invocation of this algorithm with the same |descriptor| and + |settings|, returning |previousResult|, and the UA has not received new information + about the user's intent since that invocation, return |previousResult|. +
    5. +
  5. Return whichever of the following options most accurately reflects the user's intent + for the calling algorithm, taking into account any [=powerful feature/permission state + constraints=] for |descriptor|'s {{PermissionDescriptor/name}}: +
    +
    + succeed without prompting the user +
    +
    + {{PermissionState/"granted"}} +
    +
    + show the user a prompt to decide whether to succeed +
    +
    + {{PermissionState/"prompt"}} +
    +
    + fail without prompting the user +
    +
    + {{PermissionState/"denied"}} +
    +
    +
    6. +
+ +

+ As a shorthand, a {{PermissionName}} |name|'s permission state is the + permission state of a {{PermissionDescriptor}} with its + {{PermissionDescriptor/name}} member set to |name|. +

+
+
+

+ Requesting permission to use a powerful feature +

+

+ Spec authors, please note that algorithms in this section can wait for user input; so + they shouldn't be used from other algorithms running on the main thread. +

+

+ To request permission to use a |descriptor|, the UA must perform the + following steps. This algorithm returns either {{PermissionState/"granted"}} or + {{PermissionState/"denied"}}. +

+
    +
  1. Let current state be the |descriptor|'s permission state. +
    2. +
  2. If current state is not {{PermissionState/"prompt"}}, return current + state and abort these steps. +
    3. +
  3. Ask the user for express permission for the calling algorithm to use the + powerful feature described by |descriptor|. +
    4. +
  4. If the user grants permission, return {{PermissionState/"granted"}}; otherwise return + {{PermissionState/"denied"}}. The user's interaction may provide new information about + the user's intent for this [=global object/realm=] and other [=global object/realms=] + with the same origin. +

    + This is intentionally vague about the details of the permission UI and how the UA + infers user intent. UAs should be able to explore lots of UI within this framework. +

    +
    5. +
+

+ As a shorthand, requesting permission to use a {{PermissionName}} |name|, is the + same as requesting permission to use a {{PermissionDescriptor}} with its + {{PermissionDescriptor/name}} member set to |name|. +

+
+
+

+ Prompt the user to choose +

+

+ To prompt the user to choose one of several |options| associated with a + |descriptor|, the UA must perform the following steps. This algorithm returns either + {{PermissionState/"denied"}} or one of the options. +

+
    +
  1. If |descriptor|'s permission state is {{PermissionState/"denied"}}, return + {{PermissionState/"denied"}} and abort these steps. +
    2. +
  2. If |descriptor|'s permission state is {{PermissionState/"granted"}}, the UA + may return one of |options| and abort these steps. If the UA returns without prompting, + then subsequent prompts for the user to choose + from the same set of options with the same |descriptor| must return the same option, + unless the UA receives new information about the user's intent. +
    3. +
  3. Ask the user to choose one of the options or deny permission, and wait for them to + choose. If the calling algorithm specified extra information to include in the prompt, + include it. +
    4. +
  4. If the user chose an option, return it; otherwise return + {{PermissionState/"denied"}}. If the user's interaction indicates they intend this choice + to apply to other realms, then treat this this as new information about the user's + intent for other [=global object/realms=] with the same origin. +

    + This is intentionally vague about the details of the permission UI and how the UA + infers user intent. UAs should be able to explore lots of UI within this framework. +

    +
    5. +
+

+ As a shorthand, prompting the user to choose from options associated with a + {{PermissionName}} |name|, is the same as prompting the user to choose from those + options associated with a {{PermissionDescriptor}} with its {{PermissionDescriptor/name}} + member set to |name|. +

+
+
+

+ Reacting to users revoking permission +

+

+ When the UA learns that the user no longer intends to grant permission for a [=global + object/realm=] to use a feature, react to the user revoking permission + by: +

+
    +
  1. + Queue a task on the Realm's [=Realm/settings object=]'s [=environment settings + object/responsible event loop=] to run that feature's [=powerful feature/permission + revocation algorithm=]. +
    2. +
+
+

Permissions API