/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
 *
 * The contents of this file are subject to the Mozilla Public
 * License Version 1.1 (the "License"); you may not use this file
 * except in compliance with the License. You may obtain a copy of
 * the License at http://www.mozilla.org/MPL/
 * 
 * Software distributed under the License is distributed on an "AS
 * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
 * implied. See the License for the specific language governing
 * rights and limitations under the License.
 * 
 * The Original Code is mozilla.org code.
 * 
 * The Initial Developer of the Original Code is Netscape
 * Communications Corporation. Portions created by Netscape are
 * Copyright (C) 1998-2000 Netscape Communications Corporation.
 * All Rights Reserved.
 * 
 * Contributor(s): 
 *   Michael Lowe <michael.lowe@bigfoot.com>
 *   Stuart Parmenter <pavlov@netscape.com>
 */

#include "nsISupports.idl"

interface nsITimer;
interface nsITimerCallback;

/// Signature of timer callback function
native nsTimerCallbackFunc(nsTimerCallbackFunc);
  
/*! @verbatim */
%{C++
  typedef void (*nsTimerCallbackFunc) (nsITimer *aTimer, void *aClosure);
%}
/*! @endverbatim */

/**
 * Timer interface.  Used to invoke a function or method after a fixed
 * millisecond interval.
 *
 * @author Michael Lowe <michael.lowe@bigfoot.com>
 * @author Stuart Parmenter <pavlov@netscape.com>
 * @version 1.1
 *
 * @note Implementations of nsITimer should be written such that there are no limitations
 *  on what can be called by the TimerCallbackFunc. On platforms like the Macintosh this
 *  means that callback functions must be called from the main event loop NOT from
 *  an interrupt.
 */
[scriptable, uuid(791cb316-1dd2-11b2-8f3b-caa107815990)]
interface nsITimer : nsISupports
{
  /**
   * Timer priorities
   * @name timer_priorities Timer Priorities
   */
  //@{
  const long NS_PRIORITY_HIGHEST = 10;
  const long NS_PRIORITY_HIGH    =  8;
  const long NS_PRIORITY_NORMAL  =  5;
  const long NS_PRIORITY_LOW     =  2;
  const long NS_PRIORITY_LOWEST  =  0;
  //@}



  /**
   * Timer types
   * @name timer_types Timer types
   */
  //@{

  /**
   * Timer which fires once only
   */
  const unsigned long NS_TYPE_ONE_SHOT = 0;

  /**
   * After firing, timer is stopped and not 
   * restarted until notifcation routine completes.   
   * Specified timer period will be at least time between 
   * when processing for last firing notifcation completes 
   * and when the next firing occurs.  This is the preferable
   * repeating type for most situations.
   */
  const unsigned long NS_TYPE_REPEATING_SLACK = 1;

  /**
   * Timer which aims to have constant time between firings.
   * The processing time for each timer notification should
   * not influence timer period.   However, if the processing
   * for the last timer firing could not be completed until  
   * just before the next firing occurs, then you could have 
   * two timer notification routines being executed in quick 
   * sucession.
   */
  const unsigned long NS_TYPE_REPEATING_PRECISE = 2;
  //@}

  /**
   * Initialize a timer to fire after the given millisecond interval.
   * This version takes an interface of type nsITimerCallback. 
   * nsITimerCallback::notify() method of this method is invoked.
   *
   * @param aCallback - The interface to notify
   * @param aDelay - The millisecond interval
   * @param aPriority - The timer priority
   * @param aType - The timer type : one shot or repeating
   * @return NS_OK if this operation was successful
   *
   * @attention \a aPriority and \a aType are no longer optional parameters.
   *  \a aPriority was defaulted to NS_PRIORITY_NORMAL and
   *  \a aType was defaulted to NS_TYPE_ONE_SHOT
   */
  void init(in nsITimerCallback aCallback,
            in unsigned long aDelay,
            in unsigned long aPriority,
            in long aType);

  /**
   * Initialize a timer to fire after the given millisecond interval.
   * This version takes a function to call and a closure to pass to
   * that function.
   *
   * @param aFunc - The function to invoke
   * @param aClosure - an opaque pointer to pass to that function
   * @param aDelay - The millisecond interval
   * @param aPriority - The timer priority
   * @param aType - The timer type : one shot or repeating
   * @return NS_OK if this operation was successful
   *
   * @attention \a aPriority and \a aType are no longer optional parameters.
   *  \a aPriority was defaulted to NS_PRIORITY_NORMAL and
   *  \a aType was defaulted to NS_TYPE_ONE_SHOT
   *
   * @deprecated use init()
   */
  [noscript] void initOld(in nsTimerCallbackFunc aFunc,
                          in voidPtr aClosure,
                          in unsigned long aDelay,
                          in unsigned long aPriority,
                          in long aType);

  /// Cancels the timeout
  void cancel();

  /// Change the millisecond interval for the timeout
  attribute unsigned long delay;

  /**
   * The priority of this timer.
   * @see timer_priorities
   */
  attribute unsigned long priority;

  /**
   * The type of timer this is
   * @see timer_types
   */
  attribute unsigned long type;

  /// @return the opaque pointer
  [noscript] readonly attribute voidPtr closure;
};