doc/elektra-api/latex/group__backendhandle.tex

   1 \section{KDB Backends :: KDB access functions}
   2 \label{group__backendhandle}\index{KDB Backends :: KDB access functions@{KDB Backends :: KDB access functions}}
   3 Methods to access the backend handle.
   4 \subsection*{Functions}
   5 \begin{CompactItemize}
   6 \item
   7 void $\ast$ {\bf kdbhSetBackendData} (KDB $\ast$handle, void $\ast$data)
   8 \item
   9 void $\ast$ {\bf kdbhGetBackendData} (const KDB $\ast$handle)
  10 \item
  11 KDBCap $\ast$ {\bf kdbhSetCapability} (KDB $\ast$handle, KDBCap $\ast$cap)
  12 \item
  13 KDBCap $\ast$ {\bf kdbhGetCapability} (const KDB $\ast$handle)
  14 \item
  15 Trie $\ast$ {\bf kdbhGetTrie} (const KDB $\ast$handle)
  16 \item
  17 void {\bf kdbhSetTrie} (KDB $\ast$handle, Trie $\ast$trie)
  18 \item
  19 const Key $\ast$ {\bf kdbhGetMountpoint} (KDB $\ast$handle)
  20 \item
  21 void {\bf kdbhSetMountpoint} (KDB $\ast$handle, const Key $\ast$mountpoint)
  22 \item
  23 KeySet $\ast$ {\bf kdbhGetConfig} (KDB $\ast$handle)
  24 \end{CompactItemize}
  25
  26
  27 \subsection{Detailed Description}
  28 Methods to access the backend handle.
  29
  30 To use them:
  31
  32 \begin{Code}\begin{verbatim} #include <kdb.h>
  33 \end{verbatim}
  34 \end{Code}
  35
  36
  37
  38 These functions provide access to the information stored in Backend Handles.
  39
  40 \subsection{Function Documentation}
  41 \index{backendhandle@{backendhandle}!kdbhGetBackendData@{kdbhGetBackendData}}
  42 \index{kdbhGetBackendData@{kdbhGetBackendData}!backendhandle@{backendhandle}}
  43 \subsubsection[kdbhGetBackendData]{\setlength{\rightskip}{0pt plus 5cm}void$\ast$ kdbhGetBackendData (const KDB $\ast$ {\em handle})}\label{group__backendhandle_ge463be8651422015fd12811ed66d20f3}
  44
  45
  46 Get the previously set backend-specific {\tt data} from the {\tt handle}.
  47
  48 This is useful when your backend have a backend-global context or environment.
  49
  50 This method will probably be called everytime one of your kdb$\ast$() implementations is called. And if you change something inside the data, you don't have to \doxyref{kdbhSetBackendData()}{p.}{group__backendhandle_g97fab712e488c7ec3e198492106724ab} again, bacause you are manipulating your data, and not a copy of it.
  51
  52 \begin{Desc}
  53 \item[Example:]
  54
  55 \begin{Code}\begin{verbatim}struct MyBackendData {
  56  int context1;
  57  int context2;
  58 };
  59
  60 int kdbOpen_mybackend(KDB *handle) {
  61         struct MyBackendData *context;
  62
  63         context=malloc(sizeof(struct MyBackendData));
  64
  65         // a random initialization...
  66         context->context1=1;
  67         context->context2=2;
  68
  69         kdbhSetBackendData(*handle,context);
  70
  71         return 0;
  72 }
  73
  74 int kdbGetKey_maybackend(KDB handle) {
  75         struct MyBackendData *context;
  76
  77         context=kdbhGetBackendData(handle);
  78
  79         // No do something with the context
  80         . . .
  81
  82         return 0;
  83 }
  84 \end{verbatim}
  85 \end{Code}
  86
  87 \end{Desc}
  88 On the \doxyref{kdbClose()}{p.}{group__kdb_gd9bb8bd3f1296bfa77cc9a1b41b7a859} implementation of your backend, you must remember to free all resources associated to your data.
  89
  90 \begin{Desc}
  91 \item[Example of kdbClose() implementation that correctly cleans the context:]
  92
  93 \begin{Code}\begin{verbatim}int kdbClose_mybackend(KDB &handle) {
  94         struct MyBackendData *context;
  95
  96         context=kdbhGetBackendData(handle);
  97         free(context);
  98
  99         return 0;
 100 }
 101 \end{verbatim}
 102 \end{Code}
 103
 104  \end{Desc}
 105 \begin{Desc}
 106 \item[Returns:]a pointer to the data previously set be \doxyref{kdbhSetBackendData()}{p.}{group__backendhandle_g97fab712e488c7ec3e198492106724ab} \end{Desc}
 107 \begin{Desc}
 108 \item[Parameters:]
 109 \begin{description}
 110 \item[{\em handle}]contains internal information of \doxyref{opened }{p.}{group__kdb_gb7be60c387892d2235907836c5060e1f} key database \end{description}
 111 \end{Desc}
 112 \index{backendhandle@{backendhandle}!kdbhGetCapability@{kdbhGetCapability}}
 113 \index{kdbhGetCapability@{kdbhGetCapability}!backendhandle@{backendhandle}}
 114 \subsubsection[kdbhGetCapability]{\setlength{\rightskip}{0pt plus 5cm}KDBCap$\ast$ kdbhGetCapability (const KDB $\ast$ {\em handle})}\label{group__backendhandle_g090cfa7483afbb159b75c975eb1d513c}
 115
 116
 117 Gets capability for handle.
 118
 119 \begin{Desc}
 120 \item[Parameters:]
 121 \begin{description}
 122 \item[{\em handle}]contains internal information of \doxyref{opened }{p.}{group__kdb_gb7be60c387892d2235907836c5060e1f} key database \end{description}
 123 \end{Desc}
 124 \begin{Desc}
 125 \item[Returns:]The backend name set in {\tt handle}. \end{Desc}
 126 \index{backendhandle@{backendhandle}!kdbhGetConfig@{kdbhGetConfig}}
 127 \index{kdbhGetConfig@{kdbhGetConfig}!backendhandle@{backendhandle}}
 128 \subsubsection[kdbhGetConfig]{\setlength{\rightskip}{0pt plus 5cm}KeySet$\ast$ kdbhGetConfig (KDB $\ast$ {\em handle})}\label{group__backendhandle_gb14dc8708c2ae4ffcba6cfb130019115}
 129
 130
 131 Returns configuration for handle.
 132
 133 Every backend may have its own configuration using a Keyset.
 134
 135 \begin{Desc}
 136 \item[Parameters:]
 137 \begin{description}
 138 \item[{\em handle}]contains internal information of \doxyref{opened }{p.}{group__kdb_gb7be60c387892d2235907836c5060e1f} key database \end{description}
 139 \end{Desc}
 140 \begin{Desc}
 141 \item[Returns:]the keyset containing configuration for a backend \end{Desc}
 142 \index{backendhandle@{backendhandle}!kdbhGetMountpoint@{kdbhGetMountpoint}}
 143 \index{kdbhGetMountpoint@{kdbhGetMountpoint}!backendhandle@{backendhandle}}
 144 \subsubsection[kdbhGetMountpoint]{\setlength{\rightskip}{0pt plus 5cm}const Key$\ast$ kdbhGetMountpoint (KDB $\ast$ {\em handle})}\label{group__backendhandle_g8b5612940fc9bc56e99c15ecc427cbb2}
 145
 146
 147 Gets mountpoint for handle.
 148
 149 Every mounted backend has a specific mountpoint where it is mounted. You may need to know where you were mounted inside a backend to calculate relative pathes.
 150
 151 The \doxyref{keyName()}{p.}{group__keyname_g8e805c726a60da921d3736cda7813513} is where the backend is mounted, keyString() gives the name of which backend is mounted.
 152
 153 \begin{Desc}
 154 \item[Parameters:]
 155 \begin{description}
 156 \item[{\em handle}]contains internal information of \doxyref{opened }{p.}{group__kdb_gb7be60c387892d2235907836c5060e1f} key database \end{description}
 157 \end{Desc}
 158 \begin{Desc}
 159 \item[See also:]\doxyref{kdbhSetMountpoint()}{p.}{group__backendhandle_g65c8878c24776c77716ac9e8abe1a29f} \end{Desc}
 160 \begin{Desc}
 161 \item[Returns:]The Key containing the mountpoint. \end{Desc}
 162 \index{backendhandle@{backendhandle}!kdbhGetTrie@{kdbhGetTrie}}
 163 \index{kdbhGetTrie@{kdbhGetTrie}!backendhandle@{backendhandle}}
 164 \subsubsection[kdbhGetTrie]{\setlength{\rightskip}{0pt plus 5cm}Trie$\ast$ kdbhGetTrie (const KDB $\ast$ {\em handle})}\label{group__backendhandle_g591d15bf10d8f4366ec7e1e9b8c6ddc7}
 165
 166
 167 Gets trie for handle.
 168
 169 The trie is a datastructure containing the mounted backends.
 170
 171 \begin{Desc}
 172 \item[Parameters:]
 173 \begin{description}
 174 \item[{\em handle}]contains internal information of \doxyref{opened }{p.}{group__kdb_gb7be60c387892d2235907836c5060e1f} key database \end{description}
 175 \end{Desc}
 176 \begin{Desc}
 177 \item[See also:]\doxyref{kdbhSetTrie()}{p.}{group__backendhandle_g1c5c086715963f34f2a88fac89b62f82} \end{Desc}
 178 \begin{Desc}
 179 \item[Returns:]The backend name set in {\tt handle}. \end{Desc}
 180 \index{backendhandle@{backendhandle}!kdbhSetBackendData@{kdbhSetBackendData}}
 181 \index{kdbhSetBackendData@{kdbhSetBackendData}!backendhandle@{backendhandle}}
 182 \subsubsection[kdbhSetBackendData]{\setlength{\rightskip}{0pt plus 5cm}void$\ast$ kdbhSetBackendData (KDB $\ast$ {\em handle}, \/  void $\ast$ {\em data})}\label{group__backendhandle_g97fab712e488c7ec3e198492106724ab}
 183
 184
 185 Set some backend-specific {\tt data} in the {\tt handle}.
 186
 187 This is useful when your backend have a backend-global context or environment.
 188
 189 \begin{Desc}
 190 \item[Parameters:]
 191 \begin{description}
 192 \item[{\em handle}]contains internal information of \doxyref{opened }{p.}{group__kdb_gb7be60c387892d2235907836c5060e1f} key database \item[{\em data}]a pointer to general data specific to a backend implementation. \end{description}
 193 \end{Desc}
 194 \begin{Desc}
 195 \item[See also:]\doxyref{kdbhGetBackendData()}{p.}{group__backendhandle_ge463be8651422015fd12811ed66d20f3} \end{Desc}
 196 \index{backendhandle@{backendhandle}!kdbhSetCapability@{kdbhSetCapability}}
 197 \index{kdbhSetCapability@{kdbhSetCapability}!backendhandle@{backendhandle}}
 198 \subsubsection[kdbhSetCapability]{\setlength{\rightskip}{0pt plus 5cm}KDBCap$\ast$ kdbhSetCapability (KDB $\ast$ {\em handle}, \/  KDBCap $\ast$ {\em cap})}\label{group__backendhandle_gd077fae396d9be2b9d5e01b6f9f60318}
 199
 200
 201 Sets capabilty for handle.
 202
 203 \begin{Desc}
 204 \item[Parameters:]
 205 \begin{description}
 206 \item[{\em cap}]a pointer to capability structure \item[{\em handle}]contains internal information of \doxyref{opened }{p.}{group__kdb_gb7be60c387892d2235907836c5060e1f} key database \end{description}
 207 \end{Desc}
 208 \begin{Desc}
 209 \item[Returns:]The backend name set in {\tt handle}. \end{Desc}
 210 \index{backendhandle@{backendhandle}!kdbhSetMountpoint@{kdbhSetMountpoint}}
 211 \index{kdbhSetMountpoint@{kdbhSetMountpoint}!backendhandle@{backendhandle}}
 212 \subsubsection[kdbhSetMountpoint]{\setlength{\rightskip}{0pt plus 5cm}void kdbhSetMountpoint (KDB $\ast$ {\em handle}, \/  const Key $\ast$ {\em mountpoint})}\label{group__backendhandle_g65c8878c24776c77716ac9e8abe1a29f}
 213
 214
 215 Sets mountpoint for handle.
 216
 217 You must not change the mountpoint inside your backend, it was set correctly already for you.
 218
 219 \begin{Desc}
 220 \item[Parameters:]
 221 \begin{description}
 222 \item[{\em handle}]contains internal information of \doxyref{opened }{p.}{group__kdb_gb7be60c387892d2235907836c5060e1f} key database \item[{\em mountpoint}]the key containing as name where backend is mounted and as value the backendname \end{description}
 223 \end{Desc}
 224 \begin{Desc}
 225 \item[See also:]\doxyref{kdbhGetMountpoint()}{p.}{group__backendhandle_g8b5612940fc9bc56e99c15ecc427cbb2} \end{Desc}
 226 \begin{Desc}
 227 \item[Returns:]nothing \end{Desc}
 228 \index{backendhandle@{backendhandle}!kdbhSetTrie@{kdbhSetTrie}}
 229 \index{kdbhSetTrie@{kdbhSetTrie}!backendhandle@{backendhandle}}
 230 \subsubsection[kdbhSetTrie]{\setlength{\rightskip}{0pt plus 5cm}void kdbhSetTrie (KDB $\ast$ {\em handle}, \/  Trie $\ast$ {\em trie})}\label{group__backendhandle_g1c5c086715963f34f2a88fac89b62f82}
 231
 232
 233 Sets trie for handle.
 234
 235 The trie is a datastructure containing the mounted backends. This must not done inside backends, it was set correctly already for you.
 236
 237 \begin{Desc}
 238 \item[Parameters:]
 239 \begin{description}
 240 \item[{\em handle}]contains internal information of \doxyref{opened }{p.}{group__kdb_gb7be60c387892d2235907836c5060e1f} key database \item[{\em trie}]the datastructure referencing to the other handles of backends \end{description}
 241 \end{Desc}
 242 \begin{Desc}
 243 \item[See also:]\doxyref{kdbhGetTrie()}{p.}{group__backendhandle_g591d15bf10d8f4366ec7e1e9b8c6ddc7} \end{Desc}
 244 \begin{Desc}
 245 \item[Returns:]nothing \end{Desc}