OSX/libsecurity_asn1/lib/prtime.h

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