Tizen系统信息 API 指南

绿豆宝贝

概述

Tizen SystemInfo API 提供接口和方法，从而通过从选定的系统属性请求信息来获取硬件设备状态。 SystemInfo API 使您能够访问许多设备信息，如电池电量、 可用的设备存储、 版本号、 模型名称、 蜂窝网络等等。 SystemInfo API 允许您设置异步通知，在所选设备的值发生更改时通知您。 要使用此 API，请将所需的权限添加到 config.xml 文件（请参阅下面的先决条件一节）。 当应用程序启动时，SystemInfoObject 会自动在 tizen 对象中实例化。 Tizen.systeminfo 对象是 SystemInfo 接口的一个实例，提供对系统信息的访问权限。

下图显示 API 对象如何在应用程序窗口内结构化。

使用 SystemInfo API，您的应用程序可以

• 确定属性支持
• 检索设备属性
• 跟踪系统信息
  
  
  • 添加事件侦听器
  • 删除事件侦听器
  • 事件侦听器的设置选项
    
    

先决条件

SystemInfo API 有不同级别的访问权限来处理系统和敏感数据。 您可以启用在 config.xml 文件中的 SystemInfo API 的权限。

• http://tizen.org/api/setting：允许访问 SystemInfo API 功能的特权
• http://tizen.org/api/system：允许访问 SystemInfo API 的所有功能的特权
• http://tizen.org/api/systemmanager：允许访问 imei 号码和 SIM 订阅数量的特权。
  
  

为了使用 SystemManager 的特权，您应该有“合作伙伴”的特权级别。 您可以通过

1. <font size="3">$patch.bat public</font>

复制代码

从 /tools/certificate-generator/patches 执行来启用它。

建议您使用 Tizen IDE 界面编辑 config.xml 文件。

确定属性支持

Tizen SystemInfo API 提供了 SystemInfoObject 接口，使您可以获取有关系统属性的信息。 您可以使用 SystemInfo API 来访问各种设备详细信息的状态。

如果您的应用程序需要访问特定于设备的信息，您必须使用 getCapabilities 方法来检查对该属性的支持。 如果支持该属性，则返回 true。

1. <font size="3">var deviceCapabilities;
   
2. deviceCapabilities = tizen.systeminfo.getCapabilities();
   
3. if (deviceCapabilities.wifi)
   
4. {
   
5.    console.log("wifi is available");
   
6. }</font>

复制代码

PropertyId 的有效值为：

• 电池
• Cpu
• 存储
• 显示
• 设备定位
• 构建
• 区域设置
• 网络
• 无线网络
• 蜂窝网络
• SIM 卡
• 外围设备
  
• 
  
  

检索设备属性

设备属性提供有关可用于成功完成特定任务或服务的资源的信息。 要访问互联网，您可能需要知道设备所能访问的蜂窝网络的详细信息。

您可以通过检查各自的属性状态来确定。

您可以通过使用 getPropertyValue 方法（接受 3 个参数： 属性名称、 成功回调和错误回调）来检查属性的当前状态。 使用此方法，您可以检查该设备所支持的所有属性的当前状态。

SystemInfoProperty

受支持的系统信息对象所使用的常见抽象接口。

SystemInfoBattery

了解应用程序的可用电量很重要，因为应用程序需要大量电量。 您可以确定是否可以启动应用程序或是否需要警告用户设备的所剩电量水平。

使用 SystemInfoBattery，您可以获取电池电量水平

1. <font size="3"> function onSuccessCallback(battery) {
   
2.      alert("Battery Level: " + battery.level + "\nIs Charging: "
   
3.      + battery.isCharging);
   
4. }
   
5. 
   
6.   function onErrorCallback(error) {
   
7.      alert("Not supported: " + error.message);
   
8. }
   
9. tizen.systeminfo.getPropertyValue("BATTERY", onSuccessCallback, onErrorCallback);</font>

复制代码

设备可用的电量水平从 0 到 1 设置等级。 在这里，0 表示设备没有任何电量，而 1 表示该设备被充电到其最大水平。 如果设置了阈值参数，则仅当电量水平超过阈值时才会触发充电通知。

SystemInfoCpu

CPU 负载是确定应用程序效率的一个重要因素。 使用 SystemInfoCpu，您可以获取系统当前的 CPU 负载。

1. <font size="3"> function onSuccessCallback(cpu) {
   
2.      alert("The Load on device is " + cpu.load);
   
3. }
   
4. 
   
5.   function onErrorCallback(error) {
   
6.      alert("Not supported: " + error.message);
   
7. }
   
8. tizen.systeminfo.getPropertyValue("CPU", onSuccessCallback, onErrorCallback);</font>

复制代码

设备 CPU 的最小或无负载表示为 0.0，而最大负载表示为 1.0。
SystemInfoStorage

一个设备可能有几个数据存储设备与其连接。 因此，您可能希望让用户可以选择其中任何的存储设备来存储数据。

SystemInfoStorage 接口返回 SystemInfoStorageUnit 对象的集合，每个存储单元表示容量、可用空间、类型等详细信息，不管该存储单元是否可移动。

1. <font size="3"> function singleStorageInfo(storageunit) {
   
2.      alert("Type: " + storageunit.type + "    Total Capacity: " + storageunit.capacity
   
3.      + "\nFree: " + storageunit.availableCapacity + "isRemovable: " + storageunit.isRemovable);
   
4. }
   
5. 
   
6. function onErrorCallback(error) {
   
7.      alert("Not supported: " + error.message);
   
8. }
   
9. 
   
10. function onSuccessCallback(storage) {
    
11.      alert("Number of storage devices connected " + storage.units.length);
    
12.      var i = 0;
    
13.      //for(i=0; i < storage.units.length; i++)
    
14.      //{
    
15.         alert("Type: " + storage.units[i].type);
    
16.         singleStorageInfo(storage.units[i]);
    
17.      //}
    
18. }
    
19. 
    
20. tizen.systeminfo.getPropertyValue("STORAGE", onSuccessCallback, onErrorCallback);</font>

复制代码

SystemInfoDisplay

您可能需要知道设备的分辨率，以便在运行时布局应用程序。 使用 SystemInfoDisplay，您可以获取显示屏的分辨率、dpi、物理尺寸和亮度。

1. <font size="3"> function onSuccessCallback(display) {
   
2.      alert("Resolution{w, h}: " + "{" + display.resolutionWidth + ", " + display.resolutionHeight
   
3.      + "}\nDPI{w, h}: " + "{" + display.dotsPerInchWidth + ", " + display.dotsPerInchHeight
   
4.      + "}\nPhysical dimensions{w, h}: " + "{" + display.physicalWidth + ", " + display.physicalHeight
   
5.      + "}\nBrightness: " + display.brightness);
   
6. }
   
7. 
   
8.   function onErrorCallback(error) {
   
9.      alert("Not supported: " + error.message);
   
10. }
    
11. tizen.systeminfo.getPropertyValue("DISPLAY", onSuccessCallback, onErrorCallback);</font>

复制代码

SystemInfoDeviceOrientation

您可能需要知道当前的设备显示方向。 使用 SystemInfoDeviceOrientation，您可以获得当前设备方向。

1. <font size="3"> function onSuccessCallback(orientation) {
   
2.      alert("Device Orientation =" + orientation.status);
   
3. }
   
4. 
   
5.   function onErrorCallback(error) {
   
6.      alert("Not supported: " + error.message);
   
7. }
   
8. tizen.systeminfo.getPropertyValue("DEVICE_ORIENTATION", onSuccessCallback, onErrorCallback);</font>

复制代码

SystemInfoBuild

使用 SystemInfoBuild，您可以获取关于设备制造商和型号的信息。

1. <font size="3"> function onSuccessCallback(device) {
   
2.      alert("Device Model =" + device.model + " Manufacturer = " + device.manufacturer);
   
3. }
   
4. 
   
5.   function onErrorCallback(error) {
   
6.      alert("Not supported: " + error.message);
   
7. }
   
8. tizen.systeminfo.getPropertyValue("BUILD", onSuccessCallback, onErrorCallback);</font>

复制代码

SystemInfoLocale

使用 SystemInfoLocale，您可以获取当前设备的区域设置信息。

1. <font size="3"> function onSuccessCallback(device) {
   
2.      alert("Language =" + device.language + " Country = " + device.country);
   
3. }
   
4. 
   
5.   function onErrorCallback(error) {
   
6.      alert("Not supported: " + error.message);
   
7. }
   
8. tizen.systeminfo.getPropertyValue("LOCALE", onSuccessCallback, onErrorCallback);</font>

复制代码

SystemInfoNetwork

您可能需要知道网络类型是否按照用户的要求提供足够的连接速度。 使用 SystemInfoNetwork，您可以确定网络类型。

1. <font size="3">  function onSuccessCallback(network) {
   
2.      alert(" network type: " + network.networkType);
   
3. }
   
4. 
   
5.   function onErrorCallback(error) {
   
6.      alert("Not supported: " + error.message);
   
7. }
   
8. 
   
9. tizen.systeminfo.getPropertyValue("NETWORK", onSuccessCallback, onErrorCallback);</font>

复制代码

SystemInfoWifiNetwork

您可能希望您的应用程序访问设备的 Wi-Fi 网络。 要通过您的应用程序访问网络，您需要某些网络详细信息。 使用 SystemInfoWifiNetwork，您可以确定网络的可用性、SSID、IP 地址和信号强度。

1. <font size="3"> function onSuccessCallback(wifi) {
   
2.      alert("Status: " + wifi.status +  "    SSID: " + wifi.ssid
   
3.      + "\nIP Address: " + wifi.ipAddress + "\nIPV6 Address: " + wifi.ipv6Address + "    Signal Strength: " + wifi.signalStrength);
   
4. }
   
5. 
   
6.   function onErrorCallback(error) {
   
7.      alert("Not supported: " + error.message);
   
8. }
   
9. tizen.systeminfo.getPropertyValue("WIFI_NETWORK", onSuccessCallback, onErrorCallback);</font>

复制代码

Wi-Fi 网络的 SSID 表示由制造商指定的网络公共名称。 此 SSID 通过使用 32 个字符的字母数字键唯一地标识一个网络。 此密钥确保只有使用相同密钥或 SSID 的设备可以互相通信。
SystemInfoCellularNetwork

大多数移动设备连接到蜂窝网络，使设备可以连接到并调用其他设备。 要通过您的应用程序访问此网络，您需要某些网络详细信息。 使用 SystemInfoCellularNetwork，您可以确定网络状态、接入点、IP 地址、国家/地区代码、蜂窝 ID、imei、位置区码，以及是否在设备上启用漫游。

1. <font size="3">function onSuccessCallback(cellular) {
   
2.      alert("Status: " + cellular.status +  "    Access Point: " + cellular.apn
   
3.      + "\nIP Address: " + cellular.ipAddress + "\nIPV6 Address: " + cellular.ipv6Address + "    Country code: " + cellular.mcc
   
4.      + "\nNetwork Code: " + cellular.mnc + "    Cell ID: " + cellular.cellId
   
5.      + "\nLocation Area code: " + cellular.lac + "    Is Roaming: " + cellular.isRoaming)
   
6.      + "\nFlight Mode: " + cellular.isFlightMode + "    IMEI: " + cellular.imei);
   
7. }
   
8. 
   
9.   function onErrorCallback(error) {
   
10.      alert("Not supported: " + error.message);
    
11. }
    
12. tizen.systeminfo.getPropertyValue("CELLULAR_NETWORK", onSuccessCallback, onErrorCallback);</font>

复制代码

SystemInfoSIM

使用 SystemInfoSIM，您可以获取有关设备 SIM 卡（如运营商名称和 mcc 码）的信息。

1. <font size="3"> function onSuccessCallback(sim) {
   
2.      alert("State: " + sim.state + "Operator Name: " + sim.operatorName +  "  SIM card subscriber number: " + sim.msisdn
   
3.      + "\nIntegrated Circuit Card ID: " + sim.iccid + "   Mobile Country Code (MCC): " + sim.mcc
   
4.      + "\nMobile Network Code (MNC): " + sim.mnc + "   Mobile Subscription Identification Number (MSIN): " + sim.msin
   
5.      + "\nService Provider Name (SPN): " + sim.spn);
   
6. }
   
7. 
   
8.   function onErrorCallback(error) {
   
9.      alert("Not supported: " + error.message);
   
10. }
    
11. tizen.systeminfo.getPropertyValue("SIM", onSuccessCallback, onErrorCallback);</font>

复制代码

SystemInfoPeripheral

使用 SystemInfoPeripheral，您可以获取有关设备的视频输出状态信息。

1. <font size="3"> function onSuccessCallback(device) {
   
2.      alert("Video out: " + device.isVideoOutputOn);
   
3. }
   
4. 
   
5.   function onErrorCallback(error) {
   
6.      alert("Not supported: " + error.message);
   
7. }
   
8. tizen.systeminfo.getPropertyValue("PERIPHERAL", onSuccessCallback, onErrorCallback);</font>

复制代码

跟踪系统信息

设备的一个或多个属性的状态改变可能会影响您的应用程序。 因此，检查应用程序的关键属性更新很重要。

添加事件侦听器

您可以使用 addPropertyValueChangeListener 方法，订阅系统属性的值发生变更的通知。

该 addPropertyValueChangeListener 方法采用四个参数。 前三个参数分别 addPropertyValueChangeListener 是您想要观察的属性名称、属性更改时调用的成功回调，以及观察期间设备发生错误时调用的错误回调。 最后一个参数是可选的，表示包含不同选项的 SystemInfoOptions 类型对象，用于获取请求的属性。

1. <font size="3"> function onSuccessCallback(battery) {
   
2.      console.log("Low battery:  " + battery.level);
   
3. }
   
4. 
   
5. tizen.systeminfo.addPropertyValueChangeListener("BATTERY", onSuccessCallback,
   
6. {lowThreshold : 0.2});</font>

复制代码

可以分别存储由 tizen.systeminfo.addPropertyValueChangeListener() 返回的每个标识符，以删除注册的回调（取消订阅）。

删除事件侦听器

您可以通过使用 removePropertyValueChangeListener 方法取消订阅通知来删除事件侦听器。

1. <font size="3">var id = null;
   
2. function onSuccessCallback(battery) {
   
3.     console.log("New value for Battery level is " + battery.level);
   
4.     if (id != null) // After receiving the first notification, we clear it
   
5.         tizen.systeminfo.removePropertyValueChangeListener(id);
   
6. }
   
7. 
   
8. id = tizen.systeminfo.addPropertyValueChangeListener("BATTERY", onSuccessCallback)</font>

复制代码

事件侦听器的设置选项

您可能仅需要在请求的属性的值超过一个特定的限制时获得通知。 SystemInfoOptions 提供用于获取所请求属性的选项。 您可以设置属性的阈值，仅当属性值超过阈值时便触发通知。

SystemInfoOptions 包含三个属性，即 highThreshold、lowThreshold 和 timeout。 如果属性值低于lowThreshold 或高于highThreshold，则调用成功回调。 如果经过了数毫秒，由于 addPropertyValueChangeListener 方法的调用超过了超时的值，操作被中断。

1. <font size="3">var id = null;
   
2. function onSuccessCallback(battery) {
   
3.      alert("Batter Low! Level = " + battery.level);
   
4.      if (id != null) // After receiving the first notification, we clear it
   
5.         tizen.systeminfo.removePropertyValueChangeListener(id);
   
6. }
   
7. 
   
8. id = tizen.systeminfo.addPropertyValueChangeListener("BATTERY", onSuccessCallback, {lowThreshold : 0.2});</font>

复制代码

文件附件:
systeminfodemo.zip