opensync/format/opensync_time.h

   1 /*
   2  * libopensync - A synchronization framework
   3  * Copyright (C) 2004-2005  Armin Bauer <armin.bauer@opensync.org>
   4  * Copyright (C) 2006-2008 Daniel Gollub <dgollub@suse.de>
   5  * Copyright (C) 2007 Chris Frey <cdfrey@netdirect.ca>
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Lesser General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2.1 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Lesser General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Lesser General Public
  18  * License along with this library; if not, write to the Free Software
  19  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  20  *
  21  */
  22
  23 #ifndef _OPENSYNC_TIME_H_
  24 #define _OPENSYNC_TIME_H_
  25
  26 /**
  27  * @defgroup OSyncTimeAPI OpenSync Time
  28  * @ingroup OSyncFormat
  29  * @brief The public part of the OSyncTimeAPI
  30  *
  31  */
  32
  33 /**
  34  * @defgroup OSyncTimeFormatting Time formatting helpers
  35  * @ingroup OSyncTimeAPI
  36  * @brief Helper functions for formatting time strings, stripping out
  37  *      invalid characters, etc.
  38  */
  39 /*@{*/
  40
  41 /*
  42  * Time formatting helper
  43  */
  44
  45 /*! @brief Function returns a date-timestamp in OSyncTime Spec format
  46  *
  47  * @param vtime The timestamp which gets converted to a valid osync date-timestamp
  48  * @returns vtime date-timestring (the caller is responsible for freeing)
  49  */
  50 OSYNC_EXPORT char *osync_time_timestamp(const char *vtime);
  51
  52 /*! @brief Function returns a date without timestamp in OSyncTime Spec format
  53  *
  54  * @param vtime The timestamp which gets converted to a single datestamp
  55  * @returns valid single datestamp YYYYMMDD (the caller is responsible for freeing)
  56  */
  57 OSYNC_EXPORT char *osync_time_datestamp(const char *vtime);
  58
  59 /*! @brief Function returns TRUE if vtime is a valid datestamp (YYYYMMDD)
  60  *
  61  * @returns FALSE if vtime includes a timestamp, TRUE on a single datestamp
  62  */
  63 OSYNC_EXPORT osync_bool osync_time_isdate(const char *vformat);
  64
  65 /*! @brief Function returns TRUE if vtime is in UTC (YYYYMMDDTHH:MM:SSZ)
  66  *
  67  * @returns FALSE if vtime includes no Zulu, TRUE if the timestamp is UTC
  68  */
  69 OSYNC_EXPORT osync_bool osync_time_isutc(const char *vformat);
  70
  71 /*@}*/
  72
  73 /*****************************************************************************/
  74
  75 /**
  76  * @defgroup OSyncTimeStringToStruct String to struct converters.
  77  * @ingroup OSyncTimeAPI
  78  * @brief Helper functions for converting time between vtime formatted
  79  *      strings and struct tm time structures.  These functions are not
  80  *      smart in any way, with regards to timezones or daylight saving
  81  *      time, nor do they need to be.
  82  *
  83  */
  84 /*@{*/
  85
  86 /*! @brief Function converts vtime to tm struct
  87  *
  88  * @param vtime The formatted timestamp (YYYYMMDDTHHMMSS)
  89  * @returns struct tm (caller is responsible for freeing)
  90  */
  91 OSYNC_EXPORT struct tm *osync_time_vtime2tm(const char *vtime);
  92
  93 /*! @brief Function converts struct tm in vtime string
  94  *
  95  * YYYYMMDDTHHMMSS[Z]
  96  * Returned timezone is equal to the timezone of struct tm.
  97  *
  98  * @param time The tm struct which gets converted
  99  * @param is_utc If struct tm is UTC time is_utc have to be TRUE
 100  * @returns vtime formatted as YYYYMMDDTHHMMSS[Z] (caller is responsible for freeing)
 101  */
 102 OSYNC_EXPORT char *osync_time_tm2vtime(const struct tm *time, osync_bool is_utc);
 103
 104 /*@}*/
 105
 106 /*****************************************************************************/
 107
 108 /**
 109  * @defgroup OSyncTimeUnixTimeConverters Unix time converters
 110  * @ingroup OSyncTimeAPI
 111  * @brief Helper functions for converting to and from unix time_t
 112  *      timestamps.  Includes functions supporting vtime strings,
 113  *      and struct tm's in local and UTC time.
 114  *
 115  */
 116 /*@{*/
 117
 118 /*! @brief Function converts vtime to unix time
 119  *
 120  * @param offset Seconds of UTC offset
 121  * @param vtime The osync formmatted timestamp
 122  * @returns Unix timestamp in time_t (UTC)
 123  */
 124 OSYNC_EXPORT time_t osync_time_vtime2unix(const char *vtime, int offset);
 125
 126 /*! @brief Function converts unix timestamp to vtime in UTC
 127  *
 128  * @param timestamp The unix timestamp which gets converted
 129  * @returns vtime formatted as YYYYMMDDTHHMMSSZ (caller is responsible for freeing)
 130  */
 131 OSYNC_EXPORT char *osync_time_unix2vtime(const time_t *timestamp);
 132
 133 /* Unix time_t converters */
 134
 135 /*! @brief Function converts struct tm, in localtime, to unix timestamp.
 136  *              This is the same as calling mktime(), except that
 137  *              localtime is not modified, and tm_isdst is always
 138  *              forced to -1. Aka, mktime().
 139  *
 140  * @param localtime The struct tm, in localtime, which gets converted
 141  * @returns time_t (in UTC of course)
 142  */
 143 OSYNC_EXPORT time_t osync_time_localtm2unix(const struct tm *localtime);
 144
 145 /*! @brief Function converts struct tm, in utc, to unix timestamp.
 146  *
 147  * @param utctime The struct tm, in utc, which gets converted
 148  * @returns time_t (in UTC of course)
 149  *
 150  * This algorithm abuses the POSIX time functions, only because
 151  * there seems to be no standard API to do this more simply.
 152  * We could use the tm2utc() and tm2localtime() functions defined
 153  * farther on, but those are just simple math, and assume completely
 154  * that the offset provided is perfectly accurate.  This is not
 155  * always the case, when all you have is a random date in a tm struct.
 156  *
 157  * If there is a better way, I'd love to know!  - cdfrey
 158  */
 159 OSYNC_EXPORT time_t osync_time_utctm2unix(const struct tm *utctime);
 160
 161 /*! @brief Function converts unix timestamp to struct tm in localtime.
 162  *              This is the same as calling localtime_r(), except you
 163  *              have to free the returned value. Aka, localtime().
 164  *
 165  * @param timestamp The unixtimestamp which gets converted
 166  * @returns: struct tm (in localtime) (Caller is responsible for freeing!)
 167  */
 168 OSYNC_EXPORT struct tm *osync_time_unix2localtm(const time_t *timestamp);
 169
 170 /*! @brief Function converts unix timestamp to struct tm in utc.
 171  *              This is the same as calling gmtime_r(), except you
 172  *              have to free the returned value. Aka, gmtime().
 173  *
 174  * @param timestamp The unixtimestamp which gets converted
 175  * @returns: struct tm (in UTC) (Caller is responsible for freeing)
 176  */
 177 OSYNC_EXPORT struct tm *osync_time_unix2utctm(const time_t *timestamp);
 178
 179 /*@}*/
 180
 181 /*****************************************************************************/
 182
 183 /**
 184  * @defgroup OSyncTimeTimezoneHelpers Timezone helpers
 185  * @ingroup OSyncTimeAPI
 186  * @brief Helper functions for working with timezones, and doing
 187  *      conversions with user-specified timezone offsets.
 188  *      Note that in all functions below that require a timezone offset,
 189  *      they *require* the caller to be completely accurate with it,
 190  *      including in the DST case.  The result is only as accurate
 191  *      as the offset you provide.
 192  *
 193  */
 194 /*@{*/
 195
 196 /*! @brief Function gets offset of parameter time between UTC and
 197  *      localtime in seconds east of UTC.  (i.e. east is positive,
 198  *      west is negative)
 199  *
 200  * @param local The point in time when the offset have to be calculated,
 201  *      specified in localtime (need for CEST/CET)
 202  * @returns Seconds of timezone offset
 203  */
 204 OSYNC_EXPORT int osync_time_timezone_diff(const struct tm *local);
 205
 206 /*! @brief Function converts (struct tm) ltime from localtime to UTC.
 207  *         Paramter offset is used as UTC offset.  Note that _only_ the
 208  *         following fields can be relied upon in the result:
 209  *         tm_sec, tm_min, tm_hour, tm_mday, tm_mon, tm_year.
 210  *
 211  * @param ltime The struct tm which gets converted to UTC timezone
 212  * @param offset Seconds of UTC offset, in seconds east of UTC.
 213  * @returns struct tm in UTC (caller is responsible for freeing)
 214  */
 215 OSYNC_EXPORT struct tm *osync_time_tm2utc(const struct tm *ltime, int offset);
 216
 217 /*! @brief Function converts (struct tm) utime from UTC to localtime
 218  *         Paramter offset is used as UTC offset.  Note that _only_ the
 219  *         following fields can be relied upon in the result:
 220  *         tm_sec, tm_min, tm_hour, tm_mday, tm_mon, tm_year.
 221  *
 222  * @param utime The struct tm which gets converted to localtime
 223  * @param offset Seconds of UTC offset, in seconds east of UTC.
 224  * @returns struct tm in localtime (caller is responsible for freeing)
 225  */
 226 OSYNC_EXPORT struct tm *osync_time_tm2localtime(const struct tm *utime, int offset);
 227
 228 /*! @brief Functions converts a localtime vtime stamp to a UTC vtime stamp
 229  *
 230  * @param localtime The local timestamp in vtime format
 231  * @param offset Seconds of UTC offset, in seconds east of UTC.
 232  * @returns vtime in UTC timezone (caller is responsible for freeing)
 233  */
 234 OSYNC_EXPORT char *osync_time_vtime2utc(const char* localtime, int offset);
 235
 236 /*! @brief Functions converts a UTC vtime stamp to a localtime vtime stamp
 237  *
 238  * @param utc The timestap in UTC timezone which gets converted to localtime
 239  * @param offset The offset in seconds between UTC and localtime
 240  * @returns vtime in local  timezon (caller is preponsible for freeing)
 241  */
 242 OSYNC_EXPORT char *osync_time_vtime2localtime(const char* utc, int offset);
 243
 244 /*! @brief Function converts UTC offset string in offset in seconds
 245  *
 246  * @param offset The offset string of the form a timezone field (Example +0200)
 247  * @returns seconds of UTC offset
 248  */
 249 OSYNC_EXPORT int osync_time_utcoffset2sec(const char *offset);
 250
 251 /*@}*/
 252
 253 /*****************************************************************************/
 254
 255 /**
 256  * @defgroup OSyncTimeBackwardCompatibility Backward compatibility functions.
 257  * @ingroup OSyncTimeAPI
 258  * @brief These functions should only be used as workaround for plugins
 259  *      which only support localtime without any timezone information.
 260  *
 261  *      XXX This functions should only be used as workaround for plugins which
 262  *      only supports localtime without any timezone information.
 263  */
 264 /*@{*/
 265
 266
 267 /*! @brief Functions converts timestamps of vcal to localtime
 268  *
 269  * @param vcal The vcalendar which has to be converted.
 270  * @return modified vcalendar with local timestamps (related to system time)
 271  */
 272 OSYNC_EXPORT char *osync_time_vcal2localtime(const char *vcal);
 273
 274 /*! @brief Functions converts timestamps of vcal to UTC
 275  *
 276  * @param vcal The vcalendar which has to be converted.
 277  * @return modified vcalendar with UTC timestamps (related to system time)
 278  */
 279 OSYNC_EXPORT char *osync_time_vcal2utc(const char *vcal);
 280
 281
 282 /*@}*/
 283
 284 /*****************************************************************************/
 285
 286 /**
 287  * @defgroup OSyncTimeAlarmDurationFormat Alarm duration format helpers.
 288  * @ingroup OSyncTimeAPI
 289  * @brief Functions for converting alarm durations to and from string formats.
 290  *
 291  */
 292 /*@{*/
 293
 294 /*! @brief Functions converts seconds in duration before or after alarm event
 295  *
 296  * @param seconds
 297  * @returns ical alarm duration string (caller is preponsible for freeing)
 298  */
 299 OSYNC_EXPORT char *osync_time_sec2alarmdu(int seconds);
 300
 301 /*! @brief Functions converts alarm duration event to seconds needed for reminder of vcal/ical
 302  *
 303  * TODO: Test support for ALARM after/before end and after start
 304  *
 305  * @param alarm
 306  * @returns seconds of alarm and duration
 307  */
 308
 309 OSYNC_EXPORT int osync_time_alarmdu2sec(const char *alarm);
 310
 311 /*@}*/
 312
 313 /*****************************************************************************/
 314
 315 /**
 316  * @defgroup OSyncTimeRecurrence Recurring time calculators.
 317  * @ingroup OSyncTimeAPI
 318  * @brief Functions related to calculating recurring dates.
 319  *
 320  */
 321 /*@{*/
 322
 323 /*! @brief Function converts a week day string to the struct tm wday integer.
 324  *
 325  * FIXME: how do we handle iCal weekday strings with multiple days?
 326  * something like the following?
 327  * int osync_time_str2wday(const char *weekday, int *wdaymap);
 328  *
 329  * @param swday string of the week day
 330  * @returns integer of the weekday (Sunday = 0), or -1 on error
 331  */
 332 OSYNC_EXPORT int osync_time_str2wday(const char *swday);
 333
 334 /*! @brief Function determines the exact date of relative information.
 335  *         It is used for example to determine the last sunday of a month (-1SU)
 336  *         in a specific year.
 337  *         Note that the RFC2445 spec states that a weekday without
 338  *         a prefixed numeric value means *every* weekday in the month.
 339  *         This function will fail in such a case and return NULL.
 340  *         Also note that if byday contains multiple weekdays in its
 341  *         string (e.g. -1SU,MO) only the first weekday will be used (SU).
 342  *
 343  * @param byday string of the relative day of month modifier
 344  * @param bymonth calendar number of the month (January = 1)
 345  * @param year calendar year (e.g. 1970, 2007, etc)
 346  * @returns struct tm of the relative information date with 00:00:00 timestamp
 347  *          or NULL on error.
 348  *          (Caller is responsible for freeing)
 349  */
 350 OSYNC_EXPORT struct tm *osync_time_relative2tm(const char *byday, const int bymonth, const int year);
 351
 352 #ifdef _WIN32
 353 /* Windows does not provide gmtime_r and localtime_r */
 354 /* This module uses these two functions internally   */
 355 /* They are also exported for testing purposes       */
 356 OSYNC_TEST_EXPORT inline struct tm* gmtime_r (const time_t *clock, struct tm *result);
 357 OSYNC_TEST_EXPORT inline struct tm* localtime_r (const time_t *clock, struct tm *result);
 358 #endif /* _WIN32 */
 359
 360 /*@}*/
 361
 362 #endif /*_OPENSYNC_TIME_H_*/