1 /*****************************************************************************/
2 /* Software Testing Automation Framework (STAF)                              */
3 /* (C) Copyright IBM Corp. 2001                                              */
4 /*                                                                           */
5 /* This software is licensed under the Eclipse Public License (EPL) V1.0.    */
6 /*****************************************************************************/
7 
8 #ifndef STAF_Timestamp
9 #define STAF_Timestamp
10 
11 #include <time.h>
12 #include "STAFError.h"
13 
14 #ifdef __cplusplus
15 extern "C" {
16 #endif
17 
18 typedef struct STAFRelativeTimeImpl *STAFRelativeTime_t;
19 
20 /****************************************************************************/
21 /* STAFThreadSafeLocalTimeString - This is a thread safe wrapper around     */
22 /*                                 strftime()                               */
23 /*                                                                          */
24 /* Accepts: (In)  Pointer to buffer in which to place time string           */
25 /*          (In)  Size of buffer                                            */
26 /*          (In)  Format string (identical to that accepted by strftime())  */
27 /*          (In)  The time to convert to a string (obtained from time())    */
28 /*          (Out) Pointer to OS return code                                 */
29 /*                                                                          */
30 /* Returns:  kSTAFOk, on success                                            */
31 /*           other on error                                                 */
32 /****************************************************************************/
33 STAFRC_t STAFThreadSafeLocalTimeString(char *buffer, unsigned int bufSize,
34                                        const char *format, time_t theTime,
35                                        unsigned int *osRC);
36 
37 /****************************************************************************/
38 /* STAFThreadSafeLocalTime - Provides a thread safe wrapper around          */
39 /*                           localtime()                                    */
40 /*                                                                          */
41 /* Accepts: (Out) Pointer to a tm structure (from <time.h>                  */
42 /*          (In)  The time to convert to a string (obtained from time())    */
43 /*          (Out) Pointer to OS return code                                 */
44 /*                                                                          */
45 /* Returns:  kSTAFOk, on success                                            */
46 /*           other on error                                                 */
47 /****************************************************************************/
48 STAFRC_t STAFThreadSafeLocalTime(struct tm *theTM, time_t theTime,
49                                  unsigned int *osRC);
50 
51 
52 /****************************************************************************/
53 /* STAFTimestampGetRelativeTime - Gets the current relative time            */
54 /*                                                                          */
55 /* Accepts: (Out) Pointer to a relative time                                */
56 /*          (Out) Pointer to OS return code                                 */
57 /*                                                                          */
58 /* Returns:  kSTAFOk, on success                                            */
59 /*           other on error                                                 */
60 /****************************************************************************/
61 STAFRC_t STAFTimestampGetRelativeTime(STAFRelativeTime_t *relTime,
62                                       unsigned int *osRC);
63 
64 
65 /****************************************************************************/
66 /* STAFTimestampGetRelativeTimeDifference - Gets the difference (in         */
67 /*                                          milliseconds) between two       */
68 /*                                          relative times                  */
69 /*                                                                          */
70 /* Accepts: (In)  Relative time 1                                           */
71 /*          (In)  Relative time 2                                           */
72 /*          (Out) (Relative time 1 - Relative time 2) in milliseconds       */
73 /*                                                                          */
74 /* Returns:  kSTAFOk, on success                                            */
75 /*           other on error                                                 */
76 /*                                                                          */
77 /* Notes  :  1) The difference is undefined if Relative Time 1 is less than */
78 /*              Relative Time 2                                             */
79 /*           2) The difference is undefined if it would be greater than the */
80 /*              size of an unsigned int                                     */
81 /****************************************************************************/
82 STAFRC_t STAFTimestampGetRelativeTimeDifference(const STAFRelativeTime_t lhs,
83                                                 const STAFRelativeTime_t rhs,
84                                                 unsigned int *diffInMillis);
85 
86 
87 /****************************************************************************/
88 /* STAFTimestampFreeRelativeTime - Frees a relative time                    */
89 /*                                                                          */
90 /* Accepts: (I/O) Pointer to a relative time                                */
91 /*                                                                          */
92 /* Returns:  kSTAFOk, on success                                            */
93 /*           other on error                                                 */
94 /****************************************************************************/
95 STAFRC_t STAFTimestampFreeRelativeTime(STAFRelativeTime_t *relTime);
96 
97 
98 #ifdef __cplusplus
99 }
100 
101 #include "STAFString.h"
102 #include "STAFException.h"
103 
104 // STAFTimestamp - Represents a specific point in time.  Provides methods
105 //                 to convert the timestamp to a string and to seconds
106 //                 past midnight, as well as operator-().
107 
108 class STAFTimestamp
109 {
110 public:
111 
112     // Accepted input formats are
113     //
114     //     <date><sep><time>
115     //     <date><sep>
116     //     <date>
117     //     <sep><time>
118     //     <time>
119     //     <sep>
120     //     <empty string>
121     //
122     // Note: Empty <date> defaults to current date
123     //       Empty <time> defaults to 00:00:00
124     //
125     // Accepted date formats are
126     //
127     //     YYYYMMDD
128     //     MM/DD/YYYY
129     //     MM/DD/YY      (YY < 90 is treated as 2000 + YY)
130     //
131     // Accepted time formats are (note: time is in 24-hour format)
132     //
133     //     HH:MM:SS
134     //     HH:MM
135     //     HH
136     //
137     // Note: You may specify multiple characters which could potentially
138     //       separate the date from the time (e.g. '.', '-', '@', etc.)
139 
140     STAFTimestamp(const STAFString &aString,
141                   const STAFString &dateTimeSeps = STAFString(kUTF8_HYPHEN));
142     STAFTimestamp(unsigned int year, unsigned int month, unsigned int day,
143                   unsigned int hour, unsigned int minute, unsigned int second);
144     STAFTimestamp(time_t aTime = time(0));
145 
146     static STAFTimestamp now();
147     static bool isValidTimestampString(const STAFString &aString,
148                                        const STAFString &dateTimeSeps =
149                                        STAFString(kUTF8_HYPHEN));
150     static bool isValidTimestampData(unsigned int year, unsigned int month,
151                                      unsigned int day, unsigned int hour,
152                                      unsigned int minute, unsigned int second);
153 
154     // Pass in the time difference in seconds and get a string containing the
155     // time difference in format "HH:MM:SS", or "HHH:MM:SS" if HH > 24, etc.
156     static STAFString getElapsedTime(unsigned int seconds);
157 
158     STAFString asString(const char *format = "%Y%m%d-%H:%M:%S") const;
asDateString()159     STAFString asDateString() const { return asString("%Y%m%d"); }
asTimeString()160     STAFString asTimeString() const { return asString("%H:%M:%S"); }
161 
162     unsigned int getYear() const;       // 4-digit year
163     unsigned int getMonth() const;      // 1-12
164     unsigned int getDay() const;        // 1-31
165     unsigned int getHour() const;       // 0-23
166     unsigned int getMinute() const;     // 0-59
167     unsigned int getSecond() const;     // 0-59
168 
169     unsigned int asSecondsPastMidnight() const;
170 
171     time_t getImpl() const;
172 
173     // The difference is in seconds
174     unsigned int operator-(const STAFTimestamp &rhs) const;
175 
176     bool operator<(const STAFTimestamp &rhs)  const;
177     bool operator==(const STAFTimestamp &rhs) const { return fTime == rhs.fTime; }
178     bool operator!=(const STAFTimestamp &rhs) const { return !(*this == rhs); }
179     bool operator>(const STAFTimestamp &rhs)  const { return rhs < *this; }
180     bool operator<=(const STAFTimestamp &rhs) const { return !(*this > rhs); }
181     bool operator>=(const STAFTimestamp &rhs) const { return !(*this < rhs); }
182 
183 private:
184 
185     // Need functions to validate year, month, day and hour, min, sec as
186     // mktime doesn't really handle this.
187 
188     bool isValidDate(unsigned int year, unsigned int month, unsigned int day);
189     bool isValidTime(unsigned int hour, unsigned int min, unsigned int sec);
190 
191     static STAFString getTimeFormat(unsigned int in);
192 
193     time_t fTime;
194 };
195 
196 
197 // STAFRelativeTime - Represents a relative point in time.  The primary purpose
198 //                    of this class is to get the difference between two
199 //                    of its instances.
200 
201 class STAFRelativeTime
202 {
203 public:
204 
205     STAFRelativeTime();
206 
207     unsigned int operator-(const STAFRelativeTime &rhs);
208 
209     ~STAFRelativeTime();
210 
211 private:
212 
213     // Disallow copy construction and assignment
214     STAFRelativeTime(const STAFRelativeTime &);
215     STAFRelativeTime &operator=(const STAFRelativeTime &);
216 
217     STAFRelativeTime_t fRelTime;
218 };
219 
220 
221 // Define exceptions
222 
223 STAF_EXCEPTION_DEFINITION(STAFTimestampException, STAFException);
224 STAF_EXCEPTION_DEFINITION(STAFTimestampInvalidDateTimeException,
225                           STAFTimestampException);
226 STAF_EXCEPTION_DEFINITION(STAFTimestampInvalidDateException,
227                           STAFTimestampInvalidDateTimeException);
228 STAF_EXCEPTION_DEFINITION(STAFTimestampInvalidTimeException,
229                           STAFTimestampInvalidDateTimeException);
230 
231 
232 // Now include inline definitions
233 
234 #ifndef STAF_NATIVE_COMPILER
235 #include "STAFTimestampInlImpl.cpp"
236 #endif
237 
238 // End C++ language definitions
239 
240 // End #ifdef __cplusplus
241 #endif
242 
243 #endif
244