Device

The Device API provides access to some device level functionality that is only available on Symbol devices such as suspend, calibrate, powerOff, wake, reboot etc.

Enabling the API

In order to use this API you must include the following extension in your build.yml. :::ruby extensions: [“symboldevice”]

The symboldevice extension is also included automatically if you specify the following in your build.yml :::ruby app_type: “rhoelements”

If you are building a Windows Mobile or Windows CE app with this API, you must set your app_type as “rhoelements” in your build.yml as shown here.

JavaScript Usage

Be sure to review the JavaScript API Usage guide for important information about using this API in JavaScript.

Ruby Usage

Be sure to review the Ruby API Usage guide for important information about using this API in Ruby.

Methods

calibrate

(CallBackHandler callback)

Carries out the screen calibration routine.

JavaScript Ruby Windows Mobile, Windows CE, Windows Embedded

Parameters

callback : CallBackHandler Optional

Async Callback Returning Parameters: HASH

status : STRING

Whether or not the calibration was successfully done, status will be ‘success’ or ‘failed’.
message : STRING

If ‘status’ == ‘success’, the message will contain ‘Calibration was done succesfully.’ and if ‘status’ == ‘failed’, the message will contain ‘Calibration was failed.’.

Synchronous Return:

Void : this method also supports async callbacks - check the Callback tab for callback return parameters.

Method Access:

Class Method: This method can only be accessed via the API class object.
- JavaScript: Rho.Device.calibrate(CallBackHandler callback)
- Ruby: Rho::Device.calibrate(CallBackHandler callback)

idle

(CallBackHandler callback)

Puts the device into idle mode. In this mode, the screen display is turned off. Callback is triggered only for ‘failed’ status.

JavaScript Ruby Windows Mobile, Windows CE, Windows Embedded

Parameters

callback : CallBackHandler Optional

Async Callback Returning Parameters: HASH

status : STRING

If the mode of the device was not changed to idle mode, status will be ‘failed’. In all other cases, it will remain empty.
message : STRING

If ‘status’ == ‘failed’, the message will contain an error message. In all other cases, it will remain empty.

Synchronous Return:

Void : this method also supports async callbacks - check the Callback tab for callback return parameters.

Method Access:

Class Method: This method can only be accessed via the API class object.
- JavaScript: Rho.Device.idle(CallBackHandler callback)
- Ruby: Rho::Device.idle(CallBackHandler callback)

powerOff

(CallBackHandler callback)

Puts the device into power off mode. In this mode the device will draw no power. Only supported on SB1. Callback is triggered only for ‘failed’ status.

JavaScript Ruby Windows Mobile, Windows CE, Windows Embedded

Parameters

callback : CallBackHandler Optional

Async Callback Returning Parameters: HASH

status : STRING

If the powerOff was unsuccessful, status will be ‘failed’. In all other cases, it will remain empty.
message : STRING

If ‘status’ == ‘failed’, the message will contain an error message. In all other cases, it will remain empty.

Synchronous Return:

Void : this method also supports async callbacks - check the Callback tab for callback return parameters.

Method Access:

Class Method: This method can only be accessed via the API class object.
- JavaScript: Rho.Device.powerOff(CallBackHandler callback)
- Ruby: Rho::Device.powerOff(CallBackHandler callback)

reboot

(STRING bootType, CallBackHandler callback)

It reboots the terminal using either a Warm or Cold software boot (as specified). Note on CE6 devices a “ColdCAD” boot is required to replicate the Coldboot key sequence, e.g. 1+9+Power on an MC3000. Callback is triggered only for ‘failed’ status.

JavaScript Ruby Windows Mobile, Windows CE, Windows Embedded

Parameters

bootType : STRING
callback : CallBackHandler Optional

Async Callback Returning Parameters: HASH

status : STRING

If the reboot was unsuccessful, status will be ‘failed’. In all other cases, it will remain empty.
message : STRING

If ‘status’ == ‘failed’, the message will contain an error message. In all other cases, it will remain empty.

Synchronous Return:

Void : this method also supports async callbacks - check the Callback tab for callback return parameters.

Method Access:

Class Method: This method can only be accessed via the API class object.
- JavaScript: Rho.Device.reboot(STRING bootType, CallBackHandler callback)
- Ruby: Rho::Device.reboot(STRING bootType, CallBackHandler callback)

suspend

(CallBackHandler callback)

Puts the device into suspend mode. On suspend, the device goes to hibernation mode. Callback is triggered only for ‘failed’ status. In some devices, the suspend doesnot happen instead it puts the device into an idle state.

JavaScript Ruby Windows Mobile, Windows CE, Windows Embedded

Parameters

callback : CallBackHandler Optional

Async Callback Returning Parameters: HASH

status : STRING

If the suspend was unsuccessful, status will be ‘failed’. In all other cases, it will remain empty.
message : STRING

If ‘status’ == ‘failed’, the message will contain an error message. In all other cases, it will remain empty.

Synchronous Return:

Void : this method also supports async callbacks - check the Callback tab for callback return parameters.

Method Access:

Class Method: This method can only be accessed via the API class object.
- JavaScript: Rho.Device.suspend(CallBackHandler callback)
- Ruby: Rho::Device.suspend(CallBackHandler callback)

wake

(CallBackHandler callback)

In WM/CE, wakes the device from idle state to active state. Callback is triggered only for ‘failed’ status. In Android, it will turn on the display, if it was off. The callback parameter is ignored in Android platform.

JavaScript Ruby Android Windows Mobile, Windows CE, Windows Embedded

Parameters

callback : CallBackHandler Optional

Async Callback Returning Parameters: HASH

status : STRING

In WM/CE, if the wake was unsuccessful, status will be ‘failed’. In all other cases, it will remain empty.
message : STRING

In WM/CE, if ‘status’ == ‘failed’, the message will contain an error message. In all other cases, it will remain empty.

Synchronous Return:

Void : this method also supports async callbacks - check the Callback tab for callback return parameters.

Method Access:

Class Method: This method can only be accessed via the API class object.
- JavaScript: Rho.Device.wake(CallBackHandler callback)
- Ruby: Rho::Device.wake(CallBackHandler callback)

Examples

Setting callback

Setting a callback

JavaScript
Ruby

//Callback is optional, user can call the API with or without callback.
//User can set the callback in the below manner.                            
function mycallback(data){
    var myMessage = "Status:" + data.status + "\n";
    if(data.message != ""){
        myMessage += "Message:" + data.message;
    }
    alert(myMessage);
}

#Callback is optional, user can call the API with or without callback.
#User can set the callback in the below manner.                         
def mycallback
    myMessage = "Status:" + @params['status'] + "\n";
        if(@params['message'] != "")
            myMessage += "Message:" + @params['message']
        end     
    Alert.show_popup(myMessage)
end

Calibrating the device

Calibrating the device

JavaScript
Ruby

//Calibrating the device with callback
Rho.Device.calibrate(mycallback);   
//On successful calibration, callback will update the 'status' as 'success' and 'message' as 'Calibration was done succesfully.'.
//On unsuccessful calibration, callback will update the 'status' as 'failed' and 'message' as 'Calibration was failed.'.
                            
//Calibrating the device without callback
Rho.Device.calibrate();

#Calibrating the device with callback
Rho::Device.calibrate(mycallback);  
#On successful calibration, callback will update the 'status' as 'success' and 'message' as 'Calibration was done succesfully.'.
#On unsuccessful calibration, callback will update the 'status' as 'failed' and 'message' as 'Calibration was failed.'.

#Calibrating the device without callback
Rho::Device.calibrate();

Suspending the device

Suspending the device

JavaScript
Ruby

//Suspending the device with callback
Rho.Device.suspend(mycallback);
//On successful suspend, callback will not be updated.
//On unsuccessful suspend, callback will update the 'status' as 'failed' and 'message' will contain the error message.
                            
//Suspending the device without callback
Rho.Device.suspend();

#Suspending the device with callback
Rho::Device.suspend(mycallback);
#On successful suspend, callback will not be updated.
#On unsuccessful suspend, callback will update the 'status' as 'failed' and 'message' will contain the error message.
                            
#Suspending the device without callback
Rho::Device.suspend();

Power Off the device

Power Off the device

JavaScript
Ruby

//Power Off the device with callback
Rho.Device.powerOff(mycallback);    
//On successful powerOff, callback will not be updated.
//On unsuccessful powerOff, callback will update the 'status' as 'failed' and 'message' will contain the error message.
                            
//Power Off the device without callback
Rho.Device.powerOff();

#Power Off the device with callback
Rho::Device.powerOff(mycallback);   
#On successful powerOff, callback will not be updated.
#On unsuccessful powerOff, callback will update the 'status' as 'failed' and 'message' will contain the error message.
                            
#Power Off the device without callback
Rho::Device.powerOff();

Switching device to idle mode

Switching device to idle mode

JavaScript
Ruby

//Switching device to idle mode with callback
Rho.Device.idle(mycallback);    
//On successful idle, callback will not be updated.
//On unsuccessful idle, callback will update the 'status' as 'failed' and 'message' will contain the error message.
                            
//Switching device to idle mode without callback
Rho.Device.idle();

#Switching device to idle mode with callback
Rho::Device.idle(mycallback);   
#On successful idle, callback will not be updated.
#On unsuccessful idle, callback will update the 'status' as 'failed' and 'message' will contain the error message.
                            
#Switching device to idle mode without callback
Rho::Device.idle();

Wake the device

Wake the device

JavaScript
Ruby

//Wake the device with callback
//Note: callback is ignored in Android platform. Hence no update will be retrieved on Android platform.
Rho.Device.wake(mycallback);    
//On successful wake, callback will not be updated.
//On unsuccessful wake, callback will update the 'status' as 'failed' and 'message' will contain the error message.
                            
//Wake the device without callback
Rho.Device.wake();

#Wake the device with callback
#Note: callback is ignored in Android platform. Hence no update will be retrieved on Android platform.
Rho::Device.wake(mycallback);   
#On successful wake, callback will not be updated.
#On unsuccessful wake, callback will update the 'status' as 'failed' and 'message' will contain the error message.
                            
#Wake the device without callback
Rho::Device.wake();

Rebooting the device

Rebooting the device

JavaScript
Ruby

//With callback

//The callback is updated only for failed cases as mentioned below:-
//For 'Warm' boot, the callback contains 'status' as 'failed' and 'message' as 'Failed to do Warm booting.'.
//For 'Cold' boot, the callback contains 'status' as 'failed' and 'message' as 'Failed to do Cold booting.'.
//For 'ColdCAD' boot, the callback contains 'status' as 'failed' and 'message' as 'Failed to do ColdCAD booting.'.
//Other than 'Warm' or 'Cold' or 'ColdCAD' boot, the callback contains 'status' as 'failed' and 'message' as 'Failed to do Warm booting.'.

//Rebooting the device using the string value as 'Warm'. 
Rho.Device.reboot("Warm",mycallback);

//Rebooting the device using the string value as 'Cold'. Note this feature may not be supported on all devices.
Rho.Device.reboot("Cold",mycallback);
                            
//Rebooting the device using the string value as 'ColdCAD'. Note this feature may not be supported on all devices.
Rho.Device.reboot("ColdCAD",mycallback);    

//Rebooting the device with an empty string, results in warm booting of the device. 
Rho.Device.reboot("",mycallback);   

//Rebooting the device without passing any argument and only with callback, results in warm booting of the device.
Rho.Device.reboot(mycallback);  

//Rebooting the device with any string other than 'Warm' or 'Cold' or 'ColdCAD', results in warm booting of the device.
Rho.Device.reboot("XYZ",mycallback);
                            
//Without callback
//Rebooting the device using the string value as 'Warm'. 
Rho.Device.reboot("Warm");

//Rebooting the device using the string value as 'Cold'. Note this feature may not be supported on all devices.
Rho.Device.reboot("Cold");
                            
//Rebooting the device using the string value as 'ColdCAD'. Note this feature may not be supported on all devices.
Rho.Device.reboot("ColdCAD");   

//Rebooting the device with an empty string, results in warm booting of the device. 
Rho.Device.reboot("");  

//Rebooting the device without passing any argument, results in warm booting of the device.
Rho.Device.reboot();    

//Rebooting the device with any string other than 'Warm' or 'Cold' or 'ColdCAD', results in warm booting of the device.
Rho.Device.reboot("XYZ");

#With callback

#The callback is updated only for failed cases as mentioned below:-
#For 'Warm' boot, the callback contains 'status' as 'failed' and 'message' as 'Failed to do Warm booting.'.
#For 'Cold' boot, the callback contains 'status' as 'failed' and 'message' as 'Failed to do Cold booting.'.
#For 'ColdCAD' boot, the callback contains 'status' as 'failed' and 'message' as 'Failed to do ColdCAD booting.'.
#Other than 'Warm' or 'Cold' or 'ColdCAD' boot, the callback contains 'status' as 'failed' and 'message' as 'Failed to do Warm booting.'.

#Rebooting the device using the string value as 'Warm'. 
Rho::Device.reboot("Warm",mycallback);

#Rebooting the device using the string value as 'Cold'. Note this feature may not be supported on all devices.
Rho::Device.reboot("Cold",mycallback);
                            
#Rebooting the device using the string value as 'ColdCAD'. Note this feature may not be supported on all devices.
Rho::Device.reboot("ColdCAD",mycallback);       

#Rebooting the device with an empty string, results in warm booting of the device. 
Rho::Device.reboot("",mycallback);  

#Rebooting the device without passing any argument and only with callback, results in warm booting of the device.
Rho::Device.reboot(mycallback); 

#Rebooting the device with any string other than 'Warm' or 'Cold' or 'ColdCAD', results in warm booting of the device.
Rho::Device.reboot("XYZ",mycallback);   
                            
#Without callback                           
#Rebooting the device using the string value as 'Warm'. 
Rho::Device.reboot("Warm");

#Rebooting the device using the string value as 'Cold'. Note this feature may not be supported on all devices.
Rho::Device.reboot("Cold");
                            
#Rebooting the device using the string value as 'ColdCAD'. Note this feature may not be supported on all devices.
Rho::Device.reboot("ColdCAD");      

#Rebooting the device with an empty string, results in warm booting of the device. 
Rho::Device.reboot(""); 

#Rebooting the device without passing any argument, results in warm booting of the device.
Rho::Device.reboot();   

#Rebooting the device with any string other than 'Warm' or 'Cold' or 'ColdCAD', results in warm booting of the device.
Rho::Device.reboot("XYZ");

Remarks

General

Note that some devices may not support all the API’s or there is a possiblities of discrepancy across BSP’s & platforms.

Power Off

Note that some devices may not support power off feature. Those devices may either throw an error message or it may enter into Sleep mode.

Reboot

Note that in WM5.0 and above, there is no software difference between a warm and a cold boot as the device uses persistent storage; both the file and registry will remain the same after boot. In WM/CE, not all device support Cold or ColdCAD feature. Device may warm boot even though any of these option has been selected.

Interaction with Unattended Method of the Push Module

The suspend functionality is incompatible with the unattended functionality of the push module and they should not be used together.

wake Method

The wake functionality can be used along with Push module. For eg: in the push detected event the user can call the wake method to wake the device.

Device

Methods - Class

Enabling the API

JavaScript Usage

Ruby Usage

Methods

Examples

Remarks