SystemSetting API

The System Setting API provides interfaces and methods providing web applications with access to various values of the system.

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

  • HOME_SCREEN
  • LOCK_SCREEN
  • INCOMING_CALL
  • NOTIFICATION_EMAIL

System Setting API may not be provided in some devices. The API capability can be checked by tizen.systeminfo.getCapability("http://tizen.org/feature/systemsetting").

In addition, not all the above properties may be available even though a device supports System Setting API. For instance, a watch device may provide the home screen image but may not support the lock screen wallpaper.

To check if SystemSettingType(e.g. HOME_SCREEN, LOCK_SCREEN and so on) is supported or not, use System Information API.

  • HOME_SCREEN - tizen.systeminfo.getCapability("http://tizen.org/feature/systemsetting.home_screen")
  • LOCK_SCREEN - tizen.systeminfo.getCapability("http://tizen.org/feature/systemsetting.lock_screen")
  • INCOMING_CALL - tizen.systeminfo.getCapability("http://tizen.org/feature/systemsetting.incoming_call")
  • NOTIFICATION_EMAIL - tizen.systeminfo.getCapability("http://tizen.org/feature/systemsetting.notification_email")

Remark: In order to access files, a proper privilege has to be defined additionally:

For more information on the System Setting features, see System Setting Guide.

Since: 2.0

Table of Contents

Summary of Interfaces and Methods

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

1. Type Definitions

1.1. SystemSettingType

Specifies the type of supported system setting. 
  enum SystemSettingType { "HOME_SCREEN", "LOCK_SCREEN", "INCOMING_CALL", "NOTIFICATION_EMAIL" };

Since: 2.0

The following values are supported in this release:

  • 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 supported for sound files.

2. Interfaces

2.1. SystemSettingObject

The SystemSettingObject interface defines what is instantiated by the Tizen object from the Tizen Platform. 
  [NoInterfaceObject] interface SystemSettingObject {
    readonly attribute SystemSettingManager systemsetting;
  };
  Tizen implements SystemSettingObject;

Since: 2.0

There will be a tizen.systemsetting object that allows accessing the functionality of the System Setting API.

Attributes

  • readonly SystemSettingManager systemsetting
    Object representing a system settings manager.

    Since: 2.0

2.2. SystemSettingManager

The SystemSettingManager interface is the top-level interface for the System Setting 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);
  };

Since: 2.0

Methods

setProperty
Sets the property of a device. 
void setProperty(SystemSettingType type, DOMString value, SuccessCallback successCallback, optional ErrorCallback? errorCallback);

Since: 2.0

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 method is launched with these error types:

  • InvalidValuesError - If any of the input parameters contain an invalid value
  • NotSupportedError - If the given type is not supported on the device
  • UnknownError - If any other error occurs

Privilege level: public

Privilege: http://tizen.org/privilege/setting

Parameters:

  • type: Setting type to set.
  • value: Location path of a wallpaper or ringtone file.
  • successCallback: Callback function that is called when the setting value is successfully set.
  • errorCallback [optional] [nullable]: Callback function that is called when the setting value cannot be set.

Exceptions:

  • WebAPIException

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

    • with error type SecurityError, if this functionality is not allowed or the application does not have privilege to access the storage. For more information, see Storage privileges.

Code example:

/* Checks whether System Setting API is supported. */
var systemsetting_api_supported =
    tizen.systeminfo.getCapability("http://tizen.org/feature/systemsetting");

/* Checks whether the picture on home screen can be changed or retrieved through System Setting API. */
var home_screen_system_setting =
    tizen.systeminfo.getCapability("http://tizen.org/feature/systemsetting.home_screen");

/* Defines the success callback. */
function successCallback()
{
  console.log("Succeeded in changing the property");
}

/* Defines the error callback. */
function errorCallback(error)
{
  console.log("Failed to change the property. Error: " + error.message);
}

if (systemsetting_api_supported === true)
{
  /* tizen.systemsetting will be available. */
  if (home_screen_system_setting === true)
  {
    /* Sets the home screen image. */
    /* newHomeScreenImagePath variable should hold the path of the image to be set as home screen */
    /* background. */
    tizen.systemsetting.setProperty(
        "HOME_SCREEN", newHomeScreenImagePath, successCallback, errorCallback);
  }
  else
  {
    /* If tizen.systemsetting.setProperty("HOME_SCREEN", ...) is invoked, NotSupportedError is */
    /* returned through ErrorCallback. */
  }
}
else
{
  /* tizen.systemsetting will be "undefined". */
  console.log("System Setting API is not supported on the device");
}
getProperty
Gets the value of the property of a device. 
void getProperty(SystemSettingType type, SystemSettingSuccessCallback successCallback, optional ErrorCallback? errorCallback);

Since: 2.0

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

The ErrorCallback method 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
  • NotSupportedError - If the given type is not supported on the device
  • SecurityError - If the application does not have privilege to access the storage. For more information, see Storage privileges.
  • UnknownError - If any other error occurs

Parameters:

  • type: Type of the property to get.
  • successCallback: Callback function that is called when the setting value is successfully retrieved.
  • errorCallback [optional] [nullable]: Callback function that is called when the setting value cannot be retrieved.

Exceptions:

  • WebAPIException

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

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

    • with error type UnknownError in any other error case.

Code example:

/* Defines the success callback. */
function getPropertySuccessCallback(value)
{
  /* Case: tizen.systeminfo.getCapability("http://tizen.org/feature/systemsetting.home_screen") */
  /* returns "true". */
  console.log("Succeeded in retrieving the property. The value is " + value);
}

/* Defines the error callback. */
function errorCallback(error)
{
  console.log("Failed to get the property. Error: " + error.message);
  /* If the device does not support getting the image on home screen, NotSupportedError is thrown. */
}

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

2.3. SystemSettingSuccessCallback

The SystemSettingSuccessCallback interface defines the success callback for getProperty(). 
  [Callback=FunctionOnly, NoInterfaceObject] interface SystemSettingSuccessCallback {
    void onsuccess(DOMString value);
  };

Since: 2.0

Methods

onsuccess
Called when the value of the system setting property is successfully retrieved. 
void onsuccess(DOMString value);

Since: 2.0

Parameters:

  • value: The value of the requested property.

3. Full WebIDL

module SystemSetting {
  enum SystemSettingType { "HOME_SCREEN", "LOCK_SCREEN", "INCOMING_CALL", "NOTIFICATION_EMAIL" };
  Tizen implements SystemSettingObject;
  [NoInterfaceObject] interface SystemSettingObject {
    readonly attribute SystemSettingManager systemsetting;
  };
  [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);
  };
};
Except as noted, this content - excluding the Code Examples - is licensed under Creative Commons Attribution 3.0 and all of the Code Examples contained herein are licensed under BSD-3-Clause.
For details, see the Content License.