Webinos Logo

Discovery API

Webinos API Specifications

5 Sep 2012

Authors


Abstract

The Webinos Discovery API provide web applications with an API to discover services without any previous knowledge of the service.

Table of Contents

  1. Introduction
  2. Interfaces and Dictionaries
    1. DiscoveryInterface
    2. ServiceType
    3. FindCallBack
    4. Service
    5. BindCallBack
    6. Options
    7. Filter
    8. ServiceLocation
    9. PendingOperation
    10. Webinos
  3. Enums
    1. ServiceState
  4. Features
  5. Full WebIDL

Summary of Methods

Interface Method
DiscoveryInterface PendingOperation findServices(ServiceType serviceType, FindCallBack findCallBack, Options options, Filter filter)
DOMString getServiceId(DOMString serviceType)
FindCallBack void onFound(Service service)
void onLost(Service service)
void onError(DOMError error)
Service void bind(BindCallBack bindCallBack, DOMString serviceId)
void unbind()
BindCallBack void onBind(Service service)
void onUnbind(Service service)
void onServiceAvailable(Service service)
void onServiceUnavailable(Service service)
void onError(DOMError error)
PendingOperation void cancel()
Webinos

Introduction

The Discovery API is not limited to discovery of local services but also enables discovery of remote services.

The API enables discovery of services that is exposed either:

1. in the device
2. by entities directly connected to the device,
3. by entities available on the same local IP network
4. by trusted services registered in a personal zone.

Once a service is found the API will provide a service object that is used to bind to a service and monitor the availability of the service. The binding to a service will make sure that the user is authorized to use the service, create an implementation of the API and establish a communication path to the remote peer providing the service. The service object hides the complexity of communicating over different bearers, do cross network addressing, traversing NAT/Firewalls and connection management.

Prerequisites for the Discovery API is that the web application using the API is installed, trusted and that the user of of the device is authenticated and authorized to use the API.

Interfaces and Dictionaries

Interface DiscoveryInterface

The DiscoveryInterface interface provides functionality for discovery of services. The API supports the possibility to discover services based on a given service type either in a personal zone of trusted services or via other legacy discovery methods such as Bluetooth SD, DNS SD, mDNS or UPnP. When searching for a service type the operation can be restricted by providing certain constraints and/or context information via a filter interface.

WebIDL
        [NoInterfaceObject] interface DiscoveryInterface  {

                 PendingOperation findServices(  
                        ServiceType serviceType, 
                        FindCallBack findCallBack, 
                        optional Options options, 
                        optional Filter filter);
                 

                 DOMString getServiceId(DOMString serviceType);
                 
        };

The code example below shows how an application initiates a search query to find a geolocation service. Whenever a service is found, a new HTML selection item is added to an HTML option list. Once the user selects a service, the usage of the service is authorized and an implementation of the API is instantiated by binding to the service.

Code example
        var findHandle = 0;
        var serviceHandle = 0;
        var geoServices = {};
        var serviceId;
        
        // Callback that displays a list of found services in a HTML selection list
        // The selection list is dynamically extended every time a new service is discovered.   
        function serviceFoundCB(service) {      
                var selectlist = document.getElementById('servicelist');
                var option = document.createElement('option');
        
                option.value = service.id;
                option.id = service.id;
                option.appendChild(document.createTextNode(service.displayName));
                geoServices[service.id] = service;
                selectlist.appendChild(option);
        }
        
        // Callback that removes a service from the selection list of found services,
        // when the service is not available any longer. 
        function serviceLostCB(service) {       
                var option = document.getElementById(service.id);
        
                geoServices[service.id] = NULL;
                option.parentNode.removeChild(option);
        }
        
        // Success callback when bind has been successfully executed on the service object. 
        function bindCB(myLocationService) {
                alert('Service ' + myLocationService.displayName + ' ready to use');
                myLocationService.navigator.geolocation.getCurrentPosition(showMap);
        }
        
        // Event listner that is called when the 'change' event is dispatched on the HTML selection list.  
        function serviceSelected(service) {     
                // Stops the findServices operation
                findHandle.cancel();
        
                // Binds to the service to initiate an authorized object used to
                // invoke services.  
                service.bind({onBind:bindCB});
        }
        
        if (serviceId) {
                // If serviceId is known, bind to the service directly. Assumes
                // that serviceId is stored persistently or received via an out
                // of band channel. 
                
                window.webinos.discovery.findServices(
                        {api:'http://www.w3.org/ns/api-perms/geolocation'}, 
                        {onFound:serviceFoundCB, onLost:serviceLostCB},
                        null,
                        {serviceID : serviceId});
                
                serviceHandle = window.webinos.discovery.findServices(
                        {api:'http://www.w3.org/ns/api-perms/geolocation'}, 
                        {onFound:serviceFoundCB, onLost:serviceLostCB},
                        null,
                        {serviceID: serviceId});
        } 
        else {
                // Initiate a search query for a service of the type geolocation
                findHandle = window.webinos.discovery.findServices(
                        {api:'http://webinos.org/api/w3c/geolocation'}, 
                        {onFound:serviceFoundCB, onLost:serviceLostCB});
        
                var selectlist = document.getElementById('servicelist');
                selectlist.addEventListener("change", function (e) {
                        var service = geoServices[e.target.value];
                        if (service) {
                                serviceSelected(service);
                        }
                }, false);      
        }
 

Methods

findServices

The findServices method initiates an asynchronous search query for services matching the requested serviceType and filter parameter. The method continues to search for services until the findServices method is canceled by the application or when the maximum search timer expires. The zones in which services are to be searched are expected to be managable by the webinos runtime.

Signature
PendingOperation findServices(ServiceType serviceType, FindCallBack findCallBack, optional Options options, optional Filter filter);
Parameters
  • serviceType
    • Optional: No.
    • Nullable: No
    • Type: ServiceType
    • Description: An input argument that defines which type of API that is requested. The serviceType is an URI that uniquely identifies the API.
  • findCallBack
    • Optional: No.
    • Nullable: No
    • Type: FindCallBack
    • Description: Callback interface used to report the outcome of the search process.
  • options
    • Optional: Yes.
    • Nullable: No
    • Type: Options
    • Description: Defines search options.
  • filter
    • Optional: Yes.
    • Nullable: No
    • Type: Filter
    • Description: Defines a filter that be used to limit the service operation to certain constraints and context information.
getServiceId

For the case that the application itself exposes functionality via JavaScript service interfaces the getServiceId method generates a service identity that can be shared with other peers to establish a binding without invoking a findServices operation. If no matching API is found the method will return Null.

Signature
DOMString getServiceId(DOMString serviceType);
Parameters
  • serviceType
    • Optional: No.
    • Nullable: No
    • Type: DOMString
    • Description: URI identifying which type of API that shall be exposed. The URI shall be must be declared in the manifest in the api-name attribute of the webinos:shared-api element.

Dictionary ServiceType

The Service Type dictionary is used to define which type of service that is requested.

WebIDL
        dictionary ServiceType {

                DOMString api;
        };

Dictionary Members

DOMString api

URI used to identify which type of API that is requested. The URI could either be:

1. webinos Feature URI that is defined for each API by Webinos, for example http://webinos.org/api/sensors.temperature,
2. webinos Feature URI for referred unchanged API specifications, for example http://webinos.org/api/w3c/geolocation,
3. an unique URI identifying an API exposed by a web application. The URI shall be the same URI as exposed by the web application manifest in the api-name attribute of the webinos:shared-api element.

Interface FindCallBack

FindCallBack interface definition

WebIDL
        callback interface FindCallBack {

                 void onFound(Service service);        
                 

                 void onLost(Service service);
                          

                 void onError(DOMError error);
                                 
        };

Methods

onFound

Asynchronous callback used whenever a new service is found.

Signature
void onFound(Service service);
Parameters
  • service
    • Optional: No.
    • Nullable: No
    • Type: Service
    • Description: An input argument representing the found service.
onLost

Asynchronous callback used whenever the state of a service change from available to unavailable.

Signature
void onLost(Service service);
Parameters
  • service
    • Optional: No.
    • Nullable: No
    • Type: Service
    • Description: An input argument representing the lost service.
onError

Asynchronous error callback.

Signature
void onError(DOMError error);
Parameters
  • error
    • Optional: No.
    • Nullable: No
    • Type: DOMError
    • Description: DOMError: of type TimeoutError if the timeout timer expired, SecurityError if not authorized to use the service, AbortError if the discovery process was canceled by the application

Interface Service

The Service interface provides an API to bind to a specific service and monitor the availability of a bound service in an asynchronous manner. The process of binding to a service involves:

1. mutual authentication between the service and the personal zone
2. in case of cross zone personal interworking, mutual authentication between the zones
3. agreement on data handling obligations as set out in the service's privacy policy
4. verifying access privileges and checks the need for elevated privileges
5. instantiate an implementation of the API that can be used by applications to request services from the requested API.

Once the service object is instantiated, the service object will act as a proxy to the remote peer that will be able to invoke methods associated with API type under the window object of the remote peer. For example an application that successfully binds to a "http://webinos.org/api/tv" API will be able to invoke methods from the remote peer as described in the code example below.

WebIDL
        [NoInterfaceObject] interface Service {

                readonly attribute ServiceState state;
                

                readonly attribute DOMString api;
                

                readonly attribute DOMString id;
                

                readonly attribute DOMString displayName;
                

                readonly attribute DOMString description;
                

                readonly attribute DOMString icon;
                

                void bind(BindCallBack bindCallBack, optional DOMString serviceId);
                

                void unbind();
        };
Code example
        succesBindCallBack(tvService) {
                // Invoke a remote method.
                tvService.webinos.tv.display.setChannel(channel, success);
                
                // Register an event listner from event orginating from the remote peer.
                tvService.addEventListener('channelchange', success);
        }  
 

Attributes

readonly ServiceState state

Current service state.

This attribute is readonly.
readonly DOMString api

API is a global unique URI identifying the type of API provided by the service.

This attribute is readonly.
readonly DOMString id

Id is a globally unique id representing the binding to the service. The id can be used to resume the binding again to the service without invoking the findServices process again. The id can be stored persistently to be able to resume a binding to a service across power cycles.

This attribute is readonly.
readonly DOMString displayName

A human readable name of the service.

This attribute is readonly.
readonly DOMString description

An URL referring to a detailed description of the service.

This attribute is readonly.
readonly DOMString icon

Icon is an URL referring to an icon that represents the service.

This attribute is readonly.

Methods

bind

bind Binds to the service uniquely identified by the service identity.

Signature
void bind(BindCallBack bindCallBack, optional DOMString serviceId);
Parameters
  • bindCallBack
    • Optional: No.
    • Nullable: No
    • Type: BindCallBack
    • Description: Asynchrounous callback to report the states of the bind operation and the availability of the service.
  • serviceId
    • Optional: Yes.
    • Nullable: No
    • Type: DOMString
    • Description: Unique id of the binding to the particular service. If no serviceId is provided as an in parameter, the id attribute in the Service interface will be used to bind the service.
unbind

unbind Releases all resources and connections allocated by the service object.

Signature
void unbind();

Interface BindCallBack

Bind success callback interface definition

WebIDL
         callback interface BindCallBack {

                 void onBind(Service service);
                 

                 void onUnbind(Service service);
                 

                 void onServiceAvailable(Service service);
                 

                 void onServiceUnavailable(Service service);
                          

                 void onError(DOMError error); 
        };

Methods

onBind

Asynchronous success callback.

Signature
void onBind(Service service);
Parameters
  • service
    • Optional: No.
    • Nullable: No
    • Type: Service
    • Description: An input argument representing the service.
onUnbind

Asynchronous callback used when a service is unbound.

Signature
void onUnbind(Service service);
Parameters
  • service
    • Optional: No.
    • Nullable: No
    • Type: Service
    • Description: An input argument representing the service.
onServiceAvailable

Asynchronous callback indicating that the service is available again.

Signature
void onServiceAvailable(Service service);
Parameters
  • service
    • Optional: No.
    • Nullable: No
    • Type: Service
    • Description: An input argument representing the service.
onServiceUnavailable

Asynchronous callback indicating the service is temporarily unavailable.

Signature
void onServiceUnavailable(Service service);
Parameters
  • service
    • Optional: No.
    • Nullable: No
    • Type: Service
    • Description: An input argument representing the service.
onError

Asynchronous error callback.

Signature
void onError(DOMError error);
Parameters
  • error
    • Optional: No.
    • Nullable: No
    • Type: DOMError
    • Description: DOMError (see above for definitions used by this interface).

Dictionary Options

Options dictionary

WebIDL
        dictionary Options {

                unsigned short timeout = 120;
        };

Dictionary Members

unsigned short timeout

A timeout value for the findService operation in seconds between 0-65535. Default value is 120 seconds. It is possible to disable the timeout by setting the timeout value to Number.POSITIVE_INFINITY.

Dictionary Filter

Filter dictionary

WebIDL
        dictionary Filter {

                DOMString[] zoneNames;
                

                DOMString serviceID;
                 

                boolean remoteServices = false;


                ServiceLocation? serviceLocation;      
        };

Dictionary Members

DOMString[] zoneNames

User friendly names of personal zones that will be used to search for services in addition to the person zone of the user logged into to the device.

DOMString serviceID

If set service discovery will only return the service with the given identifier. This can be used to establish a service binding directly if the service identity is already known, for example if the service identity was stored persistently for later reuse or it was received via out of band.

boolean remoteServices

If remoteService is false the findServices method will limit the search for services that are connected directly to the device (including Bluetooth, NFC, etc if available) or to the same local IP network. If remoteServices is true, the findServices method will extend the search for services outside the local IP network (including other PZHs). Default value is false.

ServiceLocation? serviceLocation

With the serviceLocation attribute it is possible to indicate where the service shall be located. If the service location is null, the location of the service is not considered during the findServices process.

Dictionary ServiceLocation

ServiceLocation interface

WebIDL
        dictionary ServiceLocation {

                double? latitude;


                double? longitude;
                

                double accuracy;                
        };

Dictionary Members

double? latitude

The latitude attribute is the geographic coordinate specified in decimal degrees. If the latitude is null the latitude of the device invoking the findServices method will be used.

double? longitude

The longitude attribute is the geographic coordinate specified in decimal degrees. If the longitude is null the longitude of the device invoking the findServices method will be used.

double accuracy

The accuracy denotes the accuracy level of the latitude and longitude coordinates in meters. This is used to limit the geographical area for finding services.

Interface PendingOperation

Pending Operation interface

WebIDL
        [NoInterfaceObject] interface PendingOperation {

                void cancel();
        };

Methods

cancel

Method Cancel

Signature
void cancel();

Cancels the pending asynchronous discovery operation. When this method is called, the user agent must immediately bring the operation to a stop and return. Allocated resources should be released and any ongoing related network operations should be terminated. An error callback is issued with the DOMError name "AbortError".

Interface Webinos (partial interface)

The WebinosDiscovery interface describes the part of the Discovery API accessible through the webinos object.

WebIDL
        partial interface Webinos {
                readonly attribute DiscoveryInterface discovery;
        };

Enums

ServiceState

Service state.

WebIDL
        enum ServiceState {"initiating", "available", "unavailable"};

Values

initiating
available
unavailable

Features

This is the list of URIs used to declare this API's features, for use in the widget config.xml and as identifier for service type in service discovery functionality. For each URI, the list of functions covered is provided.

http://webinos.org/api/discovery

Full WebIDL

WebIDL
        [NoInterfaceObject] interface DiscoveryInterface  {

                 PendingOperation findServices(  
                        ServiceType serviceType, 
                        FindCallBack findCallBack, 
                        optional Options options, 
                        optional Filter filter);
                 

                 DOMString getServiceId(DOMString serviceType);
                 
        };              

        dictionary ServiceType {

                DOMString api;
        };
                

        callback interface FindCallBack {

                 void onFound(Service service);        
                 

                 void onLost(Service service);
                          

                 void onError(DOMError error);
                                 
        };
        

        enum ServiceState {"initiating", "available", "unavailable"};
        

        
        [NoInterfaceObject] interface Service {

                readonly attribute ServiceState state;
                

                readonly attribute DOMString api;
                

                readonly attribute DOMString id;
                

                readonly attribute DOMString displayName;
                

                readonly attribute DOMString description;
                

                readonly attribute DOMString icon;
                

                void bind(BindCallBack bindCallBack, optional DOMString serviceId);
                

                void unbind();
        };
        

         
         callback interface BindCallBack {

                 void onBind(Service service);
                 

                 void onUnbind(Service service);
                 

                 void onServiceAvailable(Service service);
                 

                 void onServiceUnavailable(Service service);
                          

                 void onError(DOMError error); 
        };
        

        dictionary Options {

                unsigned short timeout = 120;
        };
        

        dictionary Filter {

                DOMString[] zoneNames;
                

                DOMString serviceID;
                 

                boolean remoteServices = false;


                ServiceLocation? serviceLocation;      
        };
        

        dictionary ServiceLocation {

                double? latitude;


                double? longitude;
                

                double accuracy;                
        };
        
        

        [NoInterfaceObject] interface PendingOperation {

                void cancel();
        };
        


        partial interface Webinos {
                readonly attribute DiscoveryInterface discovery;
        };