include/bundle_cpp.h

   1 /*
   2  * Copyright (c) 2019 - 2020 Samsung Electronics Co., Ltd.
   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 BUNDLE_CPP_H_
  18 #define BUNDLE_CPP_H_
  19
  20 /**
  21  * @file bundle_cpp.h
  22  * @brief This file declares API of the bundle C++ library.
  23  */
  24
  25 /**
  26  * @addtogroup CORE_LIB_BUNDLE_CPP_MODULE
  27  * @{
  28  */
  29
  30 #include <bundle.h>
  31
  32 #include <cstdio>
  33 #include <memory>
  34 #include <string>
  35 #include <utility>
  36 #include <vector>
  37
  38 #ifndef EXPORT_API
  39 #define EXPORT_API __attribute__((visibility("default")))
  40 #endif
  41
  42 namespace tizen_base {
  43
  44 /**
  45  * @brief The class for bundle APIs.
  46  * @since_tizen 5.5
  47  */
  48 class EXPORT_API Bundle final {
  49  public:
  50   /**
  51    * @brief The type for raw bundle.
  52    * @since_tizen 5.5
  53    */
  54   using BundleRaw =
  55       std::pair<std::unique_ptr<bundle_raw, decltype(std::free)*>, int>;
  56
  57   /**
  58    * @brief The class for information of keys.
  59    * @since_tizen 5.5
  60    */
  61   class KeyInfo final {
  62    public:
  63     /**
  64      * @brief Constructor.
  65      * @since_tizen 5.5
  66      * @param[in] handle The handle for type bundle_keyval_t
  67      * @param[in] name The key string
  68      * @param[in] own True if this object owns the handle
  69      */
  70     KeyInfo(const bundle_keyval_t* handle,  std::string name, bool own = false);
  71
  72     /**
  73      * @brief Destructor.
  74      * @since_tizen 5.5
  75      */
  76     ~KeyInfo();
  77
  78     /**
  79      * @brief Copy-constructor.
  80      * @since_tizen 5.5
  81      * @param[in] b The object to copy
  82     */
  83     KeyInfo(const KeyInfo& b);
  84
  85     /**
  86      * @brief Assignment.
  87      * @since_tizen 5.5
  88      * @param[in] b The object to copy
  89      */
  90     KeyInfo& operator = (const KeyInfo& b);
  91
  92     /**
  93      * @brief Move-constructor.
  94      * @since_tizen 5.5
  95      * @param[in] b The object to move
  96     */
  97     KeyInfo(KeyInfo&& b) noexcept;
  98
  99     /**
 100      * @brief Assignment.
 101      * @since_tizen 5.5
 102      * @param[in] b The object to move
 103      */
 104     KeyInfo& operator = (KeyInfo&& b) noexcept;
 105
 106     /**
 107      * @brief Gets the type of a key-value pair.
 108      * @since_tizen 5.5
 109      * @return The type
 110      */
 111     bundle_type GetType() const;
 112
 113     /**
 114      * @brief Determines whether the type of a key-value pair is an array.
 115      * @since_tizen 5.5
 116      * @return True when it is an array
 117      */
 118     bool IsArray() const;
 119
 120     /**
 121      * @brief Gets the key string.
 122      * @since_tizen 5.5
 123      * @return The key string
 124      */
 125     const std::string& GetName() const;
 126
 127    private:
 128     class Impl;
 129     std::unique_ptr<Impl> impl_;
 130   };
 131
 132   /**
 133    * @brief Constructor.
 134    * @since_tizen 5.5
 135    */
 136   Bundle();
 137
 138   /**
 139    * @brief Constructor.
 140    * @since_tizen 5.5
 141    * @param[in] raw The object for BundleRaw
 142    * @param[in] base64 @c true, @a raw is the encoded raw data using base64-encoding
 143    */
 144   explicit Bundle(BundleRaw raw, bool base64 = true);
 145
 146   /**
 147    * @brief Constructor.
 148    * @since_tizen 5.5
 149    * @param[in] raw The string object for raw bundle
 150    */
 151   explicit Bundle(const std::string& raw);
 152
 153   /**
 154    * @brief Constructor.
 155    * @since_tizen 5.5
 156    * @param[in] b The handle for bundle
 157    * @param[in] copy True if this object wants to copy it from the handle
 158    * @param[in] own True if this object owns the handle
 159    */
 160   explicit Bundle(bundle* b, bool copy = true, bool own = true);
 161
 162   /**
 163    * @brief Destructor.
 164    * @since_tizen 5.5
 165    */
 166   ~Bundle();
 167
 168   /**
 169    * @brief Copy-constructor.
 170    * @since_tizen 5.5
 171    * @param[in] b The object to copy
 172    */
 173   Bundle(const Bundle& b);
 174
 175   /**
 176    * @brief Assignment.
 177    * @since_tizen 5.5
 178    * @param[in] b The object to copy
 179    */
 180   Bundle& operator = (const Bundle& b);
 181
 182   /**
 183    * @brief Move-constructor.
 184    * @since_tizen 5.5
 185    * @param[in] b The object to move
 186    */
 187   Bundle(Bundle&& b) noexcept;
 188
 189   /**
 190    * @brief Assignment.
 191    * @since_tizen 5.5
 192    * @param[in] b The object to move
 193    */
 194   Bundle& operator = (Bundle&& b) noexcept;
 195
 196   /**
 197    * @brief Check the bundle is empty or not.
 198    * @since_tizen 6.0
 199    * @return true if the bundle is empty
 200    */
 201   bool IsEmpty() const noexcept;
 202
 203   /**
 204    * @brief Gets keys in bundle object.
 205    * @since_tizen 5.5
 206    * @return A string array of object KeyInfo
 207   */
 208   std::vector<KeyInfo> GetKeys();
 209
 210   /**
 211    * @brief Adds a string type key-value pair into a bundle.
 212    * @since_tizen 5.5
 213    * @param[in] key The string key
 214    * @param[in] val The string value
 215    * @return The operation result
 216    * @retval BUNDLE_ERROR_NONE Success
 217    * @retval BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
 218    * @retval BUNDLE_ERROR_KEY_EXISTS Key already exists
 219    * @retval BUNDLE_ERROR_OUT_OF_MEMORY Out of memory
 220   */
 221   int Add(const std::string& key, const std::string& val);
 222
 223   /**
 224    * @brief Adds a string type key-value pair into a bundle.
 225    * @since_tizen 5.5
 226    * @param[in] key The string key
 227    * @param[in] val The array of strings
 228    * @return The operation result
 229    * @retval BUNDLE_ERROR_NONE Success
 230    * @retval BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
 231    * @retval BUNDLE_ERROR_KEY_EXISTS Key already exists
 232    * @retval BUNDLE_ERROR_OUT_OF_MEMORY Out of memory
 233   */
 234   int Add(const std::string& key, const std::vector<std::string>& val);
 235
 236   /**
 237    * @brief Adds a string type key-value pair into a bundle.
 238    * @since_tizen 5.5
 239    * @param[in] key The string key
 240    * @param[in] val The array of bytes
 241    * @return The operation result
 242    * @retval BUNDLE_ERROR_NONE Success
 243    * @retval BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
 244    * @retval BUNDLE_ERROR_KEY_EXISTS Key already exists
 245    * @retval BUNDLE_ERROR_OUT_OF_MEMORY Out of memory
 246   */
 247   int Add(const std::string& key, const std::vector<unsigned char>& val);
 248
 249   /**
 250    * @brief Deletes a key-value object with the given key.
 251    * @since_tizen 5.5
 252    * @param[in] key The string key
 253    * @return The operation result
 254    * @retval BUNDLE_ERROR_NONE Success
 255    * @retval BUNDLE_ERROR_INVALID_PARAMETER Invalid parameter
 256    * @retval BUNDLE_ERROR_KEY_NOT_AVAILABLE Key not available
 257   */
 258   int Delete(const std::string& key);
 259
 260   /**
 261    * @brief Gets a string from the key.
 262    * @since_tizen 5.5
 263    * @param[in] key The string key
 264    * @return The string
 265   */
 266   std::string GetString(const std::string& key) const;
 267
 268   /**
 269    * @brief Gets strings from the key.
 270    * @since_tizen 5.5
 271    * @param[in] key The string key
 272    * @return The array of strings
 273   */
 274   std::vector<std::string> GetStringArray(const std::string& key) const;
 275
 276   /**
 277    * @brief Gets bytes from the key.
 278    * @since_tizen 5.5
 279    * @param[in] key The string key
 280    * @return Bytes
 281   */
 282   std::vector<unsigned char> GetByte(const std::string& key) const;
 283
 284   /**
 285    * @brief Converts this object to BundleRaw type.
 286    * @since_tizen 5.5
 287    * @param[in] base64 @c true, the BundleRaw will be encoded using base64-encoding.
 288    * @return The object of BundleRaw
 289   */
 290   BundleRaw ToRaw(bool base64 = true);
 291
 292   /**
 293    * @brief Gets the count of keys.
 294    * @since_tizen 5.5
 295    * @return The count
 296   */
 297   int GetCount() const;
 298
 299   /**
 300    * @brief Gets the data type from the key.
 301    * @since_tizen 5.5
 302    * @param[in] key The string key
 303    * @return The data type
 304   */
 305   bundle_type GetType(const std::string& key) const;
 306
 307   /**
 308    * @brief Gets the handle for bundle APIs.
 309    * @since_tizen 5.5
 310    * @return The handle for bundle
 311   */
 312   bundle* GetHandle() const;
 313
 314   /**
 315    * @brief Moves this object into the bundle handle.
 316    * @since_tizen 5.5
 317    * @return The handle for bundle
 318   */
 319   bundle* Detach();
 320
 321  private:
 322   class Impl;
 323   std::unique_ptr<Impl> impl_;
 324 };
 325
 326 }  // namespace tizen_base
 327
 328 /**
 329  * @}
 330  */
 331
 332 #endif  // BUNDLE_CPP_H_