resource/csdk/security/include/iotvticalendar.h

   1 //******************************************************************
   2 //
   3 // Copyright 2015 Intel Mobile Communications GmbH All Rights Reserved.
   4 //
   5 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
   6 //
   7 // Licensed under the Apache License, Version 2.0 (the "License");
   8 // you may not use this file except in compliance with the License.
   9 // You may obtain a copy of the License at
  10 //
  11 //      http://www.apache.org/licenses/LICENSE-2.0
  12 //
  13 // Unless required by applicable law or agreed to in writing, software
  14 // distributed under the License is distributed on an "AS IS" BASIS,
  15 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16 // See the License for the specific language governing permissions and
  17 // limitations under the License.
  18 //
  19 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  20
  21 #ifndef IOTVT_ICALENDAR_H
  22 #define IOTVT_ICALENDAR_H
  23
  24 //Not supported on Arduino due lack of absolute time need to implement iCalendar
  25 #ifndef WITH_ARDUINO
  26
  27 #include <stdint.h> // for uint8_t typedef
  28 #include <stdbool.h>
  29 #include <time.h>
  30
  31 #ifdef __cplusplus
  32 extern "C"
  33 {
  34 #endif
  35
  36 #define FREQ_DAILY (1)
  37 #define MAX_BYDAY_SIZE (7)     //7 days of week
  38 #define TM_YEAR_OFFSET (1900)  //tm_year field of c-lang tm date-time struct
  39                                //represents number of years since 1900.
  40 #define TM_DST_OFFSET (1)      //c-lang tm struct Daylight Saving Time offset.
  41 #define TOTAL_HOURS (24)       //Total hours in a day.
  42
  43 typedef struct IotvtICalRecur IotvtICalRecur_t;
  44 typedef struct IotvtICalPeriod IotvtICalPeriod_t;
  45
  46 /**
  47  *  date-time  = date "T" time.
  48  *
  49  *  date               = date-value
  50  *  date-value         = date-fullyear date-month date-mday
  51  *  date-fullyear      = 4DIGIT
  52  *  date-month         = 2DIGIT        ;01-12
  53  *  date-mday          = 2DIGIT        ;01-28, 01-29, 01-30, 01-31
  54  *                                     ;based on month/year
  55  *
  56  *  time               = time-hour time-minute time-second [time-utc]
  57  *  time-hour          = 2DIGIT        ;00-23
  58  *  time-minute        = 2DIGIT        ;00-59
  59  *  time-second        = 2DIGIT        ;00-60
  60  *                                     ;The "60" value is used to account for "leap" seconds.
  61  *
  62  *  Date-Time Forms:
  63  *  1. Date with Local time
  64  *      20150626T150000
  65  */
  66 typedef struct tm IotvtICalDateTime_t; //c-lang tm date-time struct
  67
  68 /**
  69  * Bit mask for weekdays.
  70  */
  71 typedef enum
  72 {
  73     NO_WEEKDAY  = 0X0,
  74     SUNDAY      = (0x1 << 0),
  75     MONDAY      = (0x1 << 1),
  76     TUESDAY     = (0x1 << 2),
  77     WEDNESDAY   = (0x1 << 3),
  78     THURSDAY    = (0x1 << 4),
  79     FRIDAY      = (0x1 << 5),
  80     SATURDAY    = (0x1 << 6)
  81 } IotvtICalWeekdayBM_t;
  82
  83 /**
  84  * Result code for IotvtICalendar.
  85  */
  86 typedef enum
  87 {
  88     IOTVTICAL_SUCCESS = 0,       /**< successfully completed operation. */
  89     IOTVTICAL_VALID_ACCESS,      /**< access is within allowable time. */
  90     IOTVTICAL_INVALID_ACCESS,    /**< access is not within allowable time. */
  91     IOTVTICAL_INVALID_PARAMETER, /**< invalid method parameter. */
  92     IOTVTICAL_INVALID_RRULE,     /**< rrule is not well form, missing FREQ. */
  93     IOTVTICAL_INVALID_PERIOD,    /**< period is not well form, start-datetime is after end-datetime. */
  94     IOTVTICAL_ERROR              /**< encounter error. */
  95 } IotvtICalResult_t;
  96
  97 /**
  98  *  Grammar for iCalendar data type PERIOD.
  99  *
 100  *  period = date-time "/" date-time  ; start-time / end-time.
 101  *                                    ;The start-time MUST be before the end-time.
 102  *
 103  */
 104 struct IotvtICalPeriod
 105 {
 106     IotvtICalDateTime_t startDateTime;
 107     IotvtICalDateTime_t endDateTime;
 108 };
 109
 110 /*
 111  * Grammar for iCalendar data type RECUR.
 112  *
 113  * recur      = "FREQ"=freq *(
 114  *            ( ";" "UNTIL" "=" enddate ) /
 115  *            ( ";" "BYDAY" "=" bywdaylist ) /
 116  *            )
 117  *
 118  * freq       = "DAILY"
 119  * enddate    = date
 120  * bywdaylist = weekday/ ( weekday *("," weekday) )
 121  * weekday    = "SU" / "MO" / "TU" / "WE" / "TH" / "FR" / "SA"
 122  *
 123  * Example:
 124  * 1."Allow access on every Monday, Wednesday & Friday between 3pm to 5pm"
 125  *      PERIOD:20150626T150000/20150626T170000
 126  *      RRULE: FREQ=DAILY; BYDAY=MO, WE, FR
 127  * 2."Allow access every Monday, Wednesday & Friday from 3pm to 5pm until
 128  *    July 3rd, 2015"
 129  *      PERIOD:20150626T150000/20150626T170000
 130  *      RRULE: FREQ=DAILY; UNTIL=20150703; BYDAY=MO, WE, FR
 131  */
 132 struct IotvtICalRecur
 133 {
 134     uint16_t                freq;
 135     IotvtICalDateTime_t     until;
 136     IotvtICalWeekdayBM_t    byDay;
 137 };
 138
 139 /**
 140  * This API is used by policy engine to checks if the
 141  * request to access resource is within valid time.
 142  *
 143  * @param period string representing period.
 144  * @param recur string representing recurrence rule
 145  *
 146  * @return ::IOTVTICAL_VALID_ACCESS, if the request is within valid time period
 147  * ::IOTVTICAL_INVALID_ACCESS, if the request is not within valid time period
 148  * ::IOTVTICAL_INVALID_PARAMETER, if parameter are invalid
 149  * ::IOTVTICAL_INVALID_PERIOD, if period string has invalid format
 150  * ::IOTVTICAL_INVALID_RRULE, if rrule string has invalid format.
 151  *
 152  *Eg: if(IOTVTICAL_VALID_ACCESS == IsRequestWithinValidTime(period, recur))
 153  *    {
 154  *       //Access within allowable time
 155  *    }
 156  *    else
 157  *    {
 158  *      //Access is not within allowable time.
 159  *    }
 160  */
 161 IotvtICalResult_t IsRequestWithinValidTime(const char *period, const char *recur);
 162
 163 /**
 164  * Parses periodStr and populate struct IotvtICalPeriod_t.
 165  *
 166  * @param periodStr string to be parsed.
 167  * @param period IotvtICalPeriod_t struct to be populated.
 168  *
 169  * @return ::IOTVTICAL_VALID_ACCESS, if the request is within valid time period
 170  * ::IOTVTICAL_INVALID_PARAMETER, if parameter are invalid
 171  * ::IOTVTICAL_INVALID_PERIOD, if period string has invalid format
 172  * ::IOTVTICAL_INVALID_SUCCESS, if no error while parsing.
 173  */
 174 IotvtICalResult_t ParsePeriod(const char *periodStr, IotvtICalPeriod_t *period);
 175
 176 /**
 177  * Parses recurStr and populate struct IotvtICalRecur_t.
 178  *
 179  * @param recurStr string to be parsed.
 180  * @param recur is the IotvtICalPeriod_t struct to be populated.
 181  *
 182  * @return ::IOTVTICAL_VALID_ACCESS, if the request is within valid time period
 183  * ::IOTVTICAL_INVALID_PARAMETER, if parameter are invalid
 184  * ::IOTVTICAL_INVALID_PERIOD, if period string has invalid format
 185  * ::IOTVTICAL_INVALID_RRULE, if rrule string has invalid format.
 186  */
 187 IotvtICalResult_t ParseRecur(const char *recurStr, IotvtICalRecur_t *recur);
 188
 189 #ifdef __cplusplus
 190 }
 191 #endif
 192 #endif
 193 #endif //IOTVT_ICALENDAR_H