1 /* Portions are Copyright (C) 2011 Google Inc */
2 /* ***** BEGIN LICENSE BLOCK *****
3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
4  *
5  * The contents of this file are subject to the Mozilla Public License Version
6  * 1.1 (the "License"); you may not use this file except in compliance with
7  * the License. You may obtain a copy of the License at
8  * http://www.mozilla.org/MPL/
9  *
10  * Software distributed under the License is distributed on an "AS IS" basis,
11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
12  * for the specific language governing rights and limitations under the
13  * License.
14  *
15  * The Original Code is the Netscape Portable Runtime (NSPR).
16  *
17  * The Initial Developer of the Original Code is
18  * Netscape Communications Corporation.
19  * Portions created by the Initial Developer are Copyright (C) 1998-2000
20  * the Initial Developer. All Rights Reserved.
21  *
22  * Contributor(s):
23  *
24  * Alternatively, the contents of this file may be used under the terms of
25  * either the GNU General Public License Version 2 or later (the "GPL"), or
26  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
27  * in which case the provisions of the GPL or the LGPL are applicable instead
28  * of those above. If you wish to allow use of your version of this file only
29  * under the terms of either the GPL or the LGPL, and not to allow others to
30  * use your version of this file under the terms of the MPL, indicate your
31  * decision by deleting the provisions above and replace them with the notice
32  * and other provisions required by the GPL or the LGPL. If you do not delete
33  * the provisions above, a recipient may use your version of this file under
34  * the terms of any one of the MPL, the GPL or the LGPL.
35  *
36  * ***** END LICENSE BLOCK ***** */
37 
38 /*
39  *---------------------------------------------------------------------------
40  *
41  * prtime.h --
42  *
43  *     NSPR date and time functions
44  * CVS revision 3.10
45  * This file contains definitions of NSPR's basic types required by
46  * prtime.cc. These types have been copied over from the following NSPR
47  * files prtime.h, prtypes.h(CVS revision 3.35), prlong.h(CVS revision 3.13)
48  *
49  *---------------------------------------------------------------------------
50  */
51 
52 #ifndef BASE_PRTIME_H__
53 #define BASE_PRTIME_H__
54 
55 #include <stdint.h>
56 
57 #include "base/base_export.h"
58 
59 typedef int8_t PRInt8;
60 typedef int16_t PRInt16;
61 typedef int32_t PRInt32;
62 typedef int64_t PRInt64;
63 typedef int PRIntn;
64 
65 typedef PRIntn PRBool;
66 #define PR_TRUE 1
67 #define PR_FALSE 0
68 
69 typedef enum { PR_FAILURE = -1, PR_SUCCESS = 0 } PRStatus;
70 
71 #define PR_ASSERT DCHECK
72 #define PR_CALLBACK
73 #define PR_INT16_MAX 32767
74 #define NSPR_API(__type) extern __type
75 
76 /*
77  * Long-long (64-bit signed integer type) support macros used by
78  * PR_ImplodeTime().
79  * See http://lxr.mozilla.org/nspr/source/pr/include/prlong.h
80  */
81 
82 #define LL_I2L(l, i) ((l) = (PRInt64)(i))
83 #define LL_MUL(r, a, b) ((r) = (a) * (b))
84 #define LL_ADD(r, a, b) ((r) = (a) + (b))
85 #define LL_SUB(r, a, b) ((r) = (a) - (b))
86 
87 /**********************************************************************/
88 /************************* TYPES AND CONSTANTS ************************/
89 /**********************************************************************/
90 
91 #define PR_MSEC_PER_SEC		1000UL
92 #define PR_USEC_PER_SEC		1000000UL
93 #define PR_NSEC_PER_SEC		1000000000UL
94 #define PR_USEC_PER_MSEC	1000UL
95 #define PR_NSEC_PER_MSEC	1000000UL
96 
97 /*
98  * PRTime --
99  *
100  *     NSPR represents basic time as 64-bit signed integers relative
101  *     to midnight (00:00:00), January 1, 1970 Greenwich Mean Time (GMT).
102  *     (GMT is also known as Coordinated Universal Time, UTC.)
103  *     The units of time are in microseconds. Negative times are allowed
104  *     to represent times prior to the January 1970 epoch. Such values are
105  *     intended to be exported to other systems or converted to human
106  *     readable form.
107  *
108  *     Notes on porting: PRTime corresponds to time_t in ANSI C.  NSPR 1.0
109  *     simply uses PRInt64.
110  */
111 
112 typedef PRInt64 PRTime;
113 
114 /*
115  * Time zone and daylight saving time corrections applied to GMT to
116  * obtain the local time of some geographic location
117  */
118 
119 typedef struct PRTimeParameters {
120     PRInt32 tp_gmt_offset;     /* the offset from GMT in seconds */
121     PRInt32 tp_dst_offset;     /* contribution of DST in seconds */
122 } PRTimeParameters;
123 
124 /*
125  * PRExplodedTime --
126  *
127  *     Time broken down into human-readable components such as year, month,
128  *     day, hour, minute, second, and microsecond.  Time zone and daylight
129  *     saving time corrections may be applied.  If they are applied, the
130  *     offsets from the GMT must be saved in the 'tm_params' field so that
131  *     all the information is available to reconstruct GMT.
132  *
133  *     Notes on porting: PRExplodedTime corrresponds to struct tm in
134  *     ANSI C, with the following differences:
135  *       - an additional field tm_usec;
136  *       - replacing tm_isdst by tm_params;
137  *       - the month field is spelled tm_month, not tm_mon;
138  *       - we use absolute year, AD, not the year since 1900.
139  *     The corresponding type in NSPR 1.0 is called PRTime.  Below is
140  *     a table of date/time type correspondence in the three APIs:
141  *         API          time since epoch          time in components
142  *       ANSI C             time_t                  struct tm
143  *       NSPR 1.0           PRInt64                   PRTime
144  *       NSPR 2.0           PRTime                  PRExplodedTime
145  */
146 
147 typedef struct PRExplodedTime {
148     PRInt32 tm_usec;		    /* microseconds past tm_sec (0-99999)  */
149     PRInt32 tm_sec;             /* seconds past tm_min (0-61, accomodating
150                                    up to two leap seconds) */
151     PRInt32 tm_min;             /* minutes past tm_hour (0-59) */
152     PRInt32 tm_hour;            /* hours past tm_day (0-23) */
153     PRInt32 tm_mday;            /* days past tm_mon (1-31, note that it
154 				                starts from 1) */
155     PRInt32 tm_month;           /* months past tm_year (0-11, Jan = 0) */
156     PRInt16 tm_year;            /* absolute year, AD (note that we do not
157 				                count from 1900) */
158 
159     PRInt8 tm_wday;		        /* calculated day of the week
160 				                (0-6, Sun = 0) */
161     PRInt16 tm_yday;            /* calculated day of the year
162 				                (0-365, Jan 1 = 0) */
163 
164     PRTimeParameters tm_params;  /* time parameters used by conversion */
165 } PRExplodedTime;
166 
167 /*
168  * PRTimeParamFn --
169  *
170  *     A function of PRTimeParamFn type returns the time zone and
171  *     daylight saving time corrections for some geographic location,
172  *     given the current time in GMT.  The input argument gmt should
173  *     point to a PRExplodedTime that is in GMT, i.e., whose
174  *     tm_params contains all 0's.
175  *
176  *     For any time zone other than GMT, the computation is intended to
177  *     consist of two steps:
178  *       - Figure out the time zone correction, tp_gmt_offset.  This number
179  *         usually depends on the geographic location only.  But it may
180  *         also depend on the current time.  For example, all of China
181  *         is one time zone right now.  But this situation may change
182  *         in the future.
183  *       - Figure out the daylight saving time correction, tp_dst_offset.
184  *         This number depends on both the geographic location and the
185  *         current time.  Most of the DST rules are expressed in local
186  *         current time.  If so, one should apply the time zone correction
187  *         to GMT before applying the DST rules.
188  */
189 
190 typedef PRTimeParameters (PR_CALLBACK *PRTimeParamFn)(const PRExplodedTime *gmt);
191 
192 /**********************************************************************/
193 /****************************** FUNCTIONS *****************************/
194 /**********************************************************************/
195 
196 NSPR_API(PRTime)
197 PR_ImplodeTime(const PRExplodedTime *exploded);
198 
199 /*
200  * Adjust exploded time to normalize field overflows after manipulation.
201  * Note that the following fields of PRExplodedTime should not be
202  * manipulated:
203  *   - tm_month and tm_year: because the number of days in a month and
204  *     number of days in a year are not constant, it is ambiguous to
205  *     manipulate the month and year fields, although one may be tempted
206  *     to.  For example, what does "a month from January 31st" mean?
207  *   - tm_wday and tm_yday: these fields are calculated by NSPR.  Users
208  *     should treat them as "read-only".
209  */
210 
211 NSPR_API(void) PR_NormalizeTime(
212     PRExplodedTime *exploded, PRTimeParamFn params);
213 
214 /**********************************************************************/
215 /*********************** TIME PARAMETER FUNCTIONS *********************/
216 /**********************************************************************/
217 
218 /* Time parameters that represent Greenwich Mean Time */
219 NSPR_API(PRTimeParameters) PR_GMTParameters(const PRExplodedTime *gmt);
220 
221 /*
222  * This parses a time/date string into a PRTime
223  * (microseconds after "1-Jan-1970 00:00:00 GMT").
224  * It returns PR_SUCCESS on success, and PR_FAILURE
225  * if the time/date string can't be parsed.
226  *
227  * Many formats are handled, including:
228  *
229  *   14 Apr 89 03:20:12
230  *   14 Apr 89 03:20 GMT
231  *   Fri, 17 Mar 89 4:01:33
232  *   Fri, 17 Mar 89 4:01 GMT
233  *   Mon Jan 16 16:12 PDT 1989
234  *   Mon Jan 16 16:12 +0130 1989
235  *   6 May 1992 16:41-JST (Wednesday)
236  *   22-AUG-1993 10:59:12.82
237  *   22-AUG-1993 10:59pm
238  *   22-AUG-1993 12:59am
239  *   22-AUG-1993 12:59 PM
240  *   Friday, August 04, 1995 3:54 PM
241  *   06/21/95 04:24:34 PM
242  *   20/06/95 21:07
243  *   95-06-08 19:32:48 EDT
244  *   1995-06-17T23:11:25.342156Z
245  *
246  * If the input string doesn't contain a description of the timezone,
247  * we consult the `default_to_gmt' to decide whether the string should
248  * be interpreted relative to the local time zone (PR_FALSE) or GMT (PR_TRUE).
249  * The correct value for this argument depends on what standard specified
250  * the time string which you are parsing.
251  */
252 
253 /*
254  * This is the only funtion that should be called from outside base, and only
255  * from the unit test.
256  */
257 
258 BASE_EXPORT PRStatus PR_ParseTimeString (
259 	const char *string,
260 	PRBool default_to_gmt,
261 	PRTime *result);
262 
263 #endif  // BASE_PRTIME_H__
264