1 /* ------------------------------------------------------------------ 2 * Copyright (C) 1998-2009 PacketVideo 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either 13 * express or implied. 14 * See the License for the specific language governing permissions 15 * and limitations under the License. 16 * ------------------------------------------------------------------- 17 */ 18 // -*- c++ -*- 19 // = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = 20 21 // O S C L _ T I M E ( T I M E F U N C T I O N S ) 22 23 // = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = 24 25 /*! \addtogroup osclbase OSCL Base 26 * 27 * @{ 28 */ 29 30 31 /*! \file oscl_time.h 32 \brief The file oscl_time.h defines to classes NTPTime and TimeValue 33 for getting, manipulating, and formatting time values. 34 The TimeValue class is based on the native system time format while 35 NTPTime is used for the standard Network Time Protocol format. 36 */ 37 38 39 #ifndef OSCL_TIME_H_INCLUDED 40 #define OSCL_TIME_H_INCLUDED 41 42 // - - Inclusion - - - - - - - - - - - - - - - - - - - - - - - - - - - - 43 44 #ifndef OSCL_BASE_H_INCLUDED 45 #include "oscl_base.h" 46 #endif 47 48 #ifndef OSCLCONFIG_TIME_H_INCLUDED 49 #include "osclconfig_time.h" 50 #endif 51 52 #ifndef OSCL_INT64_UTILS_INCLUDED 53 #include "oscl_int64_utils.h" 54 #endif 55 56 const int CTIME_BUFFER_SIZE = 26; 57 58 const int PV8601TIME_BUFFER_SIZE = 21; 59 60 typedef char CtimeStrBuf[CTIME_BUFFER_SIZE]; 61 typedef char PV8601timeStrBuf[PV8601TIME_BUFFER_SIZE]; 62 63 class TimeValue; // Forward definition 64 65 OSCL_IMPORT_REF void PV8601ToRFC822(PV8601timeStrBuf pv8601_buffer, CtimeStrBuf ctime_buffer); 66 OSCL_IMPORT_REF void RFC822ToPV8601(CtimeStrBuf ctime_buffer, PV8601timeStrBuf); 67 68 // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 69 //! The TimeUnits enum can be used when constructing a TimeValue class. 70 typedef enum { SECONDS = 0, MILLISECONDS = 1, MICROSECONDS = 2 } TimeUnits; 71 72 const long USEC_PER_SEC = 1000000; 73 const long MSEC_PER_SEC = 1000; 74 75 //! The following are used internally so not documented in the API 76 static const long MapToSeconds[] = {1, 1000, 1000000}; 77 static const long MapToUSeconds[] = {1000000, 1000, 1}; 78 static const long MapTo100NanoSeconds[] = {10000000, 10000, 10}; 79 const uint32 unix_ntp_offset = 2208988800U; 80 81 // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 82 83 //! The NTPTime class represents a time value as the number of seconds since 0h (UTC) Jan. 1, 1900 84 /*! 85 The NTPTime class: 86 Conversion to/from Unix (epoch at 0h Jan. 1, 1970) amount to addition/subtraction of 2208988800. 87 A single 64 bit value is used to represent the time. This value represents the number of seconds 88 since 0h (UTC) Jan. 1, 1900. There is an implied binary point betweeen the upper 32 bits and lower 89 32 bits (this is referred to as a 32.32 fractional representation). 90 For example a binary value of 00000000 00000000 00000000 00000011 10000000 00000000 00000000 00000000 91 represents 3.5 seconds since Jan 1, 1900. 92 */ 93 class NTPTime 94 { 95 96 private: 97 uint64 timevalue; 98 99 public: 100 //! The default constructor creates an NTPTime instance representing the current system time. 101 OSCL_COND_IMPORT_REF NTPTime(); 102 103 //! Copy constructor to create a new NTPTime from an existing one. 104 OSCL_COND_IMPORT_REF NTPTime(const NTPTime& src); 105 106 //! Construct an NTPTime from a uint32. 107 /*! \param seconds The uint32 input represents the number of seconds since Jan. 1, 1900. */ 108 OSCL_COND_IMPORT_REF NTPTime(const uint32 seconds); 109 110 //! Construct an NTPTime from a int. 111 /*! \param seconds The int input represents the number of seconds since Jan. 1, 1900. */ 112 OSCL_COND_IMPORT_REF NTPTime(const int32 seconds); 113 114 //! Construct a NTPTime instance from a TimeValue instance. 115 /*! 116 This constructor creates an NTPTime value representing the same absolute time as the TimeValue parameter. 117 \param t A reference to a TimeValue object. 118 */ 119 OSCL_COND_IMPORT_REF NTPTime(const TimeValue& t); 120 121 //! Construct a NTPTime instance from a uint64 value. 122 /*! \param value A 64 bit integer argument which is used as the ntp 32.32 fractional representation.*/ 123 OSCL_COND_IMPORT_REF NTPTime(const uint64 value); 124 125 126 //! The assignment operator for a 32 bit integer. 127 /*! \param newval A 32 bit integer representing the upper 32 bits of the 32.32 NTP time (e.g. the number of whole seconds since Jan 1, 1900 UTC).*/ 128 OSCL_COND_IMPORT_REF NTPTime& operator=(uint32 newval); 129 130 //! The assignment operator for a 64 bit integer. 131 /*! \param newval A 64 bit value which represents the 32.32 fractional representation of the ntp time. */ 132 OSCL_COND_IMPORT_REF NTPTime& operator=(uint64 newval); 133 134 //! The += operator is used to add a 64 bit 32.32 value to an existing NTPTime value. 135 /*! \param val The 64 bit 32.32 value to add to this object's value. */ 136 OSCL_COND_IMPORT_REF NTPTime& operator+=(uint64 val); 137 138 //! The - operator allows subtraction of one NTPTime value from another. This is useful to measure an interval. 139 /*! \param ntpt A reference to the NTPTime object to be subracted from this one. */ 140 OSCL_COND_IMPORT_REF NTPTime operator-(const NTPTime &ntpt) const; 141 142 //! This method converts a 32-bit system time to NTP time. 143 /*! 144 This method sets the value of the NTPTime instance to the absolute time 145 represented by the 32 bit input argument. 146 \param systemtime This 32-bit value is interpreted as the number of seconds 147 since the unix epoch Jan. 1 1970. 148 */ 149 void set_from_system_time(const uint32 systemtime); 150 151 //! Grab the middle 32 bits of the 64 bit 32.32 representation. 152 /* \return This method returns the middle 32 bits of the 32.32 representation. */ 153 OSCL_COND_IMPORT_REF uint32 get_middle32() const; 154 155 //! This method returns the upper 32 bits of the 32.32 representation. 156 OSCL_COND_IMPORT_REF uint32 get_upper32() const; 157 158 //! This method returns the lower 32 bits of the 32.32 representation. 159 OSCL_COND_IMPORT_REF uint32 get_lower32() const; 160 161 //! This method converts the ntp time value to system time. 162 /*! 163 This method returns a 32 bit value representing the same absolute time as the NTP time value, 164 but expressed as whole seconds since the unix epoch. The fractional part of the ntp value is discarded. 165 */ 166 int32 to_system_time() const; 167 168 //! This method returns the 32.32 ntp representation. 169 OSCL_COND_IMPORT_REF uint64 get_value() const; 170 171 //! This method sets the 32.32 representation to the current system time value. 172 OSCL_IMPORT_REF int set_to_current_time(); 173 174 }; 175 176 // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 177 //! The TimeValue class represents a time value in a format native to the system. 178 /*! 179 This class provides common time functions independent of any OS. The actual representation used 180 is native to the system that the class is compiled on to increase efficiency. 181 Macros used in this class: 182 - OSCL_HAS_ANSI_STRING_SUPPORT: 183 184 Definitions to determine the type of basic time structure used to store the time 185 - OSCL_HAS_UNIX_TIME_FUNCS 186 - OSCL_HAS_SYMBIAN_SUPPORT 187 - OSCL_HAS_MSWIN_SUPPORT 188 189 190 */ 191 class TimeValue 192 { 193 194 public: 195 //! Create a TimeValue representing the current time. 196 OSCL_COND_IMPORT_REF TimeValue(); 197 198 //! Copy constructor 199 OSCL_COND_IMPORT_REF TimeValue(const TimeValue& Tv); 200 201 //! Create a TimeValue representing an interval of tv units. 202 /*! 203 \param tv The number of units in the interval to be represented by this TimeValue. 204 \param units The units of the tv argument. Must be in the enumeration TimeUnits. 205 */ 206 OSCL_COND_IMPORT_REF TimeValue(long tv, TimeUnits units); 207 208 //! Create a TimeValue representing the absolute time specified by the BasicTimeStruct. 209 /*! \param in_tv OsclBasicTimeStruct as defined for each platform. 210 */ 211 OSCL_COND_IMPORT_REF TimeValue(const OsclBasicTimeStruct& in_tv); 212 213 //! Create a TimeValue representing the absolute time specified by the BasicDateTimeStruct. 214 /*! \param in_ts OsclBasicDateTimeStruct as defined for each platform provides the date in a 215 readable format (i.e. day, date , week etc.) 216 Notes: Implementation incomplete (= not done) on Win32, Wince, Symbian 217 */ 218 OSCL_COND_IMPORT_REF TimeValue(OsclBasicDateTimeStruct in_ts); 219 220 //! Get the local time after having adjusted for daylight saving 221 /*! 222 Notes: Implementation incomplete (= not done) on Win32, Wince, Symbian 223 */ 224 OSCL_COND_IMPORT_REF int32 get_local_time(); 225 226 227 friend class NTPTime; 228 229 //! Set the time value to zero (represents a zero interval). 230 OSCL_COND_IMPORT_REF void set_to_zero(); 231 232 //! Set the time value to the current system time. 233 OSCL_COND_IMPORT_REF void set_to_current_time(); 234 235 //! This method coverts a 32-bit NTP offset to system time 236 /*! 237 This method takes a 32-bit ntp offset which is the number of seconds from 238 0 h Jan 1, 1900 and converts it to the system time 239 */ 240 OSCL_COND_IMPORT_REF void set_from_ntp_time(const uint32 ntp_offset); 241 242 //! Get a 32 bit value representing the seconds since the (system dependent) epoch. 243 /*! 244 \return This call returns a 32 bit value representing the nubmer of seconds since the epoch. 245 On unix systems this represents the number of seconds since the unix epoch Jan 1 1970. 246 On Win32 this represents the number of seconds since Jan 1, 1601. This is intended to be used 247 for intervals rather than for absolute time. (On Win32 for example, a 32 bit value would be too 248 small to represent the number of seconds from the epoch until the current time.) 249 */ 250 OSCL_COND_IMPORT_REF uint32 get_sec() const ; 251 252 OSCL_COND_IMPORT_REF int32 to_msec() const; 253 254 //! Get a 32 bit value representing the number of microseconds in the time value. 255 /*! 256 \return Returns a uint32 value representing the number of microseconds in the time value after subtracting off the whole seconds. 257 */ 258 OSCL_COND_IMPORT_REF uint32 get_usec() const ; 259 260 //! Get a string containing a text representation of this TimeValue object. 261 /*! 262 \param ctime_strbuf A CtimeStrBuf object to which the text representation will be written, 263 \return A pointer to the input CtimeStrBuf is returned. This string is null terminated of the form 264 "Wed Jun 30 21:49:08 1993". 265 */ 266 OSCL_IMPORT_REF char *get_str_ctime(CtimeStrBuf ctime_strbuf); 267 268 //! Get a PV extended text representation of the Time based on the ISO 8601 format. 269 /*! 270 \param time_strbuf A PV8601timeStrBuf object to which the text representation will be written, 271 \return The number of characters copied to the buffer, not including the terminating null. The returned string is of the form "19850412T101530.047Z". 272 */ 273 OSCL_IMPORT_REF int get_pv8601_str_time(PV8601timeStrBuf time_strbuf); 274 275 //! Get a text representation of the time in the GMT timezone based on the RFC 822 / RFC 1123 (also described in the HTTP spec RFC 2068 and RFC 2616. 276 /*! 277 \param max_time_strlen The maximum number of characters that can be written to the buffer. 278 \param time_str A pointer to the buffer to which the characters will be written. 279 \return Returns a pointer to the buffer (same as time_str) containing a null terminated (c-style) string 280 of the form "Wed, 30 Jun 1993 21:49:08 GMT". 281 */ 282 OSCL_IMPORT_REF char *get_rfc822_gmtime_str(int max_time_strlen, 283 char *time_str); 284 285 //! Determine if the time value is zero. 286 OSCL_COND_IMPORT_REF bool is_zero(); 287 288 289 // comparison operators 290 OSCL_COND_IMPORT_REF friend bool operator ==(const TimeValue& a, const TimeValue& b); 291 OSCL_COND_IMPORT_REF friend bool operator !=(const TimeValue& a, const TimeValue& b); 292 OSCL_COND_IMPORT_REF friend bool operator <=(const TimeValue& a, const TimeValue& b); 293 OSCL_COND_IMPORT_REF friend bool operator >=(const TimeValue& a, const TimeValue& b); 294 OSCL_COND_IMPORT_REF friend bool operator <(const TimeValue& a, const TimeValue& b); 295 OSCL_COND_IMPORT_REF friend bool operator >(const TimeValue& a, const TimeValue& b); 296 297 //! Assignment operator 298 OSCL_COND_IMPORT_REF TimeValue& operator =(const TimeValue& a); 299 300 // arithmetic operators 301 //! += operator 302 OSCL_COND_IMPORT_REF TimeValue& operator +=(const TimeValue& a); 303 //! -= operator 304 OSCL_COND_IMPORT_REF TimeValue& operator -=(const TimeValue& a); 305 //! This operator scales the time value by a constant. 306 OSCL_COND_IMPORT_REF TimeValue& operator *=(const int scale); 307 308 OSCL_COND_IMPORT_REF OsclBasicTimeStruct * get_timeval_ptr(); 309 310 private: 311 312 OsclBasicTimeStruct ts; 313 const OsclBasicTimeStruct *getBasicTimeStruct() const 314 { 315 return &ts; 316 }; 317 318 }; 319 320 OSCL_COND_IMPORT_REF TimeValue operator -(const TimeValue& a, const TimeValue& b); 321 322 #if (!OSCL_DISABLE_INLINES) 323 #include "oscl_time.inl" 324 #endif 325 326 327 // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 328 329 /*! @} */ 330 331 332 #endif // OSCL_TIME_H_INCLUDED 333
