parcel/parcel.hh

   1 /*
   2  * Copyright (c) 2020 Samsung Electronics Co., Ltd. All rights reserved.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef PARCEL_PARCEL_HH_
  18 #define PARCEL_PARCEL_HH_
  19
  20 /**
  21  * @addtogroup CORE_LIB_PARCEL_MODULE
  22  * @{
  23  */
  24
  25 #include <tizen.h>
  26
  27 #include <memory>
  28 #include <string>
  29 #include <vector>
  30
  31 #include "parcel/common.hh"
  32 #include "parcel/parcelable.hh"
  33
  34 namespace tizen_base {
  35
  36 /**
  37  * @brief The class for Parcel API.
  38  * @since_tizen 6.5
  39  */
  40 class EXPORT Parcel final {
  41  public:
  42   /**
  43    * @brief Enumeration for parcel error.
  44    * @since_tizen 6.5
  45    */
  46   enum Error {
  47     None = TIZEN_ERROR_NONE, /**< Successful */
  48     IllegalByteSeq = TIZEN_ERROR_ILLEGAL_BYTE_SEQ, /**< Illegal byte sequence */
  49     InvalidParameter = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
  50     NoData = TIZEN_ERROR_NO_DATA, /**< No data available */
  51     OutOfMemory = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
  52   };
  53
  54   /**
  55    * @brief Constructor.
  56    * @since_tizen 6.5
  57    */
  58   Parcel();
  59
  60   /**
  61    * @brief Constructor
  62    * @since_tizen 6.5
  63    * @param[in] buf The bytes to write
  64    * @param[in] size the size of bytes to write
  65    * @param[in] copy If @c is true, this object copies bytes.
  66    *                 If @c is false, this object takes ownership of @buf.
  67    */
  68   Parcel(const void* buf, uint32_t size, bool copy = true);
  69
  70   /**
  71    * @brief Destructor
  72    * @since_tizen 6.5
  73    */
  74   ~Parcel();
  75
  76   /**
  77    * @brief Copy-constructor.
  78    * @since_tizen 6.5
  79    * @param[in] p The object to copy
  80    */
  81   Parcel(const Parcel& p);
  82
  83   /**
  84    * @brief Assignment.
  85    * @since_tizen 6.5
  86    * @param[in] b The object to copy
  87    */
  88   Parcel& operator = (const Parcel& p);
  89
  90   /**
  91    * @brief Move-constructor.
  92    * @since_tizen 6.5
  93    * @param[in] p The object to move
  94    */
  95   Parcel(Parcel&& p) noexcept;
  96
  97   /**
  98    * @brief Assignment.
  99    * @since_tizen 6.5
 100    * @param[in] p The object to move
 101    */
 102   Parcel& operator = (Parcel&& p) noexcept;
 103
 104   /**
 105    * @brief Checks the parcel is empty or not.
 106    * @since_tizen 6.5
 107    * @return true if the parcel is empty
 108    */
 109   bool IsEmpty() const noexcept;
 110
 111   /**
 112    * @brief Writes bytes into the parcel.
 113    * @since_tizen 6.5
 114    * @param[in] buf The bytes to write
 115    * @param[in] size The size of bytes to write
 116    */
 117   void Write(const void* buf, uint32_t size);
 118
 119   /**
 120    * @brief Reads bytes from the parcel.
 121    * @since_tizen 6.5
 122    * @param[out] buf The bytes to read
 123    * @param[in] size The size of bytes to read
 124    * @return @c 0 on success,
 125    *         otherwise a negative error value
 126    */
 127   int Read(void* buf, uint32_t size);
 128
 129   /**
 130    * @brief Writes a boolean value into the parcel.
 131    * @since_tizen 6.5
 132    * @param[in] val The boolean value
 133    */
 134   void WriteBool(bool val);
 135
 136   /**
 137    * @brief Writes a byte value into the parcel.
 138    * @since_tizen 6.5
 139    * @param[in] val The unsigned byte value
 140    */
 141   void WriteByte(char byte);
 142
 143   /**
 144    * @brief Writes an unsigned short value into the parcel.
 145    * @since_tizen 6.5
 146    * @param[in] val The unsigned short value
 147    */
 148   void WriteUInt16(uint16_t val);
 149
 150   /**
 151    * @brief Writes an unsigned integer value into the parcel.
 152    * @since_tizen 6.5
 153    * @param[in] val The unsigned integer value
 154    */
 155   void WriteUInt32(uint32_t val);
 156
 157   /**
 158    * @brief Writes an unsigned long long integer into the parcel.
 159    * @since_tizen 6.5
 160    * @param[in] val The unsigned long long integer value
 161    */
 162   void WriteUInt64(uint64_t val);
 163
 164   /**
 165    * @brief Writes a signed short value into the parcel.
 166    * @since_tizen 6.5
 167    * @param[in] val The signed short value
 168    */
 169   void WriteInt16(int16_t val);
 170
 171   /**
 172    * @brief Writes a signed integer value into the parcel.
 173    * @since_tizen 6.5
 174    * @param[in] val The signed integer value
 175    */
 176   void WriteInt32(int32_t val);
 177
 178   /**
 179    * @brief Writes a signed long long integer value into the parcel.
 180    * @since_tizen 6.5
 181    * @param[in] val The signed long long integer value
 182    */
 183   void WriteInt64(int64_t val);
 184
 185   /**
 186    * @brief Writes a floating point value into the parcel.
 187    * @since_tizen 6.5
 188    * @param[in] val The floating point value
 189    */
 190   void WriteFloat(float val);
 191
 192   /**
 193    * @brief Writes a double precision floating point value into the parcel.
 194    * @since_tizen 6.5
 195    * @param[in] val The double precision floating point value
 196    */
 197   void WriteDouble(double val);
 198
 199   /**
 200    * @brief Writes a string data into the parcel.
 201    * @since_tizen 6.5
 202    * @param[in] str The string data
 203    */
 204   void WriteString(const std::string& str);
 205
 206   /**
 207    * @brief Writes a string data into the parcel.
 208    * @since_tizen 6.5
 209    * @param[in] str The string data
 210    */
 211   void WriteCString(const char* str);
 212
 213   /**
 214    * @brief Reads a boolean value from the parcel.
 215    * @since_tizen 6.5
 216    * @param[out] val The boolean value
 217    * @return @c 0 on success,
 218    *         otherwise a negative error value
 219    */
 220   int ReadBool(bool* val);
 221
 222   /**
 223    * @brief Reads a byte value from the parcel.
 224    * @since_tizen 6.5
 225    * @param[out] val The unsigned byte value
 226    * @return @c 0 on success,
 227    *         otherwise a negative error value
 228    */
 229   int ReadByte(char* val);
 230
 231   /**
 232    * @breif Reads an unsigned short value from the parcel.
 233    * @since_tizen 6.5
 234    * @param[out] val The unsigned short value
 235    * @return @c 0 on success,
 236    *         otherwise a negative error value
 237    */
 238   int ReadUInt16(uint16_t* val);
 239
 240   /**
 241    * @brief Reads an unsigned integer value from the parcel.
 242    * @since_tizen 6.5
 243    * @param[out] val The unsigned integer value
 244    * @return @c 0 on success,
 245    *         otherwise a negative error value
 246    */
 247   int ReadUInt32(uint32_t* val);
 248
 249   /**
 250    * @brief Reads an unsigned long long integer value from the parcel.
 251    * @since_tizen 6.5
 252    * @param[out] val The unsigned long long integer value
 253    * @return @c 0 on success,
 254    *         otherwise a negative error value
 255    */
 256   int ReadUInt64(uint64_t* val);
 257
 258   /**
 259    * @brief Reads a signed byte value from the parcel.
 260    * @since_tizen 6.5
 261    * @param[out] val The signed byte value
 262    * @return @c 0 on success,
 263    *         otherwise a negative error value
 264    */
 265   int ReadInt8(int8_t* val);
 266
 267   /**
 268    * @brief Reads a signed short value from the parcel.
 269    * @since_tizen 6.5
 270    * @param[out] val The signed short value
 271    * @return @c 0 on success,
 272    *         otherwise a negative error value
 273    */
 274   int ReadInt16(int16_t* val);
 275
 276   /**
 277    * @brief Reads a signed integer value from the parcel.
 278    * @since_tizen 6.5
 279    * @param[out] val The signed integer value
 280    * @return @c 0 on success,
 281    *         otherwise a negative error value
 282    */
 283   int ReadInt32(int32_t* val);
 284
 285   /**
 286    * @brief Reads a signed long long integer value from the parcel.
 287    * @since_tizen 6.5
 288    * @param[out] val The signed long long integer value
 289    * @return @c 0 on success,
 290    *         otherwise a negative error value
 291    */
 292   int ReadInt64(int64_t* val);
 293
 294   /**
 295    * @brief Reads a floating point value from the parcel.
 296    * @since_tizen 6.5
 297    * @param[out] val The floating point value
 298    * @return @c 0 on success,
 299    *         otherwise a negative error value
 300    */
 301   int ReadFloat(float* val);
 302
 303   /**
 304    * @brief Reads a double precision floating point value from the parcel.
 305    * @since_tizen 6.5
 306    * @param[out] val The double precision floating point value
 307    * @return @c 0 on success,
 308    *         otherwise a negative error value
 309    */
 310   int ReadDouble(double* val);
 311
 312   /**
 313    * @brief Reads a string data from the parcel.
 314    * @since_tizen 6.5
 315    * @return The string data
 316    * @remarks Before using the returned value, you should check the result using get_last_result().
 317    * @see get_last_result()
 318    */
 319   std::string ReadString();
 320
 321   /**
 322    * @brief Reads a string data from the parcel.
 323    * @since_tizen 6.5
 324    * @remarks You should release @a str using free().
 325    * @param[out] str The string data
 326    * @return @c 0 on success,
 327    *         otherwise a negative error value
 328    */
 329   int ReadCString(char** str);
 330
 331   /**
 332    * @brief Resets the reader pointer of the parcel to the start.
 333    * @since_tizen 6.5
 334    */
 335   void ResetReader();
 336
 337   /**
 338    * @brief Clears the data of the parcel.
 339    * @since_tizen 6.5
 340    */
 341   void Clear();
 342
 343   /**
 344    * @brief Resets the parcel.
 345    * @since_tizen 6.5
 346    * @param[in] buf The bytes to write
 347    * @param[in] size The size of bytes to write
 348    */
 349   void Reset(const void* buf, uint32_t size);
 350
 351   /**
 352    * @brief Writes the data using @a parcelable into the parcel.
 353    * @since_tizen 6.5
 354    * @param[in] parcelable The interface to write the data into the parcel
 355    */
 356   void WriteParcelable(const Parcelable& parcelable);
 357
 358   /**
 359    * @brief Reads the data using @a parcelable from the parcel.
 360    * @since_tizen 6.5
 361    * @param[out] parcelable The interface to get data from the parcel
 362    * @return @c 0 on success,
 363    *         otherwise a negative error value
 364    */
 365   int ReadParcelable(Parcelable* parcelable);
 366
 367   /**
 368    * @brief Sets byte order of the parcel.
 369    * @since_tizen 6.5
 370    * @param[in] big_endian @c true, if byte order of the parcel is big-endian
 371    */
 372   void SetByteOrder(bool big_endian);
 373
 374   /**
 375    * @brief Gets the raw data of the parcel.
 376    * @since_tizen 7.0
 377    * @return The raw data
 378    */
 379   uint8_t* GetData() const;
 380
 381   /**
 382    * @breif Gets the size of the raw data of the parcel.
 383    * @since_tizen 7.0
 384    * @return The size of the raw data
 385    */
 386   size_t GetDataSize() const;
 387
 388   /**
 389    * @brief Gets the size of the data capacity of the parcel.
 390    * @since_tizen 7.0
 391    * @return The size of the data capacity
 392    */
 393   size_t GetDataCapacity() const;
 394
 395   /**
 396    * @breif Sets the size of the data capacity of the parcel.
 397    * @since_tizen 7.0
 398    * @param[in] size The size of the data capcity
 399    */
 400   void SetDataCapacity(size_t size);
 401
 402   /**
 403    * @brief Detaches the raw data from the parcel.
 404    * @since_tizen 7.0
 405    * @param[out] size The size of the raw data
 406    * @return The raw data
 407    */
 408   uint8_t* Detach(size_t* size);
 409
 410   /**
 411    * @brief Gets the position of the reader of the parcel.
 412    * @since_tizen 7.0
 413    * @return The position of the reader
 414    */
 415   uint32_t GetReader() const;
 416
 417   /**
 418    * @brief Converts the raw data of the parcel to the vector.
 419    * @since_tizen 7.0
 420    * @return The vector of the raw data
 421    */
 422   std::vector<uint8_t> ToRaw();
 423
 424  private:
 425   class Impl;
 426   std::unique_ptr<Impl> impl_;
 427 };
 428
 429 }  // naemspace tizen_base
 430
 431 /**
 432  * @}
 433  */
 434
 435 #endif  // PARCEL_PARCEL_HH_