path: root/lib/cosTime/doc/src/CosTimerEvent_TimerEventHandler.xml

<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">

<erlref>
  <header>
    <copyright>
      <year>2000</year>
      <year>2011</year>
      <holder>Ericsson AB, All Rights Reserved</holder>
    </copyright>
    <legalnotice>
  The contents of this file are subject to the Erlang Public License,
  Version 1.1, (the "License"); you may not use this file except in
  compliance with the License. You should have received a copy of the
  Erlang Public License along with this software. If not, it can be
  retrieved online at http://www.erlang.org/.

  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 Initial Developer of the Original Code is Ericsson AB.
    </legalnotice>

    <title>CosTimerEvent_&shy;TimerEventHandler</title>
    <shorttitle>..._TimerEventHandler</shorttitle>
    <prepared>Niclas Eklund</prepared>
    <responsible>Niclas Eklund</responsible>
    <docno></docno>
    <approved>Niclas Eklund</approved>
    <checked></checked>
    <date>2000-02-01</date>
    <rev>1.0</rev>
  </header>
  <module>CosTimerEvent_TimerEventHandler</module>
  <modulesummary>This module implements the OMG  CosTimerEvent::TimerEventHandler interface.</modulesummary>
  <description>
    <p>To get access to the record definitions for the structures use:      <br></br>
<c>-include_lib("cosTime/include/*.hrl").</c></p>
  </description>
  <funcs>
    <func>
      <name>'_get_status'(TimerEventHandler) -> Reply</name>
      <fsummary>Return the status of the target object</fsummary>
      <type>
        <v>TimerEventHandler = #objref</v>
        <v>Reply = 'ESTimeSet' | 'ESTimeCleared' | 'ESTriggered' | 'ESFailedTrigger'</v>
      </type>
      <desc>
        <p>This operation returns the status of the target object. </p>
        <list type="bulleted">
          <item>'ESTimeSet' - timer is set to trigger event(s).</item>
          <item>'ESTimeCleared' - no time set or the timer have been reset.</item>
          <item>'ESTriggered' - event has already been sent.</item>
          <item>'ESFailedTrigger' - tried to, but failed, sending the event.</item>
        </list>
        <p>If the target object is of type 'TTPeriodic' the status value 
          'ESTriggered' is not valid.</p>
      </desc>
    </func>
    <func>
      <name>time_set(TimerEventHandler) -> Reply</name>
      <fsummary>Return <c>true</c>if the time has been set for an event that is yet to be triggered, <c>false</c>otherwise. The outparameter represents the current time value of the target object</fsummary>
      <type>
        <v>TimerEventHandler = #objref</v>
        <v>Reply = {boolean(), UTO}</v>
        <v>UTO = #objref</v>
      </type>
      <desc>
        <p>This operation returns <c>true</c> if the time has been set for an event that
          is yet to be triggered, <c>false</c> otherwise. The outparameter represents
          the current time value of the target object.</p>
      </desc>
    </func>
    <func>
      <name>set_timer(TimerEventHandler, TimeType, TriggerTime) -> void()</name>
      <fsummary>Terminate terminate any previous set trigger, and set a new trigger specified by the <c>TimeType</c>and <c>UTO</c>objects</fsummary>
      <type>
        <v>TimerEventHandler = #objref</v>
        <v>TimeType = 'TTAbsolute' | 'TTRelative' | 'TTPeriodic'</v>
        <v>TriggerTime = UTO</v>
        <v>UTO = #objref</v>
      </type>
      <desc>
        <p>This operation terminates any previous set trigger, and set a new trigger
          specified by the <c>TimeType</c> and <c>UTO</c> objects.</p>
        <p>The relation between the UTO object and the TimeTypes are:</p>
        <list type="bulleted">
          <item>'TTAbsolute' - the UTO object must represent absolute time, i.e.,
           number of 100 nanoseconds passed since 15 october 
           1582 00:00.</item>
          <item>'TTRelative' - the UTO object must represent the from now until when
           the event should be triggered, e.g., within 30*10^7 nanoseconds.</item>
          <item>'TTPeriodic' - the same as for 'TTRelative', but this option
           will trigger an event periodically until timer cancelled.</item>
        </list>
      </desc>
    </func>
    <func>
      <name>cancel_timer(TimerEventHandler) -> boolean()</name>
      <fsummary>Cancel, if possible, triggering of event(s). Return<c>true</c>if an event is actually cancelled, <c>false</c>otherwise</fsummary>
      <type>
        <v>TimerEventHandler = #objref</v>
      </type>
      <desc>
        <p>This operation cancel, if possible, the triggering of event(s). Returns
          <c>true</c> if an event is actually cancelled, <c>false</c> otherwise.</p>
      </desc>
    </func>
    <func>
      <name>set_data(TimerEventHandler, EventData) -> ok</name>
      <fsummary>Change the event data sent when triggered</fsummary>
      <type>
        <v>TimerEventHandler = #objref</v>
        <v>EventData = #any</v>
      </type>
      <desc>
        <p>This operation changes the event data sent when triggered.</p>
      </desc>
    </func>
  </funcs>
  
</erlref>