1. 개요

– Web Context에서 단말기의 상태정보(Orientation, Battery, Resolution ..)에 접근하기 위한 Spec.
이때 단말기의 상태정보는 Category별로 구분되어 tree의 형태로 구성된다.
Tree의 정보는 Vocabulary Specified by WAC에 정의되어 있다.
Tree를 구성하는 정보
1) Aspects : Device의 정보들 중에서 관련이 있는 정보를 묶는 특징.
2) Components : 동일한 Aspect에 대해서 서로 다른 instance를 갖을 때 이를 표현하기 위한 값.
(e.g ‘Memory’라는 Aspect는 ‘physical’, ‘virtual’, ‘storage’ 3개의 Component를 갖을 수 있다.)
*_default는 Aspect에 대해서 기본이 되는 Component를 지칭하고 *_active는 Aspect에 대해서
활성화된 Component를 지칭한다.
3) Properties : Aspect를 구성하는 요소, (e.g Memory Aspect는 size, removable, availableSize의
property를 갖을 수 있다.)
단말기의 상태정보를 얻고자 할 때 필수정보는 Aspect와 Property 이름이다.
1.1. Features
http://wac.org/api/devicestatus를 config.xml에 선언해야 해당 기능을 사용할 수 있다.
2. Interfaces
 2.1. GetPropertySuccessCallback
– Property의 현재값을 정상적으로 얻어왔을 때 호출되는 Callback 함수.
void onSuccess(propertyValue);
현재 Property의 값이 인자로 넘겨지게되고, 만약 얻어올 수 없을 경우 ‘undefined’를 넘겨준다.
 2.2. PropertyChangeSuccessCallback
– Listener의 Success Callback, watchPropertyChange함수를 통해 등록된 property의 값이
변경될 경우 호출되는 Callback함수이다.
void onPropertyChange(property, newValue);
어떤 Property의 값이 변경되었는지를 나타내는 property인자와 어떤 값으로 변경되었는지를 
나타내는 newValue가 인자로 전달된다.
 2.3. DeviceStatusError
– UNKNOWN_ERROR = 0;                         일반적인 에러
– PERMISSION_DENIED_ERROR = 1;         권한을 얻지 못해서 발생한 에러
– TIMEOUT_ERROR = 2;                          시간을 초과하여 발생한 에러
– NOT_SUPPORTED_ERROR = 3;              기능을 지원하지 않아서 발생한 에러
– NOT_FOUND = 4;                                  property나 aspect가 undefined여서 발생한 에러
 2.4. DeviceStatusManager
         – 단말기의 상태정보를 얻기 위한 함수와 단말기의 상태가 변경되었을 때 notify를 받기 위한 함수를 제공하는 모듈

1) StringArray getComponents(String aspect);
해당 Aspect의 모든 Component의 이름을 Array of String의 형태로 반환하는 함수
만약 Aspect가 유효하지 않거나, platform에서 지원하지 않을 경우 null을 반환한다.
    code ex) var cameras = devicestatus.getComponents(‘Camera’);
2) boolean isSupported(String aspect, [Optional]String property);
Property of Aspect가 현재 단말기에서 지원하는지 여부를 boolean type으로 반환하는 함수.
만약 property 인자의 값이 null이거나 전달되지 않을 경우, Aspect의 지원여부를 확인한 뒤 해당 Aspect에 
지원하는 property가 하나라도 있을 경우 true를 반환하고, 없을 경우 false를 반환한다.
    code ex) var isSupported = deviceapis.devicestatus.isSupported(‘Battery’, ‘batteryLevel’);
3) PendingOperation getPropertyValue(PropertyRef prop, successCallback, errorCallback);
인자로 전달된 property의 현재값을 successCallback의 인자로 반환하는 함수.
property인자 중 aspect와 property는 mandatory고 component의 경우는 optional이다.
함수를 호출할 때 Success했을 때와 Fail했을 때 호출될 함수를 각각 등록하여 함수의 수행 결과를 전달받을 수 
있도록 한다.
    code ex) function successCallback(value) {
                      alert(“the battery level is ” + value);
                  }
                  function errorCallback(error) {
                      alert(“error occur ” + error.message);
                  }
                  var prop = {aspect:”Battery”, property:”batteryLevel”};
                  deviceapis.devicestatus.getPropertyValue(prop, successCallback, errorCallback);
4) unsigned long watchPropertyChange(PropertyRef prop, successCallback, 
   [Optional] errorCallback, [Optional] WatchOptions options);
Property가 변경될 때 Notification을 받기위해 Listener를 등록하는 함수. 
등록된 Property의 값이 option을 충족한채로 변경이 될 때마다 successCallback을 호출하여 변경된 값을
전달한다.
만약 options에 invalid한 option이 하나라도 존재할 경우 전체 options가 무시된다.
    code ex) function successCallback(ref, value) {
                      alert(“New value for ” + ref.property + ” is ” + value);
                  }
                  var prop = {aspect:”Battery”, property:”batteryLevel”};
                  deviceapis.devicestatus.watchPropertyChange(prop, successCallback);

5) void clearPropertyChange(unsigned long watchHandler);
watchHandler가 유효하고 현재 Watch 상태에 있을 경우 이를 종료시켜 추가적인 Callback이 호출되지
않도록 한다. 만약 watchHandler가 invalid할 경우 아무런 동작도 취하지 않은채 종료한다.
watchHandler : watchPropertyChange()함수가 반환한 identifier 값.

5. PropertyRef
– property를 참조하기 위해 사용되는 구조체로써 아래와 같은 구조를 갖는다.
interface PropertyRef {
[Optional] DOMString component;
[Mandatory] DOMString aspect;
[Mandatory] DOMString property;
}
code ex) var batteryLevel = {aspect:”battery”, component:”_default”, property:”batteryLevel”};

6. WatchOptions
– watchPropertyChange 함수를 호출할 때 사용가능 한 Option 항목이 정의된 구조체
interface WatchOptions {
long minTimeout;
long maxTimeout;
long minChangePercent;
}
minTimeout : Notification간의 최소간격을 milliseconds로 정의한 값. minTimeout내에 발생한 
이벤트는 무시된다. minTimeout은 반드시 maxTime보다 작아야 하며, 0 또는 null일 경우 무시된다.  
maxTimeout : Notification간의 최대간격을 milliseconds로 정의한 값. 만약 property가 변경되지
않았다고 하더라도 maxTimeout만큼의 시간이 소요되었을 경우 Notification이 호출된다.
maxTimeout은 반드시 minTimeout보다 커야 하며, 0 또는 null일 경우 무시된다.
minChangePercent : notification이 호출되기 위해 필요한 최소한의 변화량을 숫자로 정의한 값.
현재 property의 값이 100이고 minChangePercent가 20일 경우 property의 값이 80이하로 내려가거나
120이상으로 올라갈 경우에만 notification이 호출된다.

7. DeviceapisDeviceStatusManager
– deviceapis object의 attribute로써 DeviceStatus Module의 기능을 갖는 interface.
실제로 WRT를 구현하는 입장에서 issue가 될만한 것은 watchPropertyChange함수를 통하여 다수의 property를
확인할 때, 실제 Platform에서도 해당 property의 값이 변경될 때 Callback으로 Notify를 주는지 여부와 만약 
그렇지 않다면 Property의 값이 변경되었는지 여부를 직접 확인하는 것이 Battery나 CPU사용량에 무리가 되지는 
않는지 등을 Check!
Watch만 해놓고 clear를 하지 않을 때 Memory에 부담이 되지 않는지 여부 Check!

Aspects

Aspect Properties Component Aliases Description
Battery batteryLevelbatteryTime,batteryBeingCharged Describes one battery in a device. See also Delivery Context Ontology: hard:battery
CellularHardware status   It represents a device hardware that can be used to access to mobile operator telephony networks. See also Delivery Context Ontology: hard:CellularHardware
CellularNetwork isInRoamingsignalStrength,operatorName   It represents a Cellular Network. See also Delivery Context Ontology: net:Network
Device imeimodelversionvendor   It represents the device. See also Delivery Context Ontology: dcn:Device
Display resolutionHeightpixelAspectRatiodpiY
resolutionWidthdpiXcolorDepth
It represents a visual display on the device. See also Delivery Context Ontology:hard:Display
MemoryUnit sizeremovableavailableSize _default It represents a memory unit used in the device. See also Delivery Context Ontology:hard:MemoryUnit
OperatingSystem languageversionnamevendor It represents the device operating system. See also Delivery Context Ontology:soft:OperatingSystem
WebRuntime supportedFormatsversionname,vendor _active,_default It represents a Web runtime capable of executing widgets. See also Delivery Context Ontology: web:WebRuntime
WiFiHardware status   It represents hardware in a device that can be used to access to WiFi networks. See also Delivery Context Ontology: hard:WiFiHardware
WiFiNetwork ssidsignalStrengthnetworkStatus   It represents a WiFi Network. See also Delivery Context Ontology: net:WiFiNetwork