src/libelektra/kdbcapability.c

   1 /***************************************************************************
   2       kdbcapability.c  -  Capability and attribute functions for backends
   3                              -------------------
   4     begin                : Mon Dec 29 2003
   5     copyright            : (C) 2003 by Avi Alkalay
   6     email                : avi@unix.sh
   7  ***************************************************************************/
   8
   9 /***************************************************************************
  10  *                                                                         *
  11  *   This program is free software; you can redistribute it and/or modify  *
  12  *   it under the terms of the BSD License (revised).                      *
  13  *                                                                         *
  14  ***************************************************************************/
  15
  16
  17 /*
  18  * @defgroup capability KDB Backends :: Capabilities of backends
  19  * @brief The tactics to consider different possibilites of different backends.
  20  *
  21  * Since version 0.7 with the vast new possiblities of backends used
  22  * together in a global namespace the fact that not every backend can
  23  * fulfill any requirement as datastore and the intersection would
  24  * lead to a useless limited storage, capabilities were introduced.
  25  *
  26  * Applications heavily using kdbGet() and kdbSet() together with metadata
  27  * may be interested if what they show are default values or something you
  28  * can rely on.
  29  *
  30  * On the other hand backends may be interested to tell that they
  31  * can't fullfill the requriements described in kdbGet_backend() and
  32  * kdbSet_backend().
  33  *
  34  * Many backends are very limited in how granular the metadata is. If
  35  * many keys are stored in the same file, it is of course not possible
  36  * that one key has e.g. another owner than another key in the same
  37  * file.
  38  *
  39  * There might even be a limit in what names can be accepted by a
  40  * backend, because of syntax in a configuration file. A formal description
  41  * needed for that problem would be out of scope and not very useful.
  42  * For that reason capabilites are limited to yes/no questions
  43  * if something is provided or not.
  44  *
  45  * Capabilites are also very useful for testing driven or
  46  * iterative development. Beginning with simple reading everything out
  47  * transformed to keyset in kdbGet_backend() and generating a new
  48  * file with the keyset of kdbSet_backend() you can iterative
  49  * delete handicaps of your backend until you hit the full specification,
  50  * if it is possible.
  51  */
  52
  53 #ifdef HAVE_CONFIG_H
  54 #include "config.h"
  55 #endif
  56
  57 #if DEBUG && HAVE_STDIO_H
  58 #include <stdio.h>
  59 #endif
  60
  61 #ifdef HAVE_LOCALE_H
  62 #include <locale.h>
  63 #endif
  64
  65 #ifdef HAVE_STDLIB_H
  66 #include <stdlib.h>
  67 #endif
  68
  69 #ifdef HAVE_STDARG_H
  70 #include <stdarg.h>
  71 #endif
  72
  73 #ifdef HAVE_CTYPE_H
  74 #include <ctype.h>
  75 #endif
  76
  77 #ifdef HAVE_STRING_H
  78 #include <string.h>
  79 #endif
  80
  81 #ifdef HAVE_ERRNO_H
  82 #include <errno.h>
  83 #endif
  84
  85 #include <kdbbackend.h>
  86
  87 KDBCap *capNew ()
  88 {
  89         KDBCap * cap = (KDBCap *)malloc(sizeof(KDBCap));
  90         if (!cap) return 0;
  91         memset(cap,0,sizeof(KDBCap));
  92         return cap;
  93 }
  94
  95 void capDel (KDBCap *cap)
  96 {
  97         free (cap);
  98 }
  99
 100
 101 /*Version of the library.
 102  *
 103  * @param cap the obsolete cap object
 104  * @ingroup capability*/
 105 const char * kdbcGetVersion (const KDBCap *cap)
 106 {
 107         return cap->version;
 108 }
 109
 110
 111 /*Name of backend being or that will be used
 112  *
 113  * @param cap the obsolete cap object
 114  * @ingroup capability*/
 115 const char * kdbcGetName (const KDBCap *cap)
 116 {
 117         return cap->name;
 118 }
 119
 120
 121 /*Any text describing the backend.
 122  *
 123  * @param cap the obsolete cap object
 124  * @ingroup capability*/
 125 const char * kdbcGetDescription (const KDBCap *cap)
 126 {
 127         return cap->description;
 128 }
 129
 130
 131 /*The author of the backend.
 132  *
 133  * Best is format "Full Name <email@libelektra.org>"
 134  * e.g.:
 135  *
 136  * Avi Alkalay <avi@unix.sh>
 137  * Markus Raab <elektra@markus-raab.org>
 138  * Yannick Lecaillez <yl@itioweb.com>
 139  * Jens Andersen <jens.andersen@gmail.com>
 140  * Patrick Sabin <patricksabin@gmx.at>
 141  * Pier Luigi Fiorini <pierluigi.fiorini@mockup.org>
 142  * Rèmi <remipouak@yahoo.fr>
 143  * Studio-HB <contact@studio-hb.com>
 144  *
 145  *
 146  * @param cap the obsolete cap object
 147  * @ingroup capability*/
 148 const char * kdbcGetAuthor (const KDBCap *cap)
 149 {
 150         return cap->author;
 151 }
 152
 153
 154 /*The licence of the backend.
 155  *
 156  * - Must be "BSD" for bsd licence, this is the licence for elektra core.
 157  * - Must be "GPL2" for gpl version 2.
 158  * - Must be "GPL3" for gpl version 3.
 159  * - Must be "LGPL" for lgpl.
 160  *
 161  * Because of BSD licence even commercial is allowed.
 162  *
 163  *
 164  * @param cap the obsolete cap object
 165  * @ingroup capability*/
 166 const char * kdbcGetLicence (const KDBCap *cap){
 167         return cap->licence;
 168 }
 169
 170
 171 /*You cant get specific keys.
 172  *
 173  * The specification of kdbGet_backend() says that you must
 174  * get a key with its subkey and nothing more or less. Declaring
 175  * onlyFullGet you are allowed to get all keys when you get
 176  * a kdbGet_backend() request of your mountpoint, but you need
 177  * to return 0 for any subkeys to avoid an infinite loop.
 178  *
 179  *
 180  * @param cap the obsolete cap object
 181  * @see kdbGet_backend()
 182  * @ingroup capability
 183  * */
 184 unsigned int kdbcGetonlyFullGet (const KDBCap *cap)
 185 {
 186         return cap->onlyFullGet;
 187 }
 188
 189
 190 /*All keys need to be in keyset when setting.
 191  *
 192  * Backends have not problem with setting single keys, when the
 193  * gap between those keys is already filled out with previous
 194  * calls of kdbSet(). The keys in between may not be in the
 195  * keyset.
 196  *
 197  * Declaring onlyFullSet requires the caller to kdbGet() all
 198  * keys of the backend and manipulating this full set. This
 199  * allows the backend to regenerate the whole config, making
 200  * implementation much easier.
 201  *
 202  *
 203  * @param cap the obsolete cap object
 204  * @see kdbSet_backend()
 205  * @ingroup capability
 206  **/
 207 unsigned int kdbcGetonlyFullSet (const KDBCap *cap)
 208 {
 209         return cap->onlyFullSet;
 210 }
 211
 212
 213 /*When getting keys they cant be stated.
 214  *
 215  * @see keyStat(), keyNeedStat()
 216  * @see kdbGet_backend()
 217  * @ingroup capability
 218  **/
 219 unsigned int kdbcGetnoStat (const KDBCap *cap)
 220 {
 221         return cap->noStat;
 222 }
 223
 224
 225 /*You can only remove all keys at once.
 226  *
 227  * @see kdbSet_backend()
 228  * @ingroup capability
 229  **/
 230 unsigned int kdbcGetonlyRemoveAll (const KDBCap *cap)
 231 {
 232         return cap->onlyRemoveAll;
 233 }
 234
 235
 236 /*When setting keys with new name below parentKey, they will be added.
 237  *
 238  * Otherwise (changing keys) all keys are required.
 239  *
 240  * @see kdbSet_backend()
 241  * @ingroup capability
 242  * */
 243 unsigned int kdbcGetonlyAddKeys (const KDBCap *cap)
 244 {
 245         return cap->onlyAddKeys;
 246 }
 247
 248
 249 /*The backend does not support a owner of keys.
 250  *
 251  *
 252  * @see keySetOwner() and keyGetOwner()
 253  * @ingroup capability
 254  * */
 255 unsigned int kdbcGetnoOwner (const KDBCap *cap)
 256 {
 257         return cap->noOwner;
 258 }
 259
 260
 261 /*No value is supported in the backend.
 262  *
 263  * A backend might be useful only having comments, metadata or only
 264  * names without any values as information for applications. Declare
 265  * this if your backend is not capable of storing values.
 266  *
 267  * @see keySetRaw()
 268  * @see keySetString() and keyGetString()
 269  * @see keyValue() (togehter with keyGetValueSize() if it is binary)
 270  * @ingroup capability
 271  * */
 272 unsigned int kdbcGetnoValue (const KDBCap *cap)
 273 {
 274         return cap->noValue;
 275 }
 276
 277
 278 /*No comment is supported in the backend.
 279  *
 280  * @see keySetComment() and keyGetComment()
 281  * @ingroup capability
 282  **/
 283 unsigned int kdbcGetnoComment (const KDBCap *cap)
 284 {
 285         return cap->noComment;
 286 }
 287
 288
 289 /*No uid is supported in the backend.
 290  *
 291  * @see keySetUID()
 292  * @ingroup capability
 293  **/
 294 unsigned int kdbcGetnoUID (const KDBCap *cap)
 295 {
 296         return cap->noUID;
 297 }
 298
 299
 300 /*No gid is supported in the backend.
 301  *
 302  * @see keySetGID()
 303  * @ingroup capability
 304  **/
 305 unsigned int kdbcGetnoGID (const KDBCap *cap)
 306 {
 307         return cap->noGID;
 308 }
 309
 310
 311 /*No mode is supported in the backend.
 312  *
 313  * Means that keys will only have 664 or
 314  * 775 as mode values.
 315  *
 316  * @see keySetMode()
 317  * @ingroup capability
 318  **/
 319 unsigned int kdbcGetnoMode (const KDBCap *cap)
 320 {
 321         return cap->noMode;
 322 }
 323
 324
 325 /*Directories are not supported in the backend.
 326  *
 327  * Tells that mode won't have any executable
 328  * bits set.
 329  *
 330  * Declaring kdbcGetnoDir() means
 331  * that the backend is flat, no key will be true for keyIsDir()
 332  * and so can't have any subkeys.
 333  *
 334  * @see keySetDir()
 335  * @ingroup capability
 336  **/
 337 unsigned int kdbcGetnoDir (const KDBCap *cap)
 338 {
 339         return cap->noDir;
 340 }
 341
 342
 343 /*Access Time not supported.
 344  *
 345  * @see keySetATime()
 346  * @ingroup capability
 347  **/
 348 unsigned int kdbcGetnoATime (const KDBCap *cap)
 349 {
 350         return cap->noATime;
 351 }
 352
 353
 354 /*Modification Time not supported.
 355  *
 356  * @see keySetMTime()
 357  * @ingroup capability
 358  **/
 359 unsigned int kdbcGetnoMTime (const KDBCap *cap)
 360 {
 361         return cap->noMTime;
 362 }
 363
 364
 365 /*Meta Info and Subkeys Change Time not supported.
 366  *
 367  * @see keySetCTime()
 368  * @ingroup capability
 369  **/
 370 unsigned int kdbcGetnoCTime (const KDBCap *cap)
 371 {
 372         return cap->noCTime;
 373 }
 374
 375
 376 /*The backend does not support removing keys.*/
 377 unsigned int kdbcGetnoRemove (const KDBCap *cap)
 378 {
 379         return cap->noRemove;
 380 }
 381
 382
 383
 384 /*Mount type not supported.*/
 385 unsigned int kdbcGetnoMount (const KDBCap *cap)
 386 {
 387         return cap->noMount;
 388 }
 389
 390
 391 /*Binary types not supported.
 392  *
 393  * @see keySetBinary()
 394  * @ingroup capability
 395  **/
 396 unsigned int kdbcGetnoBinary (const KDBCap *cap)
 397 {
 398         return cap->noBinary;
 399 }
 400
 401
 402 /*String types not supported.
 403  *
 404  * @see keySetString()
 405  * @ingroup capability
 406  **/
 407 unsigned int kdbcGetnoString (const KDBCap *cap)
 408 {
 409         return cap->noString;
 410 }
 411
 412
 413 /*Typing of keys is not supported.
 414  *
 415  * @see keySetRaw() and keySetType()
 416  * @ingroup capability
 417  **/
 418 unsigned int kdbcGetnoTypes (const KDBCap *cap)
 419 {
 420         return cap->noTypes;
 421 }
 422
 423
 424 /*Do not expect errno to be set correctly.
 425  *
 426  * @see kdbhSetError()
 427  * @ingroup capability
 428  **/
 429 unsigned int kdbcGetnoError (const KDBCap *cap)
 430 {
 431         return cap->noError;
 432 }
 433
 434
 435 /*Backend does not lock.
 436  *
 437  * @ingroup capability
 438  **/
 439 unsigned int kdbcGetnoLock (const KDBCap *cap)
 440 {
 441         return cap->noLock;
 442 }
 443
 444
 445 /*Backend uses global variables and is not threadsafe.
 446  *
 447  * @ingroup capability
 448  **/
 449 unsigned int kdbcGetnoThread (const KDBCap *cap)
 450 {
 451         return cap->noThread;
 452 }
 453