1 /* 2 * Copyright (c) 2016, The OpenThread Authors. 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions are met: 7 * 1. Redistributions of source code must retain the above copyright 8 * notice, this list of conditions and the following disclaimer. 9 * 2. Redistributions in binary form must reproduce the above copyright 10 * notice, this list of conditions and the following disclaimer in the 11 * documentation and/or other materials provided with the distribution. 12 * 3. Neither the name of the copyright holder nor the 13 * names of its contributors may be used to endorse or promote products 14 * derived from this software without specific prior written permission. 15 * 16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 26 * POSSIBILITY OF SUCH DAMAGE. 27 */ 28 29 /** 30 * @file 31 * This file includes definitions for manipulating MeshCoP timestamps. 32 */ 33 34 #ifndef MESHCOP_TIMESTAMP_HPP_ 35 #define MESHCOP_TIMESTAMP_HPP_ 36 37 #include "openthread-core-config.h" 38 39 #include <string.h> 40 41 #include <openthread/dataset.h> 42 #include <openthread/platform/toolchain.h> 43 44 #include "common/clearable.hpp" 45 #include "common/encoding.hpp" 46 #include "common/random.hpp" 47 48 namespace ot { 49 namespace MeshCoP { 50 51 /** 52 * Implements Timestamp generation and parsing. 53 */ 54 OT_TOOL_PACKED_BEGIN 55 class Timestamp : public Clearable<Timestamp> 56 { 57 public: 58 /** 59 * Represents timestamp components. 60 */ 61 typedef otTimestamp Info; 62 63 /** 64 * Copies the `Timestamp` information to `Timestamp::Info` data structure. 65 * 66 * @param[out] aInfo A reference to a `Timestamp::Info` to populate. 67 */ 68 void ConvertTo(Info &aInfo) const; 69 70 /** 71 * Sets the `Timestamp` from a given component-wise `Info` structure. 72 * 73 * @param[in] aInfo A `Timestamp::Info` structure. 74 */ 75 void SetFrom(const Info &aInfo); 76 77 /** 78 * Sets the `Timestamp` to invalid value. 79 */ 80 void SetToInvalid(void); 81 82 /** 83 * Indicates whether or not the `Timestamp` is valid. 84 * 85 * @retval TRUE The timestamp is valid. 86 * @retval FALSE The timestamp is not valid. 87 */ 88 bool IsValid(void) const; 89 90 /** 91 * Sets the `Timestamp` to value used in MLE Orphan Announce messages. 92 * 93 * Second and ticks fields are set to zero with Authoritative flag set. 94 */ 95 void SetToOrphanAnnounce(void); 96 97 /** 98 * Indicates whether the timestamp indicates an MLE Orphan Announce message. 99 * 100 * @retval TRUE The timestamp indicates an Orphan Announce message. 101 * @retval FALSE The timestamp does not indicate an Orphan Announce message. 102 */ 103 bool IsOrphanAnnounce(void) const; 104 105 /** 106 * Returns the Seconds value. 107 * 108 * @returns The Seconds value. 109 */ 110 uint64_t GetSeconds(void) const; 111 112 /** 113 * Sets the Seconds value. 114 * 115 * @param[in] aSeconds The Seconds value. 116 */ 117 void SetSeconds(uint64_t aSeconds); 118 119 /** 120 * Returns the Ticks value. 121 * 122 * @returns The Ticks value. 123 */ GetTicks(void) const124 uint16_t GetTicks(void) const { return GetTicksAndAuthFlag() >> kTicksOffset; } 125 126 /** 127 * Sets the Ticks value. 128 * 129 * @param[in] aTicks The Ticks value. 130 */ 131 void SetTicks(uint16_t aTicks); 132 133 /** 134 * Returns the Authoritative value. 135 * 136 * @returns The Authoritative value. 137 */ GetAuthoritative(void) const138 bool GetAuthoritative(void) const { return (GetTicksAndAuthFlag() & kAuthoritativeFlag) != 0; } 139 140 /** 141 * Sets the Authoritative value. 142 * 143 * @param[in] aAuthoritative The Authoritative value. 144 */ 145 void SetAuthoritative(bool aAuthoritative); 146 147 /** 148 * Increments the timestamp by a random number of ticks [0, 32767]. 149 */ 150 void AdvanceRandomTicks(void); 151 152 /** 153 * Compares two timestamps. 154 * 155 * Either one or both @p aFirst or @p aSecond can be invalid. A valid timestamp is considered greater than an 156 * invalid one. If both are invalid, they are considered as equal. 157 * 158 * @param[in] aFirst A reference to the first timestamp to compare. 159 * @param[in] aSecond A reference to the second timestamp to compare. 160 * 161 * @retval -1 if @p aFirst is less than @p aSecond (`aFirst < aSecond`). 162 * @retval 0 if @p aFirst is equal to @p aSecond (`aFirst == aSecond`). 163 * @retval 1 if @p aFirst is greater than @p aSecond (`aFirst > aSecond`). 164 */ 165 static int Compare(const Timestamp &aFirst, const Timestamp &aSecond); 166 167 // Comparison operator overloads for two `Timestamp` instances. operator ==(const Timestamp & aOther) const168 bool operator==(const Timestamp &aOther) const { return Compare(*this, aOther) == 0; } operator !=(const Timestamp & aOther) const169 bool operator!=(const Timestamp &aOther) const { return Compare(*this, aOther) != 0; } operator >(const Timestamp & aOther) const170 bool operator>(const Timestamp &aOther) const { return Compare(*this, aOther) > 0; } operator <(const Timestamp & aOther) const171 bool operator<(const Timestamp &aOther) const { return Compare(*this, aOther) < 0; } operator >=(const Timestamp & aOther) const172 bool operator>=(const Timestamp &aOther) const { return Compare(*this, aOther) >= 0; } operator <=(const Timestamp & aOther) const173 bool operator<=(const Timestamp &aOther) const { return Compare(*this, aOther) <= 0; } 174 175 private: GetTicksAndAuthFlag(void) const176 uint16_t GetTicksAndAuthFlag(void) const { return BigEndian::HostSwap16(mTicksAndAuthFlag); } SetTicksAndAuthFlag(uint16_t aValue)177 void SetTicksAndAuthFlag(uint16_t aValue) { mTicksAndAuthFlag = BigEndian::HostSwap16(aValue); } 178 179 static constexpr uint8_t kTicksOffset = 1; 180 static constexpr uint16_t kTicksMask = 0x7fff << kTicksOffset; 181 static constexpr uint8_t kAuthoritativeOffset = 0; 182 static constexpr uint16_t kAuthoritativeFlag = 1 << kAuthoritativeOffset; 183 static constexpr uint16_t kMaxTicks = 0x7fff; 184 185 uint16_t mSeconds16; // bits 32-47 186 uint32_t mSeconds32; // bits 0-31 187 uint16_t mTicksAndAuthFlag; 188 } OT_TOOL_PACKED_END; 189 190 } // namespace MeshCoP 191 } // namespace ot 192 193 #endif // MESHCOP_TIMESTAMP_HPP_ 194