1 /* 2 * Copyright (c) 2020, 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 JSON formatter definition for RESTful HTTP server. 32 */ 33 34 #ifndef OTBR_REST_JSON_HPP_ 35 #define OTBR_REST_JSON_HPP_ 36 37 #include "openthread-br/config.h" 38 39 #include "openthread/dataset.h" 40 #include "openthread/link.h" 41 #include "openthread/thread_ftd.h" 42 43 #include "rest/types.hpp" 44 #include "utils/hex.hpp" 45 46 namespace otbr { 47 namespace rest { 48 49 /** 50 * The functions within this namespace provides a tranformation from an object/string/number to a serialized Json 51 * string. 52 * 53 */ 54 namespace Json { 55 56 /** 57 * This method formats an integer to a Json number and serialize it to a string. 58 * 59 * @param[in] aNumber An integer need to be format. 60 * 61 * @returns A string of serialized Json number. 62 * 63 */ 64 std::string Number2JsonString(const uint32_t &aNumber); 65 66 /** 67 * This method formats a Bytes array to a Json string and serialize it to a string. 68 * 69 * @param[in] aBytes A Bytes array representing a hex number. 70 * 71 * @returns A string of serialized Json string. 72 * 73 */ 74 std::string Bytes2HexJsonString(const uint8_t *aBytes, uint8_t aLength); 75 76 /** 77 * This method parses a hex string as byte array. 78 * 79 * @param[in] aHexString String of bytes in hex. 80 * @param[in] aBytes Byte array to write to. Must be at least @p aMaxLength. 81 * @param[in] aMaxLength Maximum length to parse (in bytes). 82 * 83 * @returns Number of bytes effectively parsed. 84 * 85 */ 86 int Hex2BytesJsonString(const std::string &aHexString, uint8_t *aBytes, uint8_t aMaxLength); 87 88 /** 89 * This method formats a C string to a Json string and serialize it to a string. 90 * 91 * @param[in] aCString A char pointer pointing to a C string. 92 * 93 * @returns A string of serialized Json string. 94 * 95 */ 96 std::string CString2JsonString(const char *aCString); 97 98 /** 99 * This method formats a string to a Json string and serialize it to a string. 100 * 101 * @param[in] aString A string. 102 * 103 * @returns A string of serialized Json string. 104 * 105 */ 106 std::string String2JsonString(const std::string &aString); 107 108 /** 109 * This method parses a Json string and checks its datatype and returns a string if it is a string. 110 * 111 * @param[in] aJsonString A Json string. 112 * @param[out] aString The string. 113 * 114 * @returns A boolean indicating whether the Json string was indeed a string. 115 */ 116 bool JsonString2String(const std::string &aJsonString, std::string &aString); 117 118 /** 119 * This method formats a Node object to a Json object and serialize it to a string. 120 * 121 * @param[in] aNode A Node object. 122 * 123 * @returns A string of serialized Json object. 124 * 125 */ 126 std::string Node2JsonString(const NodeInfo &aNode); 127 128 /** 129 * This method formats a vector of diagnostic objects to a Json array and serialize it to a string. 130 * 131 * @param[in] aDiagSet A vector of diagnostic objects. 132 * 133 * @returns A string of serialized Json array. 134 * 135 */ 136 std::string Diag2JsonString(const std::vector<std::vector<otNetworkDiagTlv>> &aDiagSet); 137 138 /** 139 * This method formats an Ipv6Address to a Json string and serialize it to a string. 140 * 141 * @param[in] aAddress An Ip6Address object. 142 * 143 * @returns A string of serialized Json string. 144 * 145 */ 146 std::string IpAddr2JsonString(const otIp6Address &aAddress); 147 148 /** 149 * This method formats a LinkModeConfig object to a Json object and serialize it to a string. 150 * 151 * @param[in] aMode A LinkModeConfig object. 152 * 153 * @returns A string of serialized Json object. 154 * 155 */ 156 std::string Mode2JsonString(const otLinkModeConfig &aMode); 157 158 /** 159 * This method formats a Connectivity object to a Json object and serialize it to a string. 160 * 161 * @param[in] aConnectivity A Connectivity object. 162 * 163 * @returns A string of serialized Json object. 164 * 165 */ 166 std::string Connectivity2JsonString(const otNetworkDiagConnectivity &aConnectivity); 167 168 /** 169 * This method formats a Route object to a Json object and serialize it to a string. 170 * 171 * @param[in] aRoute A Route object. 172 * 173 * @returns A string of serialized Json object. 174 * 175 */ 176 std::string Route2JsonString(const otNetworkDiagRoute &aRoute); 177 178 /** 179 * This method formats a RouteData object to a Json object and serialize it to a string. 180 * 181 * @param[in] aRouteData A RouteData object. 182 * 183 * @returns A string of serialized Json object. 184 * 185 */ 186 std::string RouteData2JsonString(const otNetworkDiagRouteData &aRouteData); 187 188 /** 189 * This method formats a LeaderData object to a Json object and serialize it to a string. 190 * 191 * @param[in] aLeaderData A LeaderData object. 192 * 193 * @returns A string of serialized Json object. 194 * 195 */ 196 std::string LeaderData2JsonString(const otLeaderData &aLeaderData); 197 198 /** 199 * This method formats a MacCounters object to a Json object and serialize it to a string. 200 * 201 * @param[in] aMacCounters A MacCounters object. 202 * 203 * @returns A string of serialized Json object. 204 * 205 */ 206 std::string MacCounters2JsonString(const otNetworkDiagMacCounters &aMacCounters); 207 208 /** 209 * This method formats a ChildEntry object to a Json object and serialize it to a string. 210 * 211 * @param[in] aChildEntry A ChildEntry object. 212 * 213 * @returns A string of serialized Json object. 214 * 215 */ 216 std::string ChildTableEntry2JsonString(const otNetworkDiagChildEntry &aChildEntry); 217 218 /** 219 * This method formats an error code and an error message to a Json object and serialize it to a string. 220 * 221 * @param[in] aErrorCode An enum HttpStatusCode such as '404'. 222 * @param[in] aErrorMessage Error message such as '404 Not Found'. 223 * 224 * @returns A string of serialized Json object. 225 * 226 */ 227 std::string Error2JsonString(HttpStatusCode aErrorCode, std::string aErrorMessage); 228 229 /** 230 * This method formats a Json object from an active dataset. 231 * 232 * @param[in] aDataset A dataset struct. 233 * 234 * @returns A string of serialized Json object. 235 * 236 */ 237 std::string ActiveDataset2JsonString(const otOperationalDataset &aDataset); 238 239 /** 240 * This method formats a Json object from a pending dataset. 241 * 242 * @param[in] aDataset A dataset struct. 243 * 244 * @returns A string of serialized Json object. 245 * 246 */ 247 std::string PendingDataset2JsonString(const otOperationalDataset &aPendingDataset); 248 249 /** 250 * This method parses a Json string and fills the provided dataset. Fields 251 * set to null are cleared (set to not present). Non-present fields are left 252 * as is. 253 * 254 * @param[in] aJsonActiveDataset The Json string to be parsed. 255 * @param[in] aDataset The dataset struct to be filled. 256 * 257 * @returns If the Json string has been successfully parsed. 258 * 259 */ 260 bool JsonActiveDatasetString2Dataset(const std::string &aJsonActiveDataset, otOperationalDataset &aDataset); 261 262 /** 263 * This method parses a Json string and fills the provided dataset. Fields 264 * set to null are cleared (set to not present). Non-present fields are left 265 * as is. 266 * 267 * @param[in] aJsonActiveDataset The Json string to be parsed. 268 * @param[in] aDataset The dataset struct to be filled. 269 * 270 * @returns If the Json string has been successfully parsed. 271 * 272 */ 273 bool JsonPendingDatasetString2Dataset(const std::string &aJsonPendingDataset, otOperationalDataset &aDataset); 274 275 }; // namespace Json 276 277 } // namespace rest 278 } // namespace otbr 279 280 #endif // OTBR_REST_JSON_HPP_ 281