src/app/util/time-util.h

   1 /**
   2  *
   3  *    Copyright (c) 2020 Project CHIP Authors
   4  *
   5  *    Licensed under the Apache License, Version 2.0 (the "License");
   6  *    you may not use this file except in compliance with the License.
   7  *    You may obtain a copy of the License at
   8  *
   9  *        http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  *    Unless required by applicable law or agreed to in writing, software
  12  *    distributed under the License is distributed on an "AS IS" BASIS,
  13  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  *    See the License for the specific language governing permissions and
  15  *    limitations under the License.
  16  */
  17
  18 /**
  19  *
  20  *    Copyright (c) 2020 Silicon Labs
  21  *
  22  *    Licensed under the Apache License, Version 2.0 (the "License");
  23  *    you may not use this file except in compliance with the License.
  24  *    You may obtain a copy of the License at
  25  *
  26  *        http://www.apache.org/licenses/LICENSE-2.0
  27  *
  28  *    Unless required by applicable law or agreed to in writing, software
  29  *    distributed under the License is distributed on an "AS IS" BASIS,
  30  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  31  *    See the License for the specific language governing permissions and
  32  *    limitations under the License.
  33  */
  34 /***************************************************************************/
  35 /**
  36  * @file
  37  * @brief
  38  *******************************************************************************
  39  ******************************************************************************/
  40
  41 #pragma once
  42
  43 #define SECONDS_IN_MINUTE 60
  44 #define SECONDS_IN_HOUR 3600
  45 #define SECONDS_IN_DAY (SECONDS_IN_MINUTE * 60 * 24)
  46 #define SECONDS_IN_WEEK (SECONDS_IN_DAY * 7)
  47 #define DURATION_FOREVER_U32 0xFFFFFFFFU
  48
  49 /**
  50  * @brief ZCL Date comparison function.
  51  * The results are undefined for dates that contain the do not care value
  52  * in any of the subfields.
  53  * @return -1, if val1 is smaller
  54  *          0, if they are the same
  55  *          1, if val2 is smaller
  56  */
  57 int8_t emberAfCompareDates(EmberAfDate * date1, EmberAfDate * date2);
  58
  59 /**
  60  * @brief function that copies a ZigBee Date into a buffer
  61  */
  62 void emberAfCopyDate(uint8_t * data, uint16_t index, EmberAfDate * src);
  63
  64 /**
  65  * @brief Decode the given uint32_t into a ZCL Date object where
  66  * the uint32_t is formatted as follows:
  67  *
  68  * (0xFF000000 & value) = year
  69  * (0x00FF0000 & value) = month
  70  * (0x0000FF00 & value) = day of month
  71  * (0x000000FF & value) = day of week
  72  *
  73  */
  74 void emberAfDecodeDate(uint32_t src, EmberAfDate * dest);
  75
  76 /**
  77  * @brief Encode and return the given ZCL Date object as an uint32_t.
  78  * Refer to emberAFDecodeDate for details on how the information is stored
  79  * within an uint32_t.
  80  */
  81 uint32_t emberAfEncodeDate(EmberAfDate * date);
  82
  83 /**
  84  * @brief Fills the a time structure based on the passed UTC time.
  85  *
  86  */
  87 void emberAfFillTimeStructFromUtc(uint32_t utcTime, EmberAfTimeStruct * returnTime);
  88 /**
  89  * @brief Returns the number of days in the month specified in the EmberAfTimeStruct.
  90  *
  91  */
  92 uint8_t emberAfGetNumberDaysInMonth(EmberAfTimeStruct * time);
  93
  94 /**
  95  * @brief Calculate a UTC time from the passed time structure.
  96  *
  97  */
  98 uint32_t emberAfGetUtcFromTimeStruct(EmberAfTimeStruct * time);
  99
 100 /**
 101  * @brief Determine the week day (Monday=0 ... Sunday=6) based on
 102  * a specified UTC time.
 103  */
 104 uint8_t emberAfGetWeekdayFromUtc(uint32_t utcTime);
 105
 106 /*
 107  * @brief Prints out a human readable date form from the given ZCL data type.
 108  */
 109 void emberAfPrintDate(const EmberAfDate * date);
 110 void emberAfPrintDateln(const EmberAfDate * date);
 111
 112 /**
 113  * @brief Sets current time.
 114  * Convenience function for setting the time to a value.
 115  * If the time server cluster is implemented on this device,
 116  * then this call will be passed along to the time cluster server
 117  * which will update the time. Otherwise the emberAfSetTimeCallback
 118  * is called, which in the case of the stub does nothing.
 119  *
 120  * @param utcTime: A ZigBee time, the number of seconds since the
 121  *                 year 2000.
 122  */
 123 void emberAfSetTime(uint32_t utcTime);
 124
 125 /**
 126  * @brief Retrieves current time.
 127  *
 128  * Convienience function for retrieving the current time.
 129  * If the time server cluster is implemented, then the time
 130  * is retrieved from that cluster's time attribute. Otherwise,
 131  * the emberAfGetCurrentTimeCallback is called.
 132  *
 133  * A real time is expected to in the ZigBee time format, the number
 134  * of seconds since the year 2000.
 135  */
 136 uint32_t emberAfGetCurrentTime(void);
 137
 138 /**
 139  * @brief Prints time.
 140  *
 141  * Convenience function for all clusters to print time.
 142  * This function expects to be passed a ZigBee time which
 143  * is the number of seconds since the year 2000. If
 144  * EMBER_AF_PRINT_CORE is defined, this function will print
 145  * a human readable time from the passed value. If not, this
 146  * function will print nothing.
 147  *
 148  * @param utcTime: A ZigBee time, the number of seconds since the
 149  *                 year 2000.
 150  */
 151 void emberAfPrintTime(uint32_t utcTime);
 152
 153 /**
 154  * @brief Prints the time in ISO 8601 format
 155  * yyyy-mm-dd hh:mm:ss
 156  *
 157  * @param utcTime: A ZigBee time, the number of seconds since the
 158  *                 year 2000.
 159  */
 160 void emberAfPrintTimeIsoFormat(uint32_t utcTime);