widget/nsUserIdleService.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim:expandtab:shiftwidth=2:tabstop=2:
   3  */
   4 /* This Source Code Form is subject to the terms of the Mozilla Public
   5  * License, v. 2.0. If a copy of the MPL was not distributed with this
   6  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   7
   8 #ifndef nsUserIdleService_h__
   9 #define nsUserIdleService_h__
  10
  11 #include "nsIUserIdleServiceInternal.h"
  12 #include "nsCOMPtr.h"
  13 #include "nsITimer.h"
  14 #include "nsTArray.h"
  15 #include "nsIObserver.h"
  16 #include "nsIUserIdleService.h"
  17 #include "nsCategoryCache.h"
  18 #include "nsWeakReference.h"
  19 #include "mozilla/TimeStamp.h"
  20
  21 /**
  22  * Class we can use to store an observer with its associated idle time
  23  * requirement and whether or not the observer thinks it's "idle".
  24  */
  25 class IdleListener {
  26  public:
  27   nsCOMPtr<nsIObserver> observer;
  28   uint32_t reqIdleTime;
  29   bool isIdle;
  30
  31   IdleListener(nsIObserver* obs, uint32_t reqIT, bool aIsIdle = false)
  32       : observer(obs), reqIdleTime(reqIT), isIdle(aIsIdle) {}
  33   ~IdleListener() = default;
  34 };
  35
  36 // This one will be declared later.
  37 class nsUserIdleService;
  38
  39 /**
  40  * Class to handle the daily idle timer.
  41  */
  42 class nsUserIdleServiceDaily : public nsIObserver,
  43                                public nsSupportsWeakReference {
  44  public:
  45   NS_DECL_ISUPPORTS
  46   NS_DECL_NSIOBSERVER
  47
  48   explicit nsUserIdleServiceDaily(nsIUserIdleService* aIdleService);
  49
  50   /**
  51    * Initializes the daily idle observer.
  52    * Keep this separated from the constructor, since it could cause pointer
  53    * corruption due to AddRef/Release of "this".
  54    */
  55   void Init();
  56
  57  private:
  58   virtual ~nsUserIdleServiceDaily();
  59
  60   /**
  61    * StageIdleDaily is the interim call made when an idle-daily event is due.
  62    * However we don't want to fire idle-daily until the user is idle for this
  63    * session, so this sets up a short wait for an idle event which triggers
  64    * the actual idle-daily event.
  65    *
  66    * @param aHasBeenLongWait Pass true indicating nsUserIdleServiceDaily is
  67    * having trouble getting the idle-daily event fired. If true StageIdleDaily
  68    * will use a shorter idle wait time before firing idle-daily.
  69    */
  70   void StageIdleDaily(bool aHasBeenLongWait);
  71
  72   /**
  73    * @note This is a normal pointer, part to avoid creating a cycle with the
  74    * idle service, part to avoid potential pointer corruption due to this class
  75    * being instantiated in the constructor of the service itself.
  76    */
  77   nsIUserIdleService* mIdleService;
  78
  79   /**
  80    * Place to hold the timer used by this class to determine when a day has
  81    * passed, after that it will wait for idle time to be detected.
  82    */
  83   nsCOMPtr<nsITimer> mTimer;
  84
  85   /**
  86    * Function that is called back once a day.
  87    */
  88   static void DailyCallback(nsITimer* aTimer, void* aClosure);
  89
  90   /**
  91    * Cache of observers for the "idle-daily" category.
  92    */
  93   nsCategoryCache<nsIObserver> mCategoryObservers;
  94
  95   /**
  96    * Next time we expect an idle-daily timer to fire, in case timers aren't
  97    * very reliable on the platform. Value is in PR_Now microsecond units.
  98    */
  99   PRTime mExpectedTriggerTime;
 100
 101   /**
 102    * Tracks which idle daily observer callback we ask for. There are two: a
 103    * regular long idle wait and a shorter wait if we've been waiting to fire
 104    * idle daily for an extended period. Set by StageIdleDaily.
 105    */
 106   int32_t mIdleDailyTriggerWait;
 107 };
 108
 109 class nsUserIdleService : public nsIUserIdleServiceInternal {
 110  public:
 111   NS_DECL_ISUPPORTS
 112   NS_DECL_NSIUSERIDLESERVICE NS_DECL_NSIUSERIDLESERVICEINTERNAL
 113
 114       protected : static already_AddRefed<nsUserIdleService>
 115                   GetInstance();
 116
 117   nsUserIdleService();
 118   virtual ~nsUserIdleService();
 119
 120   /**
 121    * If there is a platform specific function to poll the system idel time
 122    * then that must be returned in this function, and the function MUST return
 123    * true, otherwise then the function should be left unimplemented or made
 124    * to return false (this can also be used for systems where it depends on
 125    * the configuration of the system if the idle time can be determined)
 126    *
 127    * @param aIdleTime
 128    *        The idle time in ms.
 129    *
 130    * @return true if the idle time could be polled, false otherwise.
 131    *
 132    * @note The time returned by this function can be different than the one
 133    *       returned by GetIdleTime, as that is corrected by any calls to
 134    *       ResetIdleTimeOut(), unless you overwrite that function too...
 135    */
 136   virtual bool PollIdleTime(uint32_t* aIdleTime);
 137
 138  public:
 139   void SetDisabledForShutdown();
 140
 141  private:
 142   /**
 143    * Ensure that the timer is expiring at least at the given time
 144    *
 145    * The function might not restart the timer if there is one running currently
 146    *
 147    * @param aNextTimeout
 148    *        The last absolute time the timer should expire
 149    */
 150   void SetTimerExpiryIfBefore(mozilla::TimeStamp aNextTimeout);
 151
 152   /**
 153    * Stores the next timeout time, 0 means timer not running
 154    */
 155   mozilla::TimeStamp mCurrentlySetToTimeoutAt;
 156
 157   /**
 158    * mTimer holds the internal timer used by this class to detect when to poll
 159    * for idle time, when to check if idle timers should expire etc.
 160    */
 161   nsCOMPtr<nsITimer> mTimer;
 162
 163   /**
 164    * Array of listeners that wants to be notified about idle time.
 165    */
 166   nsTArray<IdleListener> mArrayListeners;
 167
 168   /**
 169    * Object keeping track of the daily idle thingy.
 170    */
 171   RefPtr<nsUserIdleServiceDaily> mDailyIdle;
 172
 173   /**
 174    * Number of observers currently in idle mode.
 175    */
 176   uint32_t mIdleObserverCount;
 177
 178   /**
 179    * Delta time from last non idle time to when the next observer should switch
 180    * to idle mode
 181    *
 182    * Time in seconds
 183    *
 184    * If this value is 0 it means there are no active observers
 185    */
 186   uint32_t mDeltaToNextIdleSwitchInS;
 187
 188   /**
 189    * If true, the idle service is temporarily disabled, and all idle events
 190    * will be ignored.
 191    */
 192   bool mDisabled = false;
 193
 194   /**
 195    * Absolute value for when the last user interaction took place.
 196    */
 197   mozilla::TimeStamp mLastUserInteraction;
 198
 199   /**
 200    * Function that ensures the timer is running with at least the minimum time
 201    * needed.  It will kill the timer if there are no active observers.
 202    */
 203   void ReconfigureTimer(void);
 204
 205   /**
 206    * Callback function that is called when the internal timer expires.
 207    *
 208    * This in turn calls the IdleTimerCallback that does the real processing
 209    */
 210   static void StaticIdleTimerCallback(nsITimer* aTimer, void* aClosure);
 211
 212   /**
 213    * Function that handles when a timer has expired
 214    */
 215   void IdleTimerCallback(void);
 216 };
 217
 218 #endif  // nsUserIdleService_h__