Functions
The Battery API contains the following functions, which belong to the kony.os Namespace.
Retrieves the current percentage charge level of the device battery, as an integer value.
Syntax
kony.os.getBatteryLevel();
Input Parameters
None
Example
getBatteryLevel: function() { kony.os.registerBatteryService(this.batterySuccessCallback); var battery = kony.os.getBatteryLevel(); kony.os.unregisterBatteryService(); this.view.lblDisplay.text = battery + "%"; },
Return Values
Returns an integer that ranges from 0-100 (inclusive) that specifies the battery's current charge level in percentage. For example, a return value of 30 specifies that the current charge level of the battery is 30%.
Platform Availability
- iOS
- Android
Retrieves the current state of the battery.
Syntax
kony.os.getBatteryState();
Input Parameters
None
Example
//This code is used to obtain your device battery state getBatteryState: function() { kony.os.registerBatteryService(this.batterySuccessCallback); var batteryState = kony.os.getBatteryState(); if (kony.os.BATTERY_STATE_CHARGING == batteryState) { alert("The Device is charging"); kony.os.unregisterBatteryService(); } else if (kony.os.BATTERY_STATE_DISCHARGING == batteryState) { alert("The Device is discharging"); kony.os.unregisterBatteryService(); } else if (kony.os.BATTERY_STATE_FULL == batteryState) { alert("The Device is completely charged"); kony.os.unregisterBatteryService(); } else if (kony.os.BATTERY_STATE_UNKNOWN == batteryState) { alert("The Device charging state is unkonwn"); kony.os.unregisterBatteryService(); } },
Return Values
Returns a constant from the Battery State Constants.
Remarks
The battery state indicates whether it is charging, discharging, and so forth.
Platform Availability
- iOS
- Android
Registers for the battery monitoring service of the device operating system. The callback is delivered to the most recent registered battery service.
NOTE: Whenever the battery state changes or for every 1% change in the battery level, a callback to the registerBatteryService function is triggered.
Syntax
kony.os.registerBatteryService(callbackMethod);
Input Parameters
Parameter | Description |
---|---|
callbackMethod | A JavaScript function that is automatically invoked when you register to the battery monitoring service of the device OS. |
Example
/*This code is used to register a battery service and deregister the service based on your battery level*/ registerBatteryService: function() { kony.os.registerBatteryService(this.mybatterychangecallback); var batterylevel = kony.os.getBatteryLevel(); }, mybatterychangecallback: function(batteryInfo) { var batterylevel = batteryInfo.batterylevel; if (batterylevel <= 20) { alert("The Battery Level is below 20%, make sure that you charge your device"); } else { kony.os.unregisterBatteryService(); alert("We are unregistering the Battery Service as it might cause an overhead"); } },
Return Values
None
Limitations
- The callback for the registered battery service is delivered only when the application is running; this is because, you can only receive notifications when the application is in the foreground for the iOS and Android platforms.
- The callback to the registered battery service is delivered after every one minute duration for iOS; whereas in case of in Android, the callback is delivered for every 1% change in the battery charge.
Platform Availability
- iOS
- Android
This API stops the monitoring process of the device battery. You must call this API when the use of the battery monitoring service has been completed, to reduce the overhead.
NOTE: After your app calls the kony.os.unregisterBatteryService API, the callback function registered by the kony.os.registerBatteryService API is no longer invoked.
Syntax
kony.os.unregisterBatteryService();
Input Parameters
None
Example
/*This code is used to register a battery service and deregister the service based on your battery level*/ registerBatteryService: function() { kony.os.registerBatteryService(this.mybatterychangecallback); var batterylevel = kony.os.getBatteryLevel(); }, mybatterychangecallback: function(batteryInfo) { var batterylevel = batteryInfo.batterylevel; if (batterylevel <= 20) { alert("The Battery Level is below 20%, make sure that you charge your device"); } else { kony.os.unregisterBatteryService(); alert("We are unregistering the Battery Service as it might cause an overhead"); } },
Return Values
None
Platform Availability
- iOS
- Android