1 /* 2 * Copyright (c) 2022, 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 managing the Network Name. 32 * 33 */ 34 35 #ifndef MESHCOP_NETWORK_NAME_HPP_ 36 #define MESHCOP_NETWORK_NAME_HPP_ 37 38 #include "openthread-core-config.h" 39 40 #include <openthread/dataset.h> 41 42 #include "common/as_core_type.hpp" 43 #include "common/data.hpp" 44 #include "common/equatable.hpp" 45 #include "common/locator.hpp" 46 #include "common/non_copyable.hpp" 47 #include "common/string.hpp" 48 49 namespace ot { 50 namespace MeshCoP { 51 52 /** 53 * This class represents a name string as data (pointer to a char buffer along with a length). 54 * 55 * @note The char array does NOT need to be null terminated. 56 * 57 */ 58 class NameData : private Data<kWithUint8Length> 59 { 60 friend class NetworkName; 61 62 public: 63 /** 64 * This constructor initializes the NameData object. 65 * 66 * @param[in] aBuffer A pointer to a `char` buffer (does not need to be null terminated). 67 * @param[in] aLength The length (number of chars) in the buffer. 68 * 69 */ NameData(const char * aBuffer,uint8_t aLength)70 NameData(const char *aBuffer, uint8_t aLength) { Init(aBuffer, aLength); } 71 72 /** 73 * This method returns the pointer to char buffer (not necessarily null terminated). 74 * 75 * @returns The pointer to the char buffer. 76 * 77 */ GetBuffer(void) const78 const char *GetBuffer(void) const { return reinterpret_cast<const char *>(GetBytes()); } 79 80 /** 81 * This method returns the length (number of chars in buffer). 82 * 83 * @returns The name length. 84 * 85 */ GetLength(void) const86 uint8_t GetLength(void) const { return Data<kWithUint8Length>::GetLength(); } 87 88 /** 89 * This method copies the name data into a given char buffer with a given size. 90 * 91 * The given buffer is cleared (`memset` to zero) before copying the name into it. The copied string 92 * in @p aBuffer is NOT necessarily null terminated. 93 * 94 * @param[out] aBuffer A pointer to a buffer where to copy the name into. 95 * @param[in] aMaxSize Size of @p aBuffer (maximum number of chars to write into @p aBuffer). 96 * 97 * @returns The actual number of chars copied into @p aBuffer. 98 * 99 */ 100 uint8_t CopyTo(char *aBuffer, uint8_t aMaxSize) const; 101 }; 102 103 /** 104 * This structure represents an Network Name. 105 * 106 */ 107 class NetworkName : public otNetworkName, public Unequatable<NetworkName> 108 { 109 public: 110 /** 111 * This constant specified the maximum number of chars in Network Name (excludes null char). 112 * 113 */ 114 static constexpr uint8_t kMaxSize = OT_NETWORK_NAME_MAX_SIZE; 115 116 /** 117 * This constructor initializes the Network Name as an empty string. 118 * 119 */ NetworkName(void)120 NetworkName(void) { m8[0] = '\0'; } 121 122 /** 123 * This method gets the Network Name as a null terminated C string. 124 * 125 * @returns The Network Name as a null terminated C string array. 126 * 127 */ GetAsCString(void) const128 const char *GetAsCString(void) const { return m8; } 129 130 /** 131 * This method gets the Network Name as NameData. 132 * 133 * @returns The Network Name as NameData. 134 * 135 */ 136 NameData GetAsData(void) const; 137 138 /** 139 * This method sets the Network Name from a given null terminated C string. 140 * 141 * This method also validates that the given @p aNameString follows UTF-8 encoding and can fit in `kMaxSize` 142 * chars. 143 * 144 * @param[in] aNameString A name C string. 145 * 146 * @retval kErrorNone Successfully set the Network Name. 147 * @retval kErrorAlready The name is already set to the same string. 148 * @retval kErrorInvalidArgs Given name is invalid (too long or does not follow UTF-8 encoding). 149 * 150 */ 151 Error Set(const char *aNameString); 152 153 /** 154 * This method sets the Network Name. 155 * 156 * @param[in] aNameData A reference to name data. 157 * 158 * @retval kErrorNone Successfully set the Network Name. 159 * @retval kErrorAlready The name is already set to the same string. 160 * @retval kErrorInvalidArgs Given name is too long. 161 * 162 */ 163 Error Set(const NameData &aNameData); 164 165 /** 166 * This method overloads operator `==` to evaluate whether or not two given `NetworkName` objects are equal. 167 * 168 * @param[in] aOther The other `NetworkName` to compare with. 169 * 170 * @retval TRUE If the two are equal. 171 * @retval FALSE If the two are not equal. 172 * 173 */ 174 bool operator==(const NetworkName &aOther) const; 175 }; 176 177 #if (OPENTHREAD_CONFIG_THREAD_VERSION >= OT_THREAD_VERSION_1_2) 178 /** 179 * This type represents a Thread Domain Name. 180 * 181 */ 182 typedef NetworkName DomainName; 183 #endif 184 185 /** 186 * This class manages the Network Name value. 187 * 188 */ 189 class NetworkNameManager : public InstanceLocator, private NonCopyable 190 { 191 public: 192 /** 193 * Constructor. 194 * 195 * @param[in] aInstance A reference to the OpenThread instance. 196 * 197 */ 198 explicit NetworkNameManager(Instance &aInstance); 199 200 /** 201 * This method returns the Network Name. 202 * 203 * @returns The Network Name. 204 * 205 */ GetNetworkName(void) const206 const NetworkName &GetNetworkName(void) const { return mNetworkName; } 207 208 /** 209 * This method sets the Network Name. 210 * 211 * @param[in] aNameString A pointer to a string character array. Must be null terminated. 212 * 213 * @retval kErrorNone Successfully set the Network Name. 214 * @retval kErrorInvalidArgs Given name is too long. 215 * 216 */ 217 Error SetNetworkName(const char *aNameString); 218 219 /** 220 * This method sets the Network Name. 221 * 222 * @param[in] aNameData A name data (pointer to char buffer and length). 223 * 224 * @retval kErrorNone Successfully set the Network Name. 225 * @retval kErrorInvalidArgs Given name is too long. 226 * 227 */ 228 Error SetNetworkName(const NameData &aNameData); 229 230 #if (OPENTHREAD_CONFIG_THREAD_VERSION >= OT_THREAD_VERSION_1_2) 231 /** 232 * This method returns the Thread Domain Name. 233 * 234 * @returns The Thread Domain Name. 235 * 236 */ GetDomainName(void) const237 const DomainName &GetDomainName(void) const { return mDomainName; } 238 239 /** 240 * This method sets the Thread Domain Name. 241 * 242 * @param[in] aNameString A pointer to a string character array. Must be null terminated. 243 * 244 * @retval kErrorNone Successfully set the Thread Domain Name. 245 * @retval kErrorInvalidArgs Given name is too long. 246 * 247 */ 248 Error SetDomainName(const char *aNameString); 249 250 /** 251 * This method sets the Thread Domain Name. 252 * 253 * @param[in] aNameData A name data (pointer to char buffer and length). 254 * 255 * @retval kErrorNone Successfully set the Thread Domain Name. 256 * @retval kErrorInvalidArgs Given name is too long. 257 * 258 */ 259 Error SetDomainName(const NameData &aNameData); 260 #endif // (OPENTHREAD_CONFIG_THREAD_VERSION >= OT_THREAD_VERSION_1_2) 261 262 private: 263 Error SignalNetworkNameChange(Error aError); 264 265 static const char sNetworkNameInit[]; 266 static const char sDomainNameInit[]; 267 268 NetworkName mNetworkName; 269 270 #if (OPENTHREAD_CONFIG_THREAD_VERSION >= OT_THREAD_VERSION_1_2) 271 DomainName mDomainName; 272 #endif 273 }; 274 275 } // namespace MeshCoP 276 277 DefineCoreType(otNetworkName, MeshCoP::NetworkName); 278 279 } // namespace ot 280 281 #endif // MESHCOP_EXTENDED_PANID_HPP_ 282