David Smart / iCal

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

iCal.h@5:69577415c16e, 2014-06-22 (annotated)

Committer:
WiredHome
Date:
Sun Jun 22 20:52:26 2014 +0000
Revision:
5:69577415c16e
Parent:
4:a1c25d936346
Child:
8:87549cc99d5e
Revise the parsing and time zone management.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
WiredHome 0:49245357cd1b 1 #ifndef ICAL_H
WiredHome 0:49245357cd1b 2 #define ICAL_H
WiredHome 0:49245357cd1b 3 #include "mbed.h"
WiredHome 0:49245357cd1b 4
WiredHome 0:49245357cd1b 5 // This defines the total number of events that can be handled - kind of limiting
WiredHome 5:69577415c16e 6 // but maybe ok for now. This is a kind of trade-off, based on having to receive
WiredHome 5:69577415c16e 7 // the whole iCal file into a buffer, and that not leaving a lot left over for
WiredHome 5:69577415c16e 8 // events themselves. Instead, the receive process should do more "on the fly"
WiredHome 5:69577415c16e 9 // with a then smaller buffer, leaving room for many more events. Possibly too,
WiredHome 5:69577415c16e 10 // the events could be quickly rejected if not matching the criteria.
WiredHome 0:49245357cd1b 11 #define EVENT_COUNT 10
WiredHome 0:49245357cd1b 12
WiredHome 0:49245357cd1b 13
WiredHome 0:49245357cd1b 14 // Maximum storage space for each item as free-form text
WiredHome 4:a1c25d936346 15 #ifdef WIN32
WiredHome 4:a1c25d936346 16 #define SUMMARY_CHARS 100
WiredHome 4:a1c25d936346 17 #define LOCATION_CHARS 100
WiredHome 4:a1c25d936346 18 #define CATEGORY_CHARS 20
WiredHome 4:a1c25d936346 19 #else
WiredHome 0:49245357cd1b 20 #define SUMMARY_CHARS 40
WiredHome 3:fc5cdc930896 21 #define LOCATION_CHARS 20
WiredHome 3:fc5cdc930896 22 #define CATEGORY_CHARS 20
WiredHome 4:a1c25d936346 23 #endif
WiredHome 0:49245357cd1b 24
WiredHome 0:49245357cd1b 25 typedef enum {
WiredHome 0:49245357cd1b 26 rptfNone,
WiredHome 0:49245357cd1b 27 rptfDaily,
WiredHome 0:49245357cd1b 28 rptfWeekly,
WiredHome 0:49245357cd1b 29 rptfMonthly,
WiredHome 0:49245357cd1b 30 rptfYearly
WiredHome 0:49245357cd1b 31 } RepeatFreq_t;
WiredHome 0:49245357cd1b 32
WiredHome 0:49245357cd1b 33 #if 0
WiredHome 0:49245357cd1b 34 typedef enum {
WiredHome 0:49245357cd1b 35 Sunday = 0x01,
WiredHome 0:49245357cd1b 36 Monday = 0x02,
WiredHome 0:49245357cd1b 37 Tuesday = 0x04,
WiredHome 0:49245357cd1b 38 Wednesday = 0x08,
WiredHome 0:49245357cd1b 39 Thursday = 0x10,
WiredHome 0:49245357cd1b 40 Friday = 0x20,
WiredHome 0:49245357cd1b 41 Saturday = 0x40
WiredHome 0:49245357cd1b 42 } RepeatDays_t;
WiredHome 0:49245357cd1b 43 #endif
WiredHome 0:49245357cd1b 44
WiredHome 5:69577415c16e 45 typedef int32_t tz_sec_t;
WiredHome 5:69577415c16e 46 typedef int16_t tz_min_t;
WiredHome 5:69577415c16e 47
WiredHome 0:49245357cd1b 48 typedef struct {
WiredHome 0:49245357cd1b 49 time_t Start;
WiredHome 0:49245357cd1b 50 time_t End;
WiredHome 0:49245357cd1b 51 time_t Until;
WiredHome 0:49245357cd1b 52 uint16_t Count;
WiredHome 0:49245357cd1b 53 uint16_t Interval;
WiredHome 0:49245357cd1b 54 RepeatFreq_t RepeatFreq;
WiredHome 4:a1c25d936346 55 uint8_t RepeatDays; // bit mapped (bit 0 = sunday, bit 1=monday, ...)
WiredHome 4:a1c25d936346 56 uint16_t RepeatMonths; // bit mapped (bit 0 = jan, 1=feb, ...)
WiredHome 4:a1c25d936346 57 uint32_t RepeatMonthDay; // bit mapped (bit 1 = 1st, 2=2nd, ...)
WiredHome 4:a1c25d936346 58 uint32_t RepeatMonthDayRev; // reverse -1 = last day = bit 1, -2=bit 2, ...
WiredHome 0:49245357cd1b 59 char Summary[SUMMARY_CHARS];
WiredHome 0:49245357cd1b 60 char Location[LOCATION_CHARS];
WiredHome 0:49245357cd1b 61 char Category[CATEGORY_CHARS]; // "Green", ...
WiredHome 0:49245357cd1b 62 int Priority; // 1 == High, 5 == Normal, 9 == Low
WiredHome 0:49245357cd1b 63 } Event_T;
WiredHome 0:49245357cd1b 64
WiredHome 0:49245357cd1b 65
WiredHome 0:49245357cd1b 66 extern Event_T EventList[EVENT_COUNT];
WiredHome 0:49245357cd1b 67
WiredHome 4:a1c25d936346 68
WiredHome 4:a1c25d936346 69 /// Parse an iCal stream, and extract everything useful.
WiredHome 4:a1c25d936346 70 ///
WiredHome 4:a1c25d936346 71 /// This accepts a pointer to a [large] buffer, which is the contents
WiredHome 4:a1c25d936346 72 /// of an iCal stream. It walked through all of the available
WiredHome 4:a1c25d936346 73 /// information to extract the Event list.
WiredHome 4:a1c25d936346 74 ///
WiredHome 4:a1c25d936346 75 /// @param[in] pStart is a pointer to the start of the stream.
WiredHome 4:a1c25d936346 76 /// @param[in] gridStartTime is a time value representing the start of the time-window of interest.
WiredHome 4:a1c25d936346 77 /// @param[in] gridEndTime is a time value representing the end of the time-window of interest.
WiredHome 5:69577415c16e 78 /// @param[in] tzoMin is the time-zone offset in minutes.
WiredHome 4:a1c25d936346 79 /// @param[in] showEvents when true causes it to print the events as parsed.
WiredHome 4:a1c25d936346 80 /// @returns number of events in range.
WiredHome 4:a1c25d936346 81 ///
WiredHome 5:69577415c16e 82 int ParseICalStream(char * pStart, time_t gridStartTime, time_t gridEndTime, tz_min_t tzoMin, bool showEvents = false);
WiredHome 4:a1c25d936346 83
WiredHome 4:a1c25d936346 84
WiredHome 4:a1c25d936346 85 /// Get the number of events that have been cached.
WiredHome 4:a1c25d936346 86 ///
WiredHome 4:a1c25d936346 87 /// @returns the number of events.
WiredHome 4:a1c25d936346 88 ///
WiredHome 4:a1c25d936346 89 int GetNumEvents(void);
WiredHome 4:a1c25d936346 90
WiredHome 4:a1c25d936346 91 /// Compute the intersection of two time ranges, and evaluate the recurringing events.
WiredHome 4:a1c25d936346 92 ///
WiredHome 4:a1c25d936346 93 /// This compares a pair of time ranges, each by a start and end time. If they overlap
WiredHome 4:a1c25d936346 94 /// it then computes the intersection of those two ranges. Additionally, for a
WiredHome 4:a1c25d936346 95 /// specified Event, it will evaluate the recurring events that may also fall into
WiredHome 4:a1c25d936346 96 /// the target time range.
WiredHome 4:a1c25d936346 97 ///
WiredHome 4:a1c25d936346 98 /// @note This is usually the only API you need, as this will first call
WiredHome 4:a1c25d936346 99 /// the TimeIntersects function, and if that fails, then it will evaluate
WiredHome 4:a1c25d936346 100 /// repeat information.
WiredHome 4:a1c25d936346 101 ///
WiredHome 4:a1c25d936346 102 /// @param[in,out] start1 is the starting time of range 1.
WiredHome 4:a1c25d936346 103 /// @param[in,out] end1 is the ending time of range 1.
WiredHome 4:a1c25d936346 104 /// @param[in] start2 is the starting time of range 2.
WiredHome 4:a1c25d936346 105 /// @param[in] end2 is the ending time of range 2.
WiredHome 4:a1c25d936346 106 /// @param[in] Event is a pointer to the event of interest that may have recurring series.
WiredHome 4:a1c25d936346 107 /// @returns true if the ranges overlap, and then start1 and end1 are set to the
WiredHome 4:a1c25d936346 108 /// intersection.
WiredHome 4:a1c25d936346 109 ///
WiredHome 4:a1c25d936346 110 bool RepeatIntersects(time_t * start1, time_t * end1, time_t * start2, time_t * end2, Event_T * Event = NULL);
WiredHome 4:a1c25d936346 111
WiredHome 4:a1c25d936346 112
WiredHome 4:a1c25d936346 113 /// Compute the intersection of two time ranges, and returns that intersection.
WiredHome 4:a1c25d936346 114 ///
WiredHome 4:a1c25d936346 115 /// This compares a pair of time ranges, each by a start and end time. If they overlap
WiredHome 4:a1c25d936346 116 /// it then computes the intersection of those two ranges.
WiredHome 4:a1c25d936346 117 ///
WiredHome 4:a1c25d936346 118 /// @param[in,out] start1 is the starting time of range 1.
WiredHome 4:a1c25d936346 119 /// @param[in,out] end1 is the ending time of range 1.
WiredHome 4:a1c25d936346 120 /// @param[in] start2 is the starting time of range 2.
WiredHome 4:a1c25d936346 121 /// @param[in] end2 is the ending time of range 2.
WiredHome 4:a1c25d936346 122 /// @returns true if the ranges overlap, and then start1 and end1 are set to the
WiredHome 4:a1c25d936346 123 /// intersection.
WiredHome 4:a1c25d936346 124 ///
WiredHome 4:a1c25d936346 125 bool TimeIntersects(time_t * start1, time_t * end1, time_t * start2, time_t * end2);
WiredHome 4:a1c25d936346 126
WiredHome 4:a1c25d936346 127
WiredHome 4:a1c25d936346 128 // Private Functions - no real value external to the iCal public interface
WiredHome 4:a1c25d936346 129 // other than for test code.
WiredHome 4:a1c25d936346 130
WiredHome 4:a1c25d936346 131 /// Computes the next interval for iCal events that have recurrence.
WiredHome 4:a1c25d936346 132 ///
WiredHome 4:a1c25d936346 133 /// @param[in] baseT is the base time value which is a factor only in leap-year.
WiredHome 4:a1c25d936346 134 /// @param[in] repeatFreq is a value representing the frequency of recurrence -
WiredHome 4:a1c25d936346 135 /// 0=none, 1=daily, 2=weekly, 3=monthly, 4=yearly
WiredHome 4:a1c25d936346 136 /// @param[in] interval is the multiplier of that repeat frequency to the next
WiredHome 4:a1c25d936346 137 /// event.
WiredHome 4:a1c25d936346 138 /// @returns a time_t value which is the incremental interval, and would be added
WiredHome 4:a1c25d936346 139 /// to a reference time.
WiredHome 4:a1c25d936346 140 ///
WiredHome 4:a1c25d936346 141 time_t NextInterval(time_t baseT, int repeatFreq, int interval);
WiredHome 4:a1c25d936346 142
WiredHome 4:a1c25d936346 143
WiredHome 0:49245357cd1b 144 /// Format a ctime value as a string, without the trailing <cr>
WiredHome 0:49245357cd1b 145 ///
WiredHome 0:49245357cd1b 146 /// This uses the normal ctime function, which appends a <cr>, but
WiredHome 0:49245357cd1b 147 /// it then removes that trailing line ending character. Additionally,
WiredHome 0:49245357cd1b 148 /// this keeps a few local static buffers to return the time string in
WiredHome 0:49245357cd1b 149 /// which permits a printf (for example) to call this api a few times
WiredHome 0:49245357cd1b 150 /// and get the proper representation of each.
WiredHome 0:49245357cd1b 151 ///
WiredHome 1:db274b9e40cc 152 /// @param[in] t is a time value;
WiredHome 0:49245357cd1b 153 /// @returns a pointer to a static buffer containing the converted time.
WiredHome 0:49245357cd1b 154 ///
WiredHome 0:49245357cd1b 155 char * FormatCTime(time_t t);
WiredHome 0:49245357cd1b 156
WiredHome 0:49245357cd1b 157 /// Sort the Events that have been extracted from the iCal results.
WiredHome 0:49245357cd1b 158 ///
WiredHome 0:49245357cd1b 159 void SortEvents();
WiredHome 0:49245357cd1b 160
WiredHome 0:49245357cd1b 161 /// Show the details for a specific Event, on the specified serial stream.
WiredHome 0:49245357cd1b 162 ///
WiredHome 4:a1c25d936346 163 /// Most useful during development, and perhaps no value after that.
WiredHome 0:49245357cd1b 164 ///
WiredHome 1:db274b9e40cc 165 /// @param[in] Event is the event of interest.
WiredHome 0:49245357cd1b 166 ///
WiredHome 0:49245357cd1b 167 void ShowEventInfo(Event_T & Event);
WiredHome 0:49245357cd1b 168
WiredHome 0:49245357cd1b 169 /// Access the 2-letter abbreviation for the day of the week.
WiredHome 0:49245357cd1b 170 ///
WiredHome 1:db274b9e40cc 171 /// @param[in] i is the day of the week, where 0 = sunday
WiredHome 0:49245357cd1b 172 /// @returns a pointer to the 2-letter abbreviation.
WiredHome 0:49245357cd1b 173 ///
WiredHome 0:49245357cd1b 174 const char * RepeatDayAbbrev(int i);
WiredHome 0:49245357cd1b 175
WiredHome 0:49245357cd1b 176 /// Parse a Datestamp string into a time value.
WiredHome 0:49245357cd1b 177 ///
WiredHome 0:49245357cd1b 178 /// Parses a string which can look like this: 20140505T200000
WiredHome 0:49245357cd1b 179 /// into a time_t value.
WiredHome 0:49245357cd1b 180 ///
WiredHome 1:db274b9e40cc 181 /// @param[in] string is the string to parse.
WiredHome 1:db274b9e40cc 182 /// @param[in] tzoSec is the time-zone offset in seconds.
WiredHome 0:49245357cd1b 183 /// @returns time_t value.
WiredHome 0:49245357cd1b 184 ///
WiredHome 5:69577415c16e 185 time_t ParseDateStamp(char * string, tz_sec_t tzoSec);
WiredHome 0:49245357cd1b 186
WiredHome 4:a1c25d936346 187 /// Parse a Time Zone ID value from the front-end of a Datestamp
WiredHome 0:49245357cd1b 188 ///
WiredHome 4:a1c25d936346 189 /// Parses a string which can look like one of these:
WiredHome 4:a1c25d936346 190 /// @li TZID="(GMT -06:00)":20140519T063000
WiredHome 4:a1c25d936346 191 /// @li TZID:(UTC-06:00) Central Time (US & Canada)
WiredHome 4:a1c25d936346 192 /// @li TZID:(GMT -06:00)
WiredHome 0:49245357cd1b 193 ///
WiredHome 4:a1c25d936346 194 /// @param[in] string to be parsed.
WiredHome 4:a1c25d936346 195 /// @returns time zone offset in seconds.
WiredHome 0:49245357cd1b 196 ///
WiredHome 5:69577415c16e 197 tz_sec_t ParseTZID(char * string);
WiredHome 0:49245357cd1b 198
WiredHome 4:a1c25d936346 199
WiredHome 0:49245357cd1b 200
WiredHome 0:49245357cd1b 201
WiredHome 4:a1c25d936346 202 #endif // ICAL_H