1 /*************************************************************************** 2 begin : Tue Sep 09 2003 3 copyright : (C) 2003-2010 by Martin Preuss 4 email : martin@libchipcard.de 5 6 *************************************************************************** 7 * * 8 * This library is free software; you can redistribute it and/or * 9 * modify it under the terms of the GNU Lesser General Public * 10 * License as published by the Free Software Foundation; either * 11 * version 2.1 of the License, or (at your option) any later version. * 12 * * 13 * This library is distributed in the hope that it will be useful, * 14 * but WITHOUT ANY WARRANTY; without even the implied warranty of * 15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * 16 * Lesser General Public License for more details. * 17 * * 18 * You should have received a copy of the GNU Lesser General Public * 19 * License along with this library; if not, write to the Free Software * 20 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, * 21 * MA 02111-1307 USA * 22 * * 23 ***************************************************************************/ 24 25 26 /** @file db.h */ 27 28 #ifndef GWENHYWFAR_DB_H 29 #define GWENHYWFAR_DB_H 30 31 #include <gwenhywfar/gwenhywfarapi.h> 32 #include <gwenhywfar/path.h> 33 #include <gwenhywfar/fastbuffer.h> 34 #include <gwenhywfar/types.h> 35 #include <stdio.h> 36 37 #ifdef __cplusplus 38 extern "C" { 39 #endif 40 41 42 /** @defgroup MOD_DB Database 43 * @ingroup MOD_PARSER 44 * 45 * @brief This group contains the definition of a GWEN_DB database. 46 * 47 * A GWEN_DB database consists of a tree of @ref GWEN_DB_NODE entries. 48 * Such a @ref GWEN_DB_NODE node can either be a group node, or a 49 * variable node, or a value node. Usually an application programmer 50 * will only get in touch with group nodes. The application programmer 51 * can iterate through the group nodes with GWEN_DB_GetGroup(), 52 * GWEN_DB_Groups_foreach(), and can retrieve variable values with 53 * GWEN_DB_GetIntValue(), GWEN_DB_GetCharValue() and so on. 54 * 55 * <p> 56 * The following graph shows the internal structure of a GWEN_DB: <br> 57 * @image html db2.png "Internal structure of a GWEN_DB" 58 * <br> 59 * As you can see the GWEN_DB consists of multiple units called NODE. Every 60 * node has a pointer to: 61 * <ul> 62 * <li>its parent</li> 63 * <li>its first child (only the <strong>first</strong>)</li> 64 * <li>its successor (but not its predecessor!) 65 * </ul> 66 * Such a node can be either of the following: 67 * <ul> 68 * <li>a group containing other groups and variables</li> 69 * <li>a variable containing values (and values only)</li> 70 * <li>a value containing its value data</li> 71 * </ul> 72 * </p> 73 * 74 * Each group has a name. Depending on the GWEN_DB_FLAGS given when 75 * reading a GWEN_DB from a file or creating it, it may very well be 76 * possible to have multiple groups with the same name as children of 77 * the same root node. Again: Child group nodes with the same name may 78 * very well exist. This also applies to variable nodes. 79 * 80 * For the interested reader, we again explain the difference of the 81 * three kinds of nodes. Depending on either of these cases, you can 82 * 83 * <ol> 84 * <li> Iterate through groups or get a variable with 85 * e.g. GWEN_DB_GetNextGroup(), GWEN_DB_GetNextVar() 86 * <li> Get the type of a variable with e.g. GWEN_DB_GetVariableType() 87 * -- the value of a variable is retrieved by the shortcut functions 88 * explained below. 89 * <li> Get the type of a value with GWEN_DB_GetValueType(). Again the 90 * value itself is retrieved with the shortcut functions below. 91 * </ol> 92 * 93 * To retrieve or set the value of such a variable, the following 94 * "shortcut" functions for all three supported typed exist: 95 * GWEN_DB_GetIntValue(), GWEN_DB_GetCharValue(), 96 * GWEN_DB_GetBinValue(). These functions only accept a group and a "path" 97 * to the desired variable. 98 * 99 */ 100 /*@{*/ 101 /** maximum size of a text line when reading/writing from/to streams */ 102 #define GWEN_DB_LINE_MAXSIZE 1024 103 104 /** @name DB Flags 105 * 106 * <p> 107 * Please note that the setter functions also take the flags from 108 * the module @ref MOD_PATH (e.g. @ref GWEN_PATH_FLAGS_PATHMUSTEXIST) 109 * into account. So you most likely need to specify 110 * them, too. 111 * </p> 112 * <p> 113 * However, for your conveniance there is a default flag value which suffices 114 * in most cases (@ref GWEN_DB_FLAGS_DEFAULT). 115 * </p> 116 */ 117 /*@{*/ 118 /** when reading a DB allow for empty streams (e.g. empty file) */ 119 #define GWEN_DB_FLAGS_ALLOW_EMPTY_STREAM 0x00008000 120 /** Overwrite existing values when assigning a new value to a variable */ 121 #define GWEN_DB_FLAGS_OVERWRITE_VARS 0x00010000 122 /** Overwrite existing groups when calling @ref GWEN_DB_GetGroup() */ 123 #define GWEN_DB_FLAGS_OVERWRITE_GROUPS 0x00020000 124 /** quote variable names when writing them to a stream */ 125 #define GWEN_DB_FLAGS_QUOTE_VARNAMES 0x00040000 126 /** quote values when writing them to a stream */ 127 #define GWEN_DB_FLAGS_QUOTE_VALUES 0x00080000 128 /** allows writing of subgroups when writing to a stream */ 129 #define GWEN_DB_FLAGS_WRITE_SUBGROUPS 0x00100000 130 /** adds some comments when writing to a stream */ 131 #define GWEN_DB_FLAGS_DETAILED_GROUPS 0x00200000 132 /** indents text according to the current path depth when writing to a 133 * stream to improve the readability of the created file */ 134 #define GWEN_DB_FLAGS_INDEND 0x00400000 135 /** writes a newline to the stream after writing a group to improve 136 * the readability of the created file */ 137 #define GWEN_DB_FLAGS_ADD_GROUP_NEWLINES 0x00800000 138 /** uses a colon (":") instead of an equation mark when reading/writing 139 * variable definitions */ 140 #define GWEN_DB_FLAGS_USE_COLON 0x01000000 141 /** stops reading from a stream at empty lines */ 142 #define GWEN_DB_FLAGS_UNTIL_EMPTY_LINE 0x02000000 143 /** normally the type of a variable is written to the stream, too. 144 * This flag changes this behaviour */ 145 #define GWEN_DB_FLAGS_OMIT_TYPES 0x04000000 146 /** appends data to an existing file instead of overwriting it */ 147 #define GWEN_DB_FLAGS_APPEND_FILE 0x08000000 148 /** Char values are escaped when writing them to a file. */ 149 #define GWEN_DB_FLAGS_ESCAPE_CHARVALUES 0x10000000 150 /** Char values are unescaped when reading them from a file (uses the same 151 * bit @ref GWEN_DB_FLAGS_ESCAPE_CHARVALUES uses) */ 152 #define GWEN_DB_FLAGS_UNESCAPE_CHARVALUES 0x10000000 153 /** locks a file before reading from or writing to it 154 * This is used by @ref GWEN_DB_ReadFile and @ref GWEN_DB_WriteFile */ 155 #define GWEN_DB_FLAGS_LOCKFILE 0x20000000 156 157 /** 158 * When setting a value or getting a group insert newly created 159 * values/groups rather than appending them.*/ 160 #define GWEN_DB_FLAGS_INSERT 0x40000000 161 162 /** 163 * When writing a DB use DOS line termination (e.g. CR/LF) instead if unix mode (LF only) 164 */ 165 #define GWEN_DB_FLAGS_DOSMODE 0x80000000 166 167 /** These are the default flags which you use in most cases */ 168 #define GWEN_DB_FLAGS_DEFAULT \ 169 (\ 170 GWEN_DB_FLAGS_QUOTE_VALUES | \ 171 GWEN_DB_FLAGS_WRITE_SUBGROUPS | \ 172 GWEN_DB_FLAGS_DETAILED_GROUPS | \ 173 GWEN_DB_FLAGS_INDEND | \ 174 GWEN_DB_FLAGS_ADD_GROUP_NEWLINES | \ 175 GWEN_DB_FLAGS_ESCAPE_CHARVALUES | \ 176 GWEN_DB_FLAGS_UNESCAPE_CHARVALUES\ 177 ) 178 179 180 /** same like @ref GWEN_DB_FLAGS_DEFAULT except that the produced file 181 * (when writing to a stream) is more compact (but less readable)*/ 182 #define GWEN_DB_FLAGS_COMPACT \ 183 (\ 184 GWEN_DB_FLAGS_QUOTE_VALUES | \ 185 GWEN_DB_FLAGS_WRITE_SUBGROUPS | \ 186 GWEN_DB_FLAGS_ESCAPE_CHARVALUES | \ 187 GWEN_DB_FLAGS_UNESCAPE_CHARVALUES\ 188 ) 189 190 /** These flags can be used to read a DB from a HTTP header. It uses a 191 * colon instead of the equation mark with variable definitions and stops 192 * when encountering an empty line.*/ 193 #define GWEN_DB_FLAGS_HTTP \ 194 (\ 195 GWEN_DB_FLAGS_USE_COLON |\ 196 GWEN_DB_FLAGS_UNTIL_EMPTY_LINE |\ 197 GWEN_DB_FLAGS_OMIT_TYPES | \ 198 GWEN_DB_FLAGS_DOSMODE \ 199 ) 200 /*@}*/ 201 202 203 /** @name Node Flags 204 */ 205 /*@{*/ 206 /** is set then this node has been altered */ 207 #define GWEN_DB_NODE_FLAGS_DIRTY 0x00000001 208 /** variable is volatile (will not be written) */ 209 #define GWEN_DB_NODE_FLAGS_VOLATILE 0x00000002 210 /** this is only valid for groups. It determines whether subgroups will 211 * inherit the hash mechanism set in the root node. */ 212 #define GWEN_DB_NODE_FLAGS_INHERIT_HASH_MECHANISM 0x00000004 213 /** node has to be disposed of safely (i.e. it will be overridden before freeing it) */ 214 #define GWEN_DB_NODE_FLAGS_SAFE 0x00000008 215 /*@}*/ 216 217 218 #define GWEN_DB_DEFAULT_LOCK_TIMEOUT 1000 219 220 221 /** 222 * This is the type used to store a DB. Its contents are explicitly NOT 223 * part of the API. 224 * 225 * A description of what can be done with this type can be found in 226 * @ref db.h 227 */ 228 typedef struct GWEN_DB_NODE GWEN_DB_NODE; 229 230 /** 231 * This specifies the type of a value stored in the DB. 232 */ 233 typedef enum { 234 /** type unknown */ 235 GWEN_DB_NodeType_Unknown=-1, 236 /** group */ 237 GWEN_DB_NodeType_Group=0, 238 /** variable */ 239 GWEN_DB_NodeType_Var, 240 /** simple, null terminated C-string */ 241 GWEN_DB_NodeType_ValueChar, 242 /** integer */ 243 GWEN_DB_NodeType_ValueInt, 244 /** binary, user defined data */ 245 GWEN_DB_NodeType_ValueBin, 246 /** pointer , will not be stored or read to/from files */ 247 GWEN_DB_NodeType_ValuePtr, 248 /** last value type */ 249 GWEN_DB_NodeType_ValueLast 250 } GWEN_DB_NODE_TYPE; 251 252 253 254 /** @name Constructing, Destructing, Copying 255 * 256 */ 257 /*@{*/ 258 259 /** 260 * Creates a new (empty) group with the given name. I.e. this is the 261 * constructor. When finished using this group, you should free it 262 * using @ref GWEN_DB_Group_free() in order to avoid memory leaks. 263 * @param name name of the group to create 264 */ 265 GWENHYWFAR_API 266 GWEN_DB_NODE *GWEN_DB_Group_new(const char *name); 267 268 /** 269 * Frees a DB group. I.e. this is the destructor. This is needed to 270 * avoid memory leaks. 271 * @param n db node 272 */ 273 GWENHYWFAR_API 274 void GWEN_DB_Group_free(GWEN_DB_NODE *n); 275 276 277 /** 278 * Creates a deep copy of the given node. This copy will then be owned 279 * by the caller and MUST be freed after using it by calling @ref 280 * GWEN_DB_Group_free(). 281 * @param n db node 282 */ 283 GWENHYWFAR_API 284 GWEN_DB_NODE *GWEN_DB_Group_dup(const GWEN_DB_NODE *n); 285 286 /*@}*/ 287 288 289 290 /** @name Iterating Through Groups 291 * 292 */ 293 /*@{*/ 294 /** 295 * Returns the first group node below the given one. 296 * 297 * If there is no group node then NULL is returned. This can either 298 * mean that this node does not have any children or the only 299 * children are variables instead of groups. 300 * 301 * @param n db node 302 */ 303 GWENHYWFAR_API 304 GWEN_DB_NODE *GWEN_DB_GetFirstGroup(GWEN_DB_NODE *n); 305 306 /** 307 * Returns the next group node following the given one, which has the 308 * same parent node. 309 * 310 * This function works absolutely independently of the group nodes' 311 * names -- the returned node may or may not have the same name as the 312 * specified node. The only guarantee is that the returned node will 313 * be a group node. 314 * 315 * If there is no group node then NULL is returned. This can either 316 * mean that the parent node does not have any further 317 * children, or that the other children are variables instead 318 * of groups. 319 * 320 * @note This is one of the few functions where the returned node is @e not 321 * the child of the specified node, but instead it is the next node 322 * with the same parent node. In other words, this function is an 323 * exception. In most other functions the returned node is a child of 324 * the specified node. 325 * 326 * @param n db node 327 */ 328 GWENHYWFAR_API 329 GWEN_DB_NODE *GWEN_DB_GetNextGroup(GWEN_DB_NODE *n); 330 331 332 /** 333 * Returns the first group node below the given one by name. 334 * 335 * If there is no matching group node then NULL is returned. This can either 336 * mean that this node does not have any children or the only 337 * children are variables instead of groups or their is no group of the 338 * given name. 339 * 340 * @param n db node 341 * @param name name to look for (joker and wildcards allowed) 342 */ 343 GWENHYWFAR_API 344 GWEN_DB_NODE *GWEN_DB_FindFirstGroup(GWEN_DB_NODE *n, const char *name); 345 346 /** 347 * Returns the next group node following the given one, which has the 348 * same parent node, by name. 349 * 350 * If there is no matching group node then NULL is returned. This can either 351 * mean that the parent node does not have any further 352 * children, or that the other children are variables instead 353 * of groups or that there is no group with the given name. 354 * 355 * @note This is one of the few functions where the returned node is @e not 356 * the child of the specified node, but instead it is the next node 357 * with the same parent node. In other words, this function is an 358 * exception. In most other functions the returned node is a child of 359 * the specified node. 360 * 361 * @param n db node 362 * @param name name to look for (joker and wildcards allowed) 363 */ 364 GWENHYWFAR_API 365 GWEN_DB_NODE *GWEN_DB_FindNextGroup(GWEN_DB_NODE *n, const char *name); 366 367 368 /** Callback function type for GWEN_DB_Groups_Foreach(), 369 * GWEN_DB_Variables_Foreach(), and GWEN_DB_Values_Foreach(). 370 * 371 * @param node The current node element 372 * 373 * @param user_data The arbitrary data passed to the foreach function. 374 * 375 * @return NULL if the iteration should continue, or non-NULL if the 376 * iteration should stop and that value be returned. 377 */ 378 typedef void *(*GWEN_DB_NODES_CB)(GWEN_DB_NODE *node, void *user_data); 379 380 /** Iterates through all group nodes that are @e direct children 381 * of the given node, calling the callback function 'func' on each 382 * group node. Traversal will stop when 'func' returns a non-NULL 383 * value, and the routine will return with that value. Otherwise the 384 * routine will return NULL. 385 * 386 * If no nodes that are groups are found as children, then 387 * this function will simply do nothing. 388 * 389 * @param node The group node whose children shall be iterated through. 390 * @param func The function to be called with each group node. 391 * @param user_data A pointer passed on to the function 'func'. 392 * @return The non-NULL pointer returned by 'func' as soon as it 393 * returns one. Otherwise (i.e. 'func' always returns NULL) 394 * returns NULL. 395 * @author Christian Stimming <stimming@tuhh.de> */ 396 GWENHYWFAR_API 397 void *GWEN_DB_Groups_Foreach(GWEN_DB_NODE *node, GWEN_DB_NODES_CB func, 398 void *user_data); 399 400 /** Returns the number of group nodes that are @e direct children of 401 * the given node. In other words, this is the number of group nodes 402 * that will be reached in the GWEN_DB_Groups_foreach() function. */ 403 GWENHYWFAR_API 404 unsigned int GWEN_DB_Groups_Count(const GWEN_DB_NODE *node); 405 406 /** 407 * Returns the parent group of the given node. 408 */ 409 GWENHYWFAR_API 410 GWEN_DB_NODE *GWEN_DB_GetParentGroup(GWEN_DB_NODE *n); 411 412 /*@}*/ 413 414 415 416 417 /** @name Variable Getter and Setter 418 * 419 * These getter functions check for the existence of the given variable and 420 * return the value specified by an index. 421 * Under the following circumstances the also given default value will be 422 * returned: 423 * <ul> 424 * <li>the variable does not exist</li> 425 * <li>the variable exists but has no values (should not occur)</li> 426 * <li>the variable exists but the given value index is out of range (e.g. 427 * specifying index 1 with a variable that has only one value)</li> 428 * <li>a string value is expected but the variable is not of that type. 429 * However, if you want an integer value but the variable only has a char 430 * value then the getter functions try to convert the char to an integer. 431 * Other conversions do not take place.</li> 432 * </ul> 433 * 434 * The setter functions either replace an existing variable, create a missing 435 * variable, add a value or return an error if the variable does not exist 436 * (see description of the flags). 437 * All setter functions make deep copies of the given values, so you may 438 * free the params after calling the setter function. 439 * 440 * All getter functions return a const pointer to the variable's retrieved 441 * value. 442 * All setter functions return Zero if ok and Nonzero on error. 443 * 444 * This module knows about the following types (see @ref GWEN_DB_VALUETYPE): 445 * <ul> 446 * <li>char (simple null terminated C strings)</li> 447 * <li>int (integer values)</li> 448 * <li>bin (binary, user specified data)</li> 449 * </ul> 450 * 451 * @note The value returned by a getter function is only valid as long as the 452 * corresponding variable (node) exists.<br> 453 * So if you retrieve the value of a variable and delete the variable (or even 454 * the whole DB) afterwards the pointer becomes invalid and using it will most 455 * likely crash your program.<br> 456 * If you want to use such a value even after the corresponding variable 457 * has been deleted you need to make a copy. 458 * 459 460 */ 461 /*@{*/ 462 /** 463 * Returns the variable's retrieved value. 464 * @param n db node 465 * @param path path and name of the variable 466 * @param idx index number of the value to return 467 * @param defVal default value to return in case there is no real value 468 */ 469 GWENHYWFAR_API 470 const char *GWEN_DB_GetCharValue(GWEN_DB_NODE *n, 471 const char *path, 472 int idx, 473 const char *defVal); 474 /** 475 * @return 0 on success, nonzero on error 476 * @param n db node 477 * @param flags see @ref GWEN_DB_FLAGS_OVERWRITE_VARS and others which 478 * can all be OR-combined to form the flags to use. 479 * @param path path and name of the variable 480 * @param val The string value that is copied into the DB 481 */ 482 GWENHYWFAR_API 483 int GWEN_DB_SetCharValue(GWEN_DB_NODE *n, 484 uint32_t flags, 485 const char *path, 486 const char *val); 487 488 489 490 /** 491 * @return 0 on success, nonzero on error 492 * @param n db node 493 * @param flags see @ref GWEN_DB_FLAGS_OVERWRITE_VARS and others which 494 * can all be OR-combined to form the flags to use. 495 * @param path path and name of the variable 496 * @param val The integer value to be stored as string value in the DB 497 */ 498 GWENHYWFAR_API 499 int GWEN_DB_SetCharValueFromInt(GWEN_DB_NODE *n, 500 uint32_t flags, 501 const char *path, 502 int val); 503 504 505 /** 506 * Adds the given char value to the given variable if it not already exists 507 * (depending on the arguments senseCase and check). 508 * @return 0 on success, nonzero on error 509 * @param n db node 510 * @param path path and name of the variable 511 * @param val The string value that is copied into the DB 512 * @param senseCase if 0 then the case of the value is ignored while checking 513 * @param check if 1 then the variable will be checked for this value 514 */ 515 GWENHYWFAR_API 516 int GWEN_DB_AddCharValue(GWEN_DB_NODE *n, 517 const char *path, 518 const char *val, 519 int senseCase, 520 int check); 521 522 523 /** 524 * Removes the given char value from the given variable if it exists 525 * (depending on the arguments senseCase and check). 526 * @return 0 on success, nonzero on error 527 * @param n db node 528 * @param path path and name of the variable 529 * @param val The string value to be removed 530 * @param senseCase if 0 then the case of the value is ignored while checking 531 */ 532 GWENHYWFAR_API 533 int GWEN_DB_RemoveCharValue(GWEN_DB_NODE *n, 534 const char *path, 535 const char *val, 536 int senseCase); 537 538 539 /** 540 * Returns the variable's retrieved value. 541 * @param n db node 542 * @param path path and name of the variable 543 * @param idx index number of the value to return 544 * @param defVal default value to return in case there is no real value 545 */ 546 GWENHYWFAR_API 547 int GWEN_DB_GetIntValue(GWEN_DB_NODE *n, 548 const char *path, 549 int idx, 550 int defVal); 551 552 /** 553 * @return 0 on success, nonzero on error 554 * @param n db node 555 * @param flags see @ref GWEN_DB_FLAGS_OVERWRITE_VARS and others which 556 * can all be OR-combined to form the flags to use. 557 * @param path path and name of the variable 558 * @param val new value 559 */ 560 GWENHYWFAR_API 561 int GWEN_DB_SetIntValue(GWEN_DB_NODE *n, 562 uint32_t flags, 563 const char *path, 564 int val); 565 566 567 /** 568 * Returns the variable's retrieved value. The size of the binary 569 * data is written into the int pointer argument returnValueSize. 570 * @param n db node 571 * @param path path and name of the variable 572 * @param idx index number of the value to return 573 * @param defVal default value to return in case there is no real value 574 * @param defValSize size of the default value 575 * @param returnValueSize pointer to a variable to receive the length 576 * of the data returned 577 */ 578 GWENHYWFAR_API 579 const void *GWEN_DB_GetBinValue(GWEN_DB_NODE *n, 580 const char *path, 581 int idx, 582 const void *defVal, 583 unsigned int defValSize, 584 unsigned int *returnValueSize); 585 586 /** 587 * @param n db node 588 * @param path path and name of the variable 589 * @param flags see @ref GWEN_DB_FLAGS_OVERWRITE_VARS and others which 590 * can all be OR-combined to form the flags to use. 591 * @param val The binary data that is copied into the DB. 592 * @param valSize The number of bytes in the binary data value. 593 * 594 * @return 0 on success, nonzero on error 595 */ 596 GWENHYWFAR_API 597 int GWEN_DB_SetBinValue(GWEN_DB_NODE *n, 598 uint32_t flags, 599 const char *path, 600 const void *val, 601 unsigned int valSize); 602 603 604 /** 605 * Returns the variable's retrieved value. 606 * @param n db node 607 * @param path path and name of the variable 608 * @param idx index number of the value to return 609 * @param defVal default value to return in case there is no real value 610 */ 611 GWENHYWFAR_API 612 void *GWEN_DB_GetPtrValue(GWEN_DB_NODE *n, 613 const char *path, 614 int idx, 615 void *defVal); 616 617 /** 618 * @param n db node 619 * @param path path and name of the variable 620 * @param flags see @ref GWEN_DB_FLAGS_OVERWRITE_VARS and others which 621 * can all be OR-combined to form the flags to use. 622 * @param val The pointer that is stored within the DB. 623 * 624 * @return 0 on success, nonzero on error 625 */ 626 GWENHYWFAR_API 627 int GWEN_DB_SetPtrValue(GWEN_DB_NODE *n, 628 uint32_t flags, 629 const char *path, 630 void *val); 631 632 633 /** 634 * @return 0 if okay, error code on error (GWEN_ERROR_NO_DATA if the variable doesn't exist or has no value) 635 * @param n db node 636 * @param path path and name of the variable 637 * @param index number of value to read (if there are multiple values in the variable, 0 being the first) 638 * @param dstBuf buffer to write the value into 639 * 640 * @return 0 on success, nonzero on error 641 */ 642 GWENHYWFAR_API 643 int GWEN_DB_WriteVarValueToBuffer(GWEN_DB_NODE *n, const char *path, int index, GWEN_BUFFER *dstBuf); 644 645 646 /*@}*/ 647 648 649 650 /** @name Group Handling 651 * 652 */ 653 /*@{*/ 654 655 /** 656 * This function either creates a new group, returns an existing one or 657 * returns an error if there is no group but the caller wanted one (depending 658 * on the flags given). 659 * @param n db node 660 * @param flags see @ref GWEN_DB_FLAGS_OVERWRITE_VARS and others which 661 * can all be OR-combined to form the flags to use. 662 * @param path path and name of the group to be created/located 663 */ 664 GWENHYWFAR_API 665 GWEN_DB_NODE *GWEN_DB_GetGroup(GWEN_DB_NODE *n, 666 uint32_t flags, 667 const char *path); 668 669 /** 670 * Returns the name of the given group. 671 */ 672 GWENHYWFAR_API 673 const char *GWEN_DB_GroupName(GWEN_DB_NODE *n); 674 675 /** 676 * Renames the given group. 677 * @param n db node 678 * @param newname new name for the group 679 */ 680 GWENHYWFAR_API 681 void GWEN_DB_GroupRename(GWEN_DB_NODE *n, const char *newname); 682 683 /** 684 * Adds the given group node as a new child of the given parent group node. 685 * 686 * The group name has no influence on what will happen in this 687 * function. In other words, if the parent group already has a child 688 * group with the same name as 'node', then after this function two 689 * child group nodes with the same name will exist. 690 * 691 * @note This function takes over the ownership of the new group, so 692 * you MUST NOT free it afterwards. 693 * 694 * @param parent Some group node that will be the parent of the added node 695 * @param node Group node to add 696 */ 697 GWENHYWFAR_API 698 int GWEN_DB_AddGroup(GWEN_DB_NODE *parent, GWEN_DB_NODE *node); 699 700 /** 701 * Adds the given group node as the new first child of the given parent group 702 * node. 703 * 704 * The group name has no influence on what will happen in this 705 * function. In other words, if the parent group already has a child 706 * group with the same name as 'node', then after this function two 707 * child group nodes with the same name will exist. 708 * 709 * @note This function takes over the ownership of the new group, so 710 * you MUST NOT free it afterwards. 711 * 712 * @param parent Some group node that will be the parent of the added node 713 * @param node Group node to add 714 */ 715 GWENHYWFAR_API 716 int GWEN_DB_InsertGroup(GWEN_DB_NODE *parent, GWEN_DB_NODE *node); 717 718 /** 719 * This function adds all children of the second node as new children to 720 * the first given one. 721 * 722 * @note This function does NOT take over ownership of the new 723 * group. The caller is still the owner of the given group. 724 * @param n db node 725 * @param nn node whose children are to be added (makes deep copies) 726 */ 727 GWENHYWFAR_API 728 int GWEN_DB_AddGroupChildren(GWEN_DB_NODE *n, GWEN_DB_NODE *nn); 729 730 /** 731 * Unlinks a group (and thereby all its children) from its parent and 732 * brothers. 733 * 734 * This function DOES NOT free the group, it just unlinks it. You can then use 735 * it with e.g. @ref GWEN_DB_AddGroup or other functions to relink it at any 736 * other position of even in other DBs. 737 * @param n db node 738 */ 739 GWENHYWFAR_API 740 void GWEN_DB_UnlinkGroup(GWEN_DB_NODE *n); 741 742 /** 743 * Locates and removes the group of the given name. 744 * @return 0 on success, nonzero on error 745 * @param n db node 746 * @param path path to the group to delete 747 */ 748 GWENHYWFAR_API 749 int GWEN_DB_DeleteGroup(GWEN_DB_NODE *n, 750 const char *path); 751 /** 752 * Frees all children of the given node thereby clearing it. 753 * @return 0 on success, nonzero on error 754 * @param n db node 755 * @param path path to the group under the given node to clear 756 * (if 0 then clear the given node) 757 */ 758 GWENHYWFAR_API 759 int GWEN_DB_ClearGroup(GWEN_DB_NODE *n, 760 const char *path); 761 762 /** Predicate: Returns nonzero (TRUE) or zero (FALSE) if the given 763 * NODE is a Group or not. Usually these group nodes are the only 764 * nodes that the application gets in touch with. 765 * 766 * @param n db node 767 */ 768 GWENHYWFAR_API 769 int GWEN_DB_IsGroup(const GWEN_DB_NODE *n); 770 771 /** 772 * Returns the node flags for the given db node. 773 * Please note that all modifications applied to a node will set the 774 * dirty flag in the node itself and all its parents. 775 * This allows to use this funcion here to check whether a DB has been 776 * modified. 777 * @return current node flags for this node (see 778 * @ref GWEN_DB_NODE_FLAGS_DIRTY) 779 * 780 * @param n db node 781 */ 782 GWENHYWFAR_API 783 uint32_t GWEN_DB_GetNodeFlags(const GWEN_DB_NODE *n); 784 785 /** 786 * Modifies the node flags for the given db node 787 * @param n db node 788 * @param flags flags to set (see @ref GWEN_DB_NODE_FLAGS_DIRTY) 789 */ 790 GWENHYWFAR_API 791 void GWEN_DB_SetNodeFlags(GWEN_DB_NODE *n, 792 uint32_t flags); 793 794 /** 795 * Modifies the flags of the given node and all its parents according 796 * to the parameters given. 797 * @param n db node 798 * @param newflags new flags to set (see @ref GWEN_DB_NODE_FLAGS_DIRTY) 799 * @param mask only those flags which are set in this mask are modified 800 * according to newflags 801 */ 802 GWENHYWFAR_API 803 void GWEN_DB_ModifyBranchFlagsUp(GWEN_DB_NODE *n, 804 uint32_t newflags, 805 uint32_t mask); 806 807 /** 808 * Modifies the flags of the given node and all its children according 809 * to the parameters given. 810 * @param n db node 811 * @param newflags new flags to set (see @ref GWEN_DB_NODE_FLAGS_DIRTY) 812 * @param mask only those flags which are set in this mask are modified 813 * according to newflags 814 */ 815 GWENHYWFAR_API 816 void GWEN_DB_ModifyBranchFlagsDown(GWEN_DB_NODE *n, 817 uint32_t newflags, 818 uint32_t mask); 819 820 /*@}*/ 821 822 823 824 /** @name Reading and Writing From/To IO Layers 825 * 826 * These functions read or write a DB from/to GWEN_IO_LAYER. 827 * This allows to use any source or target supported by GWEN_IO_LAYER 828 * for data storage (these are currently sockets, files and memory buffers). 829 * The flags determine how to read/write the data (e.g. if sub-groups are 830 * to be written etc). 831 */ 832 /*@{*/ 833 834 GWENHYWFAR_API 835 int GWEN_DB_ReadFromFastBuffer(GWEN_DB_NODE *n, 836 GWEN_FAST_BUFFER *fb, 837 uint32_t dbflags); 838 839 GWENHYWFAR_API 840 int GWEN_DB_ReadFromIo(GWEN_DB_NODE *n, GWEN_SYNCIO *sio, uint32_t dbflags); 841 842 GWENHYWFAR_API 843 int GWEN_DB_ReadFile(GWEN_DB_NODE *n, 844 const char *fname, 845 uint32_t dbflags); 846 847 GWENHYWFAR_API 848 int GWEN_DB_ReadFromString(GWEN_DB_NODE *n, 849 const char *str, 850 int len, 851 uint32_t dbflags); 852 853 GWENHYWFAR_API 854 int GWEN_DB_WriteToFastBuffer(GWEN_DB_NODE *node, 855 GWEN_FAST_BUFFER *fb, 856 uint32_t dbflags); 857 858 GWENHYWFAR_API 859 int GWEN_DB_WriteToIo(GWEN_DB_NODE *node, 860 GWEN_SYNCIO *sio, 861 uint32_t dbflags); 862 863 864 GWENHYWFAR_API 865 int GWEN_DB_WriteFile(GWEN_DB_NODE *n, 866 const char *fname, 867 uint32_t dbflags); 868 869 GWENHYWFAR_API 870 int GWEN_DB_WriteToBuffer(GWEN_DB_NODE *n, 871 GWEN_BUFFER *buf, 872 uint32_t dbflags); 873 874 /** 875 * Imports a file into a DB using a GWEN_DBIO importer. 876 * @param n node to read into (becomes the root of the imported data) 877 * @param fname name of the file to import 878 * @param type GWEN_DBIO type 879 * @param params parameters for the GWEN_DBIO importer (content depends on 880 * the importer, may even be NULL for some types) 881 * @param dbflags flags to use while importing (see 882 * @ref GWEN_DB_FLAGS_OVERWRITE_VARS and others) 883 */ 884 GWENHYWFAR_API 885 int GWEN_DB_ReadFileAs(GWEN_DB_NODE *n, 886 const char *fname, 887 const char *type, 888 GWEN_DB_NODE *params, 889 uint32_t dbflags); 890 891 /** 892 * Exports a DB to a file using a GWEN_DBIO exporter. 893 * @param n node to write 894 * @param fname name of the file to export to 895 * @param type GWEN_DBIO type 896 * @param params parameters for the GWEN_DBIO exporter (content depends on 897 * the exporter, may even be NULL for some types) 898 * @param dbflags flags to use while exporting (see 899 * @ref GWEN_DB_FLAGS_OVERWRITE_VARS and others) 900 */ 901 GWENHYWFAR_API 902 int GWEN_DB_WriteFileAs(GWEN_DB_NODE *n, 903 const char *fname, 904 const char *type, 905 GWEN_DB_NODE *params, 906 uint32_t dbflags); 907 908 909 /*@}*/ 910 911 912 /** @name Iterating Through Variables and variable handling 913 * 914 */ 915 /*@{*/ 916 /** 917 * Returns the first variable below the given group. 918 * If there is no variable then NULL is returned. 919 * @param n db node 920 */ 921 GWENHYWFAR_API 922 GWEN_DB_NODE *GWEN_DB_GetFirstVar(GWEN_DB_NODE *n); 923 924 925 /** 926 * Returns the next variable node following the given one, which has 927 * the same parent node. 928 * 929 * This function works absolutely independently of the variable nodes' 930 * names -- the returned node may or may not have the same name as the 931 * specified node. The only guarantee is that the returned node will 932 * be a variable node. 933 * 934 * If there is no variable node then NULL is returned. This can either 935 * mean that the parent node does not have any further children, or 936 * that the other children are groups instead of variables. 937 * 938 * @note This is the only function where the returned node is @e not 939 * the child of the specified node, but instead it is the next node 940 * with the same parent node. In other words, this function is an 941 * exception. In all other functions the returned node is a child of 942 * the specified node. 943 * 944 * @param n db node 945 */ 946 GWENHYWFAR_API 947 GWEN_DB_NODE *GWEN_DB_GetNextVar(GWEN_DB_NODE *n); 948 949 /** 950 * Returns the name of the variable specified by the given node. 951 * @param n db node specifying a variable (not a group !) 952 */ 953 GWENHYWFAR_API 954 const char *GWEN_DB_VariableName(GWEN_DB_NODE *n); 955 956 957 GWENHYWFAR_API 958 void GWEN_DB_VariableRename(GWEN_DB_NODE *n, const char *newname); 959 960 /** Iterates through all variable nodes that are @e direct children 961 * of the given node, calling the callback function 'func' on each 962 * variable node. Traversal will stop when 'func' returns a non-NULL 963 * value, and the routine will return with that value. Otherwise the 964 * routine will return NULL. 965 * 966 * If no nodes that are variables are found as children, then 967 * this function will simply do nothing. 968 * 969 * @param node The group node whose children shall be iterated through. 970 * @param func The function to be called with each group node. 971 * @param user_data A pointer passed on to the function 'func'. 972 * @return The non-NULL pointer returned by 'func' as soon as it 973 * returns one. Otherwise (i.e. 'func' always returns NULL) 974 * returns NULL. 975 * @author Christian Stimming <stimming@tuhh.de> */ 976 GWENHYWFAR_API 977 void *GWEN_DB_Variables_Foreach(GWEN_DB_NODE *node, GWEN_DB_NODES_CB func, 978 void *user_data); 979 980 /** Returns the number of variable nodes that are @e direct children 981 * of the given node. In other words, this is the number of variable 982 * nodes that will be reached in the GWEN_DB_Variables_Foreach() 983 * function. */ 984 GWENHYWFAR_API 985 unsigned int GWEN_DB_Variables_Count(const GWEN_DB_NODE *node); 986 987 /** 988 * Returns the type of the first value of the given variable 989 * @param n root node of the DB 990 * @param p path of the variable to inspect 991 */ 992 GWENHYWFAR_API 993 GWEN_DB_NODE_TYPE GWEN_DB_GetVariableType(GWEN_DB_NODE *n, 994 const char *p); 995 996 /** 997 * Deletes the given variable by removing it and its values from the DB. 998 * @param n root of the DB 999 * @param path path to the variable to remove 1000 * @return Zero on success, nonzero on error 1001 */ 1002 GWENHYWFAR_API 1003 int GWEN_DB_DeleteVar(GWEN_DB_NODE *n, 1004 const char *path); 1005 1006 /** 1007 * Checks whether the given variable exists. 1008 * @return Zero if variable not found, nonzero otherwise 1009 * @param n root of the DB 1010 * @param path path to the variable to check for 1011 */ 1012 GWENHYWFAR_API 1013 int GWEN_DB_VariableExists(GWEN_DB_NODE *n, 1014 const char *path); 1015 1016 /** 1017 * Checks whether the given variable and value exists. 1018 * @return Zero if variable not found, nonzero otherwise 1019 * @param n root of the DB 1020 * @param path path to the variable to check for 1021 * @param idx index number of the variable's value to check for 1022 */ 1023 GWENHYWFAR_API 1024 int GWEN_DB_ValueExists(GWEN_DB_NODE *n, 1025 const char *path, 1026 unsigned int idx); 1027 1028 /** Predicate: Returns nonzero (TRUE) or zero (FALSE) if the given 1029 * NODE is a Variable or not. Usually the Application does not get in 1030 * touch with such Nodes but only with nodes that are Groups. 1031 * 1032 * @param n db node 1033 */ 1034 GWENHYWFAR_API 1035 int GWEN_DB_IsVariable(const GWEN_DB_NODE *n); 1036 1037 1038 /** 1039 * Returns the first variable node below the given one by name. 1040 * 1041 * If there is no matching variable node then NULL is returned. This can 1042 * either mean that this node does not have any children or the only 1043 * children are groups/values instead of variables or their is no variable of 1044 * the given name. 1045 * 1046 * @param n db node 1047 * @param name name to look for (joker and wildcards allowed) 1048 */ 1049 GWENHYWFAR_API 1050 GWEN_DB_NODE *GWEN_DB_FindFirstVar(GWEN_DB_NODE *n, const char *name); 1051 1052 /** 1053 * Returns the next variable node following the given one, which has the 1054 * same parent node, by name. 1055 * 1056 * If there is no matching variable node then NULL is returned. This can 1057 * either mean that this node does not have any children or the only 1058 * children are groups/values instead of variables or their is no variable of 1059 * the given name. 1060 * 1061 * @note This is one of the few functions where the returned node is @e not 1062 * the child of the specified node, but instead it is the next node 1063 * with the same parent node. In other words, this function is an 1064 * exception. In most other functions the returned node is a child of 1065 * the specified node. 1066 * 1067 * @param n db node 1068 * @param name name to look for (joker and wildcards allowed) 1069 */ 1070 GWENHYWFAR_API 1071 GWEN_DB_NODE *GWEN_DB_FindNextVar(GWEN_DB_NODE *n, const char *name); 1072 1073 /*@}*/ 1074 1075 1076 /** @name Iterating Through Values and value handling 1077 * 1078 */ 1079 /*@{*/ 1080 /** 1081 * Returns the first value below the given variable. 1082 * If there is no value then NULL is returned. 1083 * @param n db node 1084 */ 1085 GWENHYWFAR_API 1086 GWEN_DB_NODE *GWEN_DB_GetFirstValue(GWEN_DB_NODE *n); 1087 1088 /** 1089 * Returns the next value node following the given one, which has the 1090 * same parent node. 1091 * 1092 * If there is no value node then NULL is returned. This can either 1093 * mean that the parent node does not have any further children, or 1094 * that the other children aren't values. 1095 * 1096 * @note This is the only function where the returned node is @e not 1097 * the child of the specified node, but instead it is the next node 1098 * with the same parent node. In other words, this function is an 1099 * exception. In all other functions the returned node is a child of 1100 * the specified node. 1101 * 1102 * @param n db node 1103 */ 1104 GWENHYWFAR_API 1105 GWEN_DB_NODE *GWEN_DB_GetNextValue(GWEN_DB_NODE *n); 1106 1107 /** Iterates through all value nodes that are @e direct children 1108 * of the given node, calling the callback function 'func' on each 1109 * value node. Traversal will stop when 'func' returns a non-NULL 1110 * value, and the routine will return with that value. Otherwise the 1111 * routine will return NULL. 1112 * 1113 * If no nodes that are values are found as children, then 1114 * this function will simply do nothing. 1115 * 1116 * @param node The variable node whose children shall be iterated through. 1117 * @param func The function to be called with each group node. 1118 * @param user_data A pointer passed on to the function 'func'. 1119 * @return The non-NULL pointer returned by 'func' as soon as it 1120 * returns one. Otherwise (i.e. 'func' always returns NULL) 1121 * returns NULL. 1122 * @author Christian Stimming <stimming@tuhh.de> */ 1123 GWENHYWFAR_API 1124 void *GWEN_DB_Values_Foreach(GWEN_DB_NODE *node, GWEN_DB_NODES_CB func, 1125 void *user_data); 1126 1127 /** Returns the number of value nodes that are @e direct children of 1128 * the given node. In other words, this is the number of value nodes 1129 * that will be reached in the GWEN_DB_Values_foreach() function. */ 1130 GWENHYWFAR_API 1131 unsigned int GWEN_DB_Values_Count(const GWEN_DB_NODE *node); 1132 1133 /** 1134 * Returns the type of the given value. 1135 * @param n db node 1136 */ 1137 GWENHYWFAR_API 1138 GWEN_DB_NODE_TYPE GWEN_DB_GetValueType(GWEN_DB_NODE *n); 1139 1140 GWENHYWFAR_API 1141 GWEN_DB_NODE_TYPE GWEN_DB_GetValueTypeByPath(GWEN_DB_NODE *n, 1142 const char *p, 1143 unsigned int i); 1144 1145 /** 1146 * Returns the value data of the given value node. 1147 * If the given node is not a char-value node then 0 is returned. 1148 */ 1149 GWENHYWFAR_API 1150 const char *GWEN_DB_GetCharValueFromNode(const GWEN_DB_NODE *n); 1151 1152 /** 1153 * Replaces the current value data of the given node by the new string. 1154 * @return 0 if ok, error code otherwise 1155 */ 1156 GWENHYWFAR_API 1157 int GWEN_DB_SetCharValueInNode(GWEN_DB_NODE *n, const char *s); 1158 1159 GWENHYWFAR_API 1160 int GWEN_DB_GetIntValueFromNode(const GWEN_DB_NODE *n); 1161 1162 GWENHYWFAR_API 1163 const void *GWEN_DB_GetBinValueFromNode(const GWEN_DB_NODE *n, 1164 unsigned int *size); 1165 1166 1167 /** Predicate: Returns nonzero (TRUE) or zero (FALSE) if the given 1168 * NODE is a Value or not. Usually the Application does not get in 1169 * touch with such Nodes but only with nodes that are Groups. 1170 * 1171 * @param n db node 1172 */ 1173 GWENHYWFAR_API 1174 int GWEN_DB_IsValue(const GWEN_DB_NODE *n); 1175 /*@}*/ 1176 1177 1178 1179 1180 1181 1182 /** @name Debugging 1183 * 1184 * These functions are for debugging purposes only. You should NOT consider 1185 * them part of the API. 1186 */ 1187 /*@{*/ 1188 1189 /** 1190 * Dumps the content of the given DB to the given file (e.g. stderr). 1191 * @param n node to dump 1192 * @param insert number of blanks to insert at every line 1193 */ 1194 GWENHYWFAR_API 1195 void GWEN_DB_Dump(GWEN_DB_NODE *n, int insert); 1196 /*@}*/ 1197 1198 1199 /** @name Higher Level Utility Functions 1200 * 1201 * These functions make use of GWEN_DB groups. 1202 */ 1203 /*@{*/ 1204 1205 1206 /** 1207 * Read the given string and replace every variable in that string ( noted as "$(varname)") with the 1208 * value of the mentioned variable. 1209 */ 1210 GWENHYWFAR_API 1211 int GWEN_DB_ReplaceVars(GWEN_DB_NODE *db, const char *s, GWEN_BUFFER *dbuf); 1212 /*@}*/ 1213 1214 1215 1216 /*@}*/ 1217 1218 1219 #ifdef __cplusplus 1220 } 1221 #endif 1222 1223 1224 #endif 1225 1226 1227 1228