Table of Contents

• 1. Introduction
• 2. Conformance
• 3. Terminology
• 4. Security and privacy considerations
• 5. Navigator Interface
  • 5.1 Attributes
• 6. Vehicle Interface
• 7. Zone Interface
  • 7.1 Attributes
  • 7.2 Methods
• 8. VehicleInterfaceCallback Callback
• 9. AvailableCallback Callback
• 10. VehicleInterfaceError Interface
  • 10.1 Attributes
• 11. VehicleInterface Interface
  • 11.1 Attributes
  • 11.2 Methods
• 12. VehicleConfigurationInterface Interface
• 13. VehicleSignalInterface Interface
  • 13.1 Methods
• 14. Data Availability
  • 14.1 Attributes
  • 14.2 Methods
  • 14.3 Methods
• 15. History
  • 15.1 Attributes
  • 15.2 Attributes
  • 15.3 Attributes
  • 15.4 Methods
• 16. Use-Cases
• A. References
  • A.1 Normative 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 and OPTIONAL 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 Promise provide a convenient way to get access to the result of an operation.

4. Security and privacy considerations

It is expected that security of vehicle APIs described in this document is based on permissions dictated by:

• The JavaScript runtime under which the APIs are used – in some cases
• The underlying operating system – always

No separate permission or access control model will be defined for vehicle APIs. Depending on a specific platform, the user agent used may have to provide tools to generate permissions for application descriptors as required by the OS. Android is an example under which such a descriptor (Android app manifest) has to be generated if the runtime maps its apps to OS-level apps.

5. Navigator Interface

partial interface Navigator {
    readonly        attribute Vehicle vehicle;
};

6. Vehicle Interface

The Vehicle interface represents the initial entry point for getting access to the vehicle information services, i.e. Engine Speed and Tire Pressure.

[NoInterfaceObject]
interface Vehicle {
};

7. Zone Interface

The Zone interface contains the constants that represent physical zones and logical zones

enum ZonePosition {
    "front",
    "center",
    "rear",
    "left",
    "middle",
    "right",
    "top",
    "central",
    "bottom"
};

interface Zone {
                    attribute ZonePosition[] value;
    readonly        attribute Zone           driver;
    boolean equals (Zone zone);
    boolean contains (Zone zone);
};

8. VehicleInterfaceCallback Callback

The VehicleInterfaceCallback

callback VehicleInterfaceCallback = void (Object value) ();

9. AvailableCallback Callback

The AvailableCallback

callback AvailableCallback = void (Availability available) ();

10. VehicleInterfaceError Interface

VehicleInterfaceError is used to identify the type of error encountered during an operation

enum VehicleError {
    "permission_denied",
    "invalid_operation",
    "timeout",
    "invalid_zone",
    "unknown"
};

[NoInterfaceObject]
interface VehicleInterfaceError {
    readonly        attribute VehicleError error;
    readonly        attribute DOMString    message;
};

11. VehicleInterface Interface

The VehicleInterface interface represents the base interface to get all vehicle properties.

interface VehicleInterface {
    Promise get (optional Zone zone);
    readonly        attribute Zone[] zones;
};

vehicle.vehicleSpeed.get().then(resolve);

function resolve(data) {
  // data is of type VehicleSpeed
  console.log("Speed: " + data.speed);
  console.log("Time Stamp: " + data.timestamp);
}

12. VehicleConfigurationInterface Interface

The VehicleConfigurationInterface interface is to be used to provide access to static vehicle information that never changes, e.g. external dimensions, identification or transmission type.

[NoInterfaceObject]
interface VehicleConfigurationInterface : VehicleInterface {
};

13. VehicleSignalInterface Interface

The VehicleSignalInterface interface represents vehicle signals that, as a rule, and unlike vehicle configurations, can change values, either programmatically (necessitating support for set method) or due to external events and occurrences, as reflected by subscription management.

[NoInterfaceObject]
interface VehicleSignalInterface : VehicleInterface {
    Promise        set (object value, optional Zone zone);
    unsigned short subscribe (VehicleInterfaceCallback callback, optional Zone zone, optional unsigned long period);
    void           unsubscribe (unsigned short handle);
};

var zone = Zone
vehicle.door.set({"lock" : true}, zone.driver).then(resolve, reject);

function resolve() {
  console.log("Successfully set");
}

function reject(errorData) {
  console.log("Error occurred during set: " + errorData.message + " code: " + errorData.error);
}

14. Data Availability

The availability API allows for developers to determine what attributes are available or not and if not, why. It also allows for notifications when the availability changes.

enum Availability {
    "available",
    "not_supported",
    "not_supported_yet",
    "not_supported_security_policy",
    "not_supported_business_policy",
    "not_supported_other"
};

partial interface VehicleInterface {
    Availability availableForRetrieval (DOMString attributeName);
    readonly        attribute boolean supported;
    short        availabilityChangedListener (AvailableCallback callback);
    void         removeAvailabilityChangedListener (short handle);
};

var speedAvailability = vehicle.vehicleSpeed.availableForRetrieval("speed");

if (speedAvailability === "available") {
  console.log("Vehicle speed available for use");
}
else {
  console.log("Vehicle speed unavailable: " + speedAvailability);
}

partial interface VehicleSignalInterface {
    Availability availableForSubscription (DOMString attributeName);
    Availability availableForSetting (DOMString attributeName);
};

var speedSubscribable = vehicle.vehicleSpeed.availableForSubscription("speed") === "available";

vehicle.vehicleSpeed.availabilityChangedListener(function (available) {
  speedSubscribable = available === "available";
  checkVehicleSpeed();
});

function checkVehicleSpeed() {
  if (speedSubscribable) {
    vehicle.vehicleSpeed.get().then(callback);
  }
}

15. History

The History API provides a way for applications to access logged data from the vehicle. What data is available and how much is up to the implementation. This section is OPTIONAL.

interface HistoryItem {
    readonly        attribute any          value;
    readonly        attribute DOMTimeStamp timestamp;
};

partial interface VehicleInterface {
    readonly        attribute History? history;
};

interface History {
    Promise get (Date begin, Date end, optional Zone zone);
    readonly        attribute boolean isLogged;
    readonly        attribute Date?   from;
    readonly        attribute Date?   to;
};

// check if there is data being logged for vehicleSpeed
if (vehicle.vehicleSpeed.history.isLogged) {
  // get all vehicleSpeed since it was first logged
  vehicle.vehicleSpeed.history.get(
    vehicle.vehicleSpeed.history.from, 
    vehicle.vehicleSpeed.history.to
  ).then(function (data) {
    console.log(data.length);
  });
}