contrib/ntp/lib/isc/win32/include/isc/time.h

   1 /*
   2  * Copyright (C) 2004, 2006-2009  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 1998-2001  Internet Software Consortium.
   4  *
   5  * Permission to use, copy, modify, and/or distribute this software for any
   6  * purpose with or without fee is hereby granted, provided that the above
   7  * copyright notice and this permission notice appear in all copies.
   8  *
   9  * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10  * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11  * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12  * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13  * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15  * PERFORMANCE OF THIS SOFTWARE.
  16  */
  17
  18 /* $Id: time.h,v 1.35 2009/01/05 23:47:54 tbox Exp $ */
  19
  20 #ifndef ISC_TIME_H
  21 #define ISC_TIME_H 1
  22
  23 #include <windows.h>
  24
  25 #include <isc/lang.h>
  26 #include <isc/types.h>
  27
  28 /***
  29  *** Intervals
  30  ***/
  31
  32 /*
  33  * The contents of this structure are private, and MUST NOT be accessed
  34  * directly by callers.
  35  *
  36  * The contents are exposed only to allow callers to avoid dynamic allocation.
  37  */
  38 struct isc_interval {
  39         isc_int64_t interval;
  40 };
  41
  42 LIBISC_EXTERNAL_DATA extern isc_interval_t *isc_interval_zero;
  43
  44 ISC_LANG_BEGINDECLS
  45
  46 void
  47 isc_interval_set(isc_interval_t *i,
  48                  unsigned int seconds, unsigned int nanoseconds);
  49 /*
  50  * Set 'i' to a value representing an interval of 'seconds' seconds and
  51  * 'nanoseconds' nanoseconds, suitable for use in isc_time_add() and
  52  * isc_time_subtract().
  53  *
  54  * Requires:
  55  *
  56  *      't' is a valid pointer.
  57  *      nanoseconds < 1000000000.
  58  */
  59
  60 isc_boolean_t
  61 isc_interval_iszero(const isc_interval_t *i);
  62 /*
  63  * Returns ISC_TRUE iff. 'i' is the zero interval.
  64  *
  65  * Requires:
  66  *
  67  *      'i' is a valid pointer.
  68  */
  69
  70 /***
  71  *** Absolute Times
  72  ***/
  73
  74 /*
  75  * The contents of this structure are private, and MUST NOT be accessed
  76  * directly by callers.
  77  *
  78  * The contents are exposed only to allow callers to avoid dynamic allocation.
  79  */
  80
  81 struct isc_time {
  82         FILETIME absolute;
  83 };
  84
  85 LIBISC_EXTERNAL_DATA extern isc_time_t *isc_time_epoch;
  86
  87 void
  88 isc_time_set(isc_time_t *t, unsigned int seconds, unsigned int nanoseconds);
  89 /*%<
  90  * Set 't' to a value which represents the given number of seconds and
  91  * nanoseconds since 00:00:00 January 1, 1970, UTC.
  92  *
  93  * Requires:
  94  *\li   't' is a valid pointer.
  95  *\li   nanoseconds < 1000000000.
  96  */
  97
  98 void
  99 isc_time_settoepoch(isc_time_t *t);
 100 /*
 101  * Set 't' to the time of the epoch.
 102  *
 103  * Notes:
 104  *      The date of the epoch is platform-dependent.
 105  *
 106  * Requires:
 107  *
 108  *      't' is a valid pointer.
 109  */
 110
 111 isc_boolean_t
 112 isc_time_isepoch(const isc_time_t *t);
 113 /*
 114  * Returns ISC_TRUE iff. 't' is the epoch ("time zero").
 115  *
 116  * Requires:
 117  *
 118  *      't' is a valid pointer.
 119  */
 120
 121 isc_result_t
 122 isc_time_now(isc_time_t *t);
 123 /*
 124  * Set 't' to the current absolute time.
 125  *
 126  * Requires:
 127  *
 128  *      't' is a valid pointer.
 129  *
 130  * Returns:
 131  *
 132  *      Success
 133  *      Unexpected error
 134  *              Getting the time from the system failed.
 135  *      Out of range
 136  *              The time from the system is too large to be represented
 137  *              in the current definition of isc_time_t.
 138  */
 139
 140 isc_result_t
 141 isc_time_nowplusinterval(isc_time_t *t, const isc_interval_t *i);
 142 /*
 143  * Set *t to the current absolute time + i.
 144  *
 145  * Note:
 146  *      This call is equivalent to:
 147  *
 148  *              isc_time_now(t);
 149  *              isc_time_add(t, i, t);
 150  *
 151  * Requires:
 152  *
 153  *      't' and 'i' are valid pointers.
 154  *
 155  * Returns:
 156  *
 157  *      Success
 158  *      Unexpected error
 159  *              Getting the time from the system failed.
 160  *      Out of range
 161  *              The interval added to the time from the system is too large to
 162  *              be represented in the current definition of isc_time_t.
 163  */
 164
 165 int
 166 isc_time_compare(const isc_time_t *t1, const isc_time_t *t2);
 167 /*
 168  * Compare the times referenced by 't1' and 't2'
 169  *
 170  * Requires:
 171  *
 172  *      't1' and 't2' are valid pointers.
 173  *
 174  * Returns:
 175  *
 176  *      -1              t1 < t2         (comparing times, not pointers)
 177  *      0               t1 = t2
 178  *      1               t1 > t2
 179  */
 180
 181 isc_result_t
 182 isc_time_add(const isc_time_t *t, const isc_interval_t *i, isc_time_t *result);
 183 /*
 184  * Add 'i' to 't', storing the result in 'result'.
 185  *
 186  * Requires:
 187  *
 188  *      't', 'i', and 'result' are valid pointers.
 189  *
 190  * Returns:
 191  *      Success
 192  *      Out of range
 193  *              The interval added to the time is too large to
 194  *              be represented in the current definition of isc_time_t.
 195  */
 196
 197 isc_result_t
 198 isc_time_subtract(const isc_time_t *t, const isc_interval_t *i,
 199                   isc_time_t *result);
 200 /*
 201  * Subtract 'i' from 't', storing the result in 'result'.
 202  *
 203  * Requires:
 204  *
 205  *      't', 'i', and 'result' are valid pointers.
 206  *
 207  * Returns:
 208  *      Success
 209  *      Out of range
 210  *              The interval is larger than the time since the epoch.
 211  */
 212
 213 isc_uint64_t
 214 isc_time_microdiff(const isc_time_t *t1, const isc_time_t *t2);
 215 /*
 216  * Find the difference in milliseconds between time t1 and time t2.
 217  * t2 is the subtrahend of t1; ie, difference = t1 - t2.
 218  *
 219  * Requires:
 220  *
 221  *      't1' and 't2' are valid pointers.
 222  *
 223  * Returns:
 224  *      The difference of t1 - t2, or 0 if t1 <= t2.
 225  */
 226
 227 isc_uint32_t
 228 isc_time_nanoseconds(const isc_time_t *t);
 229 /*
 230  * Return the number of nanoseconds stored in a time structure.
 231  *
 232  * Notes:
 233  *      This is the number of nanoseconds in excess of the number
 234  *      of seconds since the epoch; it will always be less than one
 235  *      full second.
 236  *
 237  * Requires:
 238  *      't' is a valid pointer.
 239  *
 240  * Ensures:
 241  *      The returned value is less than 1*10^9.
 242  */
 243
 244 void
 245 isc_time_formattimestamp(const isc_time_t *t, char *buf, unsigned int len);
 246 /*
 247  * Format the time 't' into the buffer 'buf' of length 'len',
 248  * using a format like "30-Aug-2000 04:06:47.997" and the local time zone.
 249  * If the text does not fit in the buffer, the result is indeterminate,
 250  * but is always guaranteed to be null terminated.
 251  *
 252  *  Requires:
 253  *      'len' > 0
 254  *      'buf' points to an array of at least len chars
 255  *
 256  */
 257
 258 void
 259 isc_time_formathttptimestamp(const isc_time_t *t, char *buf, unsigned int len);
 260 /*
 261  * Format the time 't' into the buffer 'buf' of length 'len',
 262  * using a format like "Mon, 30 Aug 2000 04:06:47 GMT"
 263  * If the text does not fit in the buffer, the result is indeterminate,
 264  * but is always guaranteed to be null terminated.
 265  *
 266  *  Requires:
 267  *      'len' > 0
 268  *      'buf' points to an array of at least len chars
 269  *
 270  */
 271
 272 void
 273 isc_time_formatISO8601(const isc_time_t *t, char *buf, unsigned int len);
 274 /*%<
 275  * Format the time 't' into the buffer 'buf' of length 'len',
 276  * using the ISO8601 format: "yyyy-mm-ddThh:mm:ssZ"
 277  * If the text does not fit in the buffer, the result is indeterminate,
 278  * but is always guaranteed to be null terminated.
 279  *
 280  *  Requires:
 281  *\li      'len' > 0
 282  *\li      'buf' points to an array of at least len chars
 283  *
 284  */
 285
 286 isc_uint32_t
 287 isc_time_seconds(const isc_time_t *t);
 288
 289 ISC_LANG_ENDDECLS
 290
 291 #endif /* ISC_TIME_H */