inc/FWebJsonJsonParser.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 2.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an "AS IS" BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18 /**
  19  * @file                FWebJsonJsonParser.h
  20  * @brief               This is the header file for the %JsonParser class.
  21  *
  22  * This header file contains the declarations of the JSON functionalities for parsing the JSON-encoded file.
  23  */
  24 #ifndef _FWEB_JSON_JSON_PARSER_H_
  25 #define _FWEB_JSON_JSON_PARSER_H_
  26
  27 #include <FBaseByteBuffer.h>
  28
  29 namespace Tizen { namespace Web { namespace Json
  30 {
  31 class IJsonValue;
  32 class _JsonParserImpl;
  33 }}} // Tizen::Web::Json
  34
  35 namespace Tizen { namespace Web { namespace Json
  36 {
  37
  38 /**
  39  * @class       JsonParser
  40  * @brief       This class contains the declarations of the JSON functionalities for parsing the JSON-encoded file.
  41  *
  42  * @since       2.0
  43  *
  44  * The %JsonParser class contains the declarations of the JSON functionalities for parsing the JSON-encoded files.
  45  *
  46  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/web/json_namespace.htm">JSON Guide</a>.
  47  *
  48  * The following example demonstrates how to use the %JsonParser methods.
  49  *
  50  * @code
  51  * Sample Data - JsonSample.json
  52  *      {"List": {
  53  *                              "debug": "on",
  54  *                              "window": {
  55  *                                                      "title": "Is an Icon List",
  56  *                                                      "name": "main_window",
  57  *                                                      "width": 500,
  58  *                                                      "height": 500
  59  *                                              },
  60  *                              "image": {
  61  *                                                      "src": "Images/fun.png",
  62  *                                                      "name": "fun1"
  63  *                                              },
  64  *                              "text": {
  65  *                                                      "data": "Click Here",
  66  *                                                      "size": 36,
  67  *                                                      "style": "bold",
  68  *                                                      "name": "text1"
  69  *                                              },
  70  *                              "properties": [
  71  *                                                              {"alignment" : "center"},
  72  *                                                              {"transperancy":"80"}
  73  *                                                      ]
  74  *      }}
  75  *
  76  *      #include <FWebJson.h>
  77  *
  78  *      using namespace Tizen::Base;
  79  *      using namespace Tizen::Base::Utility;
  80  *      using namespace Tizen::Web::Json;
  81  *
  82  *      void
  83  *      MyClass::JsonParserSample(void)
  84  *      {
  85  *              // Parses from File
  86  *              String fileName(L"/Home/JsonSample.json");
  87  *              IJsonValue* pValue = JsonParser::ParseN(fileName);
  88  *              if( pValue == null )
  89  *              {
  90  *                      AppLog("ErrorCode %s", GetLastResult());
  91  *              }
  92  *              else
  93  *              {
  94  *                      // Uses the pValue to know what is the type
  95  *                      if( pValue->GetType() == JSON_TYPE_OBJECT )
  96  *                      {
  97  *                              JsonObject* pJsonObj = static_cast<JsonObject*>(pValue);//use pJsonObj to access key-value pairs
  98  *                              pJsonObj->RemoveAll(true);
  99  *                      }
 100  *                      else if( pValue->GetType() == JSON_TYPE_ARRAY )
 101  *                      {
 102  *                              JsonArray* pJsonArray = static_cast<JsonArray*>(pValue);//use pJsonArray to access values
 103  *                              pJsonArray->RemoveAll(true);
 104  *                      }
 105  *                      delete pValue;
 106  *              }
 107  *
 108  *              // Parses from char*
 109  *              const char* jBuf = "{\"Key\":1,\"Key1\":{\"Key2\":\"val\",\"Key3\":\"val1\"},\"Key4\":[\"val2\",\"val3\"]}";
 110  *              String str(jBuf);
 111  *              int length = str.GetLength();
 112  *              IJsonValue* pValue1 = JsonParser::ParseN(jBuf, length);
 113  *
 114  *              // Converts the pValue1 to JsonObject
 115  *              JsonObject* pJsonObject = static_cast<JsonObject*>(pValue1);
 116  *              pJsonObject->RemoveAll(true);
 117  *              delete pJsonObject;
 118  *
 119  *              // Parses from ByteBuffer
 120  *              ByteBuffer *pBuf = StringUtil::StringToUtf8N( str );
 121  *              IJsonValue* pValue2 = JsonParser::ParseN(*pBuf);
 122  *
 123  *              // Converts the pValue2 to JsonObject
 124  *              pJsonObject = static_cast<JsonObject*>(pValue2);
 125  *              pJsonObject->RemoveAll(true);
 126  *              delete pJsonObject;
 127  *              delete pBuf;
 128  *      }
 129  * @endcode
 130  */
 131 class _OSP_EXPORT_ JsonParser
 132 {
 133 public:
 134         /**
 135          * Parses a JSON-encoded file to IJsonValue (node).
 136          *
 137          * @if OSPCOMPAT
 138          * @brief <i> [Compatibility] </i>
 139          * @endif
 140          * @since                       2.0
 141          * @if OSPCOMPAT
 142          * @compatibility  This method has compatibility issues with OSP compatible applications. @n
 143          *                                                        For more information, see @ref CompIoPathPage "here".
 144          * @endif
 145          *
 146          * @return                             A JSON value of type JsonArray or JsonObject, @n
 147          *                                     else @c null if the JSON data of the file is invalid
 148          * @param[in] filePath                 The path of the JSON-encoded file
 149          * @exception   E_SUCCESS                               The method is successful.
 150          * @exception   E_INVALID_ARG                   The specified file path is incorrect, or the file is not found.
 151          * @exception   E_INVALID_DATA                  The input JSON data is invalid, or the buffer is empty.
 152          * @exception   E_MAX_EXCEEDED                  The input JSON data exceeds the maximum length.
 153          * @exception   E_ILLEGAL_ACCESS                Access is denied due to insufficient permission.
 154          * @exception   E_FILE_NOT_FOUND                The specified @c filePath cannot be found.
 155          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.
 156          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 157          */
 158         static IJsonValue* ParseN(const Tizen::Base::String& filePath);
 159
 160         /**
 161          * Parses a JSON-encoded buffer to IJsonValue (node).
 162          *
 163          * @since                       2.0
 164          *
 165          * @return                         A JSON value of type JsonArray or JsonObject, @n
 166          *                                 else @c null if the JSON data of the file is invalid
 167          * @param[in] pBuffer              A JSON-encoded buffer
 168          * @param[in]   bufferLength       A JSON-encoded buffer length
 169          * @exception   E_SUCCESS                               The method is successful.
 170          * @exception   E_INVALID_ARG                   Either of the following conditions has occurred:
 171          *                                                                      - The specified @c pBuffer is @c null.
 172          *                                                                      - The specified @c bufferLength is zero or negative.
 173          * @exception   E_INVALID_DATA                  The input JSON data is invalid, or the buffer is empty.
 174          * @exception   E_MAX_EXCEEDED                  The input JSON data exceeds the maximum length.
 175          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 176          */
 177         static IJsonValue* ParseN(const void* pBuffer, int bufferLength);
 178
 179         /**
 180          * Parses a JSON-encoded Tizen::Base::ByteBuffer to IJsonValue (node).
 181          *
 182          * @since                       2.0
 183          *
 184          * @return                                A JSON value of type JsonArray or JsonObject, @n
 185          *                                        else @c null if the JSON data of the file is invalid
 186          * @param[in] buffer                       A JSON-encoded byte buffer
 187          * @exception   E_SUCCESS                               The method is successful.
 188          * @exception   E_INVALID_DATA                  The input JSON data is invalid, or the buffer is empty.
 189          * @exception   E_MAX_EXCEEDED                  The input JSON data exceeds the maximum length.
 190          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 191          */
 192         static IJsonValue* ParseN(const Tizen::Base::ByteBuffer& buffer);
 193
 194 private:
 195         //
 196         // This default constructor is intentionally declared as private because this class cannot be constructed.
 197         //
 198         // @remarks             This constructor is hidden.
 199         //
 200         JsonParser(void);
 201
 202         //
 203         // This is the destructor for this class.
 204         //
 205         // @remarks             This constructor is hidden.
 206         //
 207         virtual ~JsonParser(void);
 208
 209 private:
 210         _JsonParserImpl* __pJsonParserImpl;
 211
 212         friend class _JsonParserImpl;
 213 }; // JsonParser
 214
 215 }}} // Tizen::Web::Json
 216 #endif // _FWEB_JSON_JSON_PARSER_H_