Vibration API

Table of Contents

• 1. Introduction
• 2. Conformance
• 3. Terminology
• 4. Vibration Interface
• 5. Examples
• A. Acknowledgements
• B. References
  • B.1 Normative references
  • B.2 Informative references

2. Conformance

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 words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this specification are to be interpreted as described in [RFC2119].

This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.

Implementations that use ECMAScript to implement the APIs defined in this specification must implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [WEBIDL], as this specification uses that specification and terminology.

3. Terminology

The concepts browsing context and spin the event loop are defined in [HTML5].

4. Vibration Interface

partial interface Navigator {
    boolean vibrate ((unsigned long or sequence<unsigned long>) pattern);
};

The vibrate() method, when invoked, MUST run the algorithm for processing vibration patterns.

The rules for processing vibration patterns are as given in the following algorithm:

1. Let pattern be the value of the first argument.
2. If pattern is a list, proceed to the next step. Otherwise run the following substeps:
   1. Let list be an initially empty list, and add pattern to list.
   2. Set pattern to list.
3. If the length of pattern exceeds an implementation-dependent limit, then return false and terminate these steps.
4. If the length of pattern is even and is not zero, then remove the last entry in pattern.
5. If any entry of pattern exceeds an implementation-dependent limit, then return false and terminate these steps.
6. If the hidden attribute [PAGE-VISIBILITY] is set to true, then return false and terminate these steps.
   Note

   A trusted (also known as privileged) application that integrates closely with the operating system's functionality may vibrate the device even if such an application is not visible at all, and thus may ignore the previous step.
7. An implementation MAY return false and terminate these steps.
   Note

   For example, an implementation might abort the algorithm because the user has set a preference indicating that pages at a given origin should never be able to vibrate the device, or an implementation might cap the total amount of time a page may cause the device to vibrate and reject requests in excess of this limit.
8. Cancel the pre-existing instance of the processing vibration patterns algorithm, if any.
9. If pattern is an empty list, or if the device does not provide a vibration mechanism (or it is disabled), then return true and terminate these steps.
10. Return true, and then continue running these steps asynchronously.
11. For each time in pattern, run the following substeps:
    1. If the index of time is even (the first entry has index 0), vibrate the device for time milliseconds.
    2. Otherwise wait for time milliseconds.

When the visibilitychange event [PAGE-VISIBILITY] is dispatched at the Document in a browsing context, the user agent MUST cancel the pre-existing instance of the processing vibration patterns algorithm, if any.