doc/elektra-api/latex/group__kdbhighlevel.tex

   1 \section{KDB :: High Level methods}
   2 \label{group__kdbhighlevel}\index{KDB :: High Level methods@{KDB :: High Level methods}}
   3 High level methods to access the Key database.
   4 \subsection*{Functions}
   5 \begin{CompactItemize}
   6 \item
   7 int {\bf kdbGetKey} (KDB $\ast$handle, Key $\ast$dest)
   8 \item
   9 int {\bf kdbSetKey} (KDB $\ast$handle, const Key $\ast$key)
  10 \item
  11 int {\bf kdbGetString} (KDB $\ast$handle, const char $\ast$keyname, char $\ast$returned, size\_\-t maxSize)
  12 \item
  13 int {\bf kdbSetString} (KDB $\ast$handle, const char $\ast$keyname, const char $\ast$value)
  14 \item
  15 int {\bf kdbRemove} (KDB $\ast$handle, const char $\ast$keyname)
  16 \item
  17 ssize\_\-t {\bf kdbGetByName} (KDB $\ast$handle, KeySet $\ast$returned, const char $\ast$name, option\_\-t options)
  18 \end{CompactItemize}
  19
  20
  21 \subsection{Detailed Description}
  22 High level methods to access the Key database.
  23
  24 To use them:
  25
  26 \begin{Code}\begin{verbatim} #include <kdb.h>
  27 \end{verbatim}
  28 \end{Code}
  29
  30
  31
  32 These methods are higher level. They use \doxyref{kdbOpen()}{p.}{group__kdb_gb7be60c387892d2235907836c5060e1f}, \doxyref{kdbClose()}{p.}{group__kdb_gd9bb8bd3f1296bfa77cc9a1b41b7a859}, \doxyref{kdbGet()}{p.}{group__kdb_g37b44bda1b83bc0144916bf21a86c1b5} and \doxyref{kdbSet()}{p.}{group__kdb_g953cf29721e6000c2516cd6b5d36f571} methods to do their job, and don't have to be reimplemented for a different backend.
  33
  34 These functions avoid limitations through not implemented capabilities. This will of course cost some effort, so read through the description carefully and decide if it is appropriate for your problem.
  35
  36 Binding writers don't have to implement these functions, use features of the binding language instead. But you can use these functions as ideas what high level methods may be useful.
  37
  38 Don't use writing single keys in a loop, prefer always writing out a keyset!
  39
  40 \subsection{Function Documentation}
  41 \index{kdbhighlevel@{kdbhighlevel}!kdbGetByName@{kdbGetByName}}
  42 \index{kdbGetByName@{kdbGetByName}!kdbhighlevel@{kdbhighlevel}}
  43 \subsubsection[kdbGetByName]{\setlength{\rightskip}{0pt plus 5cm}ssize\_\-t kdbGetByName (KDB $\ast$ {\em handle}, \/  KeySet $\ast$ {\em returned}, \/  const char $\ast$ {\em name}, \/  option\_\-t {\em options})}\label{group__kdbhighlevel_g3013d5768bbcf3c34652f489151940e2}
  44
  45
  46 This method is similar \doxyref{kdbGet()}{p.}{group__kdb_g37b44bda1b83bc0144916bf21a86c1b5} but the path is given by a string.
  47
  48 When it is not possible to make a key out of that string -1 is returned .
  49
  50 When parentName starts with / cascading will be used and both keys from user and system will be fetched.
  51
  52 A typically app with about 3000 keys may have this line:
  53
  54
  55
  56 \begin{Code}\begin{verbatim}KDB *handle = kdbOpen();
  57 KeySet *myConfig = (4096, KS_END);
  58 ssize_t ret = kdbGetByName (handle, myConfig, "/sw/app/current", 0);
  59
  60 // check ret and work with keyset myConfig
  61
  62 ksDel (myConfig);
  63 kdbClose (handle);
  64  *
  65 \end{verbatim}
  66 \end{Code}
  67
  68
  69
  70 myConfig will be loaded with keys from system/sw/app/current but also user/sw/app/current.
  71
  72 When one of these \doxyref{kdbGet()}{p.}{group__kdb_g37b44bda1b83bc0144916bf21a86c1b5} fails -1 will be returned, but the other \doxyref{kdbGet()}{p.}{group__kdb_g37b44bda1b83bc0144916bf21a86c1b5} will be tried too.
  73
  74 \begin{Desc}
  75 \item[Parameters:]
  76 \begin{description}
  77 \item[{\em handle}]contains internal information of \doxyref{opened }{p.}{group__kdb_gb7be60c387892d2235907836c5060e1f} key database \item[{\em name}]the name where to get the keys below \item[{\em returned}]the (pre-initialized) KeySet returned with all keys found \item[{\em options}]ORed options to control approaches Unlike to \doxyref{kdbGet()}{p.}{group__kdb_g37b44bda1b83bc0144916bf21a86c1b5} is KDB\_\-O\_\-POP set per default. \end{description}
  78 \end{Desc}
  79 \begin{Desc}
  80 \item[Returns:]number of keys contained by {\tt returned}
  81
  82 -1 on failure
  83
  84 -1 when {\tt name} is no valid key
  85
  86 -1 on NULL pointer \end{Desc}
  87 \begin{Desc}
  88 \item[See also:]\doxyref{kdbGet()}{p.}{group__kdb_g37b44bda1b83bc0144916bf21a86c1b5} \end{Desc}
  89 \index{kdbhighlevel@{kdbhighlevel}!kdbGetKey@{kdbGetKey}}
  90 \index{kdbGetKey@{kdbGetKey}!kdbhighlevel@{kdbhighlevel}}
  91 \subsubsection[kdbGetKey]{\setlength{\rightskip}{0pt plus 5cm}int kdbGetKey (KDB $\ast$ {\em handle}, \/  Key $\ast$ {\em dest})}\label{group__kdbhighlevel_ga62877888f0cad395898859395e6635f}
  92
  93
  94 Fully retrieves the passed {\tt key} from the backend storage.
  95
  96 The backend will try to get the key, identified through its name.
  97
  98 It uses \doxyref{kdbGet()}{p.}{group__kdb_g37b44bda1b83bc0144916bf21a86c1b5} for retrieving the key and copies the found data to dest.
  99
 100 While \doxyref{kdbGetKey()}{p.}{group__kdbhighlevel_ga62877888f0cad395898859395e6635f} is perfect for a simple get of a specific key, \doxyref{kdbGet()}{p.}{group__kdb_g37b44bda1b83bc0144916bf21a86c1b5} and \doxyref{kdbGetByName()}{p.}{group__kdbhighlevel_g3013d5768bbcf3c34652f489151940e2} gives you more control over the keyset.
 101
 102 \begin{Desc}
 103 \item[Parameters:]
 104 \begin{description}
 105 \item[{\em handle}]contains internal information of \doxyref{opened }{p.}{group__kdb_gb7be60c387892d2235907836c5060e1f} key database \item[{\em dest}]a pointer to a Key that has a name set \end{description}
 106 \end{Desc}
 107 \begin{Desc}
 108 \item[Returns:]0 on success
 109
 110 -1 on failure
 111
 112 -1 on NULL pointer \end{Desc}
 113 \begin{Desc}
 114 \item[See also:]\doxyref{kdbSetKey()}{p.}{group__kdbhighlevel_g23b2f5fead4cddeb5542051a197ddc20} to set a single \doxyref{Key :: Basic Methods}{p.}{group__key}
 115
 116 commandGet() code in \doxyref{KDB :: Low Level Methods}{p.}{group__kdb} command for usage example
 117
 118 \doxyref{kdbGet()}{p.}{group__kdb_g37b44bda1b83bc0144916bf21a86c1b5} and \doxyref{kdbGetByName()}{p.}{group__kdbhighlevel_g3013d5768bbcf3c34652f489151940e2} to have more control over \doxyref{KeySet :: Class Methods}{p.}{group__keyset} and options \end{Desc}
 119 \index{kdbhighlevel@{kdbhighlevel}!kdbGetString@{kdbGetString}}
 120 \index{kdbGetString@{kdbGetString}!kdbhighlevel@{kdbhighlevel}}
 121 \subsubsection[kdbGetString]{\setlength{\rightskip}{0pt plus 5cm}int kdbGetString (KDB $\ast$ {\em handle}, \/  const char $\ast$ {\em keyname}, \/  char $\ast$ {\em returned}, \/  size\_\-t {\em maxSize})}\label{group__kdbhighlevel_g1e1b1a2beace8c9ce93d16259564b51f}
 122
 123
 124 A high-level method to get a key value, by key name.
 125
 126 This method gets a backend from any backend with \doxyref{kdbGetKey()}{p.}{group__kdbhighlevel_ga62877888f0cad395898859395e6635f} and extracts the string and store it into returned. It only works with string keys.
 127
 128 This method gives you the direct relation between a keyname and the value, without any kdb specific structures. Use it when you just want some values out of the kdb namespace.
 129
 130 You need to know the maximum string length of the object. That could be the case when you e.g. save a path which is limited with MAX\_\-PATH.
 131
 132
 133
 134 \begin{Code}\begin{verbatim}KDB *handle = kdbOpen();
 135 char buffer [MAX_PATH];
 136
 137 if (kdbGetString(handle, "user/key/to/get/pathname", buffer, sizeof(buffer)) == -1)
 138 {
 139         // handle error cases
 140 } else {
 141         printf ("The keys value is %s\n", buffer);
 142 }
 143 kdbClose(handle);
 144 \end{verbatim}
 145 \end{Code}
 146
 147
 148
 149 \begin{Desc}
 150 \item[Parameters:]
 151 \begin{description}
 152 \item[{\em handle}]contains internal information of \doxyref{opened }{p.}{group__kdb_gb7be60c387892d2235907836c5060e1f} key database \item[{\em keyname}]the name of the key to receive the value \item[{\em returned}]a buffer to put the key value \item[{\em maxSize}]the size of the buffer \end{description}
 153 \end{Desc}
 154 \begin{Desc}
 155 \item[Returns:]0 on success
 156
 157 -1 on failure
 158
 159 -1 on NULL pointers
 160
 161 -1 if maxSize is 0 or larger than SSIZE\_\-MAX \end{Desc}
 162 \begin{Desc}
 163 \item[See also:]\doxyref{kdbSetString()}{p.}{group__kdbhighlevel_g8e11b3403c9616c7fb3b9b37d1cb849e} and \doxyref{kdbRemove()}{p.}{group__kdbhighlevel_gf9adbbeb3f49c63fb2f89930445c8060} to set and remove a string
 164
 165 \doxyref{kdbGetKey()}{p.}{group__kdbhighlevel_ga62877888f0cad395898859395e6635f}, keySetKey() to work with Keys
 166
 167 \doxyref{kdbGet()}{p.}{group__kdb_g37b44bda1b83bc0144916bf21a86c1b5} and \doxyref{kdbGetByName()}{p.}{group__kdbhighlevel_g3013d5768bbcf3c34652f489151940e2} for full access to \doxyref{KDB Backends :: Internal Helper for Elektra}{p.}{group__internal} datastructures \end{Desc}
 168 \index{kdbhighlevel@{kdbhighlevel}!kdbRemove@{kdbRemove}}
 169 \index{kdbRemove@{kdbRemove}!kdbhighlevel@{kdbhighlevel}}
 170 \subsubsection[kdbRemove]{\setlength{\rightskip}{0pt plus 5cm}int kdbRemove (KDB $\ast$ {\em handle}, \/  const char $\ast$ {\em keyname})}\label{group__kdbhighlevel_gf9adbbeb3f49c63fb2f89930445c8060}
 171
 172
 173 Remove a key by its name from the backend storage.
 174
 175 With \doxyref{kdbSetString()}{p.}{group__kdbhighlevel_g8e11b3403c9616c7fb3b9b37d1cb849e} its only possible to set a key with an empty string. To really remove a key in a highlevel way you can use this method.
 176
 177 \begin{Desc}
 178 \item[Parameters:]
 179 \begin{description}
 180 \item[{\em handle}]contains internal information of \doxyref{opened }{p.}{group__kdb_gb7be60c387892d2235907836c5060e1f} key database \item[{\em keyname}]the name of the key to be removed \end{description}
 181 \end{Desc}
 182 \begin{Desc}
 183 \item[Returns:]0 on success
 184
 185 -1 on failure
 186
 187 -1 on NULL pointers \end{Desc}
 188 \begin{Desc}
 189 \item[See also:]together with \doxyref{kdbSetString()}{p.}{group__kdbhighlevel_g8e11b3403c9616c7fb3b9b37d1cb849e} and \doxyref{kdbGetString()}{p.}{group__kdbhighlevel_g1e1b1a2beace8c9ce93d16259564b51f} a highlevel interface for \doxyref{KDB :: Low Level Methods}{p.}{group__kdb}
 190
 191 commandRemove() code in \doxyref{KDB :: Low Level Methods}{p.}{group__kdb} command for usage example \end{Desc}
 192 \index{kdbhighlevel@{kdbhighlevel}!kdbSetKey@{kdbSetKey}}
 193 \index{kdbSetKey@{kdbSetKey}!kdbhighlevel@{kdbhighlevel}}
 194 \subsubsection[kdbSetKey]{\setlength{\rightskip}{0pt plus 5cm}int kdbSetKey (KDB $\ast$ {\em handle}, \/  const Key $\ast$ {\em key})}\label{group__kdbhighlevel_g23b2f5fead4cddeb5542051a197ddc20}
 195
 196
 197 Sets {\tt key} in the backend storage.
 198
 199 While \doxyref{kdbSetKey()}{p.}{group__kdbhighlevel_g23b2f5fead4cddeb5542051a197ddc20} is perfect for a simple get of a specific key, \doxyref{kdbGet()}{p.}{group__kdb_g37b44bda1b83bc0144916bf21a86c1b5} and \doxyref{kdbGetByName()}{p.}{group__kdbhighlevel_g3013d5768bbcf3c34652f489151940e2} gives you more control over the keyset.
 200
 201 \begin{Desc}
 202 \item[Parameters:]
 203 \begin{description}
 204 \item[{\em handle}]contains internal information of \doxyref{opened }{p.}{group__kdb_gb7be60c387892d2235907836c5060e1f} key database \item[{\em key}]Key to set \end{description}
 205 \end{Desc}
 206 \begin{Desc}
 207 \item[Returns:]0 on success
 208
 209 -1 on failure
 210
 211 -1 on NULL pointer \end{Desc}
 212 \begin{Desc}
 213 \item[See also:]\doxyref{kdbGetKey()}{p.}{group__kdbhighlevel_ga62877888f0cad395898859395e6635f} to get a single \doxyref{Key :: Basic Methods}{p.}{group__key}
 214
 215 \doxyref{kdbSet()}{p.}{group__kdb_g953cf29721e6000c2516cd6b5d36f571} for more control over \doxyref{KeySet :: Class Methods}{p.}{group__keyset} and options
 216
 217 commandSet() code in \doxyref{KDB :: Low Level Methods}{p.}{group__kdb} command for usage example \end{Desc}
 218 \index{kdbhighlevel@{kdbhighlevel}!kdbSetString@{kdbSetString}}
 219 \index{kdbSetString@{kdbSetString}!kdbhighlevel@{kdbhighlevel}}
 220 \subsubsection[kdbSetString]{\setlength{\rightskip}{0pt plus 5cm}int kdbSetString (KDB $\ast$ {\em handle}, \/  const char $\ast$ {\em keyname}, \/  const char $\ast$ {\em value})}\label{group__kdbhighlevel_g8e11b3403c9616c7fb3b9b37d1cb849e}
 221
 222
 223 A high-level method to set a value to a key, by key name.
 224
 225 It will check if key exists first, and keep its metadata. So you'll not loose the previous key comment.
 226
 227 This will set a text key. So if the key was previously a binary it will be retyped as string.
 228
 229 \begin{Desc}
 230 \item[Parameters:]
 231 \begin{description}
 232 \item[{\em handle}]contains internal information of \doxyref{opened }{p.}{group__kdb_gb7be60c387892d2235907836c5060e1f} key database \item[{\em keyname}]the name of the key to receive the value \item[{\em value}]the value to be set \end{description}
 233 \end{Desc}
 234 \begin{Desc}
 235 \item[Returns:]0 on success
 236
 237 -1 on NULL pointers
 238
 239 -1 on failure \end{Desc}
 240 \begin{Desc}
 241 \item[See also:]\doxyref{kdbGetString()}{p.}{group__kdbhighlevel_g1e1b1a2beace8c9ce93d16259564b51f}, \doxyref{keySetString()}{p.}{group__keyvalue_g622bde1eb0e0c4994728331326340ef2}, \doxyref{kdbSetKey()}{p.}{group__kdbhighlevel_g23b2f5fead4cddeb5542051a197ddc20} \end{Desc}