1 /* -*- Mode: C -*- */ 2 /*====================================================================== 3 FILE: icaltime.h 4 CREATOR: eric 02 June 2000 5 6 7 $Id: icaltime.h,v 1.28 2008-01-15 23:17:42 dothebart Exp $ 8 $Locker: $ 9 10 (C) COPYRIGHT 2000, Eric Busboom <eric@softwarestudio.org> 11 http://www.softwarestudio.org 12 13 This program is free software; you can redistribute it and/or modify 14 it under the terms of either: 15 16 The LGPL as published by the Free Software Foundation, version 17 2.1, available at: http://www.fsf.org/copyleft/lesser.html 18 19 Or: 20 21 The Mozilla Public License Version 1.0. You may obtain a copy of 22 the License at http://www.mozilla.org/MPL/ 23 24 The Original Code is eric. The Initial Developer of the Original 25 Code is Eric Busboom 26 27 28 ======================================================================*/ 29 30 /** @file icaltime.h 31 * @brief struct icaltimetype is a pseudo-object that abstracts time 32 * handling. 33 * 34 * It can represent either a DATE or a DATE-TIME (floating, UTC or in a 35 * given timezone), and it keeps track internally of its native timezone. 36 * 37 * The typical usage is to call the correct constructor specifying the 38 * desired timezone. If this is not known until a later time, the 39 * correct behavior is to specify a NULL timezone and call 40 * icaltime_convert_to_zone() at a later time. 41 * 42 * There are several ways to create a new icaltimetype: 43 * 44 * - icaltime_null_time() 45 * - icaltime_null_date() 46 * - icaltime_current_time_with_zone() 47 * - icaltime_today() 48 * - icaltime_from_timet_with_zone(time_t tm, int is_date, 49 * icaltimezone *zone) 50 * - icaltime_from_string_with_zone(const char* str, icaltimezone *zone) 51 * - icaltime_from_day_of_year(int doy, int year) 52 * - icaltime_from_week_number(int week_number, int year) 53 * 54 * italtimetype objects can be converted to different formats: 55 * 56 * - icaltime_as_timet(struct icaltimetype tt) 57 * - icaltime_as_timet_with_zone(struct icaltimetype tt, 58 * icaltimezone *zone) 59 * - icaltime_as_ical_string(struct icaltimetype tt) 60 * 61 * Accessor methods include: 62 * 63 * - icaltime_get_timezone(struct icaltimetype t) 64 * - icaltime_get_tzid(struct icaltimetype t) 65 * - icaltime_set_timezone(struct icaltimetype t, const icaltimezone *zone) 66 * - icaltime_day_of_year(struct icaltimetype t) 67 * - icaltime_day_of_week(struct icaltimetype t) 68 * - icaltime_start_doy_of_week(struct icaltimetype t, int fdow) 69 * - icaltime_week_number(struct icaltimetype t) 70 * 71 * Query methods include: 72 * 73 * - icaltime_is_null_time(struct icaltimetype t) 74 * - icaltime_is_valid_time(struct icaltimetype t) 75 * - icaltime_is_date(struct icaltimetype t) 76 * - icaltime_is_utc(struct icaltimetype t) 77 * - icaltime_is_floating(struct icaltimetype t) 78 * 79 * Modify, compare and utility methods include: 80 * 81 * - icaltime_add(struct icaltimetype t, struct icaldurationtype d) 82 * - icaltime_subtract(struct icaltimetype t1, struct icaltimetype t2) 83 * - icaltime_compare_with_zone(struct icaltimetype a,struct icaltimetype b) 84 * - icaltime_compare(struct icaltimetype a,struct icaltimetype b) 85 * - icaltime_compare_date_only(struct icaltimetype a, 86 * struct icaltimetype b) 87 * - icaltime_adjust(struct icaltimetype *tt, int days, int hours, 88 * int minutes, int seconds); 89 * - icaltime_normalize(struct icaltimetype t); 90 * - icaltime_convert_to_zone(const struct icaltimetype tt, 91 * icaltimezone *zone); 92 */ 93 94 #ifndef ICALTIME_H 95 #define ICALTIME_H 96 97 #include <time.h> 98 99 /* An opaque struct representing a timezone. We declare this here to avoid 100 a circular dependancy. */ 101 #ifndef ICALTIMEZONE_DEFINED 102 #define ICALTIMEZONE_DEFINED 103 typedef struct _icaltimezone icaltimezone; 104 #endif 105 106 /** icaltime_span is returned by icalcomponent_get_span() */ 107 struct icaltime_span { 108 time_t start; /**< in UTC */ 109 time_t end; /**< in UTC */ 110 int is_busy; /**< 1->busy time, 0-> free time */ 111 }; 112 113 typedef struct icaltime_span icaltime_span; 114 115 /* 116 * FIXME 117 * 118 * is_utc is redundant, and might be considered a minor optimization. 119 * It might be deprecated, so you should use icaltime_is_utc() instead. 120 */ 121 struct icaltimetype 122 { 123 int year; /**< Actual year, e.g. 2001. */ 124 int month; /**< 1 (Jan) to 12 (Dec). */ 125 int day; 126 int hour; 127 int minute; 128 int second; 129 130 int is_utc; /**< 1-> time is in UTC timezone */ 131 132 int is_date; /**< 1 -> interpret this as date. */ 133 134 int is_daylight; /**< 1 -> time is in daylight savings time. */ 135 136 const icaltimezone *zone; /**< timezone */ 137 }; 138 139 typedef struct icaltimetype icaltimetype; 140 141 /** Return a null time, which indicates no time has been set. 142 This time represent the beginning of the epoch */ 143 struct icaltimetype icaltime_null_time(void); 144 145 /** Return a null date */ 146 struct icaltimetype icaltime_null_date(void); 147 148 /** Returns the current time in the given timezone, as an icaltimetype. */ 149 struct icaltimetype icaltime_current_time_with_zone(const icaltimezone *zone); 150 151 /** Returns the current day as an icaltimetype, with is_date set. */ 152 struct icaltimetype icaltime_today(void); 153 154 /** Convert seconds past UNIX epoch to a timetype*/ 155 struct icaltimetype icaltime_from_timet(const time_t v, const int is_date); 156 157 /** Convert seconds past UNIX epoch to a timetype, using timezones. */ 158 struct icaltimetype icaltime_from_timet_with_zone(const time_t tm, 159 const int is_date, const icaltimezone *zone); 160 161 /** create a time from an ISO format string */ 162 struct icaltimetype icaltime_from_string(const char* str); 163 164 /** create a time from an ISO format string */ 165 struct icaltimetype icaltime_from_string_with_zone(const char* str, 166 const icaltimezone *zone); 167 168 /** Create a new time, given a day of year and a year. */ 169 struct icaltimetype icaltime_from_day_of_year(const int doy, 170 const int year); 171 172 /** @brief Contructor (TODO). 173 * Create a new time from a weeknumber and a year. */ 174 struct icaltimetype icaltime_from_week_number(const int week_number, 175 const int year); 176 177 /** Return the time as seconds past the UNIX epoch */ 178 time_t icaltime_as_timet(const struct icaltimetype); 179 180 /** Return the time as seconds past the UNIX epoch, using timezones. */ 181 time_t icaltime_as_timet_with_zone(const struct icaltimetype tt, 182 const icaltimezone *zone); 183 184 /** Return a string represention of the time, in RFC2445 format. */ 185 const char* icaltime_as_ical_string(const struct icaltimetype tt); 186 char* icaltime_as_ical_string_r(const struct icaltimetype tt); 187 188 /** @brief Return the timezone */ 189 const icaltimezone *icaltime_get_timezone(const struct icaltimetype t); 190 191 /** @brief Return the tzid, or NULL for a floating time */ 192 const char *icaltime_get_tzid(const struct icaltimetype t); 193 194 /** @brief Set the timezone */ 195 struct icaltimetype icaltime_set_timezone(struct icaltimetype *t, 196 const icaltimezone *zone); 197 198 /** Return the day of the year of the given time */ 199 int icaltime_day_of_year(const struct icaltimetype t); 200 201 /** Return the day of the week of the given time. Sunday is 1 */ 202 int icaltime_day_of_week(const struct icaltimetype t); 203 204 /** Return the day of the year for the Sunday of the week that the 205 given time is within. */ 206 int icaltime_start_doy_of_week(const struct icaltimetype t); 207 208 /** Return the day of the year for the first day of the week that the 209 given time is within. */ 210 int icaltime_start_doy_week(const struct icaltimetype t, int fdow); 211 212 /** Return the week number for the week the given time is within */ 213 int icaltime_week_number(const struct icaltimetype t); 214 215 /** Return true of the time is null. */ 216 int icaltime_is_null_time(const struct icaltimetype t); 217 218 /** Returns false if the time is clearly invalid, but is not null. This 219 is usually the result of creating a new time type buy not clearing 220 it, or setting one of the flags to an illegal value. */ 221 int icaltime_is_valid_time(const struct icaltimetype t); 222 223 /** @brief Returns true if time is of DATE type, false if DATE-TIME */ 224 int icaltime_is_date(const struct icaltimetype t); 225 226 /** @brief Returns true if time is relative to UTC zone */ 227 int icaltime_is_utc(const struct icaltimetype t); 228 229 /** @brief Returns true if time is a floating time */ 230 int icaltime_is_floating(const struct icaltimetype t); 231 232 /** Return -1, 0, or 1 to indicate that a<b, a==b or a>b */ 233 int icaltime_compare_with_zone(const struct icaltimetype a, 234 const struct icaltimetype b); 235 236 /** Return -1, 0, or 1 to indicate that a<b, a==b or a>b */ 237 int icaltime_compare(const struct icaltimetype a, 238 const struct icaltimetype b); 239 240 /** like icaltime_compare, but only use the date parts. */ 241 int icaltime_compare_date_only(const struct icaltimetype a, 242 const struct icaltimetype b); 243 244 /** like icaltime_compare, but only use the date parts. */ 245 int icaltime_compare_date_only_tz(const struct icaltimetype a, 246 const struct icaltimetype b, icaltimezone *tz); 247 248 /** Adds or subtracts a number of days, hours, minutes and seconds. */ 249 void icaltime_adjust(struct icaltimetype *tt, const int days, 250 const int hours, const int minutes, const int seconds); 251 252 /** Normalize the icaltime, so that all fields are within the normal range. */ 253 struct icaltimetype icaltime_normalize(const struct icaltimetype t); 254 255 /** convert tt, of timezone tzid, into a utc time. Does nothing if the 256 time is already UTC. */ 257 struct icaltimetype icaltime_convert_to_zone(const struct icaltimetype tt, 258 icaltimezone *zone); 259 260 /** Return the number of days in the given month */ 261 int icaltime_days_in_month(const int month, const int year); 262 263 /** Return whether you've specified a leapyear or not. */ 264 int icaltime_is_leap_year (const int year); 265 266 /** Return the number of days in this year */ 267 int icaltime_days_in_year (const int year); 268 269 /** @brief calculate an icaltimespan given a start and end time. */ 270 struct icaltime_span icaltime_span_new(struct icaltimetype dtstart, 271 struct icaltimetype dtend, 272 int is_busy); 273 274 /** @brief Returns true if the two spans overlap **/ 275 int icaltime_span_overlaps(icaltime_span *s1, 276 icaltime_span *s2); 277 278 /** @brief Returns true if the span is totally within the containing 279 * span 280 */ 281 int icaltime_span_contains(icaltime_span *s, 282 icaltime_span *container); 283 284 285 #endif /* !ICALTIME_H */ 286 287 288