David Smart / iCal

an iCal processing library

iCal.h@3:fc5cdc930896, 2014-05-22 (annotated)

Committer:
WiredHome
Date:
Thu May 22 16:10:39 2014 +0000
Revision:
3:fc5cdc930896
Parent:
1:db274b9e40cc
Child:
4:a1c25d936346
Documentation, and work on minor reduction in memory footprint.

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