1 karl  1.41 //%2004////////////////////////////////////////////////////////////////////////

  2 mike  1.10 //

  3 karl  1.41 // Copyright (c) 2000, 2001, 2002 BMC Software; Hewlett-Packard Development
  4            // Company, L.P.; IBM Corp.; The Open Group; Tivoli Systems.
  5            // Copyright (c) 2003 BMC Software; Hewlett-Packard Development Company, L.P.;

  6 karl  1.35 // IBM Corp.; EMC Corporation, The Open Group.

  7 karl  1.41 // Copyright (c) 2004 BMC Software; Hewlett-Packard Development Company, L.P.;
  8            // IBM Corp.; EMC Corporation; VERITAS Software Corporation; The Open Group.

  9 mike  1.10 //
 10            // Permission is hereby granted, free of charge, to any person obtaining a copy

 11 kumpf 1.26 // of this software and associated documentation files (the "Software"), to
 12            // deal in the Software without restriction, including without limitation the
 13            // rights to use, copy, modify, merge, publish, distribute, sublicense, and/or

 14 mike  1.10 // sell copies of the Software, and to permit persons to whom the Software is
 15            // furnished to do so, subject to the following conditions:

 16 karl  1.41 // 

 17 kumpf 1.26 // THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN

 18 mike  1.10 // ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS PROVIDED
 19            // "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT

 20 kumpf 1.26 // LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
 21            // PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
 22            // HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN

 23 mike  1.10 // ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 24            // WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 25            //
 26            //==============================================================================
 27            //
 28            //%/////////////////////////////////////////////////////////////////////////////
 29            
 30            #ifndef Pegasus_DateTime_h
 31            #define Pegasus_DateTime_h
 32            
 33            #include <Pegasus/Common/Config.h>
 34            #include <Pegasus/Common/Array.h>

 35 kumpf 1.29 #include <Pegasus/Common/Linkage.h>

 36 kumpf 1.14 

 37 mike  1.10 PEGASUS_NAMESPACE_BEGIN
 38            

 39 a.arora 1.39 class CIMDateTimeRep;

 40 kumpf   1.24 

 41 mike    1.10 /**

 42 karl    1.36     The CIMDateTime class represents the CIM datetime data type as a C++ class
 43                  CIMDateTime. A CIM datetime may contain a date or an interval. CIMDateTime
 44                  is an intrinsic CIM data type that represents the time as a string with a
 45                  fixed length.

 46 mike    1.10 
 47                  <PRE>
 48                  A date has the following form:

 49 karl    1.36     yyyymmddhhmmss.mmmmmmsutc

 50 mike    1.10 
 51                  Where
 52              

 53 karl    1.36     yyyy = year (1-9999)
 54                  mm = month (1-12)
 55                  dd = day (1-31)
 56                  hh = hour (0-23)
 57                  mm = minute (0-59)
 58                  ss = second (0-59)
 59                  mmmmmm = microseconds
 60                  s = '+' or '-' to represent the Coordinated Universal Time (UTC) sign
 61                  utc = offset from Coordinated Universal Time (UTC)
 62                      (same as Greenwich Mean Time(GMT) offset)

 63 mike    1.10 
 64                  An interval has the following form:
 65              

 66 karl    1.36     ddddddddhhmmss.mmmmmm:000

 67 mike    1.10 
 68                  Where
 69              

 70 karl    1.36     dddddddd = days
 71                  hh = hours (0-23)
 72                  mm = minutes (0-59)
 73                  ss = seconds (0-59)
 74                  mmmmmm = microseconds

 75 mike    1.10     </PRE>
 76              

 77 karl    1.36     Note: Intervals always end in ":000". This distinguishes intervals from dates.

 78 mike    1.10 

 79 kumpf   1.31     CIMDateTime objects are constructed from String objects or from

 80 karl    1.36     other CIMDateTime objects.  Character strings must be exactly
 81                  twenty-five characters in length and conform to either the date or interval
 82                  format.

 83 mike    1.10 

 84 kumpf   1.31     CIMDateTime objects that are not explicitly initialized will be
 85                  implicitly initialized with a zero time interval:

 86 mike    1.10 

 87 karl    1.36     00000000000000.000000:000

 88 mike    1.10 
 89              */
 90              class PEGASUS_COMMON_LINKAGE CIMDateTime
 91              {
 92              public:
 93              

 94 kumpf   1.34     /** Creates a new CIMDateTime object with a zero interval value.

 95 karl    1.12     */

 96 mike    1.10     CIMDateTime();
 97              

 98 karl    1.36     /** Creates a new CIMDateTime object from a string constant representing

 99 kumpf   1.34         the CIM DateTime-formatted datetime.

100 kumpf   1.31         See the class documentation for CIMDateTime for the definition of the

101 karl    1.12         input string for absolute and interval datetime.

102 karl    1.36     @param str  String object containing the CIM DateTime-formatted string.
103                      This must contain twenty-five characters.

104 mike    1.10     */

105 kumpf   1.31     CIMDateTime(const String & str);

106 mike    1.10 

107 kumpf   1.34     /** Creates a CIMDateTime object from another CIMDateTime object.

108 karl    1.36     @param x  Specifies the name of the CIMDateTime object to copy.

109 mike    1.10     */
110                  CIMDateTime(const CIMDateTime& x);
111              

112 a.arora 1.39     /** CIMDateTime destructor. */
113                  ~CIMDateTime();
114              

115 karl    1.36     /** Assigns one instance of the CIMDateTime object to another.
116                      @param x  The CIMDateTime Object to assign to the CIMDateTime object.
117                      For example, you can assign the d1 CIMDateTime instance to the d2
118                      CIMDateTime instance.

119 kumpf   1.34         <PRE>
120                          CIMDateTime d1;
121                          CIMDateTime d2 = "00000000000000.000000:000";

122 karl    1.36             d1 = d2;

123 kumpf   1.34         </PRE>

124 karl    1.36         Therefore, d1 is assigned the same "00000000000000.000000:000" value as d2.

125 mike    1.10     */
126                  CIMDateTime& operator=(const CIMDateTime& x);
127              

128 kumpf   1.34     /** Returns a string representing the DateTime value of the

129 karl    1.36         CIMDateTime object.

130 kumpf   1.34         @return String representing the DateTime value.

131 karl    1.12     */

132 kumpf   1.31     String toString () const;

133 mike    1.10 

134 karl    1.36     /** Sets the date and time in the CIMDateTime object from
135                  the input parameter.

136 kumpf   1.34         @param str  String constant containing the datetime

137 karl    1.36     in the datetime format. This must conform the to formatting rules specified
138                      in the CIMDateTime class description.  For example, the following sets
139                      the date to December 24, 1999 and time to 12:00 P.M.

140 mike    1.10 

141 karl    1.36         <PRE>
142                      CIMDateTime dt;
143                      dt.set("19991224120000.000000+360");
144                      </PRE>

145 mike    1.10 

146 karl    1.36     @exception InvalidDateTimeFormatException because the date and time is not
147                      formatted correctly.  See the CIMDateTime class decscription for the
148                      formatting rules.

149 mike    1.10     */

150 kumpf   1.31     void set(const String & str);

151 mike    1.10 

152 karl    1.36     /** Clears the datetime class object.  The date time is set to

153 kumpf   1.34         a zero interval value.

154 karl    1.12     */

155 mike    1.10     void clear();
156              

157 karl    1.36     /** Receives the current time as CIMDateTime. The time is returned as the local time.
158                      @return CIMDateTime object containing the current date and time.

159 kumpf   1.14     */
160                  static CIMDateTime getCurrentDateTime();
161              

162 karl    1.36     /** Computes the difference in microseconds between two CIMDateTime dates or
163                      two CIMDateTime intervals.

164 kumpf   1.34         @param startTime  Contains the start datetime.
165                      @param finishTime  Contains the finish datetime.

166 karl    1.36         @return Integer that contains the difference between the two datetime values

167 kumpf   1.34         in microseconds.

168 karl    1.36         @exception InvalidDateTimeFormatException If one argument uses the interval
169                      format and the other uses the string format.

170 kumpf   1.34         @exception DateTimeOutOfRangeException If datetime is outside the allowed
171                      range.
172              

173 karl    1.36         Note: The behavior on HP-UX and Windows platform is to throw an exception

174 kumpf   1.34         when the dates are out of range. Red Hat Linux platform normalizes the
175                      dates when they are outside their legal interval and will not throw an
176                      exception.

177 karl    1.36 

178 kumpf   1.34         Allowed Date Range:

179 karl    1.36         The mktime (3C) man page on HP-UX does not document the allowed range.
180                      The approximate range of dates allowed on HP-UX is between

181 kumpf   1.34         1901 and 2038.

182 kumpf   1.33 

183 karl    1.36         On Windows platform, the approximate range is between 1970 to 2038.
184              
185                      On Red Hat Linux platform the approximate range is between 1901 and 2038.

186 kumpf   1.14     */

187 kumpf   1.22     static Sint64 getDifference(CIMDateTime startTime, CIMDateTime finishTime);

188 karl    1.36 

189 kumpf   1.34     /** Checks whether the datetime is an interval.

190 karl    1.36         @return True if the datetime is an interval; otherwise, false.

191 kumpf   1.14     */
192                  Boolean isInterval();
193              

194 karl    1.36     /** Compares the CIMDateTime object to another CIMDateTime object for

195 kumpf   1.34         equality.
196                      @param x  CIMDateTime object to be compared.

197 karl    1.36         @return true if the two CIMDateTime objects are equal; otherwise, false.

198 kumpf   1.31     */
199                  Boolean equal (const CIMDateTime & x) const;
200              

201 kumpf   1.17 private:

202 kumpf   1.21 

203 a.arora 1.39     CIMDateTimeRep* _rep;

204 kumpf   1.31     Boolean _set(const String & dateTimeStr);

205 mike    1.10 };

206 karl    1.36 /**
207                      Add documentation here.
208                  */

209 mike    1.10 PEGASUS_COMMON_LINKAGE Boolean operator==(

210 karl    1.36     /**
211                      Add documentation here.
212                  */
213                  const CIMDateTime& x,
214                  /**
215                      Add documentation here.
216                  */

217 mike    1.10     const CIMDateTime& y);
218              
219              #define PEGASUS_ARRAY_T CIMDateTime

220 kumpf   1.25 # include <Pegasus/Common/ArrayInter.h>

221 mike    1.10 #undef PEGASUS_ARRAY_T
222              
223              PEGASUS_NAMESPACE_END
224              
225              #endif /* Pegasus_DateTime_h */