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