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