Webinos Logo

webinos Widget API

Webinos API Specifications

31 Aug 2012

Authors


Abstract

Webinos specific extensions to W3C Widget Interface

Table of Contents

  1. Introduction
  2. Interfaces and Dictionaries
    1. Widget
  3. Callbacks
    1. HideSuccessCallback
    2. HideErrorCallback
    3. DeploymentSuccessCallback
    4. DeploymentErrorCallback
  4. Features
  5. Full WebIDL

Summary of Methods

Interface Method
Widget void exit()
void hide(HideSuccessCallback onSuccess, HideErrorCallback onError)
void deployChild(DeploymentSuccessCallback onSuccess, DeploymentErrorCallback onError, DOMString childApplicationID, boolean local)

Introduction

This specification defines the common widget interface. The webinos application packaging is based on W3C Widget Specifications, and this API completes the W3C Widget Interface.

Interfaces and Dictionaries

Interface Widget (partial interface)

The webinos Widget Interface which extends the W3C Widget API with webinos specific extensions.

WebIDL
  partial interface Widget {
    
    readonly attribute DOMString     distributor;
    
    readonly attribute DOMString     distributorEmail;
    
    readonly attribute DOMString     distributorHref;
    
    readonly attribute DOMString     versionName;
    
    readonly attribute unsigned long long validFor;
    
    readonly attribute Date validUntil;
    
    readonly attribute boolean copyRestricted;

    readonly attribute DOMString restrictedTo;

    readonly attribute boolean isHidden;


    void exit();

    void hide(HideSuccessCallback onSuccess, HideErrorCallback onError);

    attribute Function? ondestroy;

    attribute Function? onbackground;

    attribute Function? onforeground;

    attribute Function? onstop;

    attribute Function? onstart;
    
    void deployChild(DeploymentSuccessCallback onSuccess, DeploymentErrorCallback onError, DOMString childApplicationID, optional boolean local);
  };

This API mainly introduces some more meta data attributes based on the webinos application packaging. In addition this API provide a number of life cycle APIs comparable to native applications in order to let an application know if it is in foreground or background.

Also this API allows to ask for installing webinos child applications to other devices in order to allow distributed applications to deploy their components on diffrent involved devices.

Attributes

readonly DOMString distributor

A distributor attribute that represents people or an organization that distributed the widget.

This attribute is readonly.
readonly DOMString distributorEmail

A string attribute that represents an email address associated with the distributor.

This attribute is readonly.
readonly DOMString distributorHref

A string attribute that represents an email address associated with the distributor.

This attribute is readonly.
readonly DOMString versionName

A human readable version name.

This attribute is readonly.
readonly unsigned long long validFor

The validFor attributed defines a time interval until when the application is valid and can be used.

The time frame is specified in elapsed milliseconds after the first application execution.

This attribute is readonly.
readonly Date validUntil

The validUntil attributed defines a date and time until the application is valid and can be used.

This attribute is readonly.
readonly boolean copyRestricted

The copyRestricted attributed defines if it is allowed to copy the application to other devices.

If true its not allowed, if false it is allowed.

This attribute is readonly.
readonly DOMString restrictedTo

The restrictedTo attributed defines copy restrictions.

If the value is "personal-zone" it is allowed to copy the application to other devices with the personal zone of the user even if copyRestricted is true

This attribute is readonly.
readonly boolean isHidden

Gives information about the visibility status of the Widget.

Asks the WRT wheather the application is currently hidden (not visible to the user) or not if the application is hidden and want to come to foreground it may notify an event to the user using the notification API.

Code example
 
 if (window.widget.isHidden){
    //do things, e.g., create a notification
 };

 
This attribute is readonly.
Function? ondestroy

Event handler indicating that the application will be terminated.

Callback function which is called if the application will be shut down by the WRT. All application memory assigned to the application will be freed after returning out of this function.

Function? onbackground

Event handler indicating that the application has been sent to background.

called after the application was put to background, e.g., another application goes to foreground and the application is not visible any more. After calling onBackground the application is still running but not visible anymore.

Function? onforeground

Event handler indicating that the application is gone to foreground.

Application goes to foreground after previously going to background.

Function? onstop

EventHandler indicating that application execution is going to be stopped.

Application execution is stopped after returning from this function.

Function? onstart

EventHandler indicating that application execution is continued.

Application execution is continued after previously stopped.

Methods

exit

Close the running application.

Signature
void exit();

Allows an application to trigger calling destroy from the runtime which results in stopping the application execution and closing the application.

Code example
 
 //terminate the widget by its own
 window.widget.exit();

 
hide

Hide the running application.

Signature
void hide(HideSuccessCallback onSuccess, HideErrorCallback onError);

Sends the application to background if possible so that it is not visible to the user anymore. If possible by the platform the application execution goes on even when the application is not visible anymore.

Code example
 
 //the widget is not visible anymore if possible
 window.widget.hide(
            function () { // i am not visible anymore },
            function () { // i am still visible }
        );

 
Parameters
deployChild

Requests to install an application on another device.

Signature
void deployChild(DeploymentSuccessCallback onSuccess, DeploymentErrorCallback onError, DOMString childApplicationID, optional boolean local);

Deploys a child application known to the WRT through the definition in the application s manifest file on another device. If local = false or not specified the WRT has to provide a list of available devices to the user where the application should be installed on, if local = true the WRT has to install the selected child on the same device as the API is bound to.

To install a child on a selected remote device the webinos device discovery API can be used to find available Widget API services on other devices where deployChild can be used remotely. Remote instances of the widget API will also provide Widget details of the running application and nothing about any application on remote devices. Thus, the only difference in using the Widget API directly or via a remote service is that deployChild will be targeted on another device.

Code example
 function error(){ 
   //installation failed
 }

 function success(childID, serviceID){
   //application was successfully deployed
   //serviceID can be used for discovery to bind directly to this application
   //if functions are exposed by the application
 }

 //installing child application with name child1.wgt on the same device 
 window.widget.deployChild(success, error, "child1.wgt", true);

 
Parameters
  • onSuccess
    • Optional: No.
    • Nullable: No
    • Type: DeploymentSuccessCallback
    • Description: SuccessCallback called after successfull installation.
  • onError
    • Optional: No.
    • Nullable: No
    • Type: DeploymentErrorCallback
    • Description: ErrorCallback called if installation was not possible.
  • childApplicationID
    • Optional: No.
    • Nullable: No
    • Type: DOMString
    • Description: the application ID of the child package to be installed.
  • local
    • Optional: Yes.
    • Nullable: No
    • Type: boolean
    • Description: Indicates if application should be installed on the same device as the requesting application or not.

Callbacks

HideSuccessCallback

Callback for successfully send the Widget to background

WebIDL
   callback HideSuccessCallback = void ();
Signature
void HideSuccessCallback();

HideErrorCallback

Callback called in case sending the Widget to background was not possible

WebIDL
   callback HideErrorCallback = void ();
Signature
void HideErrorCallback();

DeploymentSuccessCallback

Callback for successfull installations

WebIDL
   callback DeploymentSuccessCallback = void (DOMString childID, DOMString serviceID);
Signature
void DeploymentSuccessCallback(DOMString childID, DOMString serviceID);
Parameters
  • childID
    • Optional: No.
    • Nullable: No
    • Type: DOMString
    • Description: is the application id which was used during deployChild and declared in the manifest
  • serviceID
    • Optional: No.
    • Nullable: No
    • Type: DOMString
    • Description: is the unique application instance id that can be used to explicitly address the deployed service within webinos service discovery

DeploymentErrorCallback

Callback for failed installations

WebIDL
   callback DeploymentErrorCallback = void (DOMString applicationID, DOMError error);
Signature
void DeploymentErrorCallback(DOMString applicationID, DOMError error);
Parameters
  • applicationID
    • Optional: No.
    • Nullable: No
    • Type: DOMString
    • Description: The application ID the error relates to.
  • error
    • Optional: No.
    • Nullable: No
    • Type: DOMError
    • Description: A DOMError explaining what failed: SecurityError if permission has been denied, NetworkError if the device is not reachable, NotFoundError if the application id is unknown, InvalidStateError if the application is already installed

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/widget

Identifies the whole Widget API to be used for remote deploy requests.

http://webinos.org/api/widget.deploy

Identifies access to the deploy function and whether an application is allowed to trigger deployment of child applications or not.

Full WebIDL

WebIDL
   callback HideSuccessCallback = void ();
   
   callback HideErrorCallback = void ();
  
   callback DeploymentSuccessCallback = void (DOMString childID, DOMString serviceID);
   
   callback DeploymentErrorCallback = void (DOMString applicationID, DOMError error);


  partial interface Widget {
    
    readonly attribute DOMString     distributor;
    
    readonly attribute DOMString     distributorEmail;
    
    readonly attribute DOMString     distributorHref;
    
    readonly attribute DOMString     versionName;
    
    readonly attribute unsigned long long validFor;
    
    readonly attribute Date validUntil;
    
    readonly attribute boolean copyRestricted;

    readonly attribute DOMString restrictedTo;

    readonly attribute boolean isHidden;


    void exit();

    void hide(HideSuccessCallback onSuccess, HideErrorCallback onError);

    attribute Function? ondestroy;

    attribute Function? onbackground;

    attribute Function? onforeground;

    attribute Function? onstop;

    attribute Function? onstart;
    
    void deployChild(DeploymentSuccessCallback onSuccess, DeploymentErrorCallback onError, DOMString childApplicationID, optional boolean local);
  };