David Smart / iCal

an iCal processing library

iCal.h@0:49245357cd1b, 2014-04-20 (annotated)

Committer:
WiredHome
Date:
Sun Apr 20 13:25:50 2014 +0000
Revision:
0:49245357cd1b
Child:
1:db274b9e40cc
iCal processing library.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
WiredHome 0:49245357cd1b 1
WiredHome 0:49245357cd1b 2
WiredHome 0:49245357cd1b 3
WiredHome 0:49245357cd1b 4 #ifndef ICAL_H
WiredHome 0:49245357cd1b 5 #define ICAL_H
WiredHome 0:49245357cd1b 6 #include "mbed.h"
WiredHome 0:49245357cd1b 7
WiredHome 0:49245357cd1b 8 #include "NTPClient.h"
WiredHome 0:49245357cd1b 9
WiredHome 0:49245357cd1b 10 // This defines the total number of events that can be handled - kind of limiting
WiredHome 0:49245357cd1b 11 // but maybe ok for now.
WiredHome 0:49245357cd1b 12 #define EVENT_COUNT 10
WiredHome 0:49245357cd1b 13
WiredHome 0:49245357cd1b 14
WiredHome 0:49245357cd1b 15 // Maximum storage space for each item as free-form text
WiredHome 0:49245357cd1b 16 #define SUMMARY_CHARS 40
WiredHome 0:49245357cd1b 17 #define LOCATION_CHARS 30
WiredHome 0:49245357cd1b 18 #define CATEGORY_CHARS 30
WiredHome 0:49245357cd1b 19
WiredHome 0:49245357cd1b 20 typedef enum {
WiredHome 0:49245357cd1b 21 rptfNone,
WiredHome 0:49245357cd1b 22 rptfDaily,
WiredHome 0:49245357cd1b 23 rptfWeekly,
WiredHome 0:49245357cd1b 24 rptfMonthly,
WiredHome 0:49245357cd1b 25 rptfYearly
WiredHome 0:49245357cd1b 26 } RepeatFreq_t;
WiredHome 0:49245357cd1b 27
WiredHome 0:49245357cd1b 28 #if 0
WiredHome 0:49245357cd1b 29 typedef enum {
WiredHome 0:49245357cd1b 30 Sunday = 0x01,
WiredHome 0:49245357cd1b 31 Monday = 0x02,
WiredHome 0:49245357cd1b 32 Tuesday = 0x04,
WiredHome 0:49245357cd1b 33 Wednesday = 0x08,
WiredHome 0:49245357cd1b 34 Thursday = 0x10,
WiredHome 0:49245357cd1b 35 Friday = 0x20,
WiredHome 0:49245357cd1b 36 Saturday = 0x40
WiredHome 0:49245357cd1b 37 } RepeatDays_t;
WiredHome 0:49245357cd1b 38 #endif
WiredHome 0:49245357cd1b 39
WiredHome 0:49245357cd1b 40 typedef struct {
WiredHome 0:49245357cd1b 41 time_t Start;
WiredHome 0:49245357cd1b 42 time_t End;
WiredHome 0:49245357cd1b 43 time_t Until;
WiredHome 0:49245357cd1b 44 uint16_t Count;
WiredHome 0:49245357cd1b 45 uint16_t Interval;
WiredHome 0:49245357cd1b 46 RepeatFreq_t RepeatFreq;
WiredHome 0:49245357cd1b 47 uint8_t RepeatDays; // bit mapped (bit 0 = sunday, bit 1=monday, ...
WiredHome 0:49245357cd1b 48 char Summary[SUMMARY_CHARS];
WiredHome 0:49245357cd1b 49 char Location[LOCATION_CHARS];
WiredHome 0:49245357cd1b 50 char Category[CATEGORY_CHARS]; // "Green", ...
WiredHome 0:49245357cd1b 51 int Priority; // 1 == High, 5 == Normal, 9 == Low
WiredHome 0:49245357cd1b 52 } Event_T;
WiredHome 0:49245357cd1b 53
WiredHome 0:49245357cd1b 54
WiredHome 0:49245357cd1b 55 extern Event_T EventList[EVENT_COUNT];
WiredHome 0:49245357cd1b 56
WiredHome 0:49245357cd1b 57 /// Format a ctime value as a string, without the trailing <cr>
WiredHome 0:49245357cd1b 58 ///
WiredHome 0:49245357cd1b 59 /// This uses the normal ctime function, which appends a <cr>, but
WiredHome 0:49245357cd1b 60 /// it then removes that trailing line ending character. Additionally,
WiredHome 0:49245357cd1b 61 /// this keeps a few local static buffers to return the time string in
WiredHome 0:49245357cd1b 62 /// which permits a printf (for example) to call this api a few times
WiredHome 0:49245357cd1b 63 /// and get the proper representation of each.
WiredHome 0:49245357cd1b 64 ///
WiredHome 0:49245357cd1b 65 /// @param t is a time value;
WiredHome 0:49245357cd1b 66 /// @returns a pointer to a static buffer containing the converted time.
WiredHome 0:49245357cd1b 67 ///
WiredHome 0:49245357cd1b 68 char * FormatCTime(time_t t);
WiredHome 0:49245357cd1b 69
WiredHome 0:49245357cd1b 70 /// Sort the Events that have been extracted from the iCal results.
WiredHome 0:49245357cd1b 71 ///
WiredHome 0:49245357cd1b 72 void SortEvents();
WiredHome 0:49245357cd1b 73
WiredHome 0:49245357cd1b 74 /// Show the details for a specific Event, on the specified serial stream.
WiredHome 0:49245357cd1b 75 ///
WiredHome 0:49245357cd1b 76 /// Most usefor during development, and perhaps no value after that.
WiredHome 0:49245357cd1b 77 ///
WiredHome 0:49245357cd1b 78 /// @param Event is the event of interest.
WiredHome 0:49245357cd1b 79 ///
WiredHome 0:49245357cd1b 80 void ShowEventInfo(Event_T & Event);
WiredHome 0:49245357cd1b 81
WiredHome 0:49245357cd1b 82 /// Access the 2-letter abbreviation for the day of the week.
WiredHome 0:49245357cd1b 83 ///
WiredHome 0:49245357cd1b 84 /// @param i is the day of the week, where 0 = sunday
WiredHome 0:49245357cd1b 85 /// @returns a pointer to the 2-letter abbreviation.
WiredHome 0:49245357cd1b 86 ///
WiredHome 0:49245357cd1b 87 const char * RepeatDayAbbrev(int i);
WiredHome 0:49245357cd1b 88
WiredHome 0:49245357cd1b 89 /// Get the number of events that have been cached.
WiredHome 0:49245357cd1b 90 ///
WiredHome 0:49245357cd1b 91 /// @returns the number of events.
WiredHome 0:49245357cd1b 92 ///
WiredHome 0:49245357cd1b 93 int GetNumEvents(void);
WiredHome 0:49245357cd1b 94
WiredHome 0:49245357cd1b 95 /// Parse a Datestamp string into a time value.
WiredHome 0:49245357cd1b 96 ///
WiredHome 0:49245357cd1b 97 /// Parses a string which can look like this: 20140505T200000
WiredHome 0:49245357cd1b 98 /// into a time_t value.
WiredHome 0:49245357cd1b 99 ///
WiredHome 0:49245357cd1b 100 /// @param string is the string to parse.
WiredHome 0:49245357cd1b 101 /// @param ntp is a reference to an NTPClient object, in order
WiredHome 0:49245357cd1b 102 /// to get the time-zone offset.
WiredHome 0:49245357cd1b 103 /// @returns time_t value.
WiredHome 0:49245357cd1b 104 ///
WiredHome 0:49245357cd1b 105 time_t ParseDateStamp(char * string, NTPClient & ntp);
WiredHome 0:49245357cd1b 106
WiredHome 0:49245357cd1b 107 /// Parse an iCal stream, and extract everything useful.
WiredHome 0:49245357cd1b 108 ///
WiredHome 0:49245357cd1b 109 /// This accepts a pointer to a [large] buffer, which is the contents
WiredHome 0:49245357cd1b 110 /// of an iCal stream. It walked through all of the available
WiredHome 0:49245357cd1b 111 /// information to extract the Event list.
WiredHome 0:49245357cd1b 112 ///
WiredHome 0:49245357cd1b 113 /// @param pStart is a pointer to the start of the stream.
WiredHome 0:49245357cd1b 114 /// @param gridStartTime is a time value representing the start of the time-window of interest.
WiredHome 0:49245357cd1b 115 /// This permits
WiredHome 0:49245357cd1b 116 /// @param gridEndTime is a time value representing the end of the time-window of interest.
WiredHome 0:49245357cd1b 117 /// @param ntp is a reference to an NTPClient object, in order
WiredHome 0:49245357cd1b 118 /// to get the time-zone offset.
WiredHome 0:49245357cd1b 119 ///
WiredHome 0:49245357cd1b 120 void ParseICalStream(char * pStart, time_t gridStartTime, time_t gridEndTime, NTPClient & ntp);
WiredHome 0:49245357cd1b 121
WiredHome 0:49245357cd1b 122 /// Compute the intersection of two time ranges, and returns that intersection.
WiredHome 0:49245357cd1b 123 ///
WiredHome 0:49245357cd1b 124 /// This compares a pair of time ranges, each by a start and end time. If they overlap
WiredHome 0:49245357cd1b 125 /// it then computes the intersection of those two ranges.
WiredHome 0:49245357cd1b 126 ///
WiredHome 0:49245357cd1b 127 /// @param start1 is the starting time of range 1.
WiredHome 0:49245357cd1b 128 /// @param end1 is the ending time of range 1.
WiredHome 0:49245357cd1b 129 /// @param start2 is the starting time of range 2.
WiredHome 0:49245357cd1b 130 /// @param end2 is the ending time of range 2.
WiredHome 0:49245357cd1b 131 /// @returns true if the ranges overlap, and then start1 and end1 are set to the
WiredHome 0:49245357cd1b 132 /// intersection.
WiredHome 0:49245357cd1b 133 ///
WiredHome 0:49245357cd1b 134 bool TimeIntersects(time_t * start1, time_t * end1, time_t * start2, time_t * end2);
WiredHome 0:49245357cd1b 135
WiredHome 0:49245357cd1b 136 /// Computes the next interval for iCal events that have recurrence.
WiredHome 0:49245357cd1b 137 ///
WiredHome 0:49245357cd1b 138 /// @param repeatFreq is a value representing the frequency of recurrence -
WiredHome 0:49245357cd1b 139 /// 0=none, 1=daily, 2=weekly, 3=monthly, 4=yearly
WiredHome 0:49245357cd1b 140 /// @param interval is the multiplier of that repeat frequency to the next
WiredHome 0:49245357cd1b 141 /// event.
WiredHome 0:49245357cd1b 142 /// @returns a time_t value which is the incremental interval, and would be added
WiredHome 0:49245357cd1b 143 /// to a reference time.
WiredHome 0:49245357cd1b 144 ///
WiredHome 0:49245357cd1b 145 time_t NextInterval(int repeatFreq, int interval);
WiredHome 0:49245357cd1b 146
WiredHome 0:49245357cd1b 147 /// Compute the intersection of two time ranges, and evaluate the recurringing events.
WiredHome 0:49245357cd1b 148 ///
WiredHome 0:49245357cd1b 149 /// This compares a pair of time ranges, each by a start and end time. If they overlap
WiredHome 0:49245357cd1b 150 /// it then computes the intersection of those two ranges. Additionally, for a
WiredHome 0:49245357cd1b 151 /// specified Event, it will evaluate the recurring events that may also fall into
WiredHome 0:49245357cd1b 152 /// the target time range.
WiredHome 0:49245357cd1b 153 ///
WiredHome 0:49245357cd1b 154 /// @param start1 is the starting time of range 1.
WiredHome 0:49245357cd1b 155 /// @param end1 is the ending time of range 1.
WiredHome 0:49245357cd1b 156 /// @param start2 is the starting time of range 2.
WiredHome 0:49245357cd1b 157 /// @param end2 is the ending time of range 2.
WiredHome 0:49245357cd1b 158 /// @param Event is the event of interest that may have recurring series.
WiredHome 0:49245357cd1b 159 /// @returns true if the ranges overlap, and then start1 and end1 are set to the
WiredHome 0:49245357cd1b 160 /// intersection.
WiredHome 0:49245357cd1b 161 ///
WiredHome 0:49245357cd1b 162 bool RepeatIntersects(time_t * start1, time_t * end1, time_t * start2, time_t * end2, Event_T & Event);
WiredHome 0:49245357cd1b 163
WiredHome 0:49245357cd1b 164 #endif // ICAL_H