nsprpub/pr/include/prtime.h@6474c204b198 (annotated)
nsprpub/pr/include/prtime.h
Wed, 31 Dec 2014 06:09:35 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 06:09:35 +0100
- changeset 0
- 6474c204b198
- permissions
- -rw-r--r--
Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.
| michael@0 | 1 | /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ |
| michael@0 | 2 | /* This Source Code Form is subject to the terms of the Mozilla Public |
| michael@0 | 3 | * License, v. 2.0. If a copy of the MPL was not distributed with this |
| michael@0 | 4 | * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ |
| michael@0 | 5 | |
| michael@0 | 6 | /* |
| michael@0 | 7 | *---------------------------------------------------------------------- |
| michael@0 | 8 | * |
| michael@0 | 9 | * prtime.h -- |
| michael@0 | 10 | * |
| michael@0 | 11 | * NSPR date and time functions |
| michael@0 | 12 | * |
| michael@0 | 13 | *----------------------------------------------------------------------- |
| michael@0 | 14 | */ |
| michael@0 | 15 | |
| michael@0 | 16 | #ifndef prtime_h___ |
| michael@0 | 17 | #define prtime_h___ |
| michael@0 | 18 | |
| michael@0 | 19 | #include "prlong.h" |
| michael@0 | 20 | |
| michael@0 | 21 | PR_BEGIN_EXTERN_C |
| michael@0 | 22 | |
| michael@0 | 23 | /**********************************************************************/ |
| michael@0 | 24 | /************************* TYPES AND CONSTANTS ************************/ |
| michael@0 | 25 | /**********************************************************************/ |
| michael@0 | 26 | |
| michael@0 | 27 | #define PR_MSEC_PER_SEC 1000L |
| michael@0 | 28 | #define PR_USEC_PER_SEC 1000000L |
| michael@0 | 29 | #define PR_NSEC_PER_SEC 1000000000L |
| michael@0 | 30 | #define PR_USEC_PER_MSEC 1000L |
| michael@0 | 31 | #define PR_NSEC_PER_MSEC 1000000L |
| michael@0 | 32 | |
| michael@0 | 33 | /* |
| michael@0 | 34 | * PRTime -- |
| michael@0 | 35 | * |
| michael@0 | 36 | * NSPR represents basic time as 64-bit signed integers relative |
| michael@0 | 37 | * to midnight (00:00:00), January 1, 1970 Greenwich Mean Time (GMT). |
| michael@0 | 38 | * (GMT is also known as Coordinated Universal Time, UTC.) |
| michael@0 | 39 | * The units of time are in microseconds. Negative times are allowed |
| michael@0 | 40 | * to represent times prior to the January 1970 epoch. Such values are |
| michael@0 | 41 | * intended to be exported to other systems or converted to human |
| michael@0 | 42 | * readable form. |
| michael@0 | 43 | * |
| michael@0 | 44 | * Notes on porting: PRTime corresponds to time_t in ANSI C. NSPR 1.0 |
| michael@0 | 45 | * simply uses PRInt64. |
| michael@0 | 46 | */ |
| michael@0 | 47 | |
| michael@0 | 48 | typedef PRInt64 PRTime; |
| michael@0 | 49 | |
| michael@0 | 50 | /* |
| michael@0 | 51 | * Time zone and daylight saving time corrections applied to GMT to |
| michael@0 | 52 | * obtain the local time of some geographic location |
| michael@0 | 53 | */ |
| michael@0 | 54 | |
| michael@0 | 55 | typedef struct PRTimeParameters { |
| michael@0 | 56 | PRInt32 tp_gmt_offset; /* the offset from GMT in seconds */ |
| michael@0 | 57 | PRInt32 tp_dst_offset; /* contribution of DST in seconds */ |
| michael@0 | 58 | } PRTimeParameters; |
| michael@0 | 59 | |
| michael@0 | 60 | /* |
| michael@0 | 61 | * PRExplodedTime -- |
| michael@0 | 62 | * |
| michael@0 | 63 | * Time broken down into human-readable components such as year, month, |
| michael@0 | 64 | * day, hour, minute, second, and microsecond. Time zone and daylight |
| michael@0 | 65 | * saving time corrections may be applied. If they are applied, the |
| michael@0 | 66 | * offsets from the GMT must be saved in the 'tm_params' field so that |
| michael@0 | 67 | * all the information is available to reconstruct GMT. |
| michael@0 | 68 | * |
| michael@0 | 69 | * Notes on porting: PRExplodedTime corrresponds to struct tm in |
| michael@0 | 70 | * ANSI C, with the following differences: |
| michael@0 | 71 | * - an additional field tm_usec; |
| michael@0 | 72 | * - replacing tm_isdst by tm_params; |
| michael@0 | 73 | * - the month field is spelled tm_month, not tm_mon; |
| michael@0 | 74 | * - we use absolute year, AD, not the year since 1900. |
| michael@0 | 75 | * The corresponding type in NSPR 1.0 is called PRTime. Below is |
| michael@0 | 76 | * a table of date/time type correspondence in the three APIs: |
| michael@0 | 77 | * API time since epoch time in components |
| michael@0 | 78 | * ANSI C time_t struct tm |
| michael@0 | 79 | * NSPR 1.0 PRInt64 PRTime |
| michael@0 | 80 | * NSPR 2.0 PRTime PRExplodedTime |
| michael@0 | 81 | */ |
| michael@0 | 82 | |
| michael@0 | 83 | typedef struct PRExplodedTime { |
| michael@0 | 84 | PRInt32 tm_usec; /* microseconds past tm_sec (0-99999) */ |
| michael@0 | 85 | PRInt32 tm_sec; /* seconds past tm_min (0-61, accomodating |
| michael@0 | 86 | up to two leap seconds) */ |
| michael@0 | 87 | PRInt32 tm_min; /* minutes past tm_hour (0-59) */ |
| michael@0 | 88 | PRInt32 tm_hour; /* hours past tm_day (0-23) */ |
| michael@0 | 89 | PRInt32 tm_mday; /* days past tm_mon (1-31, note that it |
| michael@0 | 90 | starts from 1) */ |
| michael@0 | 91 | PRInt32 tm_month; /* months past tm_year (0-11, Jan = 0) */ |
| michael@0 | 92 | PRInt16 tm_year; /* absolute year, AD (note that we do not |
| michael@0 | 93 | count from 1900) */ |
| michael@0 | 94 | |
| michael@0 | 95 | PRInt8 tm_wday; /* calculated day of the week |
| michael@0 | 96 | (0-6, Sun = 0) */ |
| michael@0 | 97 | PRInt16 tm_yday; /* calculated day of the year |
| michael@0 | 98 | (0-365, Jan 1 = 0) */ |
| michael@0 | 99 | |
| michael@0 | 100 | PRTimeParameters tm_params; /* time parameters used by conversion */ |
| michael@0 | 101 | } PRExplodedTime; |
| michael@0 | 102 | |
| michael@0 | 103 | /* |
| michael@0 | 104 | * PRTimeParamFn -- |
| michael@0 | 105 | * |
| michael@0 | 106 | * A function of PRTimeParamFn type returns the time zone and |
| michael@0 | 107 | * daylight saving time corrections for some geographic location, |
| michael@0 | 108 | * given the current time in GMT. The input argument gmt should |
| michael@0 | 109 | * point to a PRExplodedTime that is in GMT, i.e., whose |
| michael@0 | 110 | * tm_params contains all 0's. |
| michael@0 | 111 | * |
| michael@0 | 112 | * For any time zone other than GMT, the computation is intended to |
| michael@0 | 113 | * consist of two steps: |
| michael@0 | 114 | * - Figure out the time zone correction, tp_gmt_offset. This number |
| michael@0 | 115 | * usually depends on the geographic location only. But it may |
| michael@0 | 116 | * also depend on the current time. For example, all of China |
| michael@0 | 117 | * is one time zone right now. But this situation may change |
| michael@0 | 118 | * in the future. |
| michael@0 | 119 | * - Figure out the daylight saving time correction, tp_dst_offset. |
| michael@0 | 120 | * This number depends on both the geographic location and the |
| michael@0 | 121 | * current time. Most of the DST rules are expressed in local |
| michael@0 | 122 | * current time. If so, one should apply the time zone correction |
| michael@0 | 123 | * to GMT before applying the DST rules. |
| michael@0 | 124 | */ |
| michael@0 | 125 | |
| michael@0 | 126 | typedef PRTimeParameters (PR_CALLBACK *PRTimeParamFn)(const PRExplodedTime *gmt); |
| michael@0 | 127 | |
| michael@0 | 128 | /**********************************************************************/ |
| michael@0 | 129 | /****************************** FUNCTIONS *****************************/ |
| michael@0 | 130 | /**********************************************************************/ |
| michael@0 | 131 | |
| michael@0 | 132 | /* |
| michael@0 | 133 | * The PR_Now routine returns the current time relative to the |
| michael@0 | 134 | * epoch, midnight, January 1, 1970 UTC. The units of the returned |
| michael@0 | 135 | * value are microseconds since the epoch. |
| michael@0 | 136 | * |
| michael@0 | 137 | * The values returned are not guaranteed to advance in a linear fashion |
| michael@0 | 138 | * due to the application of time correction protocols which synchronize |
| michael@0 | 139 | * computer clocks to some external time source. Consequently it should |
| michael@0 | 140 | * not be depended on for interval timing. |
| michael@0 | 141 | * |
| michael@0 | 142 | * The implementation is machine dependent. |
| michael@0 | 143 | * Cf. time_t time(time_t *tp) in ANSI C. |
| michael@0 | 144 | */ |
| michael@0 | 145 | NSPR_API(PRTime) |
| michael@0 | 146 | PR_Now(void); |
| michael@0 | 147 | |
| michael@0 | 148 | /* |
| michael@0 | 149 | * Expand time binding it to time parameters provided by PRTimeParamFn. |
| michael@0 | 150 | * The calculation is envisoned to proceed in the following steps: |
| michael@0 | 151 | * - From given PRTime, calculate PRExplodedTime in GMT |
| michael@0 | 152 | * - Apply the given PRTimeParamFn to the GMT that we just calculated |
| michael@0 | 153 | * to obtain PRTimeParameters. |
| michael@0 | 154 | * - Add the PRTimeParameters offsets to GMT to get the local time |
| michael@0 | 155 | * as PRExplodedTime. |
| michael@0 | 156 | */ |
| michael@0 | 157 | |
| michael@0 | 158 | NSPR_API(void) PR_ExplodeTime( |
| michael@0 | 159 | PRTime usecs, PRTimeParamFn params, PRExplodedTime *exploded); |
| michael@0 | 160 | |
| michael@0 | 161 | /* Reverse operation of PR_ExplodeTime */ |
| michael@0 | 162 | NSPR_API(PRTime) |
| michael@0 | 163 | PR_ImplodeTime(const PRExplodedTime *exploded); |
| michael@0 | 164 | |
| michael@0 | 165 | /* |
| michael@0 | 166 | * Adjust exploded time to normalize field overflows after manipulation. |
| michael@0 | 167 | * Note that the following fields of PRExplodedTime should not be |
| michael@0 | 168 | * manipulated: |
| michael@0 | 169 | * - tm_month and tm_year: because the number of days in a month and |
| michael@0 | 170 | * number of days in a year are not constant, it is ambiguous to |
| michael@0 | 171 | * manipulate the month and year fields, although one may be tempted |
| michael@0 | 172 | * to. For example, what does "a month from January 31st" mean? |
| michael@0 | 173 | * - tm_wday and tm_yday: these fields are calculated by NSPR. Users |
| michael@0 | 174 | * should treat them as "read-only". |
| michael@0 | 175 | */ |
| michael@0 | 176 | |
| michael@0 | 177 | NSPR_API(void) PR_NormalizeTime( |
| michael@0 | 178 | PRExplodedTime *exploded, PRTimeParamFn params); |
| michael@0 | 179 | |
| michael@0 | 180 | /**********************************************************************/ |
| michael@0 | 181 | /*********************** TIME PARAMETER FUNCTIONS *********************/ |
| michael@0 | 182 | /**********************************************************************/ |
| michael@0 | 183 | |
| michael@0 | 184 | /* Time parameters that suit current host machine */ |
| michael@0 | 185 | NSPR_API(PRTimeParameters) PR_LocalTimeParameters(const PRExplodedTime *gmt); |
| michael@0 | 186 | |
| michael@0 | 187 | /* Time parameters that represent Greenwich Mean Time */ |
| michael@0 | 188 | NSPR_API(PRTimeParameters) PR_GMTParameters(const PRExplodedTime *gmt); |
| michael@0 | 189 | |
| michael@0 | 190 | /* |
| michael@0 | 191 | * Time parameters that represent the US Pacific Time Zone, with the |
| michael@0 | 192 | * current daylight saving time rules (for testing only) |
| michael@0 | 193 | */ |
| michael@0 | 194 | NSPR_API(PRTimeParameters) PR_USPacificTimeParameters(const PRExplodedTime *gmt); |
| michael@0 | 195 | |
| michael@0 | 196 | /* |
| michael@0 | 197 | * This parses a time/date string into a PRExplodedTime |
| michael@0 | 198 | * struct. It populates all fields but it can't split |
| michael@0 | 199 | * the offset from UTC into tp_gmt_offset and tp_dst_offset in |
| michael@0 | 200 | * most cases (exceptions: PST/PDT, MST/MDT, CST/CDT, EST/EDT, GMT/BST). |
| michael@0 | 201 | * In those cases tp_gmt_offset will be the sum of these two and |
| michael@0 | 202 | * tp_dst_offset will be 0. |
| michael@0 | 203 | * It returns PR_SUCCESS on success, and PR_FAILURE |
| michael@0 | 204 | * if the time/date string can't be parsed. |
| michael@0 | 205 | * |
| michael@0 | 206 | * Many formats are handled, including: |
| michael@0 | 207 | * |
| michael@0 | 208 | * 14 Apr 89 03:20:12 |
| michael@0 | 209 | * 14 Apr 89 03:20 GMT |
| michael@0 | 210 | * Fri, 17 Mar 89 4:01:33 |
| michael@0 | 211 | * Fri, 17 Mar 89 4:01 GMT |
| michael@0 | 212 | * Mon Jan 16 16:12 PDT 1989 |
| michael@0 | 213 | * Mon Jan 16 16:12 +0130 1989 |
| michael@0 | 214 | * 6 May 1992 16:41-JST (Wednesday) |
| michael@0 | 215 | * 22-AUG-1993 10:59:12.82 |
| michael@0 | 216 | * 22-AUG-1993 10:59pm |
| michael@0 | 217 | * 22-AUG-1993 12:59am |
| michael@0 | 218 | * 22-AUG-1993 12:59 PM |
| michael@0 | 219 | * Friday, August 04, 1995 3:54 PM |
| michael@0 | 220 | * 06/21/95 04:24:34 PM |
| michael@0 | 221 | * 20/06/95 21:07 |
| michael@0 | 222 | * 95-06-08 19:32:48 EDT |
| michael@0 | 223 | * |
| michael@0 | 224 | * If the input string doesn't contain a description of the timezone, |
| michael@0 | 225 | * we consult the `default_to_gmt' to decide whether the string should |
| michael@0 | 226 | * be interpreted relative to the local time zone (PR_FALSE) or GMT (PR_TRUE). |
| michael@0 | 227 | * The correct value for this argument depends on what standard specified |
| michael@0 | 228 | * the time string which you are parsing. |
| michael@0 | 229 | */ |
| michael@0 | 230 | |
| michael@0 | 231 | NSPR_API(PRStatus) PR_ParseTimeStringToExplodedTime ( |
| michael@0 | 232 | const char *string, |
| michael@0 | 233 | PRBool default_to_gmt, |
| michael@0 | 234 | PRExplodedTime *result); |
| michael@0 | 235 | |
| michael@0 | 236 | /* |
| michael@0 | 237 | * This uses PR_ParseTimeStringToExplodedTime to parse |
| michael@0 | 238 | * a time/date string and PR_ImplodeTime to transform it into |
| michael@0 | 239 | * a PRTime (microseconds after "1-Jan-1970 00:00:00 GMT"). |
| michael@0 | 240 | * It returns PR_SUCCESS on success, and PR_FAILURE |
| michael@0 | 241 | * if the time/date string can't be parsed. |
| michael@0 | 242 | */ |
| michael@0 | 243 | |
| michael@0 | 244 | NSPR_API(PRStatus) PR_ParseTimeString ( |
| michael@0 | 245 | const char *string, |
| michael@0 | 246 | PRBool default_to_gmt, |
| michael@0 | 247 | PRTime *result); |
| michael@0 | 248 | |
| michael@0 | 249 | /* Format a time value into a buffer. Same semantics as strftime() */ |
| michael@0 | 250 | NSPR_API(PRUint32) PR_FormatTime(char *buf, int buflen, const char *fmt, |
| michael@0 | 251 | const PRExplodedTime *tm); |
| michael@0 | 252 | |
| michael@0 | 253 | /* Format a time value into a buffer. Time is always in US English format, regardless |
| michael@0 | 254 | * of locale setting. |
| michael@0 | 255 | */ |
| michael@0 | 256 | NSPR_API(PRUint32) |
| michael@0 | 257 | PR_FormatTimeUSEnglish( char* buf, PRUint32 bufSize, |
| michael@0 | 258 | const char* format, const PRExplodedTime* tm ); |
| michael@0 | 259 | |
| michael@0 | 260 | PR_END_EXTERN_C |
| michael@0 | 261 | |
| michael@0 | 262 | #endif /* prtime_h___ */ |
