### ITimer

  The ITimer class creates and references periodic time-interval-based operations.

  Timer identifiers are limited to the value 0x7FFF in all environments to allow portability to systems where where this limit is imposed by the operating system.

#### AIX Considerations

  At the end of each interval, a notification request is registered with the system for the next interval. Because of processing delays that may occur in the operating system and applications between the time an interval expires and the next one is scheduled, some drift may occur in the timer.

#### OS/2 Considerations

  ITimer objects use timer identifier values above 1000. Limit your use of timer identifiers to values below 1000 when directly creating or managing timers using operating system calls.

  The ITimer class uses the operating system message queue for timer expiration. This can cause timer actions to be delayed if the application is currently tying up the queue. If a timer event is delayed, the next timer event still occurs at the expected interval (there should be no timer drift).

### ITimer - Member Functions and Data by Group

### Constructors & Destructor

You can construct, copy, assign, and destruct objects of this class.
Note: The ITimer class does not support user-specified timer identifier values or timers that were not created with the ITimer class.

~ITimer

      public:
      virtual ~ITimer()

  The destructor does not stop the timer or deallocate resources. If you want to stop the timer and deallocate resources, call the function stop to halt the started timer.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

ITimer

  Overload 1

      public:
      ITimer()

  Constructs an ITimer object using the default constructor. When calling start to subsequently start the timer, you can specify a timer interval and a function for the timer to call each time it expires.

Exception

  IOutOfSystemResource | The system is out of available timer identifiers.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

  Overload 2

      public:
      ITimer(unsigned long timerIdentifier)

  timerIdentifier
    A value that represents the timer identifier (ID).

  Constructs an ITimer object from the timer ID of an existing ITimer object.

Exception

  IInvalidParameter | The timer identifier value is not valid.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

  Overload 3

      public:
      ITimer( const ICountedPointerTo < ITimerFn >& timerFunction,
              unsigned long timerInterval = 1000 )

  Constructs an ITimer object with a specification of code to be run and a time interval (in thousandths of a second).

  timerFunction
    A reference to an object of the ICountedPointerTo template class that was created using a class derived from ITimerFn. You must dynamically allocate the ITimerFn object using operator new.
  timerInterval
    A value that represents the time interval. One second (1000 milliseconds) is the default.

  This constructor is equivalent to using the default constructor and calling ITimer::start. Therefore, use this form of the constructor to construct a new ITimer and immediately start it.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

  Overload 4

      public:
      ITimer(const ITimer& timer)

  timer
    A reference to an existing timer object.

  Constructs an ITimer object from an existing ITimer object.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

operator =

      public:
      ITimer& operator =(const ITimer& timer)

  Assigns an ITimer object to reference an existing timer.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Comparison

Use these members to compare ITimer objects.

operator ==

      public:
      bool operator ==(const ITimer timer)

  Returns true if and only if the timers are identical.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Diagnostics

Use these members for diagnostic purposes. They return IString representations of the timer diagnostics.

asDebugInfo

      public:
      virtual IString asDebugInfo() const

  Returns a representation of the timer as diagnostic information.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

asString

      public:
      virtual IString asString() const

  Returns a string of the form "ITimer(ID)", where ID is replaced by the actual identifier of the timer.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Expiration Interval

After you start a timer, it expires each time a specified time interval passes. Use these members to access the timer expiration interval.

interval

      public:
      unsigned long interval() const

  Returns the timer interval (in thousandths of a second).

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

setInterval

      public:
      virtual ITimer& setInterval(unsigned long interval = 1000)

  Sets the timer interval (in thousandths of a second). If no interval is set for a timer, then an interval of one second is used by default.

  If this member function is called for a started timer, then the timer is stopped and restarted with the new interval. The ITimerFn being used is saved and used when the timer is restarted.

  An interval of 0 causes the timer to expire as quickly as possible.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

OS/2 Considerations

  When you run a timer on the OS/2 operating system, an effective minimum of about 1/18 of a second exists for timer intervals.

### Retrieving Objects

Use these members to retrieve a timer object using the class ITimer::Cursor.

timerAt

      public:
      static ITimer timerAt(const Cursor& cursor)

  Returns an ITimer object at the position indicated by cursor.

Exception

  IInvalidParameter | The ITimer::Cursor is invalid.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Starting and Stopping

Use these members to start and stop timers.

isStarted

      public:
      bool isStarted() const

  Returns true if the timer is currently active. A timer is not active if you have stopped it or have never started it. The timer will continue to expire as long as it is active.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

start

  Starts a time-interval-based operation with an arbitrary ITimerFn object. The ITimerFn is passed in using an ICountedPointerTo object so that ITimer can reference count the ITimerFn object and subsequently delete it when you stop the timer.

  ITimer calls the ITimerFn object each time the timer interval expires, until you stop the timer.

  Overload 1

      public:
      virtual ITimer&
        start( const ICountedPointerTo < ITimerFn >& timerFunction )

  timerFunction
    A reference to an object of the ICountedPointerTo template class that was created using a class derived from ITimerFn. You must dynamically allocate the ITimerFn object using operator new.

Exception

  IInvalidRequest | The timer has already been started.
  IAccessError | The operating system is unable to start the timer.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

  Overload 2

      public:
      virtual ITimer&
        start( const ICountedPointerTo < ITimerFn >& timerFunction,
               unsigned long timerInterval )

  timerFunction
    A reference to an object of the ICountedPointerTo template class that was created using a class derived from ITimerFn. You must dynamically allocate the ITimerFn object using operator new.
  timerInterval
    A value that represents the timer interval.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

stop

      public:
      virtual ITimer& stop()

  Stops the timer. You must stop the timer to deallocate resources used by the timer.

Exception

  IAccessError | The operating system is unable to stop the timer.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Timer Information

Use these members to access timer information, such as the timer identifier.

id

      public:
      unsigned long id() const

  Returns the timer's identifier.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### ITimer - Inherited Member Functions and Data

#### Inherited Public Functions

  - None

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  - None

#### Inherited Protected Data

  - None