System Information API Guide

Overview

The Tizen SystemInfo API provides interfaces and methods to get hardware devices status by requesting information from selected system properties. The SystemInfo API enables you to access a number of device information, such as battery level, available device storage, version number, model name, the cellular network and so on. The SystemInfo API allows you to set asynchronous notifications for changes in the values of selected devices. To use this API, add the required permissions to the config.xml file (see prerequisites section below). When the application is launched, a SystemInfoObject is instantiated automatically in the tizen object. The tizen.systeminfo object is an instance of the SystemInfo interface, which provides access to the system information.

Figure below shows how the API objects are structured inside the application window.

System Info

Using SystemInfo APIs, your applications can

 

 

 

 

Prerequisites

The SystemInfo API has different levels of access to handle system and sensitive data. You can enable permissions for the SystemInfo API in the config.xml file.

In order to use systemmanager privilege, you should have "partner" privilege level. You can enable it by executing

$patch.bat public

from <TIZEN_IDE_HOME>/tools/certificate-generator/patches.

It is recommended that you edit config.xml file by using the Tizen IDE interface.

 

 

 

 

Determine property support

The Tizen SystemInfo API provides the SystemInfoObject interface which allows you to obtain information about system properties. You can use the SystemInfo API to access the status of various device details.

If your application need to access the device-specific information, you must check the support for the property by using getCapabilities method. Returns true, if the property is supported.

var deviceCapabilities;
deviceCapabilities = tizen.systeminfo.getCapabilities();
if (deviceCapabilities.wifi)
{
   console.log("wifi is available");
}

The valid values for PropertyId are:

  • Battery
  • Cpu
  • Storage
  • Display
  • Device Orientation
  • Build
  • Locale
  • Network
  • WifiNetwork
  • CellularNetwork
  • SIM
  • Peripheral

 

 

 

 

Retrieve device properties

Device properties provides information about the resources available to complete a particular task or service successfully. To access the internet, you may want to know the the details of the cellular network that can be accessed by the device.

You can determine by checking the status of the respective properties.

You can check the current state of a property by using the getPropertyValue method which accepts 3 arguments: a property name, a success callback, and an error callback. Using this method, you can check the current state of all the properties supported by the device.

SystemInfoProperty

A common abstract interface used by the supported system information objects.

SystemInfoBattery

It is important to understand the power available for applications that require a considerable amount of power. You can determine whether the application can be launched or whether the user needs to be warned about the level of power available for the device.

Using SystemInfoBattery you can get the level of battery

 function onSuccessCallback(battery) {
     alert("Battery Level: " + battery.level + "\nIs Charging: "
     + battery.isCharging);
 }

  function onErrorCallback(error) {
     alert("Not supported: " + error.message);
 }
 tizen.systeminfo.getPropertyValue("BATTERY", onSuccessCallback, onErrorCallback);

The level of power available to a device is scaled from 0 to 1. Here, 0 indicates that the device doesn’t have any power while 1 indicates that the device is charged to its maximum capacity. If a threshold parameter is set, the notification for change is triggered only when the power level crosses the threshold values.

SystemInfoCpu

CPU load is an important factor for determining the efficiency of an application. Using SystemInfoCpu, you can get the current CPU load on the system.

 function onSuccessCallback(cpu) {
     alert("The Load on device is " + cpu.load);
 }

  function onErrorCallback(error) {
     alert("Not supported: " + error.message);
 }
 tizen.systeminfo.getPropertyValue("CPU", onSuccessCallback, onErrorCallback);
The minimum or no load on the CPU of a device is represented by 0.0 while the maximum load is represented by 1.0.

SystemInfoStorage

A device might have several data storage devices connected to it. Hence you might want to provide the users with an option to select any of these storage devices for data storage.

The SystemInfoStorage interface returns a collection of SystemInfoStorageUnit objects and each storage unit represents details such as capacity, free space, type, and whether or not the storage unit is removable.

 function singleStorageInfo(storageunit) {
     alert("Type: " + storageunit.type + "    Total Capacity: " + storageunit.capacity
     + "\nFree: " + storageunit.availableCapacity + "isRemovable: " + storageunit.isRemovable);
 }

 function onErrorCallback(error) {
     alert("Not supported: " + error.message);
 }

 function onSuccessCallback(storage) {
     alert("Number of storage devices connected " + storage.units.length);
     var i = 0;
     //for(i=0; i < storage.units.length; i++)
     //{
        alert("Type: " + storage.units[i].type);
        singleStorageInfo(storage.units[i]);
     //}
 }

 tizen.systeminfo.getPropertyValue("STORAGE", onSuccessCallback, onErrorCallback);

SystemInfoDisplay

You might want to know the resolution of the device to layout your application on runtime. Using SystemInfoDisplay, you can get the resolution, dpi, physical dimensions and brghitness of the display.

 function onSuccessCallback(display) {
     alert("Resolution{w, h}: " + "{" + display.resolutionWidth + ", " + display.resolutionHeight
     + "}\nDPI{w, h}: " + "{" + display.dotsPerInchWidth + ", " + display.dotsPerInchHeight
     + "}\nPhysical dimensions{w, h}: " + "{" + display.physicalWidth + ", " + display.physicalHeight
     + "}\nBrightness: " + display.brightness);
 }

  function onErrorCallback(error) {
     alert("Not supported: " + error.message);
 }
 tizen.systeminfo.getPropertyValue("DISPLAY", onSuccessCallback, onErrorCallback);

SystemInfoDeviceOrientation

You might want to know the current device display orientation. Using SystemInfoDeviceOrientation, you can get the current device orientation.

 function onSuccessCallback(orientation) {
     alert("Device Orientation =" + orientation.status);
 }

  function onErrorCallback(error) {
     alert("Not supported: " + error.message);
 }
 tizen.systeminfo.getPropertyValue("DEVICE_ORIENTATION", onSuccessCallback, onErrorCallback);

SystemInfoBuild

Using SystemInfoBuild, you can get the device manufacturer and model information.

 function onSuccessCallback(device) {
     alert("Device Model =" + device.model + " Manufacturer = " + device.manufacturer);
 }

  function onErrorCallback(error) {
     alert("Not supported: " + error.message);
 }
 tizen.systeminfo.getPropertyValue("BUILD", onSuccessCallback, onErrorCallback);

SystemInfoLocale

Using SystemInfoLocale, you can get the locale information of current device.

 function onSuccessCallback(device) {
     alert("Language =" + device.language + " Country = " + device.country);
 }

  function onErrorCallback(error) {
     alert("Not supported: " + error.message);
 }
 tizen.systeminfo.getPropertyValue("LOCALE", onSuccessCallback, onErrorCallback);

SystemInfoNetwork

You might to know whether the network type provides adequate connection speeds as per the requirements of the user. Using SystemInfoNetwork, you can determine the network type.

  function onSuccessCallback(network) {
     alert(" network type: " + network.networkType);
 }

  function onErrorCallback(error) {
     alert("Not supported: " + error.message);
 }

 tizen.systeminfo.getPropertyValue("NETWORK", onSuccessCallback, onErrorCallback);

SystemInfoWifiNetwork

You might want your application to access the Wi-Fi network of the device. To access this network through your application, you need certain network details. Using SystemInfoWifiNetwork, you can determine the network availability, SSID, IP address and signal strength.

 function onSuccessCallback(wifi) {
     alert("Status: " + wifi.status +  "    SSID: " + wifi.ssid
     + "\nIP Address: " + wifi.ipAddress + "\nIPV6 Address: " + wifi.ipv6Address + "    Signal Strength: " + wifi.signalStrength);
 }

  function onErrorCallback(error) {
     alert("Not supported: " + error.message);
 }
 tizen.systeminfo.getPropertyValue("WIFI_NETWORK", onSuccessCallback, onErrorCallback);
The SSID of a Wi-Fi network represents the public name of the network that is specified by the manufacturer. This SSID uniquely identifies a network by using an alphanumeric key that is 32 characters long. This key ensures that only devices using the same key or SSID can communicate with each other.

SystemInfoCellularNetwork

Most mobile devices are connected to a cellular network that enables the devices to connect to and call other devices. To access this network through your application, you need certain network details. Using SystemInfoCellularNetwork, you can determine the network status, access point, IP address, country code, cellular ID, imei, location area code and whether roaming is enabled on the device.

function onSuccessCallback(cellular) {
     alert("Status: " + cellular.status +  "    Access Point: " + cellular.apn
     + "\nIP Address: " + cellular.ipAddress + "\nIPV6 Address: " + cellular.ipv6Address + "    Country code: " + cellular.mcc
     + "\nNetwork Code: " + cellular.mnc + "    Cell ID: " + cellular.cellId
     + "\nLocation Area code: " + cellular.lac + "    Is Roaming: " + cellular.isRoaming)
     + "\nFlight Mode: " + cellular.isFlightMode + "    IMEI: " + cellular.imei);
 }

  function onErrorCallback(error) {
     alert("Not supported: " + error.message);
 }
 tizen.systeminfo.getPropertyValue("CELLULAR_NETWORK", onSuccessCallback, onErrorCallback);

SystemInfoSIM

Using SystemInfoSIM, you can get the information about device SIM card such as the operator name and mcc code.

 function onSuccessCallback(sim) {
     alert("State: " + sim.state + "Operator Name: " + sim.operatorName +  "  SIM card subscriber number: " + sim.msisdn
     + "\nIntegrated Circuit Card ID: " + sim.iccid + "   Mobile Country Code (MCC): " + sim.mcc
     + "\nMobile Network Code (MNC): " + sim.mnc + "   Mobile Subscription Identification Number (MSIN): " + sim.msin
     + "\nService Provider Name (SPN): " + sim.spn);
 }

  function onErrorCallback(error) {
     alert("Not supported: " + error.message);
 }
 tizen.systeminfo.getPropertyValue("SIM", onSuccessCallback, onErrorCallback);

SystemInfoPeripheral

Using SystemInfoPeripheral, you can get the information about device's video output status.

 function onSuccessCallback(device) {
     alert("Video out: " + device.isVideoOutputOn);
 }

  function onErrorCallback(error) {
     alert("Not supported: " + error.message);
 }
 tizen.systeminfo.getPropertyValue("PERIPHERAL", onSuccessCallback, onErrorCallback);

 

 

 

 

Trace system information

A change in the status of one or more properties of a device might affect your application. Therefore, it is important to check for updates to the properties that are critical to your application.

 

 

 

 

Add event listener

You can subscribe for notifications on change in values of system properties using addPropertyValueChangeListener method.

The addPropertyValueChangeListener method takes four arguments as parameters. The first three parameters of the addPropertyValueChangeListener method are the property name you want to watch, the success callback that is invoked when the property is changed, and the error callback that is invoked when there is an error in the device during watch. The last parameter is optional and represents an object of the SystemInfoOptions type that contains various options for obtaining the requested properties.

 function onSuccessCallback(battery) {
     console.log("Low battery:  " + battery.level);
 }

 tizen.systeminfo.addPropertyValueChangeListener("BATTERY", onSuccessCallback,
 {lowThreshold : 0.2});

Every identifier returned by tizen.systeminfo.addPropertyValueChangeListener() can be stored separately to remove the registered callback (cancelling the subscription).

 

 

 

 

Remove event listener

You can remove an event listener by unsubscribing from the notifications using removePropertyValueChangeListener method.

var id = null;
 function onSuccessCallback(battery) {
    console.log("New value for Battery level is " + battery.level);
    if (id != null) // After receiving the first notification, we clear it
        tizen.systeminfo.removePropertyValueChangeListener(id);
 }

 id = tizen.systeminfo.addPropertyValueChangeListener("BATTERY", onSuccessCallback)

 

 

 

 

Set options for event listener

You might want to get notified, only when the value of the requested property exceeds a particular limit. SystemInfoOptions provides options for obtaining the requested properties. You can set the threshold values for the properties, so that the notification is triggered only when the value crosses the threshold.

SystemInfoOptions contains three attributes namely highThreshold, lowThreshold and timeout. If the value becomes lower than lowThreshold or higher than highThreshold, the success callback is invoked. If the number of milliseconds elapsed, since the invoke of addPropertyValueChangeListener method, exceeds the timeout value, the operation is interrupted.

var id = null;
 function onSuccessCallback(battery) {
     alert("Batter Low! Level = " + battery.level);
     if (id != null) // After receiving the first notification, we clear it
        tizen.systeminfo.removePropertyValueChangeListener(id);
 }

 id = tizen.systeminfo.addPropertyValueChangeListener("BATTERY", onSuccessCallback, {lowThreshold : 0.2});

 

 

 

 

File attachments: