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",
    "middle",
    "right",
    "left",
    "rear",
    "center"
};

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: external dimensions, identification, transmission type etc...

[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);
    void           unsubscribe (unsigned short handle);
};

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

function resolve()
{
  /// success
}

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);
};

if( ( var a = vehicle.vehicleSpeed.availableForRetrieval("speed") ) === "available" )
{
  // we can use it.
}
else
{
  // tell us why:
  console.log(a);
}

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

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

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

function checkVehicleSpeed()
{
  if(canHasVehicleSpeed)
  {
    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);
  });
}