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 35 #ifndef MESHCOP_TIMESTAMP_HPP_ 36 #define MESHCOP_TIMESTAMP_HPP_ 37 38 #include "openthread-core-config.h" 39 40 #include <string.h> 41 42 #include <openthread/dataset.h> 43 #include <openthread/platform/toolchain.h> 44 45 #include "common/clearable.hpp" 46 #include "common/encoding.hpp" 47 #include "common/random.hpp" 48 49 namespace ot { 50 namespace MeshCoP { 51 52 /** 53 * Implements Timestamp generation and parsing. 54 * 55 */ 56 OT_TOOL_PACKED_BEGIN 57 class Timestamp : public Clearable<Timestamp> 58 { 59 public: 60 /** 61 * Represents timestamp components. 62 * 63 */ 64 typedef otTimestamp Info; 65 66 /** 67 * Copies the `Timestamp` information to `Timestamp::Info` data structure. 68 * 69 * @param[out] aInfo A reference to a `Timestamp::Info` to populate. 70 * 71 */ 72 void ConvertTo(Info &aInfo) const; 73 74 /** 75 * Sets the `Timestamp` from a given component-wise `Info` structure. 76 * 77 * @param[in] aInfo A `Timestamp::Info` structure. 78 * 79 */ 80 void SetFrom(const Info &aInfo); 81 82 /** 83 * Sets the `Timestamp` to invalid value. 84 * 85 */ 86 void SetToInvalid(void); 87 88 /** 89 * Indicates whether or not the `Timestamp` is valid. 90 * 91 * @retval TRUE The timestamp is valid. 92 * @retval FALSE The timestamp is not valid. 93 * 94 */ 95 bool IsValid(void) const; 96 97 /** 98 * Sets the `Timestamp` to value used in MLE Orphan Announce messages. 99 * 100 * Second and ticks fields are set to zero with Authoritative flag set. 101 * 102 */ 103 void SetToOrphanAnnounce(void); 104 105 /** 106 * Indicates whether the timestamp indicates an MLE Orphan Announce message. 107 * 108 * @retval TRUE The timestamp indicates an Orphan Announce message. 109 * @retval FALSE The timestamp does not indicate an Orphan Announce message. 110 * 111 */ 112 bool IsOrphanAnnounce(void) const; 113 114 /** 115 * Returns the Seconds value. 116 * 117 * @returns The Seconds value. 118 * 119 */ 120 uint64_t GetSeconds(void) const; 121 122 /** 123 * Sets the Seconds value. 124 * 125 * @param[in] aSeconds The Seconds value. 126 * 127 */ 128 void SetSeconds(uint64_t aSeconds); 129 130 /** 131 * Returns the Ticks value. 132 * 133 * @returns The Ticks value. 134 * 135 */ GetTicks(void) const136 uint16_t GetTicks(void) const { return GetTicksAndAuthFlag() >> kTicksOffset; } 137 138 /** 139 * Sets the Ticks value. 140 * 141 * @param[in] aTicks The Ticks value. 142 * 143 */ 144 void SetTicks(uint16_t aTicks); 145 146 /** 147 * Returns the Authoritative value. 148 * 149 * @returns The Authoritative value. 150 * 151 */ GetAuthoritative(void) const152 bool GetAuthoritative(void) const { return (GetTicksAndAuthFlag() & kAuthoritativeFlag) != 0; } 153 154 /** 155 * Sets the Authoritative value. 156 * 157 * @param[in] aAuthoritative The Authoritative value. 158 * 159 */ 160 void SetAuthoritative(bool aAuthoritative); 161 162 /** 163 * Increments the timestamp by a random number of ticks [0, 32767]. 164 * 165 */ 166 void AdvanceRandomTicks(void); 167 168 /** 169 * Compares two timestamps. 170 * 171 * Either one or both @p aFirst or @p aSecond can be invalid. A valid timestamp is considered greater than an 172 * invalid one. If both are invalid, they are considered as equal. 173 * 174 * @param[in] aFirst A reference to the first timestamp to compare. 175 * @param[in] aSecond A reference to the second timestamp to compare. 176 * 177 * @retval -1 if @p aFirst is less than @p aSecond (`aFirst < aSecond`). 178 * @retval 0 if @p aFirst is equal to @p aSecond (`aFirst == aSecond`). 179 * @retval 1 if @p aFirst is greater than @p aSecond (`aFirst > aSecond`). 180 * 181 */ 182 static int Compare(const Timestamp &aFirst, const Timestamp &aSecond); 183 184 // Comparison operator overloads for two `Timestamp` instances. operator ==(const Timestamp & aOther) const185 bool operator==(const Timestamp &aOther) const { return Compare(*this, aOther) == 0; } operator !=(const Timestamp & aOther) const186 bool operator!=(const Timestamp &aOther) const { return Compare(*this, aOther) != 0; } operator >(const Timestamp & aOther) const187 bool operator>(const Timestamp &aOther) const { return Compare(*this, aOther) > 0; } operator <(const Timestamp & aOther) const188 bool operator<(const Timestamp &aOther) const { return Compare(*this, aOther) < 0; } operator >=(const Timestamp & aOther) const189 bool operator>=(const Timestamp &aOther) const { return Compare(*this, aOther) >= 0; } operator <=(const Timestamp & aOther) const190 bool operator<=(const Timestamp &aOther) const { return Compare(*this, aOther) <= 0; } 191 192 private: GetTicksAndAuthFlag(void) const193 uint16_t GetTicksAndAuthFlag(void) const { return BigEndian::HostSwap16(mTicksAndAuthFlag); } SetTicksAndAuthFlag(uint16_t aValue)194 void SetTicksAndAuthFlag(uint16_t aValue) { mTicksAndAuthFlag = BigEndian::HostSwap16(aValue); } 195 196 static constexpr uint8_t kTicksOffset = 1; 197 static constexpr uint16_t kTicksMask = 0x7fff << kTicksOffset; 198 static constexpr uint8_t kAuthoritativeOffset = 0; 199 static constexpr uint16_t kAuthoritativeFlag = 1 << kAuthoritativeOffset; 200 static constexpr uint16_t kMaxTicks = 0x7fff; 201 202 uint16_t mSeconds16; // bits 32-47 203 uint32_t mSeconds32; // bits 0-31 204 uint16_t mTicksAndAuthFlag; 205 } OT_TOOL_PACKED_END; 206 207 } // namespace MeshCoP 208 } // namespace ot 209 210 #endif // MESHCOP_TIMESTAMP_HPP_ 211