iCal.h

00001 #ifndef ICAL_H
00002 #define ICAL_H
00003 #include "mbed.h"
00004 
00005 // This defines the total number of events that can be handled - kind of limiting
00006 // but maybe ok for now. This is a kind of trade-off, based on having to receive
00007 // the whole iCal file into a buffer, and that not leaving a lot left over for
00008 // events themselves. Instead, the receive process should do more "on the fly"
00009 // with a then smaller buffer, leaving room for many more events. Possibly too,
00010 // the events could be quickly rejected if not matching the criteria.
00011 #define EVENT_COUNT 10
00012 
00013 
00014 // Maximum storage space for each item as free-form text
00015 #ifdef WIN32
00016 #define SUMMARY_CHARS 100
00017 #define LOCATION_CHARS 100
00018 #define CATEGORY_CHARS 20
00019 #else
00020 #define SUMMARY_CHARS 40
00021 #define LOCATION_CHARS 20
00022 #define CATEGORY_CHARS 20
00023 #endif
00024 
00025 typedef enum {
00026     rptfNone,
00027     rptfDaily,
00028     rptfWeekly,
00029     rptfMonthly,
00030     rptfYearly
00031 } RepeatFreq_t;
00032 
00033 #if 0
00034 typedef enum {
00035     Sunday    = 0x01,
00036     Monday    = 0x02,
00037     Tuesday   = 0x04,
00038     Wednesday = 0x08,
00039     Thursday  = 0x10,
00040     Friday    = 0x20,
00041     Saturday  = 0x40
00042 } RepeatDays_t;
00043 #endif
00044 
00045 typedef int32_t tz_sec_t;
00046 typedef int16_t tz_min_t;
00047 
00048 /// A single event consists of quite a number of attributes.
00049 typedef struct {
00050     time_t Start;
00051     time_t End;
00052     time_t Until;
00053     uint16_t Count;
00054     uint16_t Interval;
00055     RepeatFreq_t RepeatFreq;
00056     uint8_t RepeatDays;             // bit mapped (bit 0 = sunday, bit 1=monday, ...)
00057     uint16_t RepeatMonths;          // bit mapped (bit 0 = jan, 1=feb, ...)
00058     uint32_t RepeatMonthDay;        // bit mapped (bit 1 = 1st, 2=2nd, ...)
00059     uint32_t RepeatMonthDayRev;     // reverse -1 = last day = bit 1, -2=bit 2, ...
00060     char Summary[SUMMARY_CHARS];
00061     char Location[LOCATION_CHARS];
00062     char Category[CATEGORY_CHARS];  // "Green", ...
00063     int Priority;                   // 1 == High, 5 == Normal, 9 == Low
00064 } Event_T;
00065 
00066 extern Event_T EventList[EVENT_COUNT];
00067 
00068 /// Parse an iCal stream, and extract everything useful.
00069 ///
00070 /// This accepts a pointer to a [large] buffer, which is the contents
00071 /// of an iCal stream. It walked through all of the available
00072 /// information to extract the Event list. 
00073 ///
00074 /// @param[in] pStart is a pointer to the start of the stream.
00075 /// @param[in] gridStartTime is a time value representing the start of the time-window of interest.
00076 /// @param[in] gridEndTime is a time value representing the end of the time-window of interest.
00077 /// @param[in] tzoMin is the time-zone offset in minutes.
00078 /// @param[in] showEvents when true causes it to print the events as parsed.
00079 /// @returns number of events in range.
00080 ///
00081 int ParseICalStream(char * pStart, time_t gridStartTime, time_t gridEndTime, tz_min_t tzoMin, bool showEvents = true);
00082 
00083 
00084 /// Get the number of events that have been cached.
00085 ///
00086 /// @returns the number of events.
00087 ///
00088 int GetNumEvents(void);
00089 
00090 /// Compute the intersection of two time ranges, and evaluate the recurringing events.
00091 ///
00092 /// This compares a pair of time ranges, each by a start and end time. If they overlap
00093 /// it then computes the intersection of those two ranges. Additionally, for a 
00094 /// specified Event, it will evaluate the recurring events that may also fall into
00095 /// the target time range.
00096 ///
00097 /// @note This is usually the only API you need, as this will first call
00098 ///     the TimeIntersects function, and if that fails, then it will evaluate
00099 ///     repeat information.
00100 ///
00101 /// @param[in,out] start1 is the starting time of range 1.
00102 /// @param[in,out] end1 is the ending time of range 1.
00103 /// @param[in] start2 is the starting time of range 2.
00104 /// @param[in] end2 is the ending time of range 2.
00105 /// @param[in] Event is a pointer to the event of interest that may have recurring series.
00106 /// @returns true if the ranges overlap, and then start1 and end1 are set to the
00107 ///     intersection.
00108 ///
00109 bool RepeatIntersects(time_t * start1, time_t * end1, time_t * start2, time_t * end2, Event_T * Event = NULL);
00110 
00111 
00112 /// Compute the intersection of two time ranges, and returns that intersection.
00113 ///
00114 /// This compares a pair of time ranges, each by a start and end time. If they overlap
00115 /// it then computes the intersection of those two ranges.
00116 ///
00117 /// @param[in,out] start1 is the starting time of range 1.
00118 /// @param[in,out] end1 is the ending time of range 1.
00119 /// @param[in] start2 is the starting time of range 2.
00120 /// @param[in] end2 is the ending time of range 2.
00121 /// @returns true if the ranges overlap, and then start1 and end1 are set to the
00122 ///     intersection.
00123 ///
00124 bool TimeIntersects(time_t * start1, time_t * end1, time_t * start2, time_t * end2);
00125 
00126 
00127 // Private Functions - no real value external to the iCal public interface
00128 // other than for test code.
00129 
00130 /// Computes the next interval for iCal events that have recurrence.
00131 /// 
00132 /// @param[in] baseT is the base time value which is a factor only in leap-year.
00133 /// @param[in] repeatFreq is a value representing the frequency of recurrence - 
00134 ///     0=none, 1=daily, 2=weekly, 3=monthly, 4=yearly
00135 /// @param[in] interval is the multiplier of that repeat frequency to the next
00136 ///     event.
00137 /// @returns a time_t value which is the incremental interval, and would be added
00138 ///     to a reference time.
00139 ///
00140 time_t NextInterval(time_t baseT, int repeatFreq, int interval);
00141 
00142 
00143 /// Format a ctime value as a string, without the trailing <cr>
00144 ///
00145 /// This uses the normal ctime function, which appends a <cr>, but
00146 /// it then removes that trailing line ending character. Additionally,
00147 /// this keeps a few local static buffers to return the time string in
00148 /// which permits a printf (for example) to call this api a few times
00149 /// and get the proper representation of each.
00150 ///
00151 /// @param[in] t is a time value;
00152 /// @returns a pointer to a static buffer containing the converted time.
00153 ///
00154 char * FormatCTime(time_t t);
00155 
00156 /// Sort the Events that have been extracted from the iCal results.
00157 ///
00158 void SortEvents();
00159 
00160 /// Show the details for a specific Event, on the specified serial stream.
00161 ///
00162 /// Most useful during development, and perhaps no value after that.
00163 ///
00164 /// @param[in] Event is the event of interest.
00165 ///
00166 void ShowEventInfo(Event_T & Event);
00167 
00168 /// Access the 2-letter abbreviation for the day of the week.
00169 /// 
00170 /// @param[in] i is the day of the week, where 0 = sunday
00171 /// @returns a pointer to the 2-letter abbreviation.
00172 ///
00173 const char * RepeatDayAbbrev(int i);
00174 
00175 /// Parse a Datestamp string into a time value.
00176 ///
00177 /// Parses a string which can look like this: 20140505T200000
00178 /// into a time_t value.
00179 ///
00180 /// @param[in] string is the string to parse.
00181 /// @param[in] tzoSec is the time-zone offset in seconds.
00182 /// @returns time_t value.
00183 ///
00184 time_t ParseDateStamp(char * string, tz_sec_t tzoSec);
00185 
00186 /// Parse a Time Zone ID value from the front-end of a Datestamp
00187 ///
00188 /// Parses a string which can look like one of these:
00189 /// @li TZID="(GMT -06:00)":20140519T063000
00190 /// @li TZID:(UTC-06:00) Central Time (US & Canada)
00191 /// @li TZID:(GMT -06:00)
00192 ///
00193 /// @param[in] string to be parsed.
00194 /// @returns time zone offset in seconds.
00195 ///
00196 tz_sec_t ParseTZID(char * string);
00197 
00198 
00199 
00200 
00201 #endif // ICAL_H