1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/nsprpub/pr/include/prtime.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,262 @@
1.4 +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +/*
1.10 + *----------------------------------------------------------------------
1.11 + *
1.12 + * prtime.h --
1.13 + *
1.14 + * NSPR date and time functions
1.15 + *
1.16 + *-----------------------------------------------------------------------
1.17 + */
1.18 +
1.19 +#ifndef prtime_h___
1.20 +#define prtime_h___
1.21 +
1.22 +#include "prlong.h"
1.23 +
1.24 +PR_BEGIN_EXTERN_C
1.25 +
1.26 +/**********************************************************************/
1.27 +/************************* TYPES AND CONSTANTS ************************/
1.28 +/**********************************************************************/
1.29 +
1.30 +#define PR_MSEC_PER_SEC 1000L
1.31 +#define PR_USEC_PER_SEC 1000000L
1.32 +#define PR_NSEC_PER_SEC 1000000000L
1.33 +#define PR_USEC_PER_MSEC 1000L
1.34 +#define PR_NSEC_PER_MSEC 1000000L
1.35 +
1.36 +/*
1.37 + * PRTime --
1.38 + *
1.39 + * NSPR represents basic time as 64-bit signed integers relative
1.40 + * to midnight (00:00:00), January 1, 1970 Greenwich Mean Time (GMT).
1.41 + * (GMT is also known as Coordinated Universal Time, UTC.)
1.42 + * The units of time are in microseconds. Negative times are allowed
1.43 + * to represent times prior to the January 1970 epoch. Such values are
1.44 + * intended to be exported to other systems or converted to human
1.45 + * readable form.
1.46 + *
1.47 + * Notes on porting: PRTime corresponds to time_t in ANSI C. NSPR 1.0
1.48 + * simply uses PRInt64.
1.49 + */
1.50 +
1.51 +typedef PRInt64 PRTime;
1.52 +
1.53 +/*
1.54 + * Time zone and daylight saving time corrections applied to GMT to
1.55 + * obtain the local time of some geographic location
1.56 + */
1.57 +
1.58 +typedef struct PRTimeParameters {
1.59 + PRInt32 tp_gmt_offset; /* the offset from GMT in seconds */
1.60 + PRInt32 tp_dst_offset; /* contribution of DST in seconds */
1.61 +} PRTimeParameters;
1.62 +
1.63 +/*
1.64 + * PRExplodedTime --
1.65 + *
1.66 + * Time broken down into human-readable components such as year, month,
1.67 + * day, hour, minute, second, and microsecond. Time zone and daylight
1.68 + * saving time corrections may be applied. If they are applied, the
1.69 + * offsets from the GMT must be saved in the 'tm_params' field so that
1.70 + * all the information is available to reconstruct GMT.
1.71 + *
1.72 + * Notes on porting: PRExplodedTime corrresponds to struct tm in
1.73 + * ANSI C, with the following differences:
1.74 + * - an additional field tm_usec;
1.75 + * - replacing tm_isdst by tm_params;
1.76 + * - the month field is spelled tm_month, not tm_mon;
1.77 + * - we use absolute year, AD, not the year since 1900.
1.78 + * The corresponding type in NSPR 1.0 is called PRTime. Below is
1.79 + * a table of date/time type correspondence in the three APIs:
1.80 + * API time since epoch time in components
1.81 + * ANSI C time_t struct tm
1.82 + * NSPR 1.0 PRInt64 PRTime
1.83 + * NSPR 2.0 PRTime PRExplodedTime
1.84 + */
1.85 +
1.86 +typedef struct PRExplodedTime {
1.87 + PRInt32 tm_usec; /* microseconds past tm_sec (0-99999) */
1.88 + PRInt32 tm_sec; /* seconds past tm_min (0-61, accomodating
1.89 + up to two leap seconds) */
1.90 + PRInt32 tm_min; /* minutes past tm_hour (0-59) */
1.91 + PRInt32 tm_hour; /* hours past tm_day (0-23) */
1.92 + PRInt32 tm_mday; /* days past tm_mon (1-31, note that it
1.93 + starts from 1) */
1.94 + PRInt32 tm_month; /* months past tm_year (0-11, Jan = 0) */
1.95 + PRInt16 tm_year; /* absolute year, AD (note that we do not
1.96 + count from 1900) */
1.97 +
1.98 + PRInt8 tm_wday; /* calculated day of the week
1.99 + (0-6, Sun = 0) */
1.100 + PRInt16 tm_yday; /* calculated day of the year
1.101 + (0-365, Jan 1 = 0) */
1.102 +
1.103 + PRTimeParameters tm_params; /* time parameters used by conversion */
1.104 +} PRExplodedTime;
1.105 +
1.106 +/*
1.107 + * PRTimeParamFn --
1.108 + *
1.109 + * A function of PRTimeParamFn type returns the time zone and
1.110 + * daylight saving time corrections for some geographic location,
1.111 + * given the current time in GMT. The input argument gmt should
1.112 + * point to a PRExplodedTime that is in GMT, i.e., whose
1.113 + * tm_params contains all 0's.
1.114 + *
1.115 + * For any time zone other than GMT, the computation is intended to
1.116 + * consist of two steps:
1.117 + * - Figure out the time zone correction, tp_gmt_offset. This number
1.118 + * usually depends on the geographic location only. But it may
1.119 + * also depend on the current time. For example, all of China
1.120 + * is one time zone right now. But this situation may change
1.121 + * in the future.
1.122 + * - Figure out the daylight saving time correction, tp_dst_offset.
1.123 + * This number depends on both the geographic location and the
1.124 + * current time. Most of the DST rules are expressed in local
1.125 + * current time. If so, one should apply the time zone correction
1.126 + * to GMT before applying the DST rules.
1.127 + */
1.128 +
1.129 +typedef PRTimeParameters (PR_CALLBACK *PRTimeParamFn)(const PRExplodedTime *gmt);
1.130 +
1.131 +/**********************************************************************/
1.132 +/****************************** FUNCTIONS *****************************/
1.133 +/**********************************************************************/
1.134 +
1.135 +/*
1.136 + * The PR_Now routine returns the current time relative to the
1.137 + * epoch, midnight, January 1, 1970 UTC. The units of the returned
1.138 + * value are microseconds since the epoch.
1.139 + *
1.140 + * The values returned are not guaranteed to advance in a linear fashion
1.141 + * due to the application of time correction protocols which synchronize
1.142 + * computer clocks to some external time source. Consequently it should
1.143 + * not be depended on for interval timing.
1.144 + *
1.145 + * The implementation is machine dependent.
1.146 + * Cf. time_t time(time_t *tp) in ANSI C.
1.147 + */
1.148 +NSPR_API(PRTime)
1.149 +PR_Now(void);
1.150 +
1.151 +/*
1.152 + * Expand time binding it to time parameters provided by PRTimeParamFn.
1.153 + * The calculation is envisoned to proceed in the following steps:
1.154 + * - From given PRTime, calculate PRExplodedTime in GMT
1.155 + * - Apply the given PRTimeParamFn to the GMT that we just calculated
1.156 + * to obtain PRTimeParameters.
1.157 + * - Add the PRTimeParameters offsets to GMT to get the local time
1.158 + * as PRExplodedTime.
1.159 + */
1.160 +
1.161 +NSPR_API(void) PR_ExplodeTime(
1.162 + PRTime usecs, PRTimeParamFn params, PRExplodedTime *exploded);
1.163 +
1.164 +/* Reverse operation of PR_ExplodeTime */
1.165 +NSPR_API(PRTime)
1.166 +PR_ImplodeTime(const PRExplodedTime *exploded);
1.167 +
1.168 +/*
1.169 + * Adjust exploded time to normalize field overflows after manipulation.
1.170 + * Note that the following fields of PRExplodedTime should not be
1.171 + * manipulated:
1.172 + * - tm_month and tm_year: because the number of days in a month and
1.173 + * number of days in a year are not constant, it is ambiguous to
1.174 + * manipulate the month and year fields, although one may be tempted
1.175 + * to. For example, what does "a month from January 31st" mean?
1.176 + * - tm_wday and tm_yday: these fields are calculated by NSPR. Users
1.177 + * should treat them as "read-only".
1.178 + */
1.179 +
1.180 +NSPR_API(void) PR_NormalizeTime(
1.181 + PRExplodedTime *exploded, PRTimeParamFn params);
1.182 +
1.183 +/**********************************************************************/
1.184 +/*********************** TIME PARAMETER FUNCTIONS *********************/
1.185 +/**********************************************************************/
1.186 +
1.187 +/* Time parameters that suit current host machine */
1.188 +NSPR_API(PRTimeParameters) PR_LocalTimeParameters(const PRExplodedTime *gmt);
1.189 +
1.190 +/* Time parameters that represent Greenwich Mean Time */
1.191 +NSPR_API(PRTimeParameters) PR_GMTParameters(const PRExplodedTime *gmt);
1.192 +
1.193 +/*
1.194 + * Time parameters that represent the US Pacific Time Zone, with the
1.195 + * current daylight saving time rules (for testing only)
1.196 + */
1.197 +NSPR_API(PRTimeParameters) PR_USPacificTimeParameters(const PRExplodedTime *gmt);
1.198 +
1.199 +/*
1.200 + * This parses a time/date string into a PRExplodedTime
1.201 + * struct. It populates all fields but it can't split
1.202 + * the offset from UTC into tp_gmt_offset and tp_dst_offset in
1.203 + * most cases (exceptions: PST/PDT, MST/MDT, CST/CDT, EST/EDT, GMT/BST).
1.204 + * In those cases tp_gmt_offset will be the sum of these two and
1.205 + * tp_dst_offset will be 0.
1.206 + * It returns PR_SUCCESS on success, and PR_FAILURE
1.207 + * if the time/date string can't be parsed.
1.208 + *
1.209 + * Many formats are handled, including:
1.210 + *
1.211 + * 14 Apr 89 03:20:12
1.212 + * 14 Apr 89 03:20 GMT
1.213 + * Fri, 17 Mar 89 4:01:33
1.214 + * Fri, 17 Mar 89 4:01 GMT
1.215 + * Mon Jan 16 16:12 PDT 1989
1.216 + * Mon Jan 16 16:12 +0130 1989
1.217 + * 6 May 1992 16:41-JST (Wednesday)
1.218 + * 22-AUG-1993 10:59:12.82
1.219 + * 22-AUG-1993 10:59pm
1.220 + * 22-AUG-1993 12:59am
1.221 + * 22-AUG-1993 12:59 PM
1.222 + * Friday, August 04, 1995 3:54 PM
1.223 + * 06/21/95 04:24:34 PM
1.224 + * 20/06/95 21:07
1.225 + * 95-06-08 19:32:48 EDT
1.226 + *
1.227 + * If the input string doesn't contain a description of the timezone,
1.228 + * we consult the `default_to_gmt' to decide whether the string should
1.229 + * be interpreted relative to the local time zone (PR_FALSE) or GMT (PR_TRUE).
1.230 + * The correct value for this argument depends on what standard specified
1.231 + * the time string which you are parsing.
1.232 + */
1.233 +
1.234 +NSPR_API(PRStatus) PR_ParseTimeStringToExplodedTime (
1.235 + const char *string,
1.236 + PRBool default_to_gmt,
1.237 + PRExplodedTime *result);
1.238 +
1.239 +/*
1.240 + * This uses PR_ParseTimeStringToExplodedTime to parse
1.241 + * a time/date string and PR_ImplodeTime to transform it into
1.242 + * a PRTime (microseconds after "1-Jan-1970 00:00:00 GMT").
1.243 + * It returns PR_SUCCESS on success, and PR_FAILURE
1.244 + * if the time/date string can't be parsed.
1.245 + */
1.246 +
1.247 +NSPR_API(PRStatus) PR_ParseTimeString (
1.248 + const char *string,
1.249 + PRBool default_to_gmt,
1.250 + PRTime *result);
1.251 +
1.252 +/* Format a time value into a buffer. Same semantics as strftime() */
1.253 +NSPR_API(PRUint32) PR_FormatTime(char *buf, int buflen, const char *fmt,
1.254 + const PRExplodedTime *tm);
1.255 +
1.256 +/* Format a time value into a buffer. Time is always in US English format, regardless
1.257 + * of locale setting.
1.258 + */
1.259 +NSPR_API(PRUint32)
1.260 +PR_FormatTimeUSEnglish( char* buf, PRUint32 bufSize,
1.261 + const char* format, const PRExplodedTime* tm );
1.262 +
1.263 +PR_END_EXTERN_C
1.264 +
1.265 +#endif /* prtime_h___ */
