System Information

You can access and monitor the device and system properties (both hardware and capability), such as the battery level, available device storage, version number, model name, and the cellular network being used.

The System Information API is mandatory for Tizen Mobile, Wearable, and TV profiles, which means that it is supported on all mobile, wearable, and TV devices. All mandatory APIs are supported on the Tizen emulators.

The main features of the System Information API include the following:

Checking the amount of total and available memory

You can retrieve memory amounts, such as the total and available amount of system memory.
Retrieving device capability

You can check the available capabilities of the device.
Checking device property states

You can retrieve the current state of a specific device property to determine, for example, if your application has enough resources available to complete a task or a service successfully.

You can also check and monitor the device orientation, and retrieve the number of system property information to check, for example, the number of installed SIM cards in the device.
Receiving property state updates

You can receive state updates when a specific property changes.

Prerequisites

To use the System Information API (in mobile, wearable, and TV applications), the application has to request permission by adding the following privileges to the config.xml file:

<tizen:privilege name="http://tizen.org/privilege/system"/>
<tizen:privilege name="http://tizen.org/privilege/telephony"/>

Retrieve a device capability

Retrieve a device capability using the getCapability() method of the SystemInfo interface (in mobile, wearable, and TV applications):

To get a specific capability of the device, use the getCapability() method:

var barometer = tizen.systeminfo.getCapability('http://tizen.org/feature/sensor.barometer');
console.log(' Barometer = ' + barometer);

For a list of available keys and their meaning, see the device capability keys (in mobile and wearable applications).

Retrieve the current state of a property

The property state can determine whether your application has enough resources to complete a particular task or service successfully. For example, if you are creating a file, you need to check the storage property to know whether a writable storage is available on the device.

Retrieve information about the property states using the applicable methods of the SystemInfo interface (in mobile, wearable, and TV applications):

To check the current state of the property, use the getPropertyValue() method.

The first method parameter must be of the SystemInfoPropertyId type (in mobile, wearable, and TV applications). For the available values, see the Available properties table:
```
/* Retrieve the battery property */
tizen.systeminfo.getPropertyValue('BATTERY', onPowerSuccessCallback);

/* Retrieve the cellular network property */
tizen.systeminfo.getPropertyValue('CELLULAR_NETWORK', onCellularSuccessCallback);
```
After retrieving a property, you can use all the details of the property in your code. The property values are returned in the success event handlers defined in the following steps.

Use the power property values.

In the following example, the battery level and charging status of the power property are printed to a console log:

function onPowerSuccessCallback(battery) {
    /* Log the device battery level to the console */
    console.log('The battery level is ' + battery.level);

    /* Check whether the device is charging */
    var charging = battery.isCharging;
}

Retrieve the current states of a specific device property using the getPropertyValueArray() method. For example, you can check the state of SIM cards mounted in the Tizen device:

function successCallback(properties) {
    console.log('The number of the returned system properties is ' + properties.length);
    for (var i = 0; i properties.length; i++) {
        console.log('[' + (i + 1) + '] SIM\'s state is ' + properties[i].state);
    }
}

tizen.systeminfo.getPropertyValueArray('SIM', successCallback);

Retrieve the number of system property information using the getCount() method. For example, you can check the number of SIM cards installed in the Tizen device:
```
console.log('The number of SIM cards in the device is ' + tizen.systeminfo.getCount('SIM'));
```

Retrieve the memory state

Check the total or available amount of system memory using the applicable method of the SystemInfo interface (in mobile, wearable, and TV applications):

To get the total amount of system memory, use the getTotalMemory() method:

console.log('The total memory size is ' + tizen.systeminfo.getTotalMemory() + ' bytes.');

To get the available amount of system memory, use the getAvailableMemory() method:

console.log('The available memory size is ' + tizen.systeminfo.getAvailableMemory() + ' bytes.');

Retrieve and monitor the device orientation

The device orientation defines the angle between the direction of what is considered to be the “top” side of the device and the physical upward direction. The device orientation is not directly related to the screen orientation. For example, when the Auto rotate screen option is disabled or the Web application has the screen-orientation option (in mobile and wearable applications) set to “landscape” or “portrait”, the screen is not rotated and the window.screen.orientation property does not change; however, the SystemInfo device orientation changes.

When a device is in its natural position, it is considered to be in the PORTRAIT_PRIMARY orientation (if the screen height is greater than its width) or the LANDSCAPE_PRIMARY orientation (otherwise). When the device is rotated 90 degrees clockwise (rotated right), the orientation changes from LANDSCAPE_PRIMARY to PORTRAIT_PRIMARY, from PORTRAIT_PRIMARY to LANDSCAPE_SECONDARY, from LANDSCAPE_SECONDARY to PORTRAIT_SECONDARY, and from PORTRAIT_SECONDARY back to LANDSCAPE_PRIMARY.

Table: Device orientations

LANDSCAPE_PRIMARY	PORTRAIT_PRIMARY	LANDSCAPE_SECONDARY	PORTRAIT_SECONDARY

To retrieve information about the device orientation, follow these steps:

To retrieve the current orientation of the device, use the getPropertyValue() method of the SystemInfo interface (in mobile, wearable, and TV applications) and query the DEVICE_ORIENTATION property:

function onDeviceOrientation(deviceOrientation) {
    console.log('The device orientation is now: ' + deviceOrientation.status);
}
tizen.systeminfo.getPropertyValue('DEVICE_ORIENTATION', onDeviceOrientation);

The user can rotate the device and change its orientation. To receive notifications about the orientation changes, use the addPropertyValueChangeListener() method of the SystemInfo interface:
```
var orientationListenerId;
orientationListenerId = tizen.systeminfo.addPropertyValueChangeListener('DEVICE_ORIENTATION', onDeviceOrientation);
```
To stop receiving change notifications, use the removePropertyValueChangeListener() method of the SystemInfo interface:
```
tizen.systeminfo.removePropertyValueChangeListener(orientationListenerId);
```

Receive notifications on property value changes

You can receive state updates when a change occurs in a specific property. The addPropertyValueChangeListener() method registers an event listener for a specific property, and returns the subscription identifier for the listener. You can use the SystemInfoPropertySuccessCallback interface (in mobile, wearable, and TV applications) to define the event handler for receiving the change notification.

To receive notifications on property value changes, follow these steps:

Register a SystemInfoPropertySuccessCallback event handler for the property value changes using the addPropertyValueChangeListener() method of the SystemInfo interface.

The first parameter defines the property whose value changes you want to track, and the optional last parameter defines any thresholds when you want the notifications to be triggered. In the following example, an event handler is registered for the memory property value changes:
```
function successCallback(memory) {
    console.log('The memory state is ' + memory.state);
}

tizen.systeminfo.addPropertyValueChangeListener('MEMORY', successCallback);
```
The method returns a watch identifier, which can be used to deregister the event handler.

In the success event handler of the addPropertyValueChangeListener() method, define the notification event actions.

In the following example, a warning about the low battery is logged to the console:

/* Trigger a notification */
function onSuccessCallback(battery) {
    console.log('Low battery: ' + battery.level);
}

tizen.systeminfo.addPropertyValueChangeListener('BATTERY', onSuccessCallback);

To deregister the event handler, use removePropertyValueChangeListener() method with the watch identifier returned from the addPropertyValueChangeListener() method.

In the following example, the event handler is deregistered when the first change of the SIM card state is detected:

function successCallback(properties) {
    for (var i = 0; i properties.length; i++) {
        console.log('[' + (i + 1) + '] SIM\'s state is ' + properties[i].state);
    }
    removePropertyValueChangeListener(id);
}

var id = tizen.systeminfo.addPropertyValueArrayChangeListener('SIM', successCallback);

Note
In case of WIFI_NETWORK property, value change listener is triggered on ipAddress and ip6Address properties change in the network layer. These changes are not consistent with the status or signalStrength properties of a physical adapter in physical layer.
According to the previous constraints, in a specific situation, the listener could be triggered just before network adapter shutdown. In this case, the value of status returned by the listener will be outdated.

To ensure receiving proper values, use the following code example:

function errorCallback(err) {
    console.log('Error occurred ' + err.code)
};

function successCallback() {
    setTimeout(function() {
        tizen.systeminfo.getPropertyValue('WIFI_NETWORK', function(wifi) {
            console.log("Wi-Fi status: " + wifi.status);
        }, errorCallback);
    }, 500);
};

tizen.systeminfo.addPropertyValueChangeListener('WIFI_NETWORK', successCallback, errorCallback);