Contents

1 Introduction

This module provides a mechanism to interact with the end-user through features such as:

• device vibrator,
• device notifier,
• screen backlight,
• device Wallpaper.

All the functionality of this module is accessed through the object deviceapis.deviceinteraction which is an instance of the DeviceInteractionManager interface. In case any functionality is not supported, a DOMException exception will be thrown with code NOT_SUPPORTED_ERR when the related method of the DeviceInteractionManager interface is invoked.

2 Feature Strings

When the feature:

• http://wacapps.net/api/deviceinteraction

or any of the features hierarchically under that feature are successfully requested, the interface DeviceInteractionManager is instantiated, and the resulting object appears in the global namespace as deviceapis.deviceinteraction.

This is the list of URIs used to declare this API's features, for use in the widget's configuration document. For each URL, the list of functions covered is provided.

http://wacapps.net/api/deviceinteraction

Allows access to the device interaction module

3 DeviceapisDeviceInteractionManager interface

interface DeviceapisDeviceInteractionManager {
    readonly attribute DeviceInteractionManager deviceinteraction;
}; 
Deviceapis implements DeviceapisDeviceInteractionManager;

There will be a deviceapis.deviceinteraction object that allows accessing the functionality of the deviceinteraction module.

4 DeviceInteractionManager interface

interface DeviceInteractionManager {
    void startNotify(Function successCallback,
	                              optional ErrorCB? errorCallback
 	                              long duration) ;

    void startVibrate(Function successCallback,
                                  optional ErrorCB? errorCallback
                                  optional unsinged long duration,
                                  optional DOMString pattern);

    void lightOn(Function successCallback,
	                          optional ErrorCB? errorCallback
                            long duration);

    void setWallpaper(Function successCallback,
                                  optional ErrorCB? errorCallback
                                  DOMString fileName);
    void stopNotify();
    void stopVibrate();
    void lightOff();
};

This is the top-level interface for the deviceinteraction API that provides access to the module functionalities.

4.1 Example

var di = deviceapis.deviceinteraction;

di.lightOn(function() {
	console.log("Lighting for 1 second");
},
function() {
	console.log("Failed to light");
},
1000);

di.startNotify(
function() {
	console.log("Notifying for 1 second");
},
function() {
	console.log("Failed to notify");
},
1000);

di.startVibrate(
function() {
	console.log("Vibrating for 1 second");
},
function() {
	console.log("Failed to vibrate");
},
1000);

4.2 The startNotify() method

Produces a beep/vibrate/backlight-on from the device for the supplied duration.

When this method is invoked, the notification MUST be based on the active profile:

• If the device volume is set to a value above 0, then device beeper MUST be activated for the time specified in the duration input parameter.
• If the device is in vibrate mode (i.e. sound volume is set to 0 and vibrator alert is active), the device MUST vibrate for the time specified.
• If the device is in silent mode (i.e. sound volume is 0 and vibrator alert is deactivated), the main screen backlight MUST be switched on for the time specified in the duration input parameter.

The implementation MAY impose a limit on the duration of a notification that causes the notification to stop before the specified duration expires. If the duration input argument is 0, the implementation MUST perform this operation until this limit is reached or the stopNotify method is invoked.

The success callback MUST be invoked as soon as the implementation determines that the notification can be realized. If for some reason (security or other) cannot be realized the error callback MUST be called with the appropriate error code:

• INVALID_VALUES_ERR if any input parameter has invalid values.
• SECURITY_ERR if the operation is not allowed.
• NOT_SUPPORTED_ERR if the feature is not supported.
• UNKNOWN_ERR in any other case.

If the stopNotify method is invoked before the supplied notification duration expires, the active notification (beep/vibrate/backlight-on) MUST be terminated.

Example

try {
	deviceapis.deviceinteraction.startNotify(function() {
		console.log("Notifying indefinitely");
	},
	function(e) {
		console.log("Failed to notify: " + e);
	},
	0);
} catch(e) {
	console.log("Exception thrown: " + e);
}

4.3 The stopNotify() method

Terminates an ongoing notification alert.

When this method is invoked, the implementation MUST request to stop the notification. Although the implementation MUST make this request immediately, the device MAY have further limitations (e.g. timeouts) that MAY delay the operation completion.

If a notification is not in progress (i.e. the device is not beeping/vibrating/backlight-on) when this method is invoked, it MUST be ignored.

If this functionality is not supported, or if any other error occurs when executing the request, it MUST return immediately without performing any action.

Example

deviceapis.deviceinteraction.stopNotify();

4.4 The startVibrate() method

Switch on device vibration for a specified duration and to an optional pattern.

When this method is invoked, the device vibrator MUST be activated for the time specified. The duration of vibration can be specified by 2 mechanisms:

• the duration input parameter,
• the on/off pattern.

The pattern argument is a DOMString composed by '.' and '_' chars. Where '.' denotes a 'vibration pulse' and '_' denotes a 'no vibration pulse'. The pattern has a limit of 10 characters, and the duration of every pulse SHOULD be 100 milliseconds.

For instance, the pattern "..__." denotes that the device should vibrate for 200 msecs, stop vibrating for 200 msecs and vibrate again for 100 msecs.

The success callback MUST be invoked as soon as the implementation determines that the vibration can be realized. If for some reason (security or other) cannot be realized the error callback MUST be called with the appropriate error code:

• INVALID_VALUES_ERR if any input parameter has invalid values.
• SECURITY_ERR if the operation is not allowed.
• NOT_SUPPORTED_ERR if the feature is not supported.
• UNKNOWN_ERR in any other case.

If both vibration arguments contain valid values other than null, then the pattern MUST be repeated until the duration interval has elapsed, and a complete pattern MUST be performed (i.e. the pattern MUST NOT be truncated).

If only one argument is valid and the other has a null value, then only the mechanism with the valid argument will be used.

The implementation MAY impose a duration limit that causes the vibration to stop before the specified duration expires.

If the stopVibrate method is invoked before the specified vibration duration expires, any vibration MUST be stopped.

Example

try {
	deviceapis.deviceinteraction.startVibrate(function() {
		console.log("Vibrating...");
	},
	function(e) {
		console.log("Failed to vibrate: " + e);
	},
	0);
} catch(e) {
	console.log("Exception thrown: " + e);
}

4.5 The stopVibrate() method

Terminates an ongoing device vibration alert.

When this method is invoked the device vibrator MUST be terminated. If the device is not vibrating when this method is invoked it MUST be ignored.

If this functionality is not supported, or if any other error occurs when executing the request it MUST return immediately without performing any action.

Example

deviceapis.deviceinteraction.stopVibrate();

4.6 The lightOn() method

Switches the backlight of the display on for a specified duration.

When this is not supported, or if any othee main screen backlight MUST be switched on for the time specified in the duration input parameter. If the lightOff method is invoked before the specified duration expires, the screen backlight MUST be switched off.

The implementation MAY impose a duration limit that causes the light to be switched off before the specified duration expires. If the duration input argument is 0, the implementation MUST perform this operation until this limit is reached or the lightOff method is invoked.

The implementation MUST call the success callback as soon as it determines that the request (light On) can be performed. The implementation MUST call the error callback if for any reason the request cannot be performed. The possible error codes are:

• INVALID_VALUES_ERR if any input parameter has invalid values.
• SECURITY_ERR if the operation is not allowed.
• NOT_SUPPORTED_ERR if the feature is not supported.
• UNKNOWN_ERR in any other case.

Example

try {
	deviceapis.deviceinteraction.lightOn(function() {
		console.log("Lighting indefinitely");
	},
	function(e) {
		console.log("Failed to light: " + e);
	},
	0);
} catch(e) {
	console.log("Exception thrown: " + e);
}

4.7 The lightOff() method

Terminates the screen backlight notification.

When this method is invoked, the implementaion MUST request that the screen backlight is switched off. Although the implementation MUST make the request to switch off the light immediately, the device MAY have further limitations (e.g. timeouts) that MAY delay the operation.

If this functionality is not supported, or if any other error occurs when executing the request it MUST return immediately without performing any action.

Example

deviceapis.deviceinteraction.lightOff();

4.8 The setWallpaper() method

Sets the Wallpaper of the device to the specified image file.

This method sets the device wallpaper to the image file supplied as the fileName input parameter. If the wallpaper is successfully set, the successCallback MUST be invoked.

If any of the input arguments are not compatible with the expected type for that argument, throw a "TypeMismatchError" exception.

If the wallpaper cannot be set due to any other error, for example, an unsupported image format or invalid file format, the errorCallback MUST be invoked. The following error codes may be returned in the error callback depending on the error conditions:

• NOT_SUPPORTED_ERR: If this feature is not supported.
• SECURITY_ERR: If the operation is not allowed.
• INVALID_VALUES_ERR: If any input parameter contain invalid values. For example, the successCallback is null or the fileName does not exist. Please note that in order to allow developer ignore errors, the erroCallback accepts null as a valid value.
• UNKNOWN_ERR: In any other error case.

If the errorCallback does not contain a valid function (e.g. null), or in the case of any of the above errors that should be returned in the errorCallback, the implementation MUST silently fail, the developer is not notified of the error and no further action is required.

Example

try {
	deviceapis.deviceinteraction.setWallpaper(function() {
		alert("Set wallpaper to WAC logo");
	},
	function(e) {
		alert(e.message);
	},
	"wgt-package/images/waclogo_small.jpg");
} catch(exp) {
	alert("setWallpaper Exception :[" + exp.code + "] " + exp.message);
}

Change Log

This specification was last updated on 30 April 2012. A complete list of changes are kept on our GIT repository.