Onactivate, ondeactivate & onfailure callbacks

This commit is contained in:
Sebastián Katzer 2014-12-14 00:04:12 +01:00
parent 1c289f7d01
commit 5fa96556ae
7 changed files with 269 additions and 73 deletions

View File

@ -1,6 +1,7 @@
## ChangeLog
#### Version 0.6.0 (not yet released)
- [feature:] Android support
- [feature:] `onactivate`, `ondeactivate` and `onfailure` callbacks.
- [___change___:] Disabled by default
- [enhancement:] iOS does not require user permissions, internet connection and geo location anymore.

View File

@ -22,7 +22,7 @@ The plugin focuses on enterprise-only distribution and may not compliant with al
1. [Supported Platforms](#supported-platforms)
2. [Installation](#installation)
3. [ChangeLog](#changelog)
4. [Using the plugin](#using-the-plugin)
4. [Usage](#usage)
5. [Examples](#examples)
6. [Platform specifics](#platform-specifics)
@ -65,6 +65,7 @@ More informations can be found [here][PGB_plugin].
## ChangeLog
#### Version 0.6.0 (not yet released)
- [feature:] Android support
- [feature:] `onactivate`, `ondeactivate` and `onfailure` callbacks.
- [___change___:] Disabled by default
- [enhancement:] iOS does not require user permissions, internet connection and geo location anymore.
@ -72,13 +73,19 @@ More informations can be found [here][PGB_plugin].
- The former `plugin.backgroundMode` namespace has been deprecated and will be removed with the next major release.
- See [CHANGELOG.md][changelog] to get the full changelog for the plugin.
#### Known issues
- Plug-in is broken on Windows Phone 8.1 platform.
## Using the plugin
## Usage
The plugin creates the object ```cordova.plugins.backgroundMode``` with the following methods:
1. [backgroundMode.enable][enable]
2. [backgroundMode.disable][disable]
2. [backgroundMode.configure][configure]
3. [backgroundMode.onactivate][onactivate]
4. [backgroundMode.ondeactivate][ondeactivate]
5. [backgroundMode.onfailure][onfailure]
### Plugin initialization
The plugin and its methods are not available before the *deviceready* event has been fired.
@ -110,16 +117,49 @@ The background mode can be disabled through the `backgroundMode.disable` interfa
cordova.plugins.backgroundMode.disable();
```
### Get informed when the background mode has been activated
The `backgroundMode.onactivate` interface can be used to get notified when the background mode has been activated.
```javascript
cordova.plugins.backgroundMode.onactivate = function() {};
```
### Get informed when the background mode has been deactivated
The `backgroundMode.ondeactivate` interface can be used to get notified when the background mode has been deactivated.
#### Further informations
- Once the mode has been deactivated the app will be paused soon after the callback has been fired.
```javascript
cordova.plugins.backgroundMode.ondeactivate = function() {};
```
### Get informed when the background mode could not been activated
The `backgroundMode.onfailure` interface can be used to get notified when the background mode could not been activated.
The listener has to be a function and takes the following arguments:
- errorCode: Error code which describes the error
```javascript
cordova.plugins.backgroundMode.onfailure = function(errorCode) {};
```
## Examples
The following example demonstrates how to enable the background mode after device is ready. The mode itself will be activated when the app has entered the background.
```javascript
document.addEventListener('deviceready', function () {
// Enable background mode
cordova.plugins.backgroundMode.enable();
// Android customization
cordova.plugins.backgroundMode.configure({ text:'Doing heavy tasks.'});
// Enable background mode
cordova.plugins.backgroundMode.enable();
// Called when background mode has been activated
cordova.plugins.backgroundMode.onactivate = function () {
setInterval(function () {
console.log('App is running in background');
});
}
}, false);
```
@ -170,8 +210,11 @@ This software is released under the [Apache 2.0 License][apache2_license].
[PGB]: http://docs.build.phonegap.com/en_US/index.html
[PGB_plugin]: https://build.phonegap.com/plugins/490
[changelog]: CHANGELOG.md
[enable]: #prevent-the-app-from-going-to-sleep-in-background
[disable]: #pause-the-app-while-in-background
[configure]: #android-customization
[enable]: #prevent_the_app_from_going_to_sleep_in_background
[disable]: #pause_the_app_while_in_background
[configure]: #android_customization
[onactivate]: #get_informed_when_the_background_mode_has_been_activated
[ondeactivate]: #get_informed_when_the_background_mode_has_been_deactivated
[onfailure]: #get_informed_when_the_background_mode_could_not_been_activated
[apache2_license]: http://opensource.org/licenses/Apache-2.0
[appplant]: http://appplant.de

View File

@ -75,9 +75,7 @@
* it to be something the user is actively aware of and thus not a
* candidate for killing when low on memory.
-->
<service
android:name="de.appplant.cordova.plugin.background.ForegroundService"
android:enabled="true" />
<service android:name="de.appplant.cordova.plugin.background.ForegroundService" />
</config-file>
@ -95,8 +93,7 @@
<platform name="wp8">
<config-file target="config.xml" parent="/*">
<feature name="BackgroundMode">
<param name="wp-package" value="BackgroundMode" onload="true" />
<param name="onload" value="true" />
<param name="wp-package" value="BackgroundMode" />
</feature>
</config-file>

View File

@ -37,6 +37,11 @@ import android.util.Log;
public class BackgroundMode extends CordovaPlugin {
// Event types for callbacks
private enum Event {
ACTIVATE, DEACTIVATE, FAILURE
}
// Flag indicates if the app is in background or foreground
private boolean inBackground = false;
@ -55,12 +60,11 @@ public class BackgroundMode extends CordovaPlugin {
@Override
public void onServiceConnected(ComponentName name, IBinder binder) {
// Nothing to do here
Log.d("BackgroundMode", "Service connected");
}
@Override
public void onServiceDisconnected(ComponentName name) {
Log.w("BackgroundMode", "Service disrupted");
// Nothing to do here
}
};
@ -188,11 +192,17 @@ public class BackgroundMode extends CordovaPlugin {
return;
}
try {
context.bindService(
intent, connection, Context.BIND_AUTO_CREATE);
context.startService(intent);
fireEvent(Event.ACTIVATE, null);
} catch (Exception e) {
fireEvent(Event.FAILURE, e.getMessage());
}
isBind = true;
}
@ -207,6 +217,7 @@ public class BackgroundMode extends CordovaPlugin {
context, ForegroundService.class);
if (isBind) {
fireEvent(Event.DEACTIVATE, null);
context.unbindService(connection);
}
@ -214,4 +225,32 @@ public class BackgroundMode extends CordovaPlugin {
isBind = false;
}
/**
* Fire vent with some parameters inside the web view.
*
* @param event
* The name of the event
* @param params
* Optional arguments for the event
*/
private void fireEvent (Event event, String params) {
String eventName;
switch (event) {
case ACTIVATE:
eventName = "activate"; break;
case DEACTIVATE:
eventName = "deactivate"; break;
default:
eventName = "failure";
}
String js = String.format("setTimeout('cordova.plugins.backgroundMode" +
".on%s(%s)',0)",
eventName, params);
webView.loadUrl("javascript:" + js);
}
}

View File

@ -23,6 +23,11 @@
@implementation APPBackgroundMode
NSString *const kAPPBackgroundModeNamespace = @"cordova.plugins.backgroundMode";
NSString *const kAPPBackgroundModeActivateEvent = @"activate";
NSString *const kAPPBackgroundModeDeactivateEvent = @"deactivate";
NSString *const kAPPBackgroundModeFailureEvent = @"failure";
#pragma mark -
#pragma mark Initialization methods
@ -99,6 +104,7 @@
- (void) keepAwake {
if (enabled) {
[audioPlayer play];
[self fireEvent:kAPPBackgroundModeActivateEvent withParams:NULL];
}
}
@ -111,6 +117,10 @@
NSLog(@"BackgroundMode: On simulator apps never pause in background!");
}
if (audioPlayer.isPlaying) {
[self fireEvent:kAPPBackgroundModeDeactivateEvent withParams:NULL];
}
[audioPlayer pause];
}
@ -149,11 +159,26 @@
[session setActive:YES error:NULL];
};
#pragma mark -
#pragma mark Helper methods
/**
* Restart playing sound when interrupted by phone calls.
*/
- (void) handleAudioSessionInterruption:(NSNotification*)notification {
[self fireEvent:kAPPBackgroundModeDeactivateEvent withParams:NULL];
[self keepAwake];
}
/**
* Method to fire an event with some parameters in the browser.
*/
- (void) fireEvent:(NSString*)event withParams:(NSString*)params
{
NSString* js = [NSString stringWithFormat:@"setTimeout('%@.on%@(%@)',0)",
kAPPBackgroundModeNamespace, event, params];
[self.commandDelegate evalJs:js];
}
@end

View File

@ -21,6 +21,9 @@
using WPCordovaClassLib.Cordova.Commands;
using Windows.Devices.Geolocation;
using Microsoft.Phone.Shell;
using System;
using WPCordovaClassLib.Cordova;
namespace Cordova.Extension.Commands
{
@ -30,97 +33,167 @@ namespace Cordova.Extension.Commands
public class BackgroundMode : BaseCommand
{
/// </summary>
/// Flag gibt an, ob die App im Hintergrund wach gehalten werden soll
/// Event types for callbacks
/// </summary>
private static bool IsEnabled = true;
enum Event {
ACTIVATE, DEACTIVATE, FAILURE
}
#region Instance variables
/// </summary>
/// Lokalisiert das Smartphone
/// Flag indicates if the plugin is enabled or disabled
/// </summary>
private bool IsDisabled = true;
/// </summary>
/// Geolocator to monitor location changes
/// </summary>
private static Geolocator Geolocator { get; set; }
/// </summary>
/// Registriert die Listener für die (sleep/resume) Events und startet
/// bzw. stoppt die Geo-Lokalisierung
/// </summary>
public BackgroundMode ()
{
Activate();
}
#endregion
#region Interface methods
/// </summary>
/// @js-interface
/// Setzt den Flag, dass die App im Hintergrund wach gehalten werden soll
/// Enable the mode to stay awake when switching
/// to background for the next time.
/// </summary>
public void enable (string args)
{
Enable();
IsDisabled = false;
}
/// </summary>
/// @js-interface
/// Entfernt den Flag, sodass die App im Hintergrund pausiert wird
/// Disable the background mode and stop
/// being active in background.
/// </summary>
public void disable (string args)
{
Disable();
}
/// </summary>
/// Setzt den Flag, dass die App im Hintergrund wach gehalten werden soll
/// </summary>
public static void Enable ()
{
IsEnabled = true;
}
/// </summary>
/// Entfernt den Flag, sodass die App im Hintergrund pausiert wird
/// </summary>
public static void Disable ()
{
IsEnabled = false;
IsDisabled = true;
Deactivate();
}
#endregion
#region Core methods
/// </summary>
/// Startet das Aktualisieren des Standpunktes
/// Keep the app awake by tracking
/// for position changes.
/// </summary>
public static void Activate ()
private void Activate()
{
if (Geolocator == null && IsEnabled && IsServiceAvailable())
if (IsDisabled || Geolocator != null)
return;
if (!IsServiceAvailable())
{
FireEvent(Event.FAILURE, null);
return;
}
Geolocator = new Geolocator();
Geolocator.DesiredAccuracy = PositionAccuracy.Default;
Geolocator.MovementThreshold = 100000;
Geolocator.PositionChanged += geolocator_PositionChanged;
}
FireEvent(Event.ACTIVATE, null);
}
/// </summary>
/// Beendet das Aktualisieren des Standpunktes
/// Let the app going to sleep.
/// </summary>
public static void Deactivate ()
{
if (Geolocator != null)
private void Deactivate ()
{
if (Geolocator == null)
return;
FireEvent(Event.DEACTIVATE, null);
Geolocator.PositionChanged -= geolocator_PositionChanged;
Geolocator = null;
}
}
private static void geolocator_PositionChanged (Geolocator sender, PositionChangedEventArgs args) {}
#endregion
#region Helper methods
/// </summary>
/// Gibt an, ob der Lokalisierungsdienst verfügbar ist
/// Determine if location service is available and enabled.
/// </summary>
private static bool IsServiceAvailable()
private bool IsServiceAvailable()
{
Geolocator geolocator = (Geolocator == null) ? new Geolocator() : Geolocator;
return !(geolocator.LocationStatus == PositionStatus.Disabled || geolocator.LocationStatus == PositionStatus.NotAvailable);
}
PositionStatus status = geolocator.LocationStatus;
if (status == PositionStatus.Disabled)
return false;
if (status == PositionStatus.NotAvailable)
return false;
return true;
}
/// <summary>
/// Fires the given event.
/// </summary>
private void FireEvent(Event Event, string Param)
{
string EventName;
switch (Event) {
case Event.ACTIVATE:
EventName = "activate"; break;
case Event.DEACTIVATE:
EventName = "deactivate"; break;
default:
EventName = "failure"; break;
}
string js = String.Format("cordova.plugins.backgroundMode.on{0}({1})", EventName, Param);
PluginResult pluginResult = new PluginResult(PluginResult.Status.OK, js);
pluginResult.KeepCallback = true;
DispatchCommandResult(pluginResult);
}
#endregion
#region Delegate methods
private void geolocator_PositionChanged(Geolocator sender, PositionChangedEventArgs args)
{
// Nothing to do here
}
#endregion
#region Lifecycle methods
/// <summary>
/// Occurs when the application is being deactivated.
/// </summary>
public override void OnPause(object sender, DeactivatedEventArgs e)
{
Activate();
}
/// <summary>
/// Occurs when the application is being made active after previously being put
/// into a dormant state or tombstoned.
/// </summary>
public override void OnResume(object sender, ActivatedEventArgs e)
{
Deactivate();
}
#endregion
}
}

View File

@ -87,6 +87,24 @@ exports.configure = function (options) {
}
};
/**
* Called when the background mode has been activated.
*/
exports.onactivate = function () {};
/**
* Called when the background mode has been deaktivated.
*/
exports.ondeactivate = function () {};
/**
* Called when the background mode could not been activated.
*
* @param {Integer} errorCode
* Error code which describes the error
*/
exports.onfailure = function () {};
/**
* @private
*