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