lib/silcutil/silctime.h

   1 /*
   2
   3   silctime.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2003 - 2005 Pekka Riikonen
   8
   9   This program is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU General Public License as published by
  11   the Free Software Foundation; version 2 of the License.
  12
  13   This program is distributed in the hope that it will be useful,
  14   but WITHOUT ANY WARRANTY; without even the implied warranty of
  15   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16   GNU General Public License for more details.
  17
  18 */
  19
  20 /****h* silcutil/SILC Time Interface
  21  *
  22  * DESCRIPTION
  23  *
  24  * This interface provides various utility functions for getting current
  25  * time and converting different time representations into the SilcTime
  26  * representation.
  27  *
  28  ***/
  29
  30 #ifndef SILCTIME_H
  31 #define SILCTIME_H
  32
  33 /****s* silcutil/SilcTimeAPI/SilcTime
  34  *
  35  * NAME
  36  *
  37  *    typedef struct { ... } *SilcTime, SilcTimeStruct;
  38  *
  39  * DESCRIPTION
  40  *
  41  *    This context represents time value.  It includes date and time
  42  *    down to millisecond precision.
  43  *
  44  * SOURCE
  45  *
  46  ***/
  47 typedef struct {
  48   unsigned int year       : 13;    /* Year,     0 - 8191 */
  49   unsigned int month      : 4;     /* Month,    1 - 12 */
  50   unsigned int day        : 5;     /* Day,      1 - 31 */
  51   unsigned int hour       : 5;     /* Hour,     0 - 23 */
  52   unsigned int minute     : 6;     /* Minute,   0 - 59 */
  53   unsigned int second     : 6;     /* Second,   0 - 61 */
  54   unsigned int msecond    : 10;    /* Millisec, 0 - 1000 */
  55   unsigned int utc_hour   : 5;     /* Offset to Zulu (UTC) hours */
  56   unsigned int utc_minute : 6;     /* Offset to Zulu (UTC) minutes */
  57   unsigned int utc_east   : 1;     /* Offset, 1 east (+), 0 west (-) */
  58   unsigned int dst        : 1;     /* Set if daylight saving time */
  59   /* 2 bits to spare */
  60 } *SilcTime, SilcTimeStruct;
  61 /***/
  62
  63 /****f* silcutil/SilcTimeAPI/silc_time
  64  *
  65  * SYNOPSIS
  66  *
  67  *    SilcInt64 silc_time(void);
  68  *
  69  * DESCRIPTION
  70  *
  71  *    Returns the current time of the system since Epoch.  The returned
  72  *    value is seconds since Epoch (1.1.1970).  Returns -1 on error.
  73  *
  74  ***/
  75 SilcInt64 silc_time(void);
  76
  77 /****f* silcutil/SilcTimeAPI/silc_time_string
  78  *
  79  * SYNOPSIS
  80  *
  81  *    const char *silc_time_string(SilcInt64 timeval);
  82  *
  83  * DESCRIPTION
  84  *
  85  *    Returns time and date as string.  The caller must not free the string
  86  *    and next call to this function will delete the old string.  If the
  87  *    `timeval' is zero (0) returns current time as string, otherwise the
  88  *    `timeval' as string.  Returns NULL on error.
  89  *
  90  ***/
  91 const char *silc_time_string(SilcInt64 timeval);
  92
  93 /****f* silcutil/SilcTimeAPI/silc_time_value
  94  *
  95  * SYNOPSIS
  96  *
  97  *   SilcBool silc_time_value(SilcInt64 timeval, SilcTime ret_time);
  98  *
  99  * DESCRIPTION
 100  *
 101  *    Returns time and date as SilcTime.  If the `timeval' is zero (0)
 102  *    returns current time as SilcTime, otherwise the `timeval' as SilcTime.
 103  *    Returns FALSE on error, TRUE otherwise.
 104  *
 105  ***/
 106 SilcBool silc_time_value(SilcInt64 timeval, SilcTime ret_time);
 107
 108 /****f* silcutil/SilcTimeAPI/silc_time_universal
 109  *
 110  * SYNOPSIS
 111  *
 112  *    SilcBool silc_time_universal(const char *universal_time,
 113  *                             SilcTime ret_time);
 114  *
 115  * DESCRIPTION
 116  *
 117  *    Returns time and date as SilcTime from `universal_time' string which
 118  *    format is "YYMMDDhhmmssZ", where YY is year, MM is month, DD is day,
 119  *    hh is hour, mm is minutes, ss is seconds and Z is timezone, which
 120  *    by default is Zulu (UTC).  Universal time is defined in ISO/EIC 8824-1.
 121  *
 122  *    Returns FALSE on error, TRUE otherwise.
 123  *
 124  * EXAMPLE
 125  *
 126  *    SilcTimeStruct ret_time;
 127  *
 128  *    time is 03/02/19 19:04:03 Zulu (UTC)
 129  *    silc_time_universal("030219190403Z", &ret_time);
 130  *
 131  ***/
 132 SilcBool silc_time_universal(const char *universal_time, SilcTime ret_time);
 133
 134 /****f* silcutil/SilcTimeAPI/silc_time_universal_string
 135  *
 136  * SYNOPSIS
 137  *
 138  *    SilcBool silc_time_universal_string(SilcTime timeval, char *ret_string,
 139  *                                        SilcUInt32 ret_string_size);
 140  *
 141  * DESCRIPTION
 142  *
 143  *    Encodes the SilcTime `time' into the universal time format into the
 144  *    `ret_string' buffer.  Returns FALSE if the buffer is too small.
 145  *
 146  ***/
 147 SilcBool silc_time_universal_string(SilcTime timeval, char *ret_string,
 148                                     SilcUInt32 ret_string_size);
 149
 150 /****f* silcutil/SilcTimeAPI/silc_time_generalized
 151  *
 152  * SYNOPSIS
 153  *
 154  *    SilcBool silc_time_generalized(const char *generalized_time,
 155  *                                   SilcTime ret_time);
 156  *
 157  * DESCRIPTION
 158  *
 159  *    Returns time and date as SilcTime from `generalized_time' string which
 160  *    format is "YYYYMMDDhhmmss.ppZ", where YYYY is year, MM is month, DD
 161  *    is day, hh is hour, mm is minutes, ss is seconds which may have optional
 162  *    precision pp, and Z is timezone, which by default is Zulu (UTC).
 163  *    Generalized time is defined in ISO/EIC 8824-1.
 164  *
 165  *    Returns FALSE on error, TRUE otherwise.
 166  *
 167  * EXAMPLE
 168  *
 169  *    SilcTimeStruct ret_time;
 170  *
 171  *    time is 2003/02/19 19:04:03 Zulu (UTC)
 172  *    silc_time_generalized("20030219190403Z", &ret_time);
 173  *
 174  *    time is 2003/02/19 19:05:10.212 Zulu (UTC)
 175  *    silc_time_generalized("20030219190510.212Z", &ret_time);
 176  *
 177  ***/
 178 SilcBool
 179 silc_time_generalized(const char *generalized_time, SilcTime ret_time);
 180
 181 /****f* silcutil/SilcTimeAPI/silc_time_generalized_string
 182  *
 183  * SYNOPSIS
 184  *
 185  *    SilcBool silc_time_generalized_string(SilcTime timeval, char *ret_string,
 186  *                                          SilcUInt32 ret_string_size);
 187  *
 188  * DESCRIPTION
 189  *
 190  *    Encodes the SilcTime `time' into the generalized time format into the
 191  *    `ret_string' buffer.  Returns FALSE if the buffer is too small.
 192  *
 193  ***/
 194 SilcBool silc_time_generalized_string(SilcTime timeval, char *ret_string,
 195                                       SilcUInt32 ret_string_size);
 196
 197 #endif /* SILCTIME_H */