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

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">

<erlref>
  <header>
    <copyright>
      <year>2000</year>
      <year>2013</year>
      <holder>Ericsson AB, All Rights Reserved</holder>
    </copyright>
    <legalnotice>
  Licensed under the Apache License, Version 2.0 (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.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.

  The Initial Developer of the Original Code is Ericsson AB.
    </legalnotice>

    <title>cosTime</title>
    <prepared>Niclas Eklund</prepared>
    <responsible>Niclas Eklund</responsible>
    <docno></docno>
    <approved>Niclas Eklund</approved>
    <checked></checked>
    <date>2000-01-31</date>
    <rev>PA1</rev>
  </header>
  <module>cosTime</module>
  <modulesummary>The main module of the cosTime application</modulesummary>
  <description>
    <p>To get access to the record definitions for the structures use:      <br></br>
<c>-include_lib("cosTime/include/*.hrl").</c></p>
    <p>This module contains the functions for starting and stopping the application.</p>
    <p>This application use the time base <em>15 october 1582 00:00</em>.
      Performing operations using other time bases will not yield correct result.</p>
    <p>The OMG CosTime specification defines the operation 
      <c>secure_universal_time</c>. As of today we cannot provide this functionality
      considering the criteria demanded to fulfill the OMG specification.</p>
    <p>When using this application, time and inaccuracy supplied by the user must
      be given in number of <em>100 nano seconds</em>. The 
      <em>Time Displacement Factor</em> is positive east of the meridian, while 
      those to the west are negative.</p>
    <p>This application use <c>calender:now_to_universal_time(Now)</c> to create a 
      UTC. Hence, the underlying OS must deliver a correct result when calling 
      <c>erlang:now()</c>.</p>
    <p>When determining the inaccuracy of the system, the user should consider the
      way the time objects will be used. Communicating with other ORB's, add a
      substantial overhead and should be taken into consideration.</p>
  </description>
  <funcs>
    <func>
      <name>install_time() -> Return</name>
      <fsummary>Install the cosTime Time Service part application</fsummary>
      <type>
        <v>Return = ok | {'EXIT', Reason}</v>
      </type>
      <desc>
        <p>This operation installs the cosTime Time Service part application.</p>
      </desc>
    </func>
    <func>
      <name>uninstall_time() -> Return</name>
      <fsummary>Uninstall the cosTime Time Service part application</fsummary>
      <type>
        <v>Return = ok | {'EXIT', Reason}</v>
      </type>
      <desc>
        <p>This operation uninstalls the cosTime Time Service part application.</p>
      </desc>
    </func>
    <func>
      <name>install_timerevent() -> Return</name>
      <fsummary>Install the cosTime Timer Event Service part application</fsummary>
      <type>
        <v>Return = ok | {'EXIT', Reason}</v>
      </type>
      <desc>
        <p>This operation installs the cosTime Timer Event Service part application.</p>
        <note>
          <p>The Timer Event Service part requires <em>Time Service</em> part and 
            <em>cosEvent</em> or the <em>cosNotification</em> application to be installed 
            first.</p>
        </note>
      </desc>
    </func>
    <func>
      <name>uninstall_timerevent() -> Return</name>
      <fsummary>Uninstall the cosTime Timer Event Service part application</fsummary>
      <type>
        <v>Return = ok | {'EXIT', Reason}</v>
      </type>
      <desc>
        <p>This operation uninstalls the cosTime Timer Event Service part application.</p>
      </desc>
    </func>
    <func>
      <name>start() -> Return</name>
      <fsummary>Start the cosTime application</fsummary>
      <type>
        <v>Return = ok | {error, Reason}</v>
      </type>
      <desc>
        <p>This operation starts the cosTime application.</p>
      </desc>
    </func>
    <func>
      <name>stop() -> Return</name>
      <fsummary>Stop the cosTime application</fsummary>
      <type>
        <v>Return = ok | {error, Reason}</v>
      </type>
      <desc>
        <p>This operation stops the cosTime application.</p>
      </desc>
    </func>
    <func>
      <name>start_time_service(Tdf, Inaccuracy) -> Return</name>
      <fsummary>Start a Time Service object</fsummary>
      <type>
        <v>Tdf = short()</v>
        <v>Inaccuracy = ulonglong(), eq. #100 nano seconds</v>
        <v>Return = ok | {'EXCEPTION', #'BAD_PARAM'{}}</v>
      </type>
      <desc>
        <p>This operation starts a Time Service server. Please note that there
          may only be exactly one Time Service active at a time. The <c>Inaccuracy</c>
          parameter defines the inaccuracy the underlying OS will introduce. Remember
          to take into account latency when passing time object between nodes.</p>
      </desc>
    </func>
    <func>
      <name>stop_time_service(TimeService) -> ok</name>
      <fsummary>Stop the target Time Service object</fsummary>
      <type>
        <v>TimeService = #objref</v>
      </type>
      <desc>
        <p>This operation stops the Time Service object.</p>
      </desc>
    </func>
    <func>
      <name>start_timerevent_service(TimeService) -> ok</name>
      <fsummary>Start a Timer Event Service object</fsummary>
      <type>
        <v>TimeService = #objref</v>
      </type>
      <desc>
        <p>This operation starts a Timer Event Service server. Please note that there
          may only be exactly one Timer Event Service per node active at a time. The
          supplied TimeServcie reference will be the object Timer Event Service
          contacts to get access to a new UTC.</p>
      </desc>
    </func>
    <func>
      <name>stop_timerevent_service(TimerEventService) -> ok</name>
      <fsummary>Stop the target Timer Event Service object</fsummary>
      <type>
        <v>TimerEventService = #objref</v>
      </type>
      <desc>
        <p>This operation stops the Timer Event Service object.</p>
      </desc>
    </func>
  </funcs>
  
</erlref>