inc/FWebJsonJsonWriter.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                FWebJsonJsonWriter.h
  20  * @brief               This is the header file for composing a JSON-encoded file.
  21  *
  22  * This header file contains the declarations of the JSON functionalities for composing JSON-encoded file.
  23  */
  24 #ifndef _FWEB_JSON_JSON_WRITER_H_
  25 #define _FWEB_JSON_JSON_WRITER_H_
  26
  27 #include <FBaseString.h>
  28 #include <FBaseByteBuffer.h>
  29
  30 namespace Tizen { namespace Web { namespace Json
  31 {
  32 class IJsonValue;
  33 class _JsonWriterImpl;
  34 }}} // Tizen::Web::Json
  35
  36 namespace Tizen { namespace Web { namespace Json
  37 {
  38
  39 /**
  40  * @class       JsonWriter
  41  * @brief       This class contains the declarations of the JSON functionalities for composing JSON-encoded file.
  42  *
  43  * @since       2.0
  44  *
  45  * The %JsonWriter class contains the declarations of the JSON functionalities for composing JSON-encoded files.
  46  *
  47  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/web/json_namespace.htm">JSON Guide</a>.
  48  *
  49  * The following example demonstrates how to use the %JsonWriter methods.
  50  *
  51  * @code
  52  *      #include <FWebJson.h>
  53  *
  54  *      using namespace Tizen::Base;
  55  *      using namespace Tizen::Web::Json;
  56  *
  57  *      void
  58  *      MyClass::JsonWriterSample(void)
  59  *      {
  60  *              String *pKey1 = new String(L"Key1");
  61  *              String *pKey2 = new String(L"Key2");
  62  *              JsonString *pJsonValue1 = new JsonString(L"Value1");
  63  *              JsonString *pJsonValue2 = new JsonString(L"Value2");
  64  *              JsonObject *pJsonObject = new JsonObject();
  65  *              pJsonObject->Construct();
  66  *              pJsonObject->Add(pKey1, pJsonValue1);
  67  *              pJsonObject->Add(pKey2, pJsonValue2);
  68  *
  69  *              //Composes to File
  70  *              String fileName(L"/Home/JsonComposeSample.json");
  71  *              result r = JsonWriter::Compose( pJsonObject, fileName );
  72  *              if( r != E_SUCCESS )
  73  *              {
  74  *                      AppLog("Compose failed");
  75  *              }
  76  *
  77  *              //Composes to char*
  78  *              char* pComposeBuf = new char[40];
  79  *              r = JsonWriter::Compose( pJsonObject, pComposeBuf, 40 );
  80  *
  81  *              //Composes to ByteBuffer
  82  *              ByteBuffer *pBuffer = new ByteBuffer();
  83  *              pBuffer->Construct(40);
  84  *              r = JsonWriter::Compose(pJsonObject, *pBuffer);
  85  *
  86  *              pJsonObject->RemoveAll(true);
  87  *              delete pJsonObject;
  88  *              delete pBuffer;
  89  *      }
  90  * @endcode
  91  */
  92 class _OSP_EXPORT_ JsonWriter
  93 {
  94 public:
  95         /**
  96          * Serializes the JSON-encoded data from IJsonValue to a file.
  97          *
  98          * @if OSPCOMPAT
  99          * @brief <i> [Compatibility] </i>
 100          * @endif
 101          * @since               2.0
 102          * @if OSPCOMPAT
 103          * @compatibility  This method has compatibility issues with OSP compatible applications. @n
 104          *                                                        For more information, see @ref CompIoPathPage "here".
 105          * @endif
 106          *
 107          * @return              An error code
 108          * @param[in]           pValue                  The JSON value to encode
 109          * @param[out]          filePath                The JSON file path
 110          * @exception           E_SUCCESS               The method is successful.
 111          * @exception           E_INVALID_DATA          The specified @c pValue is @c null.
 112          * @exception           E_INVALID_ARG           The specified @c filePath is incorrect.
 113          * @exception           E_ILLEGAL_ACCESS        Access is denied due to insufficient permission.
 114          * @exception           E_STORAGE_FULL          The disk space is full.
 115          * @exception           E_SYSTEM                The method cannot proceed due to a severe system error.
 116          */
 117         static result Compose(const IJsonValue* pValue, Tizen::Base::String& filePath);
 118
 119         /**
 120          * Serializes the JSON-encoded data from IJsonValue to a buffer.
 121          *
 122          * @since               2.0
 123          *
 124          * @return              An error code
 125          * @param[in]           pValue                  The JSON value to encode
 126          * @param[in]           bufferLength            The JSON-encoded data buffer length
 127          * @param[out]          pBuffer                 The buffer with JSON-encoded data
 128          * @exception           E_SUCCESS               The method is successful.
 129          * @exception           E_INVALID_ARG   Either of the following conditions has occurred:
 130          *                                                              - The specified @c pBuffer is @c null.
 131          *                                                              - The specified bufferLength is negative.
 132          * @exception           E_INVALID_DATA          The specified @c pValue is @c null.
 133          */
 134         static result Compose(const IJsonValue* pValue, void* pBuffer, int bufferLength);
 135
 136         /**
 137          * Serializes the JSON-encoded data from IJsonValue to Tizen::Base::ByteBuffer.
 138          *
 139          * @since               2.0
 140          *
 141          * @return              An error code
 142          * @param[in]           pValue                  The JSON value to encode
 143          * @param[out]          buffer                  The buffer with JSON-encoded data
 144          * @exception           E_SUCCESS               The method is successful.
 145          * @exception           E_INVALID_DATA          The specified @c pValue is @c null.
 146          * @remarks     The ByteBuffer parameter has to be constructed with a non-zero capacity before calling this method.
 147          */
 148         static result Compose(const IJsonValue* pValue, Tizen::Base::ByteBuffer& buffer);
 149
 150         /**
 151          * Serializes the JSON-encoded data from IJsonValue to Tizen::Base::ByteBuffer with unescaped wide characters.
 152          *
 153          * @since               2.1
 154          *
 155          * @return              An error code
 156          * @param[in]           pValue                  The JSON value to encode
 157          * @param[out]          buffer                  The buffer with JSON-encoded data
 158          * @exception           E_SUCCESS               The method is successful.
 159          * @exception           E_INVALID_DATA          The specified @c pValue is @c null.
 160          * @remarks     The ByteBuffer parameter has to be constructed with a non-zero capacity before calling this method.
 161          */
 162         static result ComposeUnescapeUnicode(const IJsonValue* pValue, Tizen::Base::ByteBuffer& buffer);
 163
 164 private:
 165         //
 166         // This default constructor is intentionally declared as private because this class cannot be constructed.
 167         //
 168         // @remarks             This constructor is hidden.
 169         //
 170         JsonWriter(void);
 171
 172         //
 173         // This is the destructor for this class.
 174         //
 175         // @remarks             This constructor is hidden.
 176         //
 177         virtual ~JsonWriter(void);
 178
 179 private:
 180         _JsonWriterImpl* __pJsonWriterImpl;
 181
 182         friend class _JsonWriterImpl;
 183 }; // JsonWriter
 184
 185 }}} // Tizen::Web::Json
 186 #endif // _FWEB_JSON_JSON_WRITER_H_