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