LCOV - code coverage report
Current view: top level - src/bindings/cpp/include - kdb.hpp (source / functions) Hit Total Coverage
Test: coverage-filtered.info Lines: 44 48 91.7 %
Date: 2019-09-12 12:28:41 Functions: 10 11 90.9 %

          Line data    Source code
       1             : /**
       2             :  * @file
       3             :  *
       4             :  * @brief
       5             :  *
       6             :  * @copyright BSD License (see LICENSE.md or https://www.libelektra.org)
       7             :  */
       8             : 
       9             : #ifndef ELEKTRA_KDB_HPP
      10             : #define ELEKTRA_KDB_HPP
      11             : 
      12             : #include <string>
      13             : 
      14             : #include <kdbexcept.hpp>
      15             : #include <key.hpp>
      16             : #include <keyset.hpp>
      17             : 
      18             : #include <kdb.h>
      19             : 
      20             : 
      21             : /**
      22             :  * @brief This is the main namespace for the C++ binding and libraries.
      23             :  *
      24             :  * Classes or Functions directly below this namespace are header-only.
      25             :  * Sub namespaces are intended for libraries and you need to link
      26             :  * the library if you want to use them.
      27             :  * - @see kdb::tools
      28             :  */
      29             : namespace kdb
      30             : {
      31             : 
      32             : /**
      33             :  * @copydoc KDB
      34             :  *
      35             :  * @brief Access to the key database.
      36             :  *
      37             :  * @invariant the object holds a valid connection to the key database
      38             :  * or is empty
      39             :  */
      40           0 : class KDB
      41             : {
      42             : public:
      43             :         KDB ();
      44             :         explicit KDB (Key & errorKey);
      45          28 :         virtual ~KDB () throw ()
      46       15745 :         {
      47       10237 :                 close ();
      48          28 :         }
      49             : 
      50             :         virtual inline void open (Key & errorKey);
      51             :         virtual inline void close () throw ();
      52             :         virtual inline void close (Key & errorKey) throw ();
      53             : 
      54             :         virtual inline int get (KeySet & returned, std::string const & keyname);
      55             :         virtual inline int get (KeySet & returned, Key & parentKey);
      56             :         virtual inline int set (KeySet & returned, std::string const & keyname);
      57             :         virtual inline int set (KeySet & returned, Key & parentKey);
      58             : 
      59             :         inline int ensure (const KeySet & contract, Key & parentKey);
      60             : 
      61             : private:
      62             :         ckdb::KDB * handle; ///< holds an kdb handle
      63             : };
      64             : 
      65             : /**
      66             :  * Constructs a class KDB.
      67             :  *
      68             :  * @throw KDBException if database could not be opened
      69             :  *
      70             :  * @copydoc kdbOpen
      71             :  */
      72        9790 : inline KDB::KDB ()
      73             : {
      74       19580 :         Key errorKey;
      75        9790 :         open (errorKey);
      76        9790 : }
      77             : 
      78             : /**
      79             :  * Constructs a class KDB.
      80             :  *
      81             :  * @param errorKey is useful if you want to get the warnings in
      82             :  * the successful case, when no exception is thrown.
      83             :  *
      84             :  * @throw KDBException if database could not be opened
      85             :  *
      86             :  * @copydoc kdbOpen
      87             :  */
      88         447 : inline KDB::KDB (Key & errorKey)
      89             : {
      90         447 :         open (errorKey);
      91             : }
      92             : 
      93             : /**
      94             :  * Open the database
      95             :  *
      96             :  * @param errorKey is useful if you want to get the warnings in
      97             :  * the successful case, when no exception is thrown.
      98             :  *
      99             :  * @copydoc kdbOpen
     100             :  */
     101       10259 : inline void KDB::open (Key & errorKey)
     102             : {
     103       10259 :         handle = ckdb::kdbOpen (errorKey.getKey ());
     104       10259 :         if (!handle)
     105             :         {
     106           0 :                 throw kdb::KDBException (errorKey);
     107             :         }
     108       10259 : }
     109             : 
     110             : /**
     111             :  * Close the database.
     112             :  *
     113             :  * The return value does not matter because its only a null pointer check.
     114             :  *
     115             :  * @copydoc kdbClose
     116             :  */
     117       10241 : inline void KDB::close () throw ()
     118             : {
     119       20482 :         Key errorKey;
     120       10241 :         ckdb::kdbClose (handle, errorKey.getKey ());
     121       10241 :         handle = nullptr;
     122       10241 : }
     123             : 
     124             : 
     125             : /**
     126             :  * Close the database.
     127             :  *
     128             :  * The return value does not matter because its only a null pointer check.
     129             :  *
     130             :  * @param errorKey is useful if you want to get the warnings
     131             :  *
     132             :  * @copydoc kdbClose
     133             :  */
     134          34 : inline void KDB::close (Key & errorKey) throw ()
     135             : {
     136          34 :         ckdb::kdbClose (handle, errorKey.getKey ());
     137          34 :         handle = nullptr;
     138          34 : }
     139             : 
     140             : /**
     141             :  * @class doxygenKDBReturn
     142             :  * @brief
     143             :  *
     144             :  * @retval 0 if no key was updated
     145             :  * @retval 1 if user or system keys were updated
     146             :  * @retval 2 if user and system keys were updated
     147             :  */
     148             : 
     149             : /**
     150             :  * Get all keys below keyname inside returned.
     151             :  *
     152             :  * @copydoc kdbGet
     153             :  *
     154             :  * @include cpp_example_get.cpp
     155             :  *
     156             :  * @param returned the keyset where the keys will be in
     157             :  * @param keyname the root keyname which should be used to get keys below it
     158             :  *
     159             :  * @copydetails doxygenKDBReturn
     160             :  *
     161             :  * @throw KDBException if there were problems with the database
     162             :  *
     163             :  * @see KDB::get (KeySet & returned, Key & parentKey)
     164             :  */
     165       10871 : inline int KDB::get (KeySet & returned, std::string const & keyname)
     166             : {
     167       21742 :         Key parentKey (keyname.c_str (), KEY_CASCADING_NAME, KEY_END);
     168       21740 :         return get (returned, parentKey);
     169             : }
     170             : 
     171             : /**
     172             :  * Get all keys below parentKey inside returned.
     173             :  *
     174             :  * @copydoc kdbGet
     175             :  *
     176             :  * @param returned the keyset where the keys will be in
     177             :  * @param parentKey the parentKey of returned
     178             :  *
     179             :  * @copydetails doxygenKDBReturn
     180             :  *
     181             :  * @throw KDBException if there were problems with the database
     182             :  */
     183       15396 : inline int KDB::get (KeySet & returned, Key & parentKey)
     184             : {
     185       30792 :         int ret = ckdb::kdbGet (handle, returned.getKeySet (), parentKey.getKey ());
     186       15396 :         if (ret == -1)
     187             :         {
     188          54 :                 throw KDBException (parentKey);
     189             :         }
     190       15378 :         return ret;
     191             : }
     192             : 
     193             : /**
     194             :  * Set all keys below keyname.
     195             :  *
     196             :  * If the keyname of the parentKey is invalid (e.g. empty) all keys will be set.
     197             :  *
     198             :  * @copydoc kdbSet
     199             :  *
     200             :  * @copydetails doxygenKDBReturn
     201             :  *
     202             :  * @param returned the keyset where the keys will be in
     203             :  * @param keyname the keyname below the names should be set
     204             :  *
     205             :  * @throw KDBException if there were problems with the database
     206             :  */
     207          78 : inline int KDB::set (KeySet & returned, std::string const & keyname)
     208             : {
     209         156 :         Key parentKey (keyname.c_str (), KEY_CASCADING_NAME, KEY_END);
     210         150 :         return set (returned, parentKey);
     211             : }
     212             : 
     213             : /**
     214             :  * Set all keys below parentKey.
     215             :  *
     216             :  * If the keyname of the parentKey is invalid (e.g. empty) all keys will be set.
     217             :  *
     218             :  * @copydoc kdbSet
     219             :  *
     220             :  * @copydetails doxygenKDBReturn
     221             :  *
     222             :  * @param returned the keyset where the keys are passed to the user
     223             :  * @param parentKey the parentKey of returned
     224             :  *
     225             :  * @throw KDBException if there were problems with the database
     226             :  */
     227        1928 : inline int KDB::set (KeySet & returned, Key & parentKey)
     228             : {
     229        3856 :         int ret = ckdb::kdbSet (handle, returned.getKeySet (), parentKey.getKey ());
     230        1928 :         if (ret == -1)
     231             :         {
     232         276 :                 throw KDBException (parentKey);
     233             :         }
     234        1836 :         return ret;
     235             : }
     236             : 
     237             : /**
     238             :  * Ensures that the conditions defined in @p contract are met by this KDB.
     239             :  *
     240             :  * @see ckdb::kdbEnsure()
     241             :  *
     242             :  * @param contract  The contract to ensure.
     243             :  * @param parentKey The parentKey to use.
     244             :  *
     245             :  * @throw KDBException if there were problems with the contract or the database
     246             :  * @throw ContractException if the contract couldn't be ensured
     247             :  */
     248          14 : int KDB::ensure (const KeySet & contract, Key & parentKey)
     249             : {
     250             :         // have to ksDup because contract is consumed and ksDel()ed by kdbEnsure
     251          28 :         int ret = ckdb::kdbEnsure (handle, ckdb::ksDup (contract.getKeySet ()), parentKey.getKey ());
     252          14 :         if (ret == -1)
     253             :         {
     254           0 :                 throw KDBException (parentKey);
     255             :         }
     256          14 :         if (ret == 1)
     257             :         {
     258           0 :                 throw ContractException (parentKey);
     259             :         }
     260          14 :         return ret;
     261             : }
     262             : 
     263             : 
     264             : } // end of namespace kdb
     265             : 
     266             : #endif

Generated by: LCOV version 1.13