toolkit/components/timermanager/nsIUpdateTimerManager.idl

   1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #include "nsISupports.idl"
   7
   8 interface nsITimerCallback;
   9
  10 /**
  11  * An interface describing a global application service that allows long
  12  * duration (e.g. 1-7 or more days, weeks or months) timers to be registered
  13  * and then fired.
  14  */
  15 [scriptable, uuid(0765c92c-6145-4253-9db4-594d8023087e)]
  16 interface nsIUpdateTimerManager : nsISupports
  17 {
  18   /**
  19    * Register an interval with the timer manager. The timer manager
  20    * periodically checks to see if the interval has expired and if it has
  21    * calls the specified callback. This is persistent across application
  22    * restarts and can handle intervals of long durations. The callback will be
  23    * called soon after the first registration unless you ask to skip it.
  24    * @param   id
  25    *          An id that identifies the interval, used for persistence
  26    * @param   callback
  27    *          A nsITimerCallback object that is notified when the interval
  28    *          expires
  29    * @param   interval
  30    *          The length of time, in seconds, of the interval
  31    * @param   skipFirst
  32    *          Whether to skip the initial callback on first registration.
  33    *
  34    * Note: to avoid having to instantiate a component to call registerTimer
  35    * the component can intead register an update-timer category with comma
  36    * separated values as a single string:
  37    *
  38    * contractID,method,id,preference,interval
  39    *
  40    * via a manifest entry. The values are as follows:
  41    *   contractID : the contract ID for the component.
  42    *   method     : the method used to instantiate the interface. This should be
  43    *                either getService or createInstance depending on your
  44    *                component.
  45    *   id         : the id that identifies the interval, used for persistence.
  46    *   preference : the preference to for timer interval. This value can be
  47    *                optional by specifying an empty string for the value.
  48    *   interval   : the default interval in seconds for the timer.
  49    */
  50   void registerTimer(in AString id,
  51                      in nsITimerCallback callback,
  52                      in unsigned long interval,
  53                      [optional] in boolean skipFirst);
  54
  55   /**
  56    * Unregister an existing interval from the timer manager.
  57    *
  58    * @param   id
  59    *          An id that identifies the interval.
  60    */
  61   void unregisterTimer(in AString id);
  62 };