1KeyDB :: High Level methods(L3i)brary Functions ManuKaelyDB :: High Level methods(3)
2
3
4

NAME

6       KeyDB :: High Level methods - High level methods to access the Key
7       database.
8
9
10   Functions
11       int kdbGetValue (KDBHandle handle, const char *keyname, char *returned,
12           size_t maxSize)
13           A high-level method to get a key value, by key name.
14       int kdbSetValue (KDBHandle handle, const char *keyname, const char
15           *value)
16           A high-level method to set a value to a key, by key name.
17       int kdbGetValueByParent (KDBHandle handle, const char *parentName,
18           const char *baseName, char *returned, size_t maxSize)
19           Fill up the returned buffer with the value of a key, which name is
20           the concatenation of parentName and baseName.
21       int kdbSetValueByParent (KDBHandle handle, const char *parentName,
22           const char *baseName, const char *value)
23           Sets the provided value to the key whose name is the concatenation
24           of parentName and baseName.
25       int kdbGetKeyByParent (KDBHandle handle, const char *parentName, const
26           char *baseName, Key *returned)
27           Given a parent key name plus a basename, returns the key.
28       int kdbGetKeyByParentKey (KDBHandle handle, const Key *parent, const
29           char *baseName, Key *returned)
30           Similar to previous, provided for convenience.
31       ssize_t kdbGetChildKeys (KDBHandle handle, const char *parentName,
32           KeySet *returned, unsigned long options)
33           This method is similar and calls kdbGetKeyChildKeys().
34       ssize_t kdbGetRootKeys (KDBHandle handle, KeySet *returned)
35           Returns a KeySet with all root keys currently recognized and
36           present on the system.
37       int kdbRemove (KDBHandle handle, const char *keyName)
38           Remove a key by its name from the backend storage.
39

Detailed Description

41       High level methods to access the Key database.
42
43       To use them:
44
45        #include <kdb.h>
46
47
48       These methods are higher level. They use the above methods to do their
49       job, and don't have to be reimplemented for a different backend.
50
51       Binding writers don't have to implement these functions, use features
52       of the binding language instead. But you can use these functions as
53       ideas what high level methods may be useful.
54

Function Documentation

56   int kdbGetValue (KDBHandle handle, const char * keyname, char * returned,
57       size_t maxSize)
58       A high-level method to get a key value, by key name.
59
60       This method is valid only for string keys. You have to use other
61       methods to get non-string keys.
62
63       Parameters:
64           keyname the name of the key to receive the value
65           returned a buffer to put the key value
66           maxSize the size of the buffer
67
68       Returns:
69           0 on success
70
71           -1 on failure and errno is propagated
72
73       See also:
74           kdbSetValue(), kdbGetKey(), kdbGetValueByParent(), keyGetString()
75
76       Definition at line 114 of file kdbhighlevel.c.
77
78       References kdbGetKey(), KEY_SWITCH_END, keyDel(), keyGetString(), and
79       keyNew().
80
81       Referenced by kdbGetValueByParent().
82
83   int kdbSetValue (KDBHandle handle, const char * keyname, const char *
84       value)
85       A high-level method to set a value to a key, by key name.
86
87       It will obviously check if key exists first, and keep its metadata. So
88       you'll not loose the precious key comment.
89
90       This will set a text key. So if the key was previously a binary, etc
91       key, it will be retyped as text.
92
93       Parameters:
94           keyname the name of the key to receive the value
95           value the value to be set
96
97       Returns:
98           0 on success
99
100           -1 on failure and errno is propagated KDB_RET_TYPEMISMATCH if key
101           is a directory
102
103       See also:
104           kdbGetValue(), keySetString(), kdbSetKey()
105
106       Definition at line 145 of file kdbhighlevel.c.
107
108       References KDB_RET_TYPEMISMATCH, kdbGetKey(), kdbSetKey(),
109       KEY_SWITCH_END, keyDel(), keyIsDir(), keyNew(), and keySetString().
110
111       Referenced by kdbSetValueByParent().
112
113   int kdbGetValueByParent (KDBHandle handle, const char * parentName, const
114       char * baseName, char * returned, size_t maxSize)
115       Fill up the returned buffer with the value of a key, which name is the
116       concatenation of parentName and baseName.
117
118       Example:.RS 4
119
120
121       char *parent='user/sw/MyApp';
122       char *keys[]={'key1','key2','key3'};
123       char buffer[150];   // a big buffer
124       int c;
125
126       for (c=0; c<3; c++) {
127           kdbGetValueByParent(handle,parent,keys[c],buffer,sizeof(buffer));
128           // Do something with buffer....
129       }
130
131
132       Parameters:
133           parentName the name of the parent key
134           baseName the name of the child key
135           returned pre-allocated buffer to be filled with key value
136           maxSize size of the returned buffer
137
138       Returns:
139           0 on success
140
141           -1 on failure and errno is propagated
142
143       See also:
144           kdbGetKeyByParent()
145
146       Definition at line 193 of file kdbhighlevel.c.
147
148       References kdbGetValue(), _KDBBackend::name, and strblen().
149
150   int kdbSetValueByParent (KDBHandle handle, const char * parentName, const
151       char * baseName, const char * value)
152       Sets the provided value to the key whose name is the concatenation of
153       parentName and baseName.
154
155       Parameters:
156           parentName the name of the parent key
157           baseName the name of the child key
158           value the value to set
159
160       Returns:
161           0 on success
162
163           -1 on failure and errno is propagated
164
165       Definition at line 217 of file kdbhighlevel.c.
166
167       References kdbSetValue(), _KDBBackend::name, and strblen().
168
169   int kdbGetKeyByParent (KDBHandle handle, const char * parentName, const
170       char * baseName, Key * returned)
171       Given a parent key name plus a basename, returns the key.
172
173       So here you'll provide something like
174
175       · system/sw/myApp plus key1 to get system/sw/myApp/key1
176
177       · user/sw/MyApp plus dir1/key2 to get user/sw/MyApp/dir1/key2
178
179       Parameters:
180           parentName parent key name
181           baseName leaf or child name
182           returned a pointer to an initialized key to be filled
183
184       Returns:
185           0 on success
186
187           -1 on failure and errno is propagated
188
189       See also:
190           kdbGetKey(), kdbGetValueByParent(), kdbGetKeyByParentKey()
191
192       Definition at line 245 of file kdbhighlevel.c.
193
194       References kdbGetKey(), keySetName(), _KDBBackend::name, and strblen().
195
196   int kdbGetKeyByParentKey (KDBHandle handle, const Key * parent, const char
197       * baseName, Key * returned)
198       Similar to previous, provided for convenience.
199
200       Parameters:
201           parent pointer to the parent key
202
203       See also:
204           kdbGetKey(), kdbGetKeyByParent(), kdbGetValueByParent()
205
206       Returns:
207           0 on success, or what kdbGetKey() returns, and errno is set
208
209       Definition at line 263 of file kdbhighlevel.c.
210
211       References kdbGetKey(), keyGetFullName(), keyGetFullNameSize(),
212       keySetName(), _KDBBackend::name, and strblen().
213
214   ssize_t kdbGetChildKeys (KDBHandle handle, const char * parentName, KeySet
215       * returned, unsigned long options)
216       This method is similar and calls kdbGetKeyChildKeys().
217
218       It is provided for convenience.
219
220       Instead of passing the parentName with a key it directly uses a string.
221
222       Returns:
223           0 on success
224
225           -1 on failure and errno is propagated from kdbGetKeyChildKeys()
226
227       See also:
228           kdbGetKeyChildKeys()
229
230       Definition at line 290 of file kdbhighlevel.c.
231
232       References kdbGetKeyChildKeys(), KEY_SWITCH_END, keyDel(), and
233       keyNew().
234
235       Referenced by commandEdit(), and commandList().
236
237   ssize_t kdbGetRootKeys (KDBHandle handle, KeySet * returned)
238       Returns a KeySet with all root keys currently recognized and present on
239       the system.
240
241       Currently, the system and current user's user keys are returned.
242
243       Parameters:
244           returned the initialized KeySet to be filled
245
246       Returns:
247           the number of root keys found
248
249           -1 on failure and errno is propagated
250
251       See also:
252           KeyNamespace
253
254           commandList() code in KeyDB :: Class Methods command for usage
255           example
256
257       Definition at line 318 of file kdbhighlevel.c.
258
259       References _Key::flags, KEY_SWITCH_END, KEY_SWITCH_FLAG,
260       KEY_SWITCH_NEEDSYNC, keyDel(), keyNew(), ksInsert(), and _KeySet::size.
261
262       Referenced by commandList().
263
264   int kdbRemove (KDBHandle handle, const char * keyName)
265       Remove a key by its name from the backend storage.
266
267       This is a convenience to kdbRemoveKey().
268
269       Parameters:
270           keyName the name of the key to be removed
271
272       Returns:
273           0 on success
274
275           -1 on failure and errno is propagated
276
277       See also:
278           commandRemove() code in KeyDB :: Class Methods command for usage
279           example
280
281       Definition at line 350 of file kdbhighlevel.c.
282
283       References kdbRemoveKey(), KEY_SWITCH_END, keyDel(), keyNew(), and
284       keySetName().
285
286       Referenced by commandEdit(), and commandRemove().
287
288
289
290Elektra Project                   25 Mar 2007   KeyDB :: High Level methods(3)