1 /* 2 * Copyright (c) 2024, 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 an offset range. 32 */ 33 34 #ifndef OFFSET_RANGE_HPP_ 35 #define OFFSET_RANGE_HPP_ 36 37 #include "openthread-core-config.h" 38 39 #include <stdbool.h> 40 #include <stdint.h> 41 42 #include "common/clearable.hpp" 43 44 namespace ot { 45 46 class Message; 47 48 /** 49 * Represents an offset range. 50 * 51 */ 52 class OffsetRange : public Clearable<OffsetRange> 53 { 54 public: 55 /** 56 * Initializes the `OffsetRange`. 57 * 58 * @param[in] aOffset The start offset. 59 * @param[in] aLength The range length (number of bytes). 60 * 61 */ 62 void Init(uint16_t aOffset, uint16_t aLength); 63 64 /** 65 * Initializes the `OffsetRange` from given start and end offsets. 66 * 67 * The range is inclusive of the start offset (@p aStartOffset) but exclusive of the end offset (@p aEndOffset). 68 * 69 * @param[in] aStartOffset The start offset (inclusive). 70 * @param[in] aEndOffset The end offset (exclusive). 71 * 72 */ 73 void InitFromRange(uint16_t aStartOffset, uint16_t aEndOffset); 74 75 /** 76 * Initializes the `OffsetRange` from a given `Message` from its offset to the message end. 77 * 78 * The start offset of the range is set to `aMessage.GetOffset()`, and the end offset is set to include all bytes 79 * in the message up to its current length `aMessage.GetLength()`. 80 * 81 * @param[in] aMessage The `Message` to initialize the `OffsetRange` from. 82 * 83 */ 84 void InitFromMessageOffsetToEnd(const Message &aMessage); 85 86 /** 87 * Initializes the `OffsetRange` from a given `Message` from zero offset up to to its full length. 88 * 89 * The start offset of the range is set to zero, and the end offset is set to include full length of @p aMessage. 90 * 91 * @param[in] aMessage The `Message` to initialize the `OffsetRange` from. 92 * 93 */ 94 void InitFromMessageFullLength(const Message &aMessage); 95 96 /** 97 * Gets the start offset of the `OffsetRange` 98 * 99 * @returns The start offset. 100 * 101 */ GetOffset(void) const102 uint16_t GetOffset(void) const { return mOffset; } 103 104 /** 105 * Gets the end offset of the `OffsetRange`. 106 * 107 * This offset is exclusive, meaning it marks the position immediately after the last byte within the range. 108 * 109 * @returns The end offset. 110 * 111 */ GetEndOffset(void) const112 uint16_t GetEndOffset(void) const { return (mOffset + mLength); } 113 114 /** 115 * Gets the `OffsetRange` length. 116 * 117 * @returns The length of the `OffsetRange` in bytes. 118 * 119 */ GetLength(void) const120 uint16_t GetLength(void) const { return mLength; } 121 122 /** 123 * Indicates whether or not the `OffsetRange` is empty. 124 * 125 * @retval TRUE The `OffsetRange` is empty. 126 * @retval FALSE The `OffsetRange` is not empty (contains at least one byte). 127 * 128 */ IsEmpty(void) const129 bool IsEmpty(void) const { return (mLength == 0); } 130 131 /** 132 * Indicates whether or not the `OffsetRange` contains a given number of bytes. 133 * 134 * @param[in] aLength The length to check. 135 * 136 * @retval TRUE The `OffsetRange` contains @p aLength or more bytes. 137 * @retval FALSE The `OffsetRange` does not contain @p aLength bytes. 138 * 139 */ Contains(uint32_t aLength) const140 bool Contains(uint32_t aLength) const { return aLength <= mLength; } 141 142 /** 143 * Advances the start offset forward by the given number of bytes. 144 * 145 * This method ensures the start offset does not go beyond the end offset of the `OffsetRange`. If @p aLength is 146 * greater than the available bytes in the `OffsetRange`, the start offset is adjusted to the end offset, 147 * effectively shrinking the range to zero length. 148 * 149 * @param[in] aLength The number of bytes to advance the start offset. 150 * 151 */ 152 void AdvanceOffset(uint32_t aLength); 153 154 /** 155 * Shrinks the `OffsetRange` length to a given length. 156 * 157 * If the current length of the `OffsetRange` is longer than @p aLength, the offset range is shortened to 158 * @p aLength. If the range is already shorter or the same, it remains unchanged. 159 * 160 * @param[in] aLength The new length to use. 161 * 162 */ 163 void ShrinkLength(uint16_t aLength); 164 165 private: 166 uint16_t mOffset; 167 uint16_t mLength; 168 }; 169 170 } // namespace ot 171 172 #endif // OFFSET_RANGE_HPP_ 173
