Back to index

lightning-sunbird  0.9+nobinonly
prtime.h
Go to the documentation of this file.
00001 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
00002 /* ***** BEGIN LICENSE BLOCK *****
00003  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00004  *
00005  * The contents of this file are subject to the Mozilla Public License Version
00006  * 1.1 (the "License"); you may not use this file except in compliance with
00007  * the License. You may obtain a copy of the License at
00008  * http://www.mozilla.org/MPL/
00009  *
00010  * Software distributed under the License is distributed on an "AS IS" basis,
00011  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00012  * for the specific language governing rights and limitations under the
00013  * License.
00014  *
00015  * The Original Code is the Netscape Portable Runtime (NSPR).
00016  *
00017  * The Initial Developer of the Original Code is
00018  * Netscape Communications Corporation.
00019  * Portions created by the Initial Developer are Copyright (C) 1998-2000
00020  * the Initial Developer. All Rights Reserved.
00021  *
00022  * Contributor(s):
00023  *
00024  * Alternatively, the contents of this file may be used under the terms of
00025  * either the GNU General Public License Version 2 or later (the "GPL"), or
00026  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00027  * in which case the provisions of the GPL or the LGPL are applicable instead
00028  * of those above. If you wish to allow use of your version of this file only
00029  * under the terms of either the GPL or the LGPL, and not to allow others to
00030  * use your version of this file under the terms of the MPL, indicate your
00031  * decision by deleting the provisions above and replace them with the notice
00032  * and other provisions required by the GPL or the LGPL. If you do not delete
00033  * the provisions above, a recipient may use your version of this file under
00034  * the terms of any one of the MPL, the GPL or the LGPL.
00035  *
00036  * ***** END LICENSE BLOCK ***** */
00037 
00038 /*
00039  *----------------------------------------------------------------------
00040  *
00041  * prtime.h --
00042  *
00043  *     NSPR date and time functions
00044  *
00045  *-----------------------------------------------------------------------
00046  */
00047 
00048 #ifndef prtime_h___
00049 #define prtime_h___
00050 
00051 #include "prlong.h"
00052 
00053 PR_BEGIN_EXTERN_C
00054 
00055 /**********************************************************************/
00056 /************************* TYPES AND CONSTANTS ************************/
00057 /**********************************************************************/
00058 
00059 #define PR_MSEC_PER_SEC            1000UL
00060 #define PR_USEC_PER_SEC            1000000UL
00061 #define PR_NSEC_PER_SEC            1000000000UL
00062 #define PR_USEC_PER_MSEC    1000UL
00063 #define PR_NSEC_PER_MSEC    1000000UL
00064 
00065 /*
00066  * PRTime --
00067  *
00068  *     NSPR represents basic time as 64-bit signed integers relative
00069  *     to midnight (00:00:00), January 1, 1970 Greenwich Mean Time (GMT).
00070  *     (GMT is also known as Coordinated Universal Time, UTC.)
00071  *     The units of time are in microseconds. Negative times are allowed
00072  *     to represent times prior to the January 1970 epoch. Such values are
00073  *     intended to be exported to other systems or converted to human
00074  *     readable form.
00075  *
00076  *     Notes on porting: PRTime corresponds to time_t in ANSI C.  NSPR 1.0
00077  *     simply uses PRInt64.
00078  */
00079 
00080 typedef PRInt64 PRTime;
00081 
00082 /*
00083  * Time zone and daylight saving time corrections applied to GMT to
00084  * obtain the local time of some geographic location
00085  */
00086 
00087 typedef struct PRTimeParameters {
00088     PRInt32 tp_gmt_offset;     /* the offset from GMT in seconds */
00089     PRInt32 tp_dst_offset;     /* contribution of DST in seconds */
00090 } PRTimeParameters;
00091 
00092 /*
00093  * PRExplodedTime --
00094  *
00095  *     Time broken down into human-readable components such as year, month,
00096  *     day, hour, minute, second, and microsecond.  Time zone and daylight
00097  *     saving time corrections may be applied.  If they are applied, the
00098  *     offsets from the GMT must be saved in the 'tm_params' field so that
00099  *     all the information is available to reconstruct GMT.
00100  *
00101  *     Notes on porting: PRExplodedTime corrresponds to struct tm in
00102  *     ANSI C, with the following differences:
00103  *       - an additional field tm_usec;
00104  *       - replacing tm_isdst by tm_params;
00105  *       - the month field is spelled tm_month, not tm_mon;
00106  *       - we use absolute year, AD, not the year since 1900.
00107  *     The corresponding type in NSPR 1.0 is called PRTime.  Below is
00108  *     a table of date/time type correspondence in the three APIs:
00109  *         API          time since epoch          time in components
00110  *       ANSI C             time_t                  struct tm
00111  *       NSPR 1.0           PRInt64                   PRTime
00112  *       NSPR 2.0           PRTime                  PRExplodedTime
00113  */
00114 
00115 typedef struct PRExplodedTime {
00116     PRInt32 tm_usec;            /* microseconds past tm_sec (0-99999)  */
00117     PRInt32 tm_sec;             /* seconds past tm_min (0-61, accomodating
00118                                    up to two leap seconds) */  
00119     PRInt32 tm_min;             /* minutes past tm_hour (0-59) */
00120     PRInt32 tm_hour;            /* hours past tm_day (0-23) */
00121     PRInt32 tm_mday;            /* days past tm_mon (1-31, note that it
00122                                             starts from 1) */
00123     PRInt32 tm_month;           /* months past tm_year (0-11, Jan = 0) */
00124     PRInt16 tm_year;            /* absolute year, AD (note that we do not
00125                                             count from 1900) */
00126 
00127     PRInt8 tm_wday;                 /* calculated day of the week
00128                                             (0-6, Sun = 0) */
00129     PRInt16 tm_yday;            /* calculated day of the year 
00130                                             (0-365, Jan 1 = 0) */
00131 
00132     PRTimeParameters tm_params;  /* time parameters used by conversion */
00133 } PRExplodedTime;
00134 
00135 /*
00136  * PRTimeParamFn --
00137  *
00138  *     A function of PRTimeParamFn type returns the time zone and
00139  *     daylight saving time corrections for some geographic location,
00140  *     given the current time in GMT.  The input argument gmt should
00141  *     point to a PRExplodedTime that is in GMT, i.e., whose
00142  *     tm_params contains all 0's.
00143  *
00144  *     For any time zone other than GMT, the computation is intended to
00145  *     consist of two steps:
00146  *       - Figure out the time zone correction, tp_gmt_offset.  This number
00147  *         usually depends on the geographic location only.  But it may
00148  *         also depend on the current time.  For example, all of China
00149  *         is one time zone right now.  But this situation may change
00150  *         in the future.
00151  *       - Figure out the daylight saving time correction, tp_dst_offset.
00152  *         This number depends on both the geographic location and the
00153  *         current time.  Most of the DST rules are expressed in local
00154  *         current time.  If so, one should apply the time zone correction
00155  *         to GMT before applying the DST rules.
00156  */
00157 
00158 typedef PRTimeParameters (PR_CALLBACK *PRTimeParamFn)(const PRExplodedTime *gmt);
00159 
00160 /**********************************************************************/
00161 /****************************** FUNCTIONS *****************************/
00162 /**********************************************************************/
00163 
00164 /*
00165  * The PR_Now routine returns the current time relative to the
00166  * epoch, midnight, January 1, 1970 UTC. The units of the returned
00167  * value are microseconds since the epoch.
00168  *
00169  * The values returned are not guaranteed to advance in a linear fashion
00170  * due to the application of time correction protocols which synchronize
00171  * computer clocks to some external time source. Consequently it should
00172  * not be depended on for interval timing.
00173  *
00174  * The implementation is machine dependent.
00175  * Cf. time_t time(time_t *tp) in ANSI C.
00176  */
00177 #if defined(HAVE_WATCOM_BUG_2)
00178 PRTime __pascal __export __loadds
00179 #else
00180 NSPR_API(PRTime) 
00181 #endif
00182 PR_Now(void);
00183 
00184 /*
00185  * Expand time binding it to time parameters provided by PRTimeParamFn.
00186  * The calculation is envisoned to proceed in the following steps:
00187  *   - From given PRTime, calculate PRExplodedTime in GMT
00188  *   - Apply the given PRTimeParamFn to the GMT that we just calculated
00189  *     to obtain PRTimeParameters.
00190  *   - Add the PRTimeParameters offsets to GMT to get the local time
00191  *     as PRExplodedTime.
00192  */
00193 
00194 NSPR_API(void) PR_ExplodeTime(
00195     PRTime usecs, PRTimeParamFn params, PRExplodedTime *exploded);
00196 
00197 /* Reverse operation of PR_ExplodeTime */
00198 #if defined(HAVE_WATCOM_BUG_2)
00199 PRTime __pascal __export __loadds
00200 #else
00201 NSPR_API(PRTime) 
00202 #endif
00203 PR_ImplodeTime(const PRExplodedTime *exploded);
00204 
00205 /*
00206  * Adjust exploded time to normalize field overflows after manipulation.
00207  * Note that the following fields of PRExplodedTime should not be
00208  * manipulated:
00209  *   - tm_month and tm_year: because the number of days in a month and
00210  *     number of days in a year are not constant, it is ambiguous to
00211  *     manipulate the month and year fields, although one may be tempted
00212  *     to.  For example, what does "a month from January 31st" mean?
00213  *   - tm_wday and tm_yday: these fields are calculated by NSPR.  Users
00214  *     should treat them as "read-only".
00215  */
00216 
00217 NSPR_API(void) PR_NormalizeTime(
00218     PRExplodedTime *exploded, PRTimeParamFn params);
00219 
00220 /**********************************************************************/
00221 /*********************** TIME PARAMETER FUNCTIONS *********************/
00222 /**********************************************************************/
00223 
00224 /* Time parameters that suit current host machine */
00225 NSPR_API(PRTimeParameters) PR_LocalTimeParameters(const PRExplodedTime *gmt);
00226 
00227 /* Time parameters that represent Greenwich Mean Time */
00228 NSPR_API(PRTimeParameters) PR_GMTParameters(const PRExplodedTime *gmt);
00229 
00230 /*
00231  * Time parameters that represent the US Pacific Time Zone, with the
00232  * current daylight saving time rules (for testing only)
00233  */
00234 NSPR_API(PRTimeParameters) PR_USPacificTimeParameters(const PRExplodedTime *gmt);
00235 
00236 /*
00237  * This parses a time/date string into a PRTime
00238  * (microseconds after "1-Jan-1970 00:00:00 GMT").
00239  * It returns PR_SUCCESS on success, and PR_FAILURE
00240  * if the time/date string can't be parsed.
00241  *
00242  * Many formats are handled, including:
00243  *
00244  *   14 Apr 89 03:20:12
00245  *   14 Apr 89 03:20 GMT
00246  *   Fri, 17 Mar 89 4:01:33
00247  *   Fri, 17 Mar 89 4:01 GMT
00248  *   Mon Jan 16 16:12 PDT 1989
00249  *   Mon Jan 16 16:12 +0130 1989
00250  *   6 May 1992 16:41-JST (Wednesday)
00251  *   22-AUG-1993 10:59:12.82
00252  *   22-AUG-1993 10:59pm
00253  *   22-AUG-1993 12:59am
00254  *   22-AUG-1993 12:59 PM
00255  *   Friday, August 04, 1995 3:54 PM
00256  *   06/21/95 04:24:34 PM
00257  *   20/06/95 21:07
00258  *   95-06-08 19:32:48 EDT
00259  *
00260  * If the input string doesn't contain a description of the timezone,
00261  * we consult the `default_to_gmt' to decide whether the string should
00262  * be interpreted relative to the local time zone (PR_FALSE) or GMT (PR_TRUE).
00263  * The correct value for this argument depends on what standard specified
00264  * the time string which you are parsing.
00265  */
00266 
00267 NSPR_API(PRStatus) PR_ParseTimeString (
00268        const char *string,
00269        PRBool default_to_gmt,
00270        PRTime *result);
00271 
00272 /*
00273  * FIXME: should we also have a formatting function, such as asctime, ctime,
00274  * and strftime in standard C library?  But this would involve
00275  * internationalization issues.  Might want to provide a US English version.
00276  */
00277 
00278 /**********************************************************************/
00279 /*********************** OLD COMPATIBILITYFUNCTIONS *******************/
00280 /**********************************************************************/
00281 #ifndef NO_NSPR_10_SUPPORT
00282 
00283 /* Format a time value into a buffer. Same semantics as strftime() */
00284 NSPR_API(PRUint32) PR_FormatTime(char *buf, int buflen, const char *fmt, 
00285                                            const PRExplodedTime *tm);
00286 
00287 /* Format a time value into a buffer. Time is always in US English format, regardless
00288  * of locale setting.
00289  */
00290 NSPR_API(PRUint32)
00291 PR_FormatTimeUSEnglish( char* buf, PRUint32 bufSize,
00292                         const char* format, const PRExplodedTime* tm );
00293 
00294 #endif /* NO_NSPR_10_SUPPORT */
00295 
00296 PR_END_EXTERN_C
00297 
00298 #endif /* prtime_h___ */