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