Ambient Humidity Events

Unofficial Draft

Latest editor's draft:
http://dvcs.w3.org/hg/dap/raw-file/tip/humidity/Overview.html
Editors:
Marcos Cáceres (W3C Invited Expert)
Balaji N.V (Samsung Electronics)

This document is licensed under a Creative Commons Attribution 4.0 License.

Abstract

This specification defines a means to receive events that correspond to changes in ambient humidity.

Status of This Document

This document is draft of a potential specification. It has no official standing of any kind and does not represent the support or consensus of any standards organization.

Introduction

The AmbientHumidityEvent interface provides web developers information about the ambient humidity levels near the hosting device.

This is achieved by interrogating a humidistat or similar detectors of a device.

Use Cases

TBW

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 word MUST in this document is to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

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

Terminology

The EventHandler interface represents a callback function used for event handlers as defined in [HTML5].

The concepts queue a task and fires a simple event are defined in [HTML5].

The terms event handlers and event handler event types are defined in [HTML5].

The concepts create an event and fire an event are defined in [DOM4].

The current humidity is a value that represents the ralative humidity expressed as a value between 0 and 1 (e.g., 0.533, which equates to 53.3% humidity).

Security and privacy considerations

Humidity

The HTML5 specification [HTML5] defines a Window interface, which this specification extends:

attribute EventHandler onhumidity

The onhumidity event handler and its corresponding event handler event type ambienthumidity MUST be supported as an IDL attribute by all objects implementing the Window interface.

AmbientHumidityEvent Interface

readonly attribute double value
The current ambient humidity.
double value

When a user agent is required to fire an ambient humidity event, the user agent MUST run the following steps:

  1. Create an event that uses the AmbientHumidityEvent interface, with the name ambienthumidity, which bubbles, is not cancelable, and has no default action, that also meets the following conditions:
    1. If the implementation is unable to report the current ambient humidity, initialize the value attribute to positive Infinity, otherwise initialize the attribute to the current ambient humidity.
  2. Queue a task to dispatch the newly created event at the Window object.

When the current humidity changes, the user agent MUST fire a ambient humidity event.

Note
The definition of granularity i.e. how often the event is fired is left to the implementation. Implementations may fire the event if they have reason to believe that the page does not have sufficiently fresh data.

Event handlers

The following are the event handlers (and their corresponding event handler event types) that MUST be supported as attributes by the Window object:

event handler event handler event type
onhumidity ambienthumidity