Samsung Electronics logo

Samsung Web API: SystemSetting

© 2014 Samsung Electronics Co., Ltd. All rights reserved.

Introduction

This API provides interfaces and methods providing Web applications with access to various values of the system.

This API provides an interface and method through features such as:

  • HOME_SCREEN
  • LOCK_SCREEN
  • INCOMING_CALL
  • NOTIFICATION_EMAIL

Table of Contents

Summary of Interfaces and Methods

Interface Method
SystemSettingObject
SystemSettingManager void setProperty(SystemSettingType type, DOMString value, SuccessCallback successCallback, ErrorCallback? errorCallback)
void getProperty(SystemSettingType type, SystemSettingSuccessCallback successCallback, ErrorCallback? errorCallback)
SystemSettingSuccessCallback void onsuccess(DOMString value)

1. Type Definitions

1.1. SystemSettingType

This enumerator indicates the type of supported system setting. The following values are supported in this release: 

  enum SystemSettingType {"HOME_SCREEN", "LOCK_SCREEN", "INCOMING_CALL", "NOTIFICATION_EMAIL"};
  • HOME_SCREEN - For homescreen background image.
  • LOCK_SCREEN - For lockscreen background image.
  • INCOMING_CALL - For incoming call ringtone.
  • NOTIFICATION_EMAIL - For email notification alert tone.

Defines supporting setting types. The HOME_SCREEN and LOCK_SCREEN are supported for images files. The INCOMING_CALL and NOTIFICATION_EMAIL are support for sound files.

2. Interfaces

2.1. SystemSettingObject

This interface defines what is instantiated by the WebAPIs object. 

  [NoInterfaceObject] interface SystemSettingObject {
    readonly attribute SystemSettingManager systemsetting;
  };
    WebAPIs implements SystemSettingObject;

There will be a webapis.systemsetting object that allows accessing the functionality of the SystemSetting API.

2.2. SystemSettingManager

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

  [NoInterfaceObject] interface SystemSettingManager {

     void setProperty(SystemSettingType type,
              DOMString value,
              SuccessCallback successCallback,
              optional ErrorCallback? errorCallback) raises (WebAPIException);

     void getProperty(SystemSettingType type,
              SystemSettingSuccessCallback successCallback,
              optional ErrorCallback? errorCallback) raises (WebAPIException);
     
  };

METHODS

setProperty

Sets the property of a device.

Signature
void setProperty(SystemSettingType type, DOMString value, SuccessCallback successCallback, optional ErrorCallback? errorCallback);

This method allows the user to set the image or sound file specified as an input parameter as the wallpaper or ringtone of a device.

The ErrorCallback is launched with these error types:

  • TypeMismatchError - If any input parameter is not compatible with the expected type for that parameter.
  • InvalidValuesError - If any of the input parameters contain an invalid value.
  • UnknownError - If any other error occurs.
Parameters
  • type
    • Optional: No.
    • Nullable: No.
    • Type: SystemSettingType.
    • Description: The setting type to set.
  • value
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: The location path of a wallpaper or ringtone file.
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: SuccessCallback.
    • Description: To be invoked if the setting value is successfully set.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: To be invoked if the setting value cannot be set.
Exceptions
  • WebAPIException:

    with error type UnknownError in any other error case.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    with error type NotSupportedError, if this feature is not supported.

    with error type InvalidValuesError, if any of the input parameters contain an invalid value.

Code example
 // Define the success callback
 function successCallback() {
   console.log("Success to setProperty");
 }

 // Define the error callback.
 function errorCallback(error) {
   console.log("Fail to setProperty" + error.message);
 }

 webapis.systemsetting.setProperty("HOME_SCREEN", "/storage/scard0/Images/image1.jpg", successCallback, errorCallback);

getProperty

Gets the value of the property of a device.

Signature
void getProperty(SystemSettingType type, SystemSettingSuccessCallback successCallback, optional ErrorCallback? errorCallback);

This method allows the user to get the value of the specified system property as wallpaper or ringtone of a device.

The ErrorCallback is launched with these error types:

  • TypeMismatchError - If any input parameter is not compatible with the expected type for that parameter.
  • InvalidValuesError - If any of the input parameters contain an invalid value.
  • UnknownError - If any other error occurs.
Parameters
  • type
    • Optional: No.
    • Nullable: No.
    • Type: SystemSettingType.
    • Description: The type of the property to get.
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: SystemSettingSuccessCallback.
    • Description: To be invoked if the setting value is successfully retrieved.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: To be invoked if the setting value cannot be retrieved.
Exceptions
  • WebAPIException:

    with error type UnknownError in any other error case.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    with error type NotSupportedError, if this feature is not supported.

    with error type InvalidValuesError, if any of the input parameters contain an invalid value.

Code example
 // Define the success callback
 function getPropertySuccessCallback(value) {
   console.log("Success to getProperty : " + value);
 }

 // Define the error callback.
 function errorCallback(error) {
   console.log("Fail to getProperty" + error.message);
 }

 webapis.systemsetting.getProperty("HOME_SCREEN", getPropertySuccessCallback, errorCallback);

2.3. SystemSettingSuccessCallback

The success callback for getProperty(). 

  [Callback=FunctionOnly, NoInterfaceObject] interface SystemSettingSuccessCallback {
    void onsuccess(DOMString value);
  };

3. Full WebIDL 

module SystemSetting {

  [NoInterfaceObject] interface SystemSettingObject {
    readonly attribute SystemSettingManager systemsetting;
  };
    WebAPIs implements SystemSettingObject;

  enum SystemSettingType {"HOME_SCREEN", "LOCK_SCREEN", "INCOMING_CALL", "NOTIFICATION_EMAIL"};

  [NoInterfaceObject] interface SystemSettingManager {

     void setProperty(SystemSettingType type,
              DOMString value,
              SuccessCallback successCallback,
              optional ErrorCallback? errorCallback) raises (WebAPIException);

     void getProperty(SystemSettingType type,
              SystemSettingSuccessCallback successCallback,
              optional ErrorCallback? errorCallback) raises (WebAPIException);
     
  };

  [Callback=FunctionOnly, NoInterfaceObject] interface SystemSettingSuccessCallback {
    void onsuccess(DOMString value);
  };

};