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 SHOULD are to be interpreted as described in [RFC2119].

3. Terminology

The term 'VISS' is used to refer to the 'Vehicle Information Service Specification' (see here) which is in the process of developed in W3C Automotive Working Group along with this specification. The term 'VIS Server' is used to refer to a server which conforms to the 'VISS' specification.

The term 'VIAS' is used to refer to the 'Vehicle Information API Specification' which is this document.

The term 'VSS' is used to refer to the 'Vehicle Signal Specification' (see here) which is defined in Genivi alliance activity.

The term 'WebSocket' when used in this document, is as defined in the W3C WebSocket API (see here) and the WebSocket Protocol (see RFC6455).

4. Security and Privacy Considerations

This specification defines an interface to the underling server and does not expose any platform capabilities by itself. The underling server is responsible for managing privileges of each client connection and the VIAS implementation is responsible for passing requests and responses securely between clients and the server.

One of possible implementation methods of VIAS would be as a form of JavaScript library.
In that case, as a necessary security consideration, the JavaScript library SHOULD be provided from a trusted origin. Otherwise a malicious library could be loaded instead and any data goes through the library could be eavesdropped or tampered. Authorization tokens may goes through the library as well and if token leaking happens, security of the underlying server could be damaged. The underlying server itself should be considered as one of trusted origins from the VIAS JavaScript library implementation.

Some part of vehicle data is considered as privacy sensitive and client programs SHOULD treat these data with respect to the user's right. As a privacy protection enforcer, the VIAS implementation MUST obtain user's permision for exposing vehicle data to a client program. If the implementation have an exceptional behavior to treat private information in emergent cases, the behavior also SHOULD be covered by the permission.

5. VISClient Interface

[Constructor(optional VISClientOptions options)]
interface VISClient {
    readonly attribute DOMString?      host;
    readonly attribute DOMString?      protocol;
    readonly attribute unsigned short? port;

    void            connect(ConnectCallback connectCallback,
                            ErrorCallback errorCallback);
    void            authorize(object tokens,
                              AuthorizeCallback authorizeCallback,
                              ErrorCallback errorCallback);
    void            getVSS(DOMString path,
                           GetVSSCallback getVSSCallback,
                           ErrorCallback errorCallback);
    void            get(DOMString path,
                        GetCallback getCallback,
                        ErrorCallback errorCallback);
    void            set(DOMString path,
                        any value,
                        SetCallback setCallback,
                        ErrorCallback errorCallback);
    VISSubscription subscribe(DOMString path,
                              SubscriptionCallback subscriptionCallback,
                              ErrorCallback errorCallback,
                              optional SubscribeFilters filters);
    void            unsubscribe(VISSubscription subscription,
                                UnsubscribeCallback unsubscribeCallback,
                                ErrorCallback errorCallback);
    void            unsubscribeAll(UnsubscribeCallback unsubscribeCallback,
                                   ErrorCallback errorCallback);
    void            disconnect(DisconnectCallback disconnectCallback,
                               ErrorCallback errorCallback);
};

interface VISClientOptions {
    attribute DOMString?      host;
    attribute DOMString?      protocol;
    attribute unsigned short? port;
};

interface VISValue {
    attribute any          value;
    attribute DOMTimeStamp timeStamp;
};

interface VISError {
    attribute unsigned short number;
    attribute DOMString?     reason;
    attribute DOMString?     message;
    attribute DOMTimeStamp   timeStamp;
};

Constructor

The VISClient constructor, when invoked, must return a new VISClient object.
This constructor takes VISClientOptions object as a parameter. The parameter is optional and the necessity depends on underlying communication type.

const client = new VISClient({ /* VISClientOptions object */ });

VISClientOptions Interface

VISClientOptions interface is designed assuming a connection to a vehicle signal server which is specifiable by protocol, host and port. In case the underlying connection requires other parameters, implementer can add parameters according to the requirement.
These values are set at initialization only and cannot be changed after a connection has established.

Methods

Once created, a client provides several functions for interacting with the server.

Many of the functions listed below require a `path` string to be passed that identifies the portion of the VSS that is being referenced. See VSS below for how to generate this string based on traversing the VSS tree.

callback ConnectCallback = void ();

callback DisconnectCallback = void ();

callback ErrorCallback = void (VISError error);

callback AuthorizeCallback = void (unsigned long TTL);

callback GetVSSCallback = void (VSS vss);

callback GetCallback = void (VISValue value);

callback SetCallback = void ();

callback SubscriptionCallback = void (VISValue value);

callback UnsubscribeCallback = void ();

VISValue Interface

VISValue conveys a vehicle signal or attribute value.

VISError Interface

Error number, reason, message represents both of client-side and server-side error. Server-side error difinition depends on underlying server. Client-side error definition is implementation dependent and not defined in this document.

Example

const client = new VISClient({
  host: 'wwwivi',
  protocol: 'wss',
  port: 443,
});

const connectCallback = () => {
  console.log(`Connected to ${client.protocol}://${client.host}:${client.port}`);
  client.authorize(/* TOKEN */, (ttl) => {
    console.log(`Authorize succeeded. TTL: ${ttl}`);

    /* do other things here */
  }, (err) => {
    console.err('Authorize failed with provided token.');
    return;
  })
};

const errorCallback = (error) => {
  console.err(`Error : ${error.number}`);
};

client.connect(connectCallback, errorCallback);

6. VISSubscription Interface

[Constructor]
interface VISSubscription {
    readonly attribute DOMString            path;
    readonly attribute VISSubscribeFilters? filters;
};

interface VISSubscribeFilters {
    attribute unsigned long?     interval;
    attribute VISSubscribeRange? range;
    attribute unsigned long?     minChange;
};

interface VISSubscribeRange {
    attribute long? below;
    attribute long? above;
};

The VISSubscription object is obtained as return value of the subscribe() method. Once created the object can be used to access the original options and to pass to the unsubscribe() method. The Subscription object does not expose any functions directly, but contains the following properties:

VISSubscriptions are immutable once created.

Example

const client = new VISClient({ host: 'wwwivi' });

const connectCallback = () => {
  const filters = {
    interval: 100,
    range: { above: 100, below: 200 },
    minChange: 50
  };

  var subscription = client.subscribe('body.mirrors.left', (val) => {
    if (val) {
      console.log(`Value received: ${val}`);
    }

    /* ... after some time or some event, unsubscribe from the subscription: */
    client.unsubscribe(subscription, () => {
      console.log(`Unsubscribe succeeded`);
    }, (err) => {
      if (err) {
        console.err(`Error while unsubscribing: ${err.number}`);
      }
    });
  }, (err) => {
      console.err(`Error while subscribing: ${err.number}`);
  }, filters);
};

client.connect(connectCallback);

7. VSS Interface

[Constructor]
interface VSS {
    sequence<DOMString> pathsByCSS(DOMString cssSelector);
    boolean             pathExistsByCSS(DOMString cssSelector);
    boolean             canGet(DOMString path);
    boolean             canSet(DOMString path);
    object              at(DOMString? path);
};

The VSS object returned by the getVSS() method above should provide APIs sufficient to fully traverse the VSS tree and determine what signals are available at the current permission level. Traversing the VSS tree can be accomplished using any of a number of query languages (i.e. CSS path selectors, XPath, etc.); CSS-based querying is shown in the functions below, but additional query languages may be added in the future. It is out of scope here to define the exact traversal methods and feature set, but these function SHOULD follow standards protocols such as CSS or XPATH.

Example

const client = new VISClient({
  host: 'wwwivi',
});

const openWindow = () => {
  client.getVSS('Signal.Cabin' ,(vss) => {
    const paths = vss.pathsByCSS('Row1 Left Window > Position');
    if (!paths.length) {
      console.err('Could not find front-left window in VSS');
      return;
    }

    if (vss.canSet(paths[0])) {
      client.set(paths[0], 0, () => {
        console.log(`Set window ${paths[0]} to open succeeded`);
      }, (err) => {
        console.err(`Set window ${paths[0]} to open failed: ${err.number}`);
      });
    } else {
      console.err('Not authorized to open front-left window');
    }
  }, (err) => {
      console.err(`Error while getVSS: ${err.number}`);
  });
}

client.connect(openWindow);