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