//File: CosTime.idl
//Part of the Time Service

#ifndef _COS_TIME_IDL_
#define _COS_TIME_IDL_

#include <TimeBase.idl>
#pragma prefix  "omg.org";

module CosTime {

 	/**
  	* TimeComparaison defines the possilbe values that can be returned as a result of comparaing two UTOs. The values are self explanatory.
  	* In an IntervalC comparaison, TCIndeterminate value is returned if the error envelopes around the two times being compared overlap.
  	* For this purpose the error envelope is assumed to be symmetricallly placed around the base time covering time-inaccuracy to time+inaccuracy.
  	* For IntervalC comparaison, two UTOs are deemedto contain the same time only if the Time attribute of the two objects are equal and the Inaccuracy
  	* attributes of both the objects are zero.
  	*/
 	enum TimeComparison {
 		TCEqualTo,
 		TCLessThan,
 		TCGreaterThan,
 		TCIndeterminate
 	};

 	/**
  	* ComparaisonType defines the two types of time comparaison that are supported.
  	* IntervalC comparaison does the comparaison taking into account the error envelope.
  	* MidC comparaison just compare the base times. A Midc comparaison can never return TCIndeterminate.
  	*/
 	enum ComparisonType{
 		IntervalC,
 		MidC
 	};

 	/**
  	* OverlapType specifies the type of overlap between two time intervals.
  	* When Interval A wholly contains interval B, then it is an OTContainer of interval B and the overlap interval
  	* is the same as the interval B. When interval B wholly contains interval A, then interval A is OTContained in interval
  	* B and the overlap region is the same as interval A. When neither interval is wholly contained in the other but
  	* they overlap, then the OTOverlap case applies and the overlap region is the length of interval that overlaps.
  	* Finally, when the two intervals do not overlap, the OTNoOverlap case applies.
  	*/
 	enum OverlapType {
 		OTContainer,
 		OTContained,
 		OTOverlap,
 		OTNoOverlap
 	};

 	/**
  	* This exception is raised when the underlying trusted time service fails, or is unable to provide time that meets
  	* the required security assusrance.
  	*/
 	exception TimeUnavailable {};

	 interface TIO;		// forward declaration

 	/**
  	* The Uto provides various operations on basic time. These include the following groups of operations:
  	* - Construction of a UTO from piece parts, and extraction of piece parts from a UTO
  	* - Comparaison of time.
  	* - Conversion from relative to absolute time, and conversion to an interval.
  	* Of these, the first operation is required for completenesss,since in its absence it would be difficult to provide
  	* a time input to the timer event handler, for example. The second operation is required by the RFP, and the third is
  	* required for completeness and usability.
  	*
  	* The Uto interface corresponds to an object that contains utc time,and is the means for manipulating the time contained in
  	* the object. This interface has opearations for getting a UtcT type data structure containing the current value of time in the object,
  	* as well as operations for getting the values of individual fields of utc time, getting absolute time from relative time, and comparing
  	* and doing bounds operations on UTOs. The UTO interface does not provide any operation for modifying the time in the object. It is intended that
  	* UTOs are immutable.
  	*/
  interface UTO {
  		readonly attribute TimeBase::TimeT			time;
  		readonly attribute TimeBase::InaccuracyT	inaccuracy;
  		readonly attribute TimeBase::TdfT 			tdf;
  		readonly attribute TimeBase::UtcT 			utc_time;
  		UTO absolute_time();
  		TimeComparison compare_time(
  			in	ComparisonType	comparison_type,
  			in	CosTime::UTO    uto_
  		);
  		TIO time_to_interval(
  			in	CosTime::UTO	uto_);
  		TIO interval();
  };

 	/**
  	* The TIO represents a time interval and contains operations relevant to time intervals
  	*/
 	interface TIO {

   	/**
    	* This attribute returns an IntervalT structure with the value of its fields filled in with the corresponding values from
    	* the TIO
    	*/
  		readonly attribute TimeBase::IntervalT 	time_interval;

   	/**
    	* This operation returns a value of type OverlapType depending on how the interval in the object and the time range
    	* represented by the parameter UTO overlap. The interval in the object is interval A and the interval in the parameter
    	* UTO is interval B. If OverlapType is not OTNoOverLap, then the out parameter overlap contains the overlap interval, otherwise
    	* the out parameter contains the gap between the two intervals. The exception CORBA::BAD_PARAM is raised if the UTO passed in is invalid
    	*/
  		OverlapType spans (
  			in	UTO			time,
  			out TIO			overlap);

   	/**
    	* This operation returns a value of type OverlapType depending on how the interval in the object and interval in the parameter TIO
    	* overlap. The interval in the object is interval A and the interval in the parameter TOI is interval B. If OverlapType is not
    	* OTNoOverlap, then the out parameter overlap contains the overlap interval, otherwise the out parameter contains the gap between the
    	* two interval. The exception CORBA::BAD_PARAM is raised if the TOI passed in is invalid.
    	*/
  		OverlapType overlaps (
  			in 	TIO			interval,
  			out TIO			overlap);
  		UTO time ();
  };

 	/**
  	* The TimeService interface provides operations for obtaining the current time, constructing a UTO with specified values for each
  	* attribute, and constructing a TIO wuth specified upped and lower bounds.
  	*/
 	interface TimeService {

 	/**
  	* The universal_time operation returns the current time and an estimate of inaccuracy in a UTO. It raises TimeUnavailable exceptions
  	* to indicate failure of an underlying time provider. The time returned in the UTO by this operation is not guaranteed to be secure
  	* or trusted. If any time is available at alll, that tile is returned by this operation.
  	*/
 	UTO universal_time()
 			raises(TimeUnavailable);
 	/**
  	* The secure_universal_time operation returns the current time in a UTO only if the time can be guaranteed to have been obtained
  	* securely. In order to make such a guarantee, the  underlying TimeService must meet the criteria to be followed for secure time
  	* implementation guideslines. If there is any uncertainty at all about meeting any aspect of these criteria, then this operation must
  	* return the TimeUnavailable exception. Thus, time obtained through this operation can alwys be trusted.
  	*/
 	UTO secure_universal_time()
 			raises(TimeUnavailable);

		UTO new_universal_time(
 			in TimeBase::TimeT			time,
 			in TimeBase::InaccuracyT	inaccuracy,
 			in TimeBase::TdfT			tdf);

		UTO uto_from_utc(
			 in TimeBase::UtcT			utc);

		TIO new_interval(
 			in TimeBase::TimeT			lower,
 			in TimeBase::TimeT			upper);
	};
};

#endif // _COS_TIME_IDL_
