base/android/application_status_listener.h

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef BASE_ANDROID_APPLICATION_STATUS_LISTENER_H_
   6 #define BASE_ANDROID_APPLICATION_STATUS_LISTENER_H_
   7
   8 #include <jni.h>
   9
  10 #include "base/android/jni_android.h"
  11 #include "base/base_export.h"
  12 #include "base/basictypes.h"
  13 #include "base/memory/ref_counted.h"
  14 #include "base/memory/singleton.h"
  15 #include "base/observer_list_threadsafe.h"
  16
  17 namespace base {
  18 namespace android {
  19
  20 // Define application state values like APPLICATION_STATE_VISIBLE in a
  21 // way that ensures they're always the same than their Java counterpart.
  22 //
  23 // Note that these states represent the most visible Activity state.
  24 // If there are activities with states paused and stopped, only
  25 // HAS_PAUSED_ACTIVITIES should be returned.
  26 //
  27 // A Java counterpart will be generated for this enum.
  28 // GENERATED_JAVA_ENUM_PACKAGE: org.chromium.base
  29 enum ApplicationState {
  30   APPLICATION_STATE_HAS_RUNNING_ACTIVITIES = 1,
  31   APPLICATION_STATE_HAS_PAUSED_ACTIVITIES = 2,
  32   APPLICATION_STATE_HAS_STOPPED_ACTIVITIES = 3,
  33   APPLICATION_STATE_HAS_DESTROYED_ACTIVITIES = 4
  34 };
  35
  36 // A native helper class to listen to state changes of the Android
  37 // Application. This mirrors org.chromium.base.ApplicationStatus.
  38 // any thread.
  39 //
  40 // To start listening, create a new instance, passing a callback to a
  41 // function that takes an ApplicationState parameter. To stop listening,
  42 // simply delete the listener object. The implementation guarantees
  43 // that the callback will always be called on the thread that created
  44 // the listener.
  45 //
  46 // Example:
  47 //
  48 //    void OnApplicationStateChange(ApplicationState state) {
  49 //       ...
  50 //    }
  51 //
  52 //    // Start listening.
  53 //    ApplicationStatusListener* my_listener =
  54 //        new ApplicationStatusListener(
  55 //            base::Bind(&OnApplicationStateChange));
  56 //
  57 //    ...
  58 //
  59 //    // Stop listening.
  60 //    delete my_listener
  61 //
  62 class BASE_EXPORT ApplicationStatusListener {
  63  public:
  64   typedef base::Callback<void(ApplicationState)> ApplicationStateChangeCallback;
  65
  66   explicit ApplicationStatusListener(
  67       const ApplicationStateChangeCallback& callback);
  68   ~ApplicationStatusListener();
  69
  70   // Internal use: must be public to be called from base_jni_registrar.cc
  71   static bool RegisterBindings(JNIEnv* env);
  72
  73   // Internal use only: must be public to be called from JNI and unit tests.
  74   static void NotifyApplicationStateChange(ApplicationState state);
  75
  76  private:
  77   void Notify(ApplicationState state);
  78
  79   ApplicationStateChangeCallback callback_;
  80
  81   DISALLOW_COPY_AND_ASSIGN(ApplicationStatusListener);
  82 };
  83
  84 }  // namespace android
  85 }  // namespace base
  86
  87 #endif  // BASE_ANDROID_APPLICATION_STATUS_LISTENER_H_