widget/src/xpwidgets/nsIdleService.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim:expandtab:shiftwidth=2:tabstop=2:
   3  */
   4 /* ***** BEGIN LICENSE BLOCK *****
   5  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   6  *
   7  * The contents of this file are subject to the Mozilla Public License Version
   8  * 1.1 (the "License"); you may not use this file except in compliance with
   9  * the License. You may obtain a copy of the License at
  10  * http://www.mozilla.org/MPL/
  11  *
  12  * Software distributed under the License is distributed on an "AS IS" basis,
  13  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  14  * for the specific language governing rights and limitations under the
  15  * License.
  16  *
  17  * The Original Code is mozilla.org code.
  18  *
  19  * The Initial Developer of the Original Code is
  20  * Gijs Kruitbosch <gijskruitbosch@gmail.com>.
  21  * Portions created by the Initial Developer are Copyright (C) 2007
  22  * the Initial Developer. All Rights Reserved.
  23  *
  24  * Contributor(s):
  25  *  Gijs Kruitbosch <gijskruitbosch@gmail.com>
  26  *  Mike Kristoffersen <moz@mikek.dk>
  27  *
  28  * Alternatively, the contents of this file may be used under the terms of
  29  * either the GNU General Public License Version 2 or later (the "GPL"), or
  30  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  31  * in which case the provisions of the GPL or the LGPL are applicable instead
  32  * of those above. If you wish to allow use of your version of this file only
  33  * under the terms of either the GPL or the LGPL, and not to allow others to
  34  * use your version of this file under the terms of the MPL, indicate your
  35  * decision by deleting the provisions above and replace them with the notice
  36  * and other provisions required by the GPL or the LGPL. If you do not delete
  37  * the provisions above, a recipient may use your version of this file under
  38  * the terms of any one of the MPL, the GPL or the LGPL.
  39  *
  40  * ***** END LICENSE BLOCK ***** */
  41
  42 #ifndef nsIdleService_h__
  43 #define nsIdleService_h__
  44
  45 #include "nsIIdleService.h"
  46 #include "nsCOMPtr.h"
  47 #include "nsITimer.h"
  48 #include "nsTArray.h"
  49 #include "nsIObserver.h"
  50 #include "nsIIdleService.h"
  51 #include "nsCategoryCache.h"
  52
  53 /**
  54  * Class we can use to store an observer with its associated idle time
  55  * requirement and whether or not the observer thinks it's "idle".
  56  */
  57 class IdleListener {
  58 public:
  59   nsCOMPtr<nsIObserver> observer;
  60   PRUint32 reqIdleTime;
  61   bool isIdle;
  62
  63   IdleListener(nsIObserver* obs, PRUint32 reqIT, bool aIsIdle = false) :
  64     observer(obs), reqIdleTime(reqIT), isIdle(aIsIdle) {}
  65   ~IdleListener() {}
  66 };
  67
  68 // This one will be declared later.
  69 class nsIdleService;
  70
  71 /**
  72  * Class to handle the daily idle timer.
  73  */
  74 class nsIdleServiceDaily : public nsIObserver
  75 {
  76 public:
  77   NS_DECL_ISUPPORTS
  78   NS_DECL_NSIOBSERVER
  79
  80   nsIdleServiceDaily(nsIdleService* aIdleService);
  81
  82   /**
  83    * This function will make this class release its allocated resources (its
  84    * idle timer and/or its normal timer).
  85    */
  86   void Shutdown();
  87
  88 private:
  89   /**
  90    * @note This is a normal pointer, or the idle service could keep it self
  91    * alive.
  92    */
  93   nsIdleService* mIdleService;
  94
  95   /**
  96    * Set to true when the instantiated object has a idle observer.
  97    */
  98   bool mObservesIdle;
  99
 100   /**
 101    * Place to hold the timer used by this class to determine when a day has
 102    * passed, after that it will wait for idle time to be detected.
 103    */
 104   nsCOMPtr<nsITimer> mTimer;
 105
 106   /**
 107    * Function that is called back once a day.
 108    */
 109   static void DailyCallback(nsITimer* aTimer, void* aClosure);
 110
 111   /**
 112    * Cache of observers for the "idle-daily" category.
 113    */
 114   nsCategoryCache<nsIObserver> mCategoryObservers;
 115 };
 116
 117 class nsIdleService : public nsIIdleService
 118 {
 119 public:
 120   nsIdleService();
 121
 122   // Implement nsIIdleService methods.
 123   NS_IMETHOD AddIdleObserver(nsIObserver* aObserver, PRUint32 aIdleTime);
 124   NS_IMETHOD RemoveIdleObserver(nsIObserver* aObserver, PRUint32 aIdleTime);
 125   NS_IMETHOD GetIdleTime(PRUint32* idleTime);
 126
 127   void ResetIdleTimeOut();
 128
 129 protected:
 130   ~nsIdleService();
 131
 132   /**
 133    * If there is a platform specific function to poll the system idel time
 134    * then that must be returned in this function, and the function MUST return
 135    * true, otherwise then the function should be left unimplemented or made
 136    * to return false (this can also be used for systems where it depends on
 137    * the configuration of the system if the idle time can be determined)
 138    *
 139    * @param aIdleTime
 140    *        The idle time in ms.
 141    *
 142    * @return true if the idle time could be polled, false otherwise.
 143    *
 144    * @note The time returned by this function can be different than the one
 145    *       returned by GetIdleTime, as that is corrected by any calls to
 146    *       ResetIdleTimeOut(), unless you overwrite that function too...
 147    */
 148   virtual bool PollIdleTime(PRUint32* aIdleTime);
 149
 150   /**
 151    * Function that determines if we are in poll mode or not.
 152    *
 153    * @return true if polling is supported, false otherwise.
 154    */
 155   virtual bool UsePollMode();
 156
 157   /**
 158    * Send expired events and start timers.
 159    *
 160    * @param aNoTimeReset
 161    *        If true new times will not be calculated.
 162    */
 163   void CheckAwayState(bool aNoTimeReset);
 164
 165 private:
 166   /**
 167    * Start the internal timer, restart it if it is allready running.
 168    *
 169    * @param aDelay
 170    *        The time in seconds that should pass before the next timeout.
 171    */
 172
 173   void StartTimer(PRUint32 aDelay);
 174
 175   /**
 176    * Stop the internal timer, it is safe to call this function, even when
 177    * there are no timers running.
 178    */
 179   void StopTimer();
 180
 181   /**
 182    * mTimer holds the internal timer used by this class to detect when to poll
 183    * for idle time, when to check if idle timers should expire etc.
 184    */
 185   nsCOMPtr<nsITimer> mTimer;
 186
 187   /**
 188    * Array of listeners that wants to be notified about idle time.
 189    */
 190   nsTArray<IdleListener> mArrayListeners;
 191
 192   /**
 193    * Object keeping track of the daily idle thingy.
 194    */
 195   nsCOMPtr<nsIdleServiceDaily> mDailyIdle;
 196
 197   /**
 198    * Contains the time of the last idle reset or 0 if there haven't been a
 199    * reset.
 200    * <p>
 201    * Time is kept in seconds since the epoch at midnight, January 1, 1970 UTC.
 202    */
 203   PRUint32 mLastIdleReset;
 204
 205   /**
 206    * The time since the last handled activity (which might be different than
 207    * mLastIdleReset, since the activity that reset the idle timer could just
 208    * have happend, and not handled yet).
 209    * <p>
 210    * Time is kept in seconds since the epoch at midnight, January 1, 1970 UTC.
 211    */
 212   PRUint32 mLastHandledActivity;
 213
 214   /**
 215    * Callback function that is called when the internal timer expires.
 216    */
 217   static void IdleTimerCallback(nsITimer* aTimer, void* aClosure);
 218
 219   /**
 220    * Whether the idle time calculated in the last call to GetIdleTime is
 221    * actually valid (see nsIdleService.idl - we return 0 when it isn't).
 222    */
 223   bool mPolledIdleTimeIsValid;
 224 };
 225
 226 #endif // nsIdleService_h__