1 /* 2 COLLECTION LIBRARY 3 4 Header file for collection interface. 5 6 Copyright (C) Dmitri Pal <dpal@redhat.com> 2009 7 8 Collection Library is free software: you can redistribute it and/or modify 9 it under the terms of the GNU Lesser General Public License as published by 10 the Free Software Foundation, either version 3 of the License, or 11 (at your option) any later version. 12 13 Collection 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 16 GNU Lesser General Public License for more details. 17 18 You should have received a copy of the GNU Lesser General Public License 19 along with Collection Library. If not, see <http://www.gnu.org/licenses/>. 20 */ 21 22 #ifndef COLLECTION_H 23 #define COLLECTION_H 24 25 #include <stdint.h> 26 27 /** @mainpage The COLLECTION interface 28 * The collection is a set of items of different types. 29 * 30 * To better understand how collections work imagine travel bags. 31 * They usually come in different sizes and one can put a bag in a bag when 32 * they put away to the shelf in a garage or closet. Collection is such bag 33 * except that you can put other bags into each other even if they are not 34 * empty.<br> 35 * When you put items into a bag you do not see the contents of the bag. 36 * You just hold the bag. How many other bags inside this bag you do not know. 37 * But you might know that you put a "wallet" somewhere there. 38 * You ask the bag you hold: "find my wallet and give it to me". 39 * get_item function will return you the item that is your "wallet". 40 * You can then change something or just get information about the item you 41 * retrieved. But in most cases you do not need the wallet itself. You want to 42 * get something from the wallet or put something into it. IMO money would 43 * be an obvious choice. To do this you use update_xxx_property functions.<br> 44 * There might be a bag somewhere deep and you might want to add something to 45 * it. add_xxx_property_xxx functions allow you to specify sub collection you 46 * want the item to be added to. If this sub collection argument is NULL top 47 * level collection is assumed.<br> 48 * The search in the collections uses a "x!y!z" notation to refer to an item (or 49 * property). You can search for "wallet" and it will find any first instance of 50 * the "wallet" in your luggage. But you might have two wallets. One is yours and 51 * another is your significant other's. So you might say find "my!wallet". 52 * It will find wallet in your bag (collection) named "my". This collection can 53 * be many levels deep inside other collections. You do not need to know the 54 * full path to get to it. But if you have the full path you can use the fill 55 * path like this "luggage!newbags!my!wallet".<br> 56 * It is useful to be able to put bags into bags as well as get them out of each 57 * other. When the collection is created the header keeps a reference count on 58 * how many copies of the collection are known to the world. So one can put a 59 * collection into collection and give up its access to it (embed) or still hold 60 * to the reference. By embedding the collection the caller effectively gives 61 * up its responsibility to destroy the collection after it is used.<br> 62 * By extracting reference from an internal collection the caller gains access 63 * to the collection directly and thus has responsibility to destroy it after 64 * use. 65 * 66 * Internally collection is implemented as a link list rather than a hash 67 * table. 68 * This makes it suitable for small (dozens of items) sets of data for which 69 * the order is important. Thus the collection properties and sub collections 70 * can be used to model objects like a book case. Imagine a book case that 71 * consists of multiple shelves. You can perform operations like "add a new 72 * shelf after second shelf" or "put a book on the 4th shelf right before 73 * the book with the red cover." 74 * 75 * A bit of terminology: 76 * - <b>collection</b> - an object implemented as a link list that holds 77 * properties (attributes). 78 * - <b>property</b> - a named logical element of the collection. 79 * - <b>item</b> - physical element of the collection, think about it 80 * as a node in the link list. 81 * - <b>value</b> - data associated with the property. 82 * - <b>type</b> - type of the data associated with a property. 83 * - <b>length</b> - length of the data associated with the property. 84 * - <b>sub collection</b> - collection embedded into another collection. 85 * It is a property with the value of a special 86 * type. The name of the property that denotes 87 * a sub collection can be different from the name 88 * of the collection it refers to. 89 * - <b>traverse</b> - call a function that will internally iterate 90 * through a collection and do something with its 91 * elements. 92 * - <b>iterate</b> - step through a collection yourselves. 93 * 94 * Characters with codes less than space in ASCII table are illegal for 95 * property names. 96 * Character '!' also illegal in a property or collection name and 97 * reserved for "x!y!z" notation. 98 * 99 * There is always a header item in any collection that starts the collection. 100 * Most of the functions in the interface (unless explicitly stated otherwise) 101 * assume that the collection_item * argument points to the header element. 102 * Passing in elements extracted from the middle of a collection to functions 103 * that expect header elements is illegal. There might be not enough checking 104 * at the moment but this will be enforced in future versions of the library. 105 * 106 */ 107 108 #ifndef EOK 109 #define EOK 0 110 #endif 111 112 /** 113 * @defgroup collection COLLECTION interface 114 * @{ 115 */ 116 117 /** 118 * @brief Default class for a free form collection. 119 */ 120 #define COL_CLASS_DEFAULT 0 121 122 /** 123 * @brief Value indicates that property is not found. 124 * 125 * Used in search functions. 126 */ 127 #define COL_NOMATCH 0 128 /** 129 * @brief Value indicates that property is found. 130 * 131 * Used in search functions. 132 */ 133 #define COL_MATCH 1 134 135 136 /** 137 * @defgroup coltypes Type definition constants 138 * @{ 139 */ 140 /** 141 * @brief Indicates that property is of type "string". 142 * 143 * For elements of type string the length includes the trailing 0. 144 */ 145 #define COL_TYPE_STRING 0x00000001 146 /** @brief Indicates that property is of type "binary". */ 147 #define COL_TYPE_BINARY 0x00000002 148 /** @brief Indicates that property is of type "integer". */ 149 #define COL_TYPE_INTEGER 0x00000004 150 /** @brief Indicates that property is of type "unsigned". */ 151 #define COL_TYPE_UNSIGNED 0x00000008 152 /** @brief Indicates that property is of type "long". */ 153 #define COL_TYPE_LONG 0x00000010 154 /** @brief Indicates that property is of type "unsigned long". */ 155 #define COL_TYPE_ULONG 0x00000020 156 /** @brief Indicates that property is of type "double". */ 157 #define COL_TYPE_DOUBLE 0x00000040 158 /** @brief Indicates that property is of Boolean type. */ 159 #define COL_TYPE_BOOL 0x00000080 160 /** 161 * @brief Indicates that property is of type "collection". 162 * 163 * The item of this type denotes that starting element of a 164 * collection. 165 */ 166 #define COL_TYPE_COLLECTION 0x00000100 167 /** 168 * @brief Indicates that property is of type "sub collection". 169 * 170 * An item of this type is a pointer to an existing external 171 * collection. 172 */ 173 #define COL_TYPE_COLLECTIONREF 0x00000200 174 /** 175 * @brief Special type that denotes the end of the collection. 176 * 177 * Useful when traversing collections. 178 */ 179 #define COL_TYPE_END 0x10000000 180 /** 181 * @brief Special type that denotes any property in the collection. 182 * 183 * Useful when traversing collection and searching for a property 184 * of unknown type but known name. 185 */ 186 #define COL_TYPE_ANY 0x0FFFFFFF 187 /** 188 * @} 189 */ 190 191 192 /** 193 * @defgroup addmodes Constants defining add modes 194 * 195 * The following constants define how one collection can be added to another. 196 * 197 * @{ 198 */ 199 /** @brief Add a collection into a collection as a reference */ 200 #define COL_ADD_MODE_REFERENCE 0 201 /** 202 * @brief Embed the collection into another collection. 203 * 204 * The collection will become part of another collection. 205 * After this operation the handle to the collection being added 206 * should not be used or freed. 207 * Embedding a collection can be done only once. 208 * If the collection is referenced by another collection, 209 * the operation will fail. 210 */ 211 #define COL_ADD_MODE_EMBED 1 212 /** 213 * @brief Perform a deep copy. 214 * 215 * Perform a deep copy of a collection with 216 * all its sub collections */ 217 #define COL_ADD_MODE_CLONE 2 218 /** 219 * @brief Create a flattened copy. 220 * 221 * Create a deep copy of a collection with 222 * its sub collections flattening and NOT 223 * resolving duplicates. 224 */ 225 #define COL_ADD_MODE_FLAT 3 226 /** 227 * @brief Create a flattened copy with constructed names. 228 * 229 * Creates a deep copy of a collection with 230 * its sub collections flattening and NOT 231 * resolving duplicates. Names are constructed 232 * in dotted notation. 233 * For example the sub collection 234 * named "sub" containing "foo" and 235 * "bar" will be flattened as: 236 * "sub.foo", "sub.bar". 237 */ 238 #define COL_ADD_MODE_FLATDOT 4 239 /** 240 * @} 241 */ 242 243 244 /** 245 * @defgroup traverseconst Constants defining traverse modes 246 * 247 * The following constants define how a collection can be 248 * traversed or iterated. 249 * 250 * Flags defined below can generally be combined with each other. 251 * 252 * \ref COL_TRAVERSE_FLAT, \ref COL_TRAVERSE_SHOWSUB, 253 * \ref COL_TRAVERSE_ONLYSUB are mutually exclusive flags. 254 * If combined together results will be unpredictable.<br> 255 * <b>DO NOT MIX THEM IN ONE ITERATOR.</b> 256 * 257 * 258 * @{ 259 */ 260 /** @brief Traverse all items in the collection. */ 261 #define COL_TRAVERSE_DEFAULT 0x00000000 262 /** 263 * @brief Traverse only the top level. 264 * 265 * Traverse only top level 266 * ignored if the IGNORE flag is 267 * specified 268 */ 269 #define COL_TRAVERSE_ONELEVEL 0x00000001 270 /** 271 * @brief Insert end collection marker. 272 * 273 * Call the handler once more when the 274 * end of the collection is reached. 275 * Specifying this flag would cause a traversing 276 * function to call a callback once more passing 277 * in a virtual property of type \ref COL_TYPE_END. 278 * Good for processing nested collections. 279 */ 280 #define COL_TRAVERSE_END 0x00000002 281 /** @brief Ignore sub collections as if none is present. */ 282 #define COL_TRAVERSE_IGNORE 0x00000004 283 /** 284 * @brief Flatten the collection. 285 * 286 * Traversing this way would act as if 287 * all the properties of sub collection are properties 288 * of the root collection. The referencing properties or 289 * headers of the referenced collections are skipped. 290 * 291 * If we think of the book case example 292 * this is very useful when one wants to iterate through 293 * all the books skipping information about 294 * which shelf they are on. 295 */ 296 #define COL_TRAVERSE_FLAT 0x00000008 297 /** 298 * @defgroup moreiterflag Additional iterator flags 299 * 300 * \note NOTE: These flags ignored by traverse functions and 301 * can be used only in the iterator. 302 * 303 * @{ 304 */ 305 /** 306 * @brief Include headers of sub collections. 307 * 308 * When one collection is embedded or referenced by another collection 309 * there are two names we can be interested in. The name of the property 310 * that defines the reference and the name of the embedded collection. 311 * It is recommended that they be the same, however there may be cases 312 * when the name of the referencing property and referenced collection 313 * should be different. By default only the name of the referencing 314 * property is returned while iterating through the collection and 315 * its sub collections. Specifying this flag would cause the names 316 * of the collection (header elements) be included into the iteration 317 * process. 318 * 319 * Flag is ignored if the \ref COL_TRAVERSE_ONELEVEL flag is 320 * specified and not ignored. 321 * Flag is ignored is also ignored if the FLAT flag is specified. */ 322 #define COL_TRAVERSE_SHOWSUB 0x00010000 323 /** 324 * @brief Show sub collections. 325 * 326 * Show the header of the sub collection instead of the reference. 327 * Flag is ignored if the \ref COL_TRAVERSE_ONELEVEL flag is 328 * specified and not ignored. 329 * Flag is ignored is also ignored if the FLAT flag is specified. */ 330 #define COL_TRAVERSE_ONLYSUB 0x00020000 331 /** 332 * @} 333 */ 334 335 /** 336 * @} 337 */ 338 339 /** 340 * @defgroup copyconst Constants defining copy modes 341 * 342 * The following constants define modes accepted by copy 343 * collection function(s). 344 * 345 * @{ 346 */ 347 /** 348 * @brief Perform a deep copy. 349 * 350 * Referenced collections of the donor are copied as sub 351 * collections. 352 */ 353 #define COL_COPY_NORMAL 0 354 /** 355 * @brief Perform a deep flat copy. 356 * 357 * Collection is flattened. No name construction performed. 358 */ 359 #define COL_COPY_FLAT 1 360 /** 361 * @brief Perform a deep flat copy constructing names. 362 * 363 * Collection is flattened. Names are concatenated with dot. 364 */ 365 #define COL_COPY_FLATDOT 2 366 /** @brief Perform a deep copy but leave references as references. */ 367 #define COL_COPY_KEEPREF 3 368 /** @brief Copy only top level collection. */ 369 #define COL_COPY_TOP 4 370 /** 371 * @} 372 */ 373 374 /** 375 * @defgroup sortconst Constants defining sort order 376 * 377 * All flags can be combined in OR operation. 378 * Flags \ref COL_SORT_ASC and \ref COL_SORT_DESC are 379 * mutually exclusive. If both specified the 380 * collection will be sorted in the descending order. 381 * 382 * @{ 383 */ 384 /** @brief Sort in ascending order. */ 385 #define COL_SORT_ASC 0x00000000 386 /** @brief Sort in descending order. */ 387 #define COL_SORT_DESC 0x00000001 388 /** @brief Sort all sub collections. */ 389 #define COL_SORT_SUB 0x00000002 390 /** 391 * @brief Sort only embedded sub collections. 392 * 393 * Ignored if \ref COL_SORT_SUB is not specified. 394 */ 395 #define COL_SORT_MYSUB 0x00000004 396 /** 397 * @} 398 */ 399 400 401 /* Public declaration of the private data */ 402 #ifndef COLLECTION_PRIV_H 403 /** 404 * @struct collection_item 405 * @brief Opaque structure that holds one property. 406 * 407 * Your implementation can assume that following members 408 * will always be members of the collection_item. 409 * but you should use get_item_xxx functions to get them 410 * and never access internal data directly. 411 * 412 * - char *property; 413 * - int property_len; 414 * - int type; 415 * - int length; 416 * - void *data; 417 */ 418 struct collection_item; 419 /** 420 * @struct collection_iterator 421 * @brief Opaque iterator structure. 422 * 423 * The iterator structure is used 424 * when one wants to traverse the collection 425 * going through its properties and optionally 426 * sub collections. 427 * 428 * Caller should never assume 429 * anything about internals of this structure. 430 */ 431 struct collection_iterator; 432 433 #endif /* COLLECTION_PRIV_H */ 434 435 436 /** 437 * @brief Create a collection 438 * 439 * The function will create a collection. 440 * Each collection should have name and class. 441 * 442 * @param[out] ci Newly allocated collection object. 443 * @param[in] name The name is supposed to be a unique identifier of 444 * the collection. This is useful when the collections 445 * are stored within other collections or inside other 446 * aggregation objects. Caller is free to use any name. 447 * Name should consist of the ASCII characters with codes 448 * non less than space. Exclamation mark character is 449 * a special character and can't be used in name of 450 * collection or property.<br> 451 * Maximum allowed length is defined at compile time. 452 * The default value is 64k. 453 * @param[in] cclass Class is used to relate the collection to a specific 454 * group of the collections of the same structure. 455 * This is very useful when you try to represent 456 * objects using collections and you want to check if 457 * the objects have same structure or not. 458 * There is no predefined name space for the collection 459 * classes. Defining classes is left to the application 460 * developers.<br> 461 * <b>NOTE:</b> 462 * If you decide to build an interface using collection 463 * library pick a range for the classes you are 464 * going to use and make sure that they do not collide 465 * with other interfaces built on top of the collection. 466 * 467 * @return 0 - Collection was created successfully. 468 * @return ENOMEM - No memory. 469 * @return EINVAL - Invalid characters in the collection name. 470 * @return EMSGSIZE - Collection name is too long. 471 */ 472 int col_create_collection(struct collection_item **ci, 473 const char *name, 474 unsigned cclass); 475 476 /** 477 * @brief Destroy a collection 478 * 479 * The function will destroy a collection. 480 * 481 * @param[in] ci Collection object. 482 * 483 */ 484 void col_destroy_collection(struct collection_item *ci); 485 486 /** 487 * @brief Cleanup Callback 488 * 489 * Signature of the callback that needs to be used when 490 * the collection is destroyed and a special cleanup operation 491 * is required for items in the collection. 492 * 493 * @param[in] property The name of the property will 494 * be passed in this parameter. 495 * @param[in] property_len Length of the property name 496 * will be passed in this parameter. 497 * @param[in] type Type of the data will be passed 498 * in this parameter. 499 * @param[in] data Pointer to the data will be passed 500 * in this parameter. 501 * @param[in] length Length of data will be passed in 502 * this parameter. 503 * @param[in] custom_data Custom data will be passed in 504 * this parameter. 505 */ 506 507 typedef void (*col_item_cleanup_fn)(const char *property, 508 int property_len, 509 int type, 510 void *data, 511 int length, 512 void *custom_data); 513 514 /** 515 * @brief Destroy a collection with callback 516 * 517 * Execute a provided callback for each item 518 * in the collection or subcollection immediately 519 * before freeing item. The callback is executed for each 520 * element including the collection header. 521 * It is the responsibility of the callback implementor 522 * to properly handle gifferent collection elements 523 * depending upon whether it is a header, reference to 524 * an embedded or external collection or a normal data 525 * element. 526 * 527 * The function will destroy a collection. 528 * 529 * @param[in] ci Collection object. 530 * @param[in] cb Cleanup callback. 531 * @param[in] custom_data Application data passed into 532 * the cleanup callback. 533 * 534 */ 535 void col_destroy_collection_with_cb(struct collection_item *ci, 536 col_item_cleanup_fn cb, 537 void *custom_data); 538 539 /** 540 * @brief Copy item callback. 541 * 542 * Callback is used by the 543 * \ref col_copy_collection_with_cb "col_copy_collection_with_cb" function. 544 * Function is called after the new item is created but not yet 545 * inserted into the target collection. 546 * The implementer of the callback can alter the item data 547 * or indicate to the caller that the item should be skipped. 548 * 549 * @param[in] item Newly allocated item that will be inserted 550 * into the new collection. 551 * @param[in] ext_data Data the application might want to 552 * pass to the callback. 553 * @param[out] skip Pointer to a variable that indicates if the 554 * item should be skipped or not. 555 * Set this variable to any nonzero value 556 * and the item will be skipped. 557 * @return 0 - Success 558 * @return Function can return any error code. This code 559 * will be propagated through the internal functions and 560 * returned to the application. 561 * 562 */ 563 typedef int (*col_copy_cb)(struct collection_item *item, 564 void *ext_data, 565 int *skip); 566 567 /** 568 * @brief Copy collection with data modification. 569 * 570 * Function create a deep copy of the current collection. 571 * Calls caller provided callback before copying each item's data. 572 * This is useful if the data needs to be resolved in some way. 573 * The best use is when the template is copied and the values 574 * in the template are resolved to the actual values. 575 * The acceptable modes are defined \ref copyconst "here". 576 * 577 * @param[out] col_copy Newly created collection object. 578 * @param[in] col_to_copy Collection object that will be copied. 579 * @param[in] name_to_use Name of the new collection. 580 * @param[in] copy_mode How to \ref copyconst "copy". 581 * @param[in] copy_cb Pointer to a callback \ref col_copy_cb. 582 * Can be NULL. In this case data is copied 583 * without modification. 584 * @param[in] ext_data Data the application might want to 585 * pass to the callback. 586 * 587 * @return 0 - Collection was copied successfully. 588 * @return ENOMEM - No memory. 589 * @return EINVAL - The value of some of the arguments is invalid. 590 * @return Any error code returned by the callback. 591 * 592 */ 593 int col_copy_collection_with_cb(struct collection_item **col_copy, 594 struct collection_item *col_to_copy, 595 const char *name_to_use, 596 int copy_mode, 597 col_copy_cb copy_cb, 598 void *ext_data); 599 600 /** 601 * @brief Copy collection without data modification. 602 * 603 * Function creates a deep copy of the current collection. 604 * It wraps the \ref col_copy_collection_with_cb function. 605 * The acceptable modes are defined \ref copyconst "here". 606 * 607 * @param[out] col_copy Newly created collection object. 608 * @param[in] col_to_copy Collection object that will be copied. 609 * @param[in] name_to_use Name of the new collection. 610 * @param[in] copy_mode How to \ref copyconst "copy". 611 * 612 * @return 0 - Collection was copied successfully. 613 * @return ENOMEM - No memory. 614 * @return EINVAL - The value of some of the arguments is invalid. 615 * 616 */ 617 int col_copy_collection(struct collection_item **col_copy, 618 struct collection_item *col_to_copy, 619 const char *name_to_use, 620 int copy_mode); 621 622 /** 623 * @brief Add collection to collection. 624 * 625 * Function adds one collection into another 626 * depending upon a specified \ref addmodes "mode". 627 * 628 * @param[in] ci Root collection object. 629 * @param[in] subcollection Name of the inner collection to 630 * add collection to. If NULL the collection 631 * is added to the root collection. 632 * @param[in] as_property Name of the property that will constitute 633 * the reference. If NULL the name of 634 * the collection being added will be used. 635 * If specified the restrictions to 636 * the name characters and length apply. 637 * For more details about the name related 638 * restrictions see 639 * \ref addproperty "col_add_xxx_property" 640 * functions. 641 * @param[in] ci_to_add Collection to add. 642 * @param[in] mode Specifies \ref addmodes "how" 643 * the collection should be added. 644 * 645 * @return 0 - Collection was added successfully. 646 * @return ENOMEM - No memory. 647 * @return EINVAL - The value of some of the arguments is invalid. 648 * The attempt to update a property which is 649 * a reference to a collection or a collection 650 * name. 651 * @return ENOENT - Property to update is not found. 652 */ 653 int col_add_collection_to_collection(struct collection_item *ci, 654 const char *subcollection, 655 const char *as_property, 656 struct collection_item *ci_to_add, 657 int mode); 658 /** 659 * @brief Search Callback 660 * 661 * Signature of the callback that needs to be used when 662 * traversing a collection or looking for a specific item. 663 * 664 * @param[in] property The name of the property will 665 * be passed in this parameter. 666 * @param[in] property_len Length of the property name 667 * will be passed in this parameter. 668 * @param[in] type Type of the data will be passed 669 * in this parameter. 670 * @param[in] data Pointer to the data will be passed 671 * in this parameter. 672 * @param[in] length Length of data will be passed in 673 * this parameter. 674 * @param[in] custom_data Custom data will be passed in 675 * this parameter. 676 * @param[out] stop Pointer to a variable where the handler 677 * can put nonzero to stop traversing 678 * of the collection. 679 * @return 0 - Success 680 * @return Function can return any error code. This code 681 * will be propagated through the internal functions and 682 * returned to the application. 683 */ 684 typedef int (*col_item_fn)(const char *property, 685 int property_len, 686 int type, 687 void *data, 688 int length, 689 void *custom_data, 690 int *stop); 691 692 /** 693 * @brief Traverse collection 694 * 695 * Function to traverse the entire collection 696 * including (optionally) sub collections. 697 * 698 * @param[in] ci Collection object to traverse. 699 * @param[in] mode_flags How to traverse. 700 * See details \ref traverseconst "here". 701 * @param[in] item_handler Application supplied callback. 702 * It will be called for each item 703 * in the collection including headers. 704 * @param[in] custom_data Custom data that application 705 * might want to pass to the callback. 706 * 707 * @return 0 - Collection was traversed successfully. 708 * @return ENOMEM - No memory. 709 * @return EINVAL - The value of some of the arguments is invalid. 710 * @return Any error code returned by the callback. 711 * 712 */ 713 int col_traverse_collection(struct collection_item *ci, 714 int mode_flags, 715 col_item_fn item_handler, 716 void *custom_data); 717 718 /** 719 * @brief Search and do function. 720 * 721 * Looks up an item in the collection based on the property and type. 722 * Actually it is a traverse function with special traversing logic. 723 * It traverses the whole collection but calls the supplied 724 * callback only for the items that match the search criteria. 725 * It is the responsibility of the caller to define how the callback 726 * is going to indicate that the item it was looking for is found. 727 * Function will not return error if the item is not found. 728 * It is the responsibility of the calling application to check 729 * the data passed in custom_data and see if the item was found and 730 * that the action was performed. 731 * 732 * @param[in] ci Collection object to traverse. 733 * @param[in] property_to_find Name of the property to find. 734 * Parameter supports "x!y" 735 * notation. 736 * @param[in] type Type filter. Only properties 737 * of the given type will match. 738 * Can be 0 to indicate that all 739 * types should be evaluated. 740 * @param[in] mode_flags How to traverse the collection. 741 * See details \ref traverseconst "here". 742 * @param[in] item_handler Function to call when the item is found. 743 * @param[in] custom_data Custom data passed to the callback. 744 * 745 * @return 0 - Operation completed successfully. 746 * @return EINVAL - The value of some of the arguments is invalid. 747 * @return ENOENT - The search criteria is incorrect. 748 * @return ENOMEM - No memory. 749 * @return Any error code returned by the callback. 750 * 751 */ 752 int col_get_item_and_do(struct collection_item *ci, 753 const char *property_to_find, 754 int type, 755 int mode_flags, 756 col_item_fn item_handler, 757 void *custom_data); 758 759 /** 760 * @brief Search function to get an item. 761 * 762 * Convenience function to get individual item. 763 * Caller should be aware that this is not a copy of the item 764 * but the pointer to actual item stored in the collection. 765 * The returned pointer should never be altered or freed by caller of the function. 766 * The caller should be sure that the collection does not go out of scope 767 * while the pointer to its data is in use. 768 * Working with the internals of the collection item structure directly 769 * may cause problems in future if the internal implementation changes. 770 * The caller needs to be aware that function does not return 771 * error if item is not found. The caller needs to check if 772 * item is not NULL to determine whether something was found. 773 * Internally function is a wrapper around the \ref col_get_item_and_do 774 * function. 775 * 776 * Use \ref getitem "item management" functions to work with the item. 777 * 778 * @param[in] ci Collection object to traverse. 779 * @param[in] property_to_find Name of the property to find. 780 * Parameter supports "x!y" 781 * notation. 782 * @param[in] type Type filter. Only properties 783 * of the given type will match. 784 * Can be 0 to indicate that all 785 * types should be evaluated. 786 * @param[in] mode_flags How to traverse the collection. 787 * See details \ref traverseconst "here". 788 * @param[in] item Pointer to found item or NULL 789 * if item is not found. 790 * 791 * @return 0 - No internal errors during search. 792 * @return EINVAL - The value of some of the arguments is invalid. 793 * @return ENOENT - The search criteria is incorrect. 794 * @return ENOMEM - No memory. 795 * 796 */ 797 int col_get_item(struct collection_item *ci, 798 const char *property_to_find, 799 int type, 800 int mode_flags, 801 struct collection_item **item); 802 803 /** 804 * @brief Search function to get one of the duplicate items. 805 * 806 * Convenience function to get an individual item out of the list of duplicates. 807 * Caller should be aware that this is not a copy of the item 808 * but the pointer to actual item stored in the collection. 809 * The returned pointer should never be altered or freed by caller 810 * of the function. 811 * The caller should be sure that the collection does not go out of scope 812 * while the pointer to its data is in use. 813 * Working with the internals of the collection item structure directly 814 * may cause problems in future if the internal implementation changes. 815 * If collection to search or property to find is NULL function returns NULL. 816 * 817 * Use \ref getitem "item management" functions to work with the item. 818 * 819 * @param[in] ci Collection object to traverse. 820 * @param[in] subcollection Name of the sub collection to find 821 * item in. If NULL, the top level collection 822 * is used. One can use "foo!bar!baz" 823 * notation to identify the sub collection. 824 * @param[in] property_to_find Name of the property to find. 825 * @param[in] type Type filter. Only properties 826 * of the given type will match. 827 * Can be 0 to indicate that all 828 * types should be evaluated. 829 * @param[in] idx Index of the duplicate to find. 830 * 0 - any first instance 831 * positive - N-th instance (index is 0-based) 832 * negative - last instance 833 * @param[in] exact If 0 then if index above is greater than 834 * actual number of duplicates the last duplicate 835 * if be returned. 836 * If non-zero the funtion will return ENOENT 837 * in case the index is greater than actual 838 * number of duplicates. 839 * @param[out] item Pointer to found item or NULL 840 * if item is not found. 841 * @return 0 No errors. 842 * @return EINVAL Invalid argument. 843 * @return ENOENT Item is not found. 844 */ 845 int col_get_dup_item(struct collection_item *ci, 846 const char *subcollection, 847 const char *property_to_find, 848 int type, 849 int idx, 850 int exact, 851 struct collection_item **item); 852 853 /** 854 * @brief Sort collection. 855 * 856 * If the sub collections are included in sorting 857 * each collection is sorted separately (this is not a global sort). 858 * It might be dangerous to sort sub collections if 859 * sub collection is not owned by the current collection. 860 * If it is a reference to an external collection 861 * there might be an issue. To skip the collections that 862 * externally referenced use \ref COL_SORT_MYSUB flag. 863 * Keep in mind that if a collection is referenced 864 * more than once by other collection and that collection 865 * is sorted with sub collections the referenced 866 * collection will be sorted more than once. 867 * 868 * NOTE: Current implementation of the sorting 869 * function is very simple and alternative 870 * implementations might be provided later. 871 * 872 * @param[in] col Collection to sort. 873 * @param[in] cmp_flags For more information see 874 * \ref compflags "comparison flags". 875 * @param[in] sort_flags For more information see 876 * \ref sortconst "sort flags". 877 * 878 * @return 0 - No internal errors during sorting. 879 * @return EINVAL - The value of some of the arguments is invalid. 880 * 881 */ 882 int col_sort_collection(struct collection_item *col, 883 unsigned cmp_flags, 884 unsigned sort_flags); 885 886 /** 887 * @brief Delete property. 888 * 889 * Delete property from the collection. 890 * It is recommended to use a more efficient function 891 * \ref col_remove_item for the same purpose if 892 * the property is unique or if the collection 893 * has a known structure. 894 * The col_delete_property function has some advantage only 895 * if it is not known where property 896 * resides and what is the structure of the collection. 897 * In this case "foo!bar!baz" notation can be used in 898 * the property_to_find argument to find and delete 899 * the property "baz" that is in a sub collection "bar" 900 * which is in turn a part of a collection "foo". 901 * 902 * @param[in] ci Collection to delete property from. 903 * @param[in] property_to_find Property to delete. 904 * @param[in] type Use type if names are not unique 905 * and you know the type of the value 906 * you want to delete. Otherwise set to 0. 907 * @param[in] mode_flags The flags define how the collection 908 * should be searched. For more information 909 * see \ref traverseconst "traverse constants". 910 * 911 * @return 0 - Property was deleted successfully. 912 * @return EINVAL - The value of some of the arguments is invalid. 913 * @return ENOMEM - No memory. 914 * @return ENOENT - Property not found. 915 * 916 */ 917 int col_delete_property(struct collection_item *ci, 918 const char *property_to_find, 919 int type, 920 int mode_flags); 921 922 /** 923 * @brief Is property in the collection? 924 * 925 * Convenience function to check if the property 926 * is indeed in the collection. 927 * 928 * @param[in] ci Collection to search. 929 * @param[in] property_to_find Property to find. 930 * @param[in] type Use type if names are not unique 931 * and you know the type of the value 932 * you want to check. Otherwise set to 0. 933 * @param[in] mode_flags The flags define how the collection 934 * should be searched. For more information 935 * see \ref traverseconst "traverse constants". 936 * @param[out] found The variable that will receive the result 937 * of the search. 938 * COL_NOMATCH - if not found 939 * COL_MATCH if found 940 * 941 * @return 0 - Search completed successfully. 942 * @return EINVAL - The value of some of the arguments is invalid. 943 * @return ENOMEM - No memory. 944 * 945 */ 946 int col_is_item_in_collection(struct collection_item *ci, 947 const char *property_to_find, 948 int type, 949 int mode_flags, 950 int *found); 951 952 /** 953 * @brief Get a reference to a collection 954 * 955 * Get a pointer to a collection included into another collection. 956 * If the col_to_find is NULL function returns a reference 957 * to the top level collection. 958 * Delete extracted collection after use to decrease reference count. 959 * 960 * @param[in] ci Collection to search. 961 * @param[out] acceptor Variable that accepts pointer to 962 * an extracted collection. 963 * Use \ref col_destroy_collection to 964 * free returned object reference after 965 * use. 966 * @param[in] col_to_find Collection to find. 967 * "foo!bar!baz" notation can be used. 968 * 969 * @return 0 - Success. 970 * @return EINVAL - The value of some of the arguments is invalid. 971 * @return ENOMEM - No memory. 972 */ 973 int col_get_collection_reference(struct collection_item *ci, 974 struct collection_item **acceptor, 975 const char *col_to_find); 976 977 /** 978 * @brief Get a reference from the item 979 * 980 * Get a pointer to a collection from a current item 981 * if current item is a reference to the collection. 982 * If current item is not a reference to a collection an error 983 * will be returned. 984 * Delete extracted collection after use to decrease reference count. 985 * 986 * @param[in] item Item to extract the reference from. 987 * @param[out] acceptor Variable that accepts pointer to 988 * an extracted collection. 989 * Use \ref col_destroy_collection to 990 * free returned object reference after 991 * use. 992 * 993 * @return 0 - Success. 994 * @return EINVAL - The value of some of the arguments is invalid. 995 */ 996 int col_get_reference_from_item(struct collection_item *item, 997 struct collection_item **acceptor); 998 999 1000 1001 /** 1002 * @brief Get collection class. 1003 * 1004 * The classes of the collections can be used to convey information 1005 * about the collection's internal structure. 1006 * Some interfaces built on top of the collection might 1007 * impose restrictions on the collection structure. 1008 * For example the interface can decide that it is going 1009 * to deal with the collections that do not have sub collections 1010 * and elements of the collections are always only strings. 1011 * So the interface will define a class of the collection 1012 * and create a function that would take the strings and create 1013 * such a collection. Then other functions of that interface 1014 * would check if the provided collection is of the specified class. 1015 * If not the interface would reject the collection right away. 1016 * If the collection is of the valid class the interface might 1017 * call the validation function to make sure that this is really 1018 * the case however it needs to validate it only once and lower level 1019 * functions can rely on the class value of the collection 1020 * without performing duplicate validation. 1021 * 1022 * @param[in] ci Collection object. 1023 * @param[out] cclass Variable that will receive 1024 * the value of the class. 1025 * @return 0 - Success. 1026 * @return EINVAL - The value of some of the arguments is invalid. 1027 * 1028 */ 1029 int col_get_collection_class(struct collection_item *ci, 1030 unsigned *cclass); 1031 1032 /** 1033 * @brief Set collection class. 1034 * 1035 * Sometimes as a result of the collection modification 1036 * the class of the collection can change. 1037 * 1038 * @param[in] ci Collection object. 1039 * @param[in] cclass New class value. 1040 * 1041 * @return 0 - Success. 1042 * @return EINVAL - The value of some of the arguments is invalid. 1043 * 1044 */ 1045 int col_set_collection_class(struct collection_item *ci, 1046 unsigned cclass); 1047 1048 /** 1049 * @brief Get count of the elements. 1050 * 1051 * It is useful to know how many items are there in the collection. 1052 * 1053 * @param[in] ci Collection object. 1054 * @param[out] count Variable will receive the value 1055 * of the number of the items in 1056 * the collection. Collection 1057 * header or references to external 1058 * collections are counted as well. 1059 * This means that every collection 1060 * has at least one item - the header. 1061 * 1062 * @return 0 - Success. 1063 * @return EINVAL - The value of some of the arguments is invalid. 1064 * 1065 */ 1066 int col_get_collection_count(struct collection_item *ci, 1067 unsigned *count); 1068 1069 1070 /** 1071 * @brief Check the class of collection. 1072 * 1073 * Convenience function to check if the collection is of the specific class. 1074 * In case of internal error assumes that collection is not of the right class. 1075 * 1076 * @param[in] ci Collection object. 1077 * @param[in] cclass Class value to compare to to. 1078 * 1079 * @return 0 - If any internal error or classes do not match. 1080 * @return 1 - No error and classes do match. 1081 * 1082 */ 1083 int col_is_of_class(struct collection_item *ci, 1084 unsigned cclass); 1085 1086 1087 /** 1088 * @defgroup addproperty Add property functions 1089 * 1090 * Functions in this section add properties to a collection. 1091 * 1092 * All the functions in this section add a property of the specified 1093 * type to the collection object. 1094 * They are convenience wrappers around the col_insert_xxx_property 1095 * functions. 1096 * They always append property to the end of the collection. 1097 * 1098 * Common parameters for these functions are: 1099 * 1100 * @param[in] ci Root collection object. 1101 * @param[in] subcollection Name of the inner collection to 1102 * add property to. If NULL the property 1103 * is added to the root collection. 1104 * @param[in] property Name of the property.<br> 1105 * Name should consist of the ASCII characters 1106 * with codes non less than space. 1107 * Exclamation mark character is 1108 * a special character and can't be used 1109 * in name of collection or property.<br> 1110 * Maximum allowed length is defined at compile time. 1111 * The default value is 64k. 1112 * 1113 * @return 0 - Property was added successfully. 1114 * @return ENOMEM - No memory. 1115 * @return EINVAL - Invalid characters in the property name. 1116 * Value argument is invalid in some way. 1117 * @return EMSGSIZE - Property name is too long. 1118 * @return ENOENT - Sub collection is not found. 1119 * 1120 * @{ 1121 */ 1122 1123 /** 1124 * @brief Add a string property to a collection. 1125 * 1126 * @param[in] ci Root collection object. 1127 * @param[in] subcollection Name of the inner collection to 1128 * add property to. If NULL the property 1129 * is added to the root collection. 1130 * @param[in] property Name of the property.<br> 1131 * Name should consist of the ASCII characters 1132 * with codes non less than space. 1133 * Exclamation mark character is 1134 * a special character and can't be used 1135 * in name of collection or property.<br> 1136 * Maximum allowed length is defined at compile time. 1137 * The default value is 64k. 1138 * @param[in] string Null terminated string to add. 1139 * @param[in] length Length of the string. Should include the length 1140 * of the terminating 0. 1141 * If the length is shorter than the full string 1142 * the string will be truncated. If the length is 1143 * longer than the actual string there might be 1144 * garbage at end of the actual string. 1145 * Library will always properly NULL terminate 1146 * the string at the given position dictated 1147 * by length but in no way will inspect the validity 1148 * of the passed in data. This is left to the calling 1149 * application. 1150 * 1151 * @return 0 - Property was added successfully. 1152 * @return ENOMEM - No memory. 1153 * @return EINVAL - Invalid characters in the property name. 1154 * Value argument is invalid in some way. 1155 * @return EMSGSIZE - Property name is too long. 1156 * @return ENOENT - Sub collection is not found. 1157 * 1158 */ 1159 int col_add_str_property(struct collection_item *ci, 1160 const char *subcollection, 1161 const char *property, 1162 const char *string, 1163 int length); 1164 1165 /** 1166 * @brief Add a binary property to a collection. 1167 * 1168 * @param[in] ci Root collection object. 1169 * @param[in] subcollection Name of the inner collection to 1170 * add property to. If NULL the property 1171 * is added to the root collection. 1172 * @param[in] property Name of the property.<br> 1173 * Name should consist of the ASCII characters 1174 * with codes non less than space. 1175 * Exclamation mark character is 1176 * a special character and can't be used 1177 * in name of collection or property.<br> 1178 * Maximum allowed length is defined at compile time. 1179 * The default value is 64k. 1180 * @param[in] binary_data Data to add. 1181 * @param[in] length Length of the data. 1182 * 1183 * @return 0 - Property was added successfully. 1184 * @return ENOMEM - No memory. 1185 * @return EINVAL - Invalid characters in the property name. 1186 * Value argument is invalid in some way. 1187 * @return EMSGSIZE - Property name is too long. 1188 * @return ENOENT - Sub collection is not found. 1189 * 1190 */ 1191 int col_add_binary_property(struct collection_item *ci, 1192 const char *subcollection, 1193 const char *property, 1194 void *binary_data, 1195 int length); 1196 1197 /** 1198 * @brief Add an integer property to a collection. 1199 * 1200 * @param[in] ci Root collection object. 1201 * @param[in] subcollection Name of the inner collection to 1202 * add property to. If NULL the property 1203 * is added to the root collection. 1204 * @param[in] property Name of the property.<br> 1205 * Name should consist of the ASCII characters 1206 * with codes non less than space. 1207 * Exclamation mark character is 1208 * a special character and can't be used 1209 * in name of collection or property.<br> 1210 * Maximum allowed length is defined at compile time. 1211 * The default value is 64k. 1212 * @param[in] number Integer value to add. Value is signed. 1213 * 1214 * @return 0 - Property was added successfully. 1215 * @return ENOMEM - No memory. 1216 * @return EINVAL - Invalid characters in the property name. 1217 * Value argument is invalid in some way. 1218 * @return EMSGSIZE - Property name is too long. 1219 * @return ENOENT - Sub collection is not found. 1220 * 1221 */ 1222 int col_add_int_property(struct collection_item *ci, 1223 const char *subcollection, 1224 const char *property, 1225 int32_t number); 1226 1227 /** 1228 * @brief Add an unsigned integer property to a collection. 1229 * 1230 * @param[in] ci Root collection object. 1231 * @param[in] subcollection Name of the inner collection to 1232 * add property to. If NULL the property 1233 * is added to the root collection. 1234 * @param[in] property Name of the property.<br> 1235 * Name should consist of the ASCII characters 1236 * with codes non less than space. 1237 * Exclamation mark character is 1238 * a special character and can't be used 1239 * in name of collection or property.<br> 1240 * Maximum allowed length is defined at compile time. 1241 * The default value is 64k. 1242 * @param[in] number Unsigned integer value to add. 1243 * 1244 * @return 0 - Property was added successfully. 1245 * @return ENOMEM - No memory. 1246 * @return EINVAL - Invalid characters in the property name. 1247 * Value argument is invalid in some way. 1248 * @return EMSGSIZE - Property name is too long. 1249 * @return ENOENT - Sub collection is not found. 1250 * 1251 */ 1252 int col_add_unsigned_property(struct collection_item *ci, 1253 const char *subcollection, 1254 const char *property, 1255 uint32_t number); 1256 1257 /** 1258 * @brief Add an long property to a collection. 1259 * 1260 * @param[in] ci Root collection object. 1261 * @param[in] subcollection Name of the inner collection to 1262 * add property to. If NULL the property 1263 * is added to the root collection. 1264 * @param[in] property Name of the property.<br> 1265 * Name should consist of the ASCII characters 1266 * with codes non less than space. 1267 * Exclamation mark character is 1268 * a special character and can't be used 1269 * in name of collection or property.<br> 1270 * Maximum allowed length is defined at compile time. 1271 * The default value is 64k. 1272 * @param[in] number Long integer value to add. Value is signed. 1273 * 1274 * @return 0 - Property was added successfully. 1275 * @return ENOMEM - No memory. 1276 * @return EINVAL - Invalid characters in the property name. 1277 * Value argument is invalid in some way. 1278 * @return EMSGSIZE - Property name is too long. 1279 * @return ENOENT - Sub collection is not found. 1280 * 1281 */ 1282 int col_add_long_property(struct collection_item *ci, 1283 const char *subcollection, 1284 const char *property, 1285 int64_t number); 1286 1287 /** 1288 * @brief Add an unsigned long property to a collection. 1289 * 1290 * @param[in] ci Root collection object. 1291 * @param[in] subcollection Name of the inner collection to 1292 * add property to. If NULL the property 1293 * is added to the root collection. 1294 * @param[in] property Name of the property.<br> 1295 * Name should consist of the ASCII characters 1296 * with codes non less than space. 1297 * Exclamation mark character is 1298 * a special character and can't be used 1299 * in name of collection or property.<br> 1300 * Maximum allowed length is defined at compile time. 1301 * The default value is 64k. 1302 * @param[in] number Unsigned long integer value to add. 1303 * 1304 * @return 0 - Property was added successfully. 1305 * @return ENOMEM - No memory. 1306 * @return EINVAL - Invalid characters in the property name. 1307 * Value argument is invalid in some way. 1308 * @return EMSGSIZE - Property name is too long. 1309 * @return ENOENT - Sub collection is not found. 1310 * 1311 */ 1312 int col_add_ulong_property(struct collection_item *ci, 1313 const char *subcollection, 1314 const char *property, 1315 uint64_t number); 1316 1317 /** 1318 * @brief Add a property of type double to a collection. 1319 * 1320 * @param[in] ci Root collection object. 1321 * @param[in] subcollection Name of the inner collection to 1322 * add property to. If NULL the property 1323 * is added to the root collection. 1324 * @param[in] property Name of the property.<br> 1325 * Name should consist of the ASCII characters 1326 * with codes non less than space. 1327 * Exclamation mark character is 1328 * a special character and can't be used 1329 * in name of collection or property.<br> 1330 * Maximum allowed length is defined at compile time. 1331 * The default value is 64k. 1332 * @param[in] number Floating point value. 1333 * 1334 * @return 0 - Property was added successfully. 1335 * @return ENOMEM - No memory. 1336 * @return EINVAL - Invalid characters in the property name. 1337 * Value argument is invalid in some way. 1338 * @return EMSGSIZE - Property name is too long. 1339 * @return ENOENT - Sub collection is not found. 1340 * 1341 */ 1342 int col_add_double_property(struct collection_item *ci, 1343 const char *subcollection, 1344 const char *property, 1345 double number); 1346 /** 1347 * @brief Add a Boolean property to a collection. 1348 * 1349 * @param[in] ci Root collection object. 1350 * @param[in] subcollection Name of the inner collection to 1351 * add property to. If NULL the property 1352 * is added to the root collection. 1353 * @param[in] property Name of the property.<br> 1354 * Name should consist of the ASCII characters 1355 * with codes non less than space. 1356 * Exclamation mark character is 1357 * a special character and can't be used 1358 * in name of collection or property.<br> 1359 * Maximum allowed length is defined at compile time. 1360 * The default value is 64k. 1361 * @param[in] logical Boolean value. 0 - false, nonzero - true. 1362 * 1363 * @return 0 - Property was added successfully. 1364 * @return ENOMEM - No memory. 1365 * @return EINVAL - Invalid characters in the property name. 1366 * Value argument is invalid in some way. 1367 * @return EMSGSIZE - Property name is too long. 1368 * @return ENOENT - Sub collection is not found. 1369 * 1370 */ 1371 int col_add_bool_property(struct collection_item *ci, 1372 const char *subcollection, 1373 const char *property, 1374 unsigned char logical); 1375 1376 1377 /** 1378 * @brief Add a property of a specified type to a collection. 1379 * 1380 * @param[in] ci Root collection object. 1381 * @param[in] subcollection Name of the inner collection to 1382 * add property to. If NULL the property 1383 * is added to the root collection. 1384 * @param[in] property Name of the property.<br> 1385 * Name should consist of the ASCII characters 1386 * with codes non less than space. 1387 * Exclamation mark character is 1388 * a special character and can't be used 1389 * in name of collection or property.<br> 1390 * Maximum allowed length is defined at compile time. 1391 * The default value is 64k. 1392 * @param[in] type See type definitions \ref coltypes "here". 1393 * @param[in] data Data to add. 1394 * @param[in] length Length of the data. 1395 * 1396 * @return 0 - Property was added successfully. 1397 * @return ENOMEM - No memory. 1398 * @return EINVAL - Invalid characters in the property name. 1399 * Value argument is invalid in some way. 1400 * @return EMSGSIZE - Property name is too long. 1401 * @return ENOENT - Sub collection is not found. 1402 * 1403 */ 1404 int col_add_any_property(struct collection_item *ci, 1405 const char *subcollection, 1406 const char *property, 1407 int type, 1408 void *data, 1409 int length); 1410 1411 /** 1412 * @defgroup addprop_withref Add properties with reference 1413 * 1414 * Family of functions that add properties to a collection 1415 * and return reference to an item that holds 1416 * a newly created property. 1417 * 1418 * All the functions in this section append a property of 1419 * the specified type to the collection object. 1420 * 1421 * Parameters for the functions and return values are the same 1422 * as for the \ref addproperty "col_add_xxx_property" functions. 1423 * The only difference is that these functions have one additional 1424 * argument: 1425 * 1426 * @param[out] ret_ref Reference to the newly added item that 1427 * holds the property. 1428 * 1429 * @{ 1430 */ 1431 1432 /** 1433 * @brief Add a string property to a collection. 1434 * 1435 * @param[in] ci Root collection object. 1436 * @param[in] subcollection Name of the inner collection to 1437 * add property to. If NULL the property 1438 * is added to the root collection. 1439 * @param[in] property Name of the property.<br> 1440 * Name should consist of the ASCII characters 1441 * with codes non less than space. 1442 * Exclamation mark character is 1443 * a special character and can't be used 1444 * in name of collection or property.<br> 1445 * Maximum allowed length is defined at compile time. 1446 * The default value is 64k. 1447 * @param[in] string Null terminated string to add. 1448 * @param[in] length Length of the string. Should include the length 1449 * of the terminating 0. 1450 * If the length is shorter than the full string 1451 * the string will be truncated. If the length is 1452 * longer than the actual string there might be 1453 * garbage at end of the actual string. 1454 * Library will always properly NULL terminate 1455 * the string at the given position dictated 1456 * by length but in no way will inspect the validity 1457 * of the passed in data. This is left to the calling 1458 * application. 1459 * @param[out] ret_ref Reference to the newly added item that 1460 * holds the property. 1461 * 1462 * @return 0 - Property was added successfully. 1463 * @return ENOMEM - No memory. 1464 * @return EINVAL - Invalid characters in the property name. 1465 * Value argument is invalid in some way. 1466 * @return EMSGSIZE - Property name is too long. 1467 * @return ENOENT - Sub collection is not found. 1468 * 1469 */ 1470 int col_add_str_property_with_ref(struct collection_item *ci, 1471 const char *subcollection, 1472 const char *property, 1473 char *string, int length, 1474 struct collection_item **ret_ref); 1475 1476 /** 1477 * @brief Add a binary property to a collection. 1478 * 1479 * @param[in] ci Root collection object. 1480 * @param[in] subcollection Name of the inner collection to 1481 * add property to. If NULL the property 1482 * is added to the root collection. 1483 * @param[in] property Name of the property.<br> 1484 * Name should consist of the ASCII characters 1485 * with codes non less than space. 1486 * Exclamation mark character is 1487 * a special character and can't be used 1488 * in name of collection or property.<br> 1489 * Maximum allowed length is defined at compile time. 1490 * The default value is 64k. 1491 * @param[in] binary_data Data to add. 1492 * @param[in] length Length of the data. 1493 * @param[out] ret_ref Reference to the newly added item that 1494 * holds the property. 1495 * 1496 * @return 0 - Property was added successfully. 1497 * @return ENOMEM - No memory. 1498 * @return EINVAL - Invalid characters in the property name. 1499 * Value argument is invalid in some way. 1500 * @return EMSGSIZE - Property name is too long. 1501 * @return ENOENT - Sub collection is not found. 1502 * 1503 */ 1504 int col_add_binary_property_with_ref(struct collection_item *ci, 1505 const char *subcollection, 1506 const char *property, 1507 void *binary_data, int length, 1508 struct collection_item **ret_ref); 1509 1510 /** 1511 * @brief Add an integer property to a collection. 1512 * 1513 * @param[in] ci Root collection object. 1514 * @param[in] subcollection Name of the inner collection to 1515 * add property to. If NULL the property 1516 * is added to the root collection. 1517 * @param[in] property Name of the property.<br> 1518 * Name should consist of the ASCII characters 1519 * with codes non less than space. 1520 * Exclamation mark character is 1521 * a special character and can't be used 1522 * in name of collection or property.<br> 1523 * Maximum allowed length is defined at compile time. 1524 * The default value is 64k. 1525 * @param[in] number Integer value to add. Value is signed. 1526 * @param[out] ret_ref Reference to the newly added item that 1527 * holds the property. 1528 * 1529 * @return 0 - Property was added successfully. 1530 * @return ENOMEM - No memory. 1531 * @return EINVAL - Invalid characters in the property name. 1532 * Value argument is invalid in some way. 1533 * @return EMSGSIZE - Property name is too long. 1534 * @return ENOENT - Sub collection is not found. 1535 * 1536 */ 1537 int col_add_int_property_with_ref(struct collection_item *ci, 1538 const char *subcollection, 1539 const char *property, int32_t number, 1540 struct collection_item **ret_ref); 1541 1542 /** 1543 * @brief Add an unsigned integer property to a collection. 1544 * 1545 * @param[in] ci Root collection object. 1546 * @param[in] subcollection Name of the inner collection to 1547 * add property to. If NULL the property 1548 * is added to the root collection. 1549 * @param[in] property Name of the property.<br> 1550 * Name should consist of the ASCII characters 1551 * with codes non less than space. 1552 * Exclamation mark character is 1553 * a special character and can't be used 1554 * in name of collection or property.<br> 1555 * Maximum allowed length is defined at compile time. 1556 * The default value is 64k. 1557 * @param[in] number Unsigned integer value to add. 1558 * @param[out] ret_ref Reference to the newly added item that 1559 * holds the property. 1560 * 1561 * @return 0 - Property was added successfully. 1562 * @return ENOMEM - No memory. 1563 * @return EINVAL - Invalid characters in the property name. 1564 * Value argument is invalid in some way. 1565 * @return EMSGSIZE - Property name is too long. 1566 * @return ENOENT - Sub collection is not found. 1567 * 1568 */ 1569 int col_add_unsigned_property_with_ref(struct collection_item *ci, 1570 const char *subcollection, 1571 const char *property, uint32_t number, 1572 struct collection_item **ret_ref); 1573 1574 /** 1575 * @brief Add an long property to a collection. 1576 * 1577 * @param[in] ci Root collection object. 1578 * @param[in] subcollection Name of the inner collection to 1579 * add property to. If NULL the property 1580 * is added to the root collection. 1581 * @param[in] property Name of the property.<br> 1582 * Name should consist of the ASCII characters 1583 * with codes non less than space. 1584 * Exclamation mark character is 1585 * a special character and can't be used 1586 * in name of collection or property.<br> 1587 * Maximum allowed length is defined at compile time. 1588 * The default value is 64k. 1589 * @param[in] number Long integer value to add. Value is signed. 1590 * @param[out] ret_ref Reference to the newly added item that 1591 * holds the property. 1592 * 1593 * @return 0 - Property was added successfully. 1594 * @return ENOMEM - No memory. 1595 * @return EINVAL - Invalid characters in the property name. 1596 * Value argument is invalid in some way. 1597 * @return EMSGSIZE - Property name is too long. 1598 * @return ENOENT - Sub collection is not found. 1599 * 1600 */ 1601 int col_add_long_property_with_ref(struct collection_item *ci, 1602 const char *subcollection, 1603 const char *property, int64_t number, 1604 struct collection_item **ret_ref); 1605 1606 /** 1607 * @brief Add an unsigned long property to a collection. 1608 * 1609 * @param[in] ci Root collection object. 1610 * @param[in] subcollection Name of the inner collection to 1611 * add property to. If NULL the property 1612 * is added to the root collection. 1613 * @param[in] property Name of the property.<br> 1614 * Name should consist of the ASCII characters 1615 * with codes non less than space. 1616 * Exclamation mark character is 1617 * a special character and can't be used 1618 * in name of collection or property.<br> 1619 * Maximum allowed length is defined at compile time. 1620 * The default value is 64k. 1621 * @param[in] number Unsigned long integer value to add. 1622 * @param[out] ret_ref Reference to the newly added item that 1623 * holds the property. 1624 * 1625 * @return 0 - Property was added successfully. 1626 * @return ENOMEM - No memory. 1627 * @return EINVAL - Invalid characters in the property name. 1628 * Value argument is invalid in some way. 1629 * @return EMSGSIZE - Property name is too long. 1630 * @return ENOENT - Sub collection is not found. 1631 * 1632 */ 1633 int col_add_ulong_property_with_ref(struct collection_item *ci, 1634 const char *subcollection, 1635 const char *property, uint64_t number, 1636 struct collection_item **ret_ref); 1637 1638 /** 1639 * @brief Add a property of type double to a collection. 1640 * 1641 * @param[in] ci Root collection object. 1642 * @param[in] subcollection Name of the inner collection to 1643 * add property to. If NULL the property 1644 * is added to the root collection. 1645 * @param[in] property Name of the property.<br> 1646 * Name should consist of the ASCII characters 1647 * with codes non less than space. 1648 * Exclamation mark character is 1649 * a special character and can't be used 1650 * in name of collection or property.<br> 1651 * Maximum allowed length is defined at compile time. 1652 * The default value is 64k. 1653 * @param[in] number Floating point value. 1654 * @param[out] ret_ref Reference to the newly added item that 1655 * holds the property. 1656 * 1657 * @return 0 - Property was added successfully. 1658 * @return ENOMEM - No memory. 1659 * @return EINVAL - Invalid characters in the property name. 1660 * Value argument is invalid in some way. 1661 * @return EMSGSIZE - Property name is too long. 1662 * @return ENOENT - Sub collection is not found. 1663 * 1664 */ 1665 int col_add_double_property_with_ref(struct collection_item *ci, 1666 const char *subcollection, 1667 const char *property, double number, 1668 struct collection_item **ret_ref); 1669 1670 /** 1671 * @brief Add a Boolean property to a collection. 1672 * 1673 * @param[in] ci Root collection object. 1674 * @param[in] subcollection Name of the inner collection to 1675 * add property to. If NULL the property 1676 * is added to the root collection. 1677 * @param[in] property Name of the property.<br> 1678 * Name should consist of the ASCII characters 1679 * with codes non less than space. 1680 * Exclamation mark character is 1681 * a special character and can't be used 1682 * in name of collection or property.<br> 1683 * Maximum allowed length is defined at compile time. 1684 * The default value is 64k. 1685 * @param[in] logical Boolean value. 0 - false, nonzero - true. 1686 * @param[out] ret_ref Reference to the newly added item that 1687 * holds the property. 1688 * 1689 * @return 0 - Property was added successfully. 1690 * @return ENOMEM - No memory. 1691 * @return EINVAL - Invalid characters in the property name. 1692 * Value argument is invalid in some way. 1693 * @return EMSGSIZE - Property name is too long. 1694 * @return ENOENT - Sub collection is not found. 1695 * 1696 */ 1697 int col_add_bool_property_with_ref(struct collection_item *ci, 1698 const char *subcollection, 1699 const char *property, unsigned char logical, 1700 struct collection_item **ret_ref); 1701 1702 1703 /** 1704 * @brief Add a property of a specified type to a collection. 1705 * 1706 * @param[in] ci Root collection object. 1707 * @param[in] subcollection Name of the inner collection to 1708 * add property to. If NULL the property 1709 * is added to the root collection. 1710 * @param[in] property Name of the property.<br> 1711 * Name should consist of the ASCII characters 1712 * with codes non less than space. 1713 * Exclamation mark character is 1714 * a special character and can't be used 1715 * in name of collection or property.<br> 1716 * Maximum allowed length is defined at compile time. 1717 * The default value is 64k. 1718 * @param[in] type See type definitions \ref coltypes "here". 1719 * @param[in] data Data to add. 1720 * @param[in] length Length of the data. 1721 * @param[out] ret_ref Reference to the newly added item that 1722 * holds the property. 1723 * 1724 * @return 0 - Property was added successfully. 1725 * @return ENOMEM - No memory. 1726 * @return EINVAL - Invalid characters in the property name. 1727 * Value argument is invalid in some way. 1728 * @return EMSGSIZE - Property name is too long. 1729 * @return ENOENT - Sub collection is not found. 1730 * 1731 */ 1732 int col_add_any_property_with_ref(struct collection_item *ci, 1733 const char *subcollection, 1734 const char *property, 1735 int type, void *data, int length, 1736 struct collection_item **ret_ref); 1737 1738 /** 1739 * @} 1740 */ 1741 1742 /** 1743 * @} 1744 */ 1745 1746 /** 1747 * @defgroup insertproperty Insert property functions 1748 * 1749 * Functions in this section insert properties into a collection 1750 * at a specified position. 1751 * 1752 * Common parameters for these functions are: 1753 * 1754 * @param[in] ci Root collection object. 1755 * @param[in] subcollection Name of the inner collection to 1756 * add property to. If NULL the property 1757 * is added to the root collection. 1758 * @param[in] disposition Defines relation point. 1759 * For more information see 1760 * \ref dispvalues "disposition defines". 1761 * @param[in] refprop Property to relate to 1762 * @param[in] idx Index (see comments below). 1763 * @param[in] flags Flags that control naming issues. 1764 * @param[in] property Name of the property.<br> 1765 * Name should consist of the ASCII characters 1766 * with codes non less than space. 1767 * Exclamation mark character is 1768 * a special character and can't be used 1769 * in name of collection or property.<br> 1770 * Maximum allowed length is defined at compile time. 1771 * The default value is 64k. 1772 * 1773 * 1774 * Other arguments are the same as the arguments for the 1775 * \ref addproperty "col_add_xxx_property" functions. 1776 * 1777 * @return 0 - Property was insterted successfully. 1778 * @return ENOMEM - No memory. 1779 * @return EINVAL - Invalid characters in the property name. 1780 * Value argument is invalid in some way. 1781 * @return EMSGSIZE - Property name is too long. 1782 * @return ENOENT - Sub collection or property to relate to is not found. 1783 * @return EEXIST - Property with given name already exists. 1784 * This error is returned if collection 1785 * should hold unique names. 1786 * For more information see description of the 1787 * "flags" argument. 1788 * @return ENOSYS - Flag or disposition value is not implemented. 1789 * @{ 1790 */ 1791 /** @brief Insert a string property. */ 1792 int col_insert_str_property(struct collection_item *ci, 1793 const char *subcollection, 1794 int disposition, 1795 const char *refprop, 1796 int idx, 1797 unsigned flags, 1798 const char *property, 1799 const char *string, 1800 int length); 1801 1802 /** @brief Insert a binary property. */ 1803 int col_insert_binary_property(struct collection_item *ci, 1804 const char *subcollection, 1805 int disposition, 1806 const char *refprop, 1807 int idx, 1808 unsigned flags, 1809 const char *property, 1810 void *binary_data, 1811 int length); 1812 1813 /** @brief Insert an integer property. */ 1814 int col_insert_int_property(struct collection_item *ci, 1815 const char *subcollection, 1816 int disposition, 1817 const char *refprop, 1818 int idx, 1819 unsigned flags, 1820 const char *property, 1821 int32_t number); 1822 1823 /** @brief Insert an unsigned property. */ 1824 int col_insert_unsigned_property(struct collection_item *ci, 1825 const char *subcollection, 1826 int disposition, 1827 const char *refprop, 1828 int idx, 1829 unsigned flags, 1830 const char *property, 1831 uint32_t number); 1832 1833 /** @brief Insert a long property. */ 1834 int col_insert_long_property(struct collection_item *ci, 1835 const char *subcollection, 1836 int disposition, 1837 const char *refprop, 1838 int idx, 1839 unsigned flags, 1840 const char *property, 1841 int64_t number); 1842 1843 /** @brief Insert an unsigned long property. */ 1844 int col_insert_ulong_property(struct collection_item *ci, 1845 const char *subcollection, 1846 int disposition, 1847 const char *refprop, 1848 int idx, 1849 unsigned flags, 1850 const char *property, 1851 uint64_t number); 1852 1853 /** @brief Insert a property with a floating point value. */ 1854 int col_insert_double_property(struct collection_item *ci, 1855 const char *subcollection, 1856 int disposition, 1857 const char *refprop, 1858 int idx, 1859 unsigned flags, 1860 const char *property, 1861 double number); 1862 1863 /** @brief Insert a property with a Boolean value. */ 1864 int col_insert_bool_property(struct collection_item *ci, 1865 const char *subcollection, 1866 int disposition, 1867 const char *refprop, 1868 int idx, 1869 unsigned flags, 1870 const char *property, 1871 unsigned char logical); 1872 1873 /** @brief Insert a string property and get back a reference. */ 1874 int col_insert_str_property_with_ref(struct collection_item *ci, 1875 const char *subcollection, 1876 int disposition, 1877 const char *refprop, 1878 int idx, 1879 unsigned flags, 1880 const char *property, 1881 const char *string, 1882 int length, 1883 struct collection_item **ret_ref); 1884 1885 /** @brief Insert a binary property and get back a reference. */ 1886 int col_insert_binary_property_with_ref(struct collection_item *ci, 1887 const char *subcollection, 1888 int disposition, 1889 const char *refprop, 1890 int idx, 1891 unsigned flags, 1892 const char *property, 1893 void *binary_data, 1894 int length, 1895 struct collection_item **ret_ref); 1896 1897 /** @brief Insert an integer property and get back a reference. */ 1898 int col_insert_int_property_with_ref(struct collection_item *ci, 1899 const char *subcollection, 1900 int disposition, 1901 const char *refprop, 1902 int idx, 1903 unsigned flags, 1904 const char *property, 1905 int32_t number, 1906 struct collection_item **ret_ref); 1907 1908 /** @brief Insert an unsigned property and get back a reference. */ 1909 int col_insert_unsigned_property_with_ref(struct collection_item *ci, 1910 const char *subcollection, 1911 int disposition, 1912 const char *refprop, 1913 int idx, 1914 unsigned flags, 1915 const char *property, 1916 uint32_t number, 1917 struct collection_item **ret_ref); 1918 1919 /** @brief Insert a long property and get back a reference. */ 1920 int col_insert_long_property_with_ref(struct collection_item *ci, 1921 const char *subcollection, 1922 int disposition, 1923 const char *refprop, 1924 int idx, 1925 unsigned flags, 1926 const char *property, 1927 int64_t number, 1928 struct collection_item **ret_ref); 1929 1930 /** @brief Insert an unsigned long property and get back a reference. */ 1931 int col_insert_ulong_property_with_ref(struct collection_item *ci, 1932 const char *subcollection, 1933 int disposition, 1934 const char *refprop, 1935 int idx, 1936 unsigned flags, 1937 const char *property, 1938 uint64_t number, 1939 struct collection_item **ret_ref); 1940 1941 /** 1942 * @brief Insert a property with a floating 1943 * point value and get back a reference. 1944 */ 1945 int col_insert_double_property_with_ref(struct collection_item *ci, 1946 const char *subcollection, 1947 int disposition, 1948 const char *refprop, 1949 int idx, 1950 unsigned flags, 1951 const char *property, 1952 double number, 1953 struct collection_item **ret_ref); 1954 1955 /** @brief Insert a property with a Boolean value and get back a reference. */ 1956 int col_insert_bool_property_with_ref(struct collection_item *ci, 1957 const char *subcollection, 1958 int disposition, 1959 const char *refprop, 1960 int idx, 1961 unsigned flags, 1962 const char *property, 1963 unsigned char logical, 1964 struct collection_item **ret_ref); 1965 1966 /** @brief Insert property of any type and get back a reference. */ 1967 int col_insert_property_with_ref(struct collection_item *ci, 1968 const char *subcollection, 1969 int disposition, 1970 const char *refprop, 1971 int idx, 1972 unsigned flags, 1973 const char *property, 1974 int type, 1975 const void *data, 1976 int length, 1977 struct collection_item **ret_ref); 1978 1979 1980 /** 1981 * @} 1982 */ 1983 1984 /** 1985 * @defgroup updateproperty Update property functions 1986 * 1987 * Functions in this section update properties in a collection. 1988 * 1989 * All update functions search the property using the 1990 * internal traverse function. 1991 * Use same "x!y" notation to specify a property. 1992 * For more details about the search logic see 1993 * \ref col_get_item_and_do function. 1994 * 1995 * The existing value of the property is destroyed and lost. 1996 * 1997 * It is not possible to rename the property using these functions. 1998 * To do more advanced modifications see \ref col_modify_item function 1999 * and \ref modwrap "item modification wrappers" . 2000 * 2001 * Common parameters for these functions are: 2002 * 2003 * @param[in] ci Root collection object. 2004 * @param[in] property Name of the property. 2005 * @param[in] mode_flags Specify how the collection 2006 * should to be traversed. 2007 * 2008 * The rest of the arguments specify the new values for 2009 * the property. For more details about these arguments see 2010 * the description of the \ref addproperty "col_add_xxx_property" 2011 * corresponding function. 2012 * 2013 * 2014 * @return 0 - Property was updated successfully. 2015 * @return ENOMEM - No memory. 2016 * @return EINVAL - The value of some of the arguments is invalid. 2017 * The attempt to update a property which is 2018 * a reference to a collection or a collection 2019 * name. 2020 * @return ENOENT - Property to update is not found. 2021 * 2022 * @{ 2023 */ 2024 /** 2025 * Update a property with a string value. 2026 * Length should include the terminating 0. 2027 */ 2028 int col_update_str_property(struct collection_item *ci, 2029 const char *property, 2030 int mode_flags, 2031 char *string, 2032 int length); 2033 /** 2034 * Update a property with a binary value. 2035 */ 2036 int col_update_binary_property(struct collection_item *ci, 2037 const char *property, 2038 int mode_flags, 2039 void *binary_data, 2040 int length); 2041 /** 2042 * Update a property with an integer value. 2043 */ 2044 int col_update_int_property(struct collection_item *ci, 2045 const char *property, 2046 int mode_flags, 2047 int32_t number); 2048 /** 2049 * Update a property with an unsigned value. 2050 */ 2051 int col_update_unsigned_property(struct collection_item *ci, 2052 const char *property, 2053 int mode_flags, 2054 uint32_t number); 2055 /** 2056 * Update a property with a long value. 2057 */ 2058 int col_update_long_property(struct collection_item *ci, 2059 const char *property, 2060 int mode_flags, 2061 int64_t number); 2062 /** 2063 * Update a property with an unsigned long value. 2064 */ 2065 int col_update_ulong_property(struct collection_item *ci, 2066 const char *property, 2067 int mode_flags, 2068 uint64_t number); 2069 /** 2070 * Update a property with a floating point value. 2071 */ 2072 int col_update_double_property(struct collection_item *ci, 2073 const char *property, 2074 int mode_flags, 2075 double number); 2076 /** 2077 * Update a property with a Boolean value. 2078 */ 2079 int col_update_bool_property(struct collection_item *ci, 2080 const char *property, 2081 int mode_flags, 2082 unsigned char logical); 2083 2084 /** 2085 * Update a property with a value by specifying type 2086 * and value. See definitions of the type constants 2087 * \ref coltypes "here". 2088 * All other col_update_xxx_property functions are wrappers 2089 * around this one. 2090 */ 2091 int col_update_property(struct collection_item *ci, 2092 const char *property, 2093 int type, 2094 void *new_data, 2095 int length, 2096 int mode_flags); 2097 2098 2099 /** 2100 * @} 2101 */ 2102 2103 /** 2104 * @defgroup getitem Item management 2105 * 2106 * Group of functions that allows retrieving individual elements 2107 * of the \ref collection_item hiding the internal implementation. 2108 * 2109 * @{ 2110 */ 2111 2112 /** 2113 * @defgroup compflags Comparison flags 2114 * 2115 * This section describes the flags used in item comparison. 2116 * 2117 * Flags: 2118 * - \ref COL_CMPIN_PROP_EQU 2119 * - \ref COL_CMPIN_PROP_BEG 2120 * - \ref COL_CMPIN_PROP_MID 2121 * - \ref COL_CMPIN_PROP_END 2122 * 2123 * are mutually exclusive. 2124 * 2125 * All other flags can be provided in any combination. 2126 * 2127 * @{ 2128 */ 2129 /** @brief Properties should be exactly equal */ 2130 #define COL_CMPIN_PROP_EQU 0x000000004 2131 /** @brief Properties should start with the same substring. */ 2132 #define COL_CMPIN_PROP_BEG 0x000000005 2133 /** @brief One property should be a substring of another. */ 2134 #define COL_CMPIN_PROP_MID 0x000000006 2135 /** @brief Properties should have the same substring at the end. */ 2136 #define COL_CMPIN_PROP_END 0x000000007 2137 2138 /** 2139 * @brief Make sure that there is a dot. 2140 * 2141 * Useful with _BEG, _MID and _END flags to check that the there is 2142 * a dot (if present) in the right place (before, after or both). 2143 * For example the first item is named "foo.bar" and the second 2144 * is "bar". Using _END the "bar" will be found but if _DOT flag is 2145 * used too the function will also check if there was a "." before the found 2146 * string in this case. 2147 * Ignored in case of _EQU. 2148 */ 2149 #define COL_CMPIN_PROP_DOT 0x000000008 2150 2151 /** @brief Compare property lengths. */ 2152 #define COL_CMPIN_PROP_LEN 0x000000010 2153 2154 /** @brief Compare types. */ 2155 #define COL_CMPIN_TYPE 0x000000020 2156 2157 /** @brief Compare data lengths. */ 2158 #define COL_CMPIN_DATA_LEN 0x000000040 2159 2160 /** 2161 * @brief Compare data. 2162 * 2163 * Compares data (up to the length of the second one) 2164 * if type is the same. If type is different 2165 * function will assume data is different 2166 * without performing actual comparison. 2167 */ 2168 #define COL_CMPIN_DATA 0x000000080 2169 2170 /** 2171 * @} 2172 */ 2173 2174 2175 /** 2176 * @defgroup outflags Comparison results flags 2177 * 2178 * This section describes the flags set as a result of 2179 * a comparison operation. 2180 * 2181 * @{ 2182 */ 2183 2184 /** 2185 * @brief Second item's property is greater. 2186 * 2187 * If _EQU was specified and the property of the second item 2188 * is greater the following bit will be set 2189 */ 2190 #define COL_CMPOUT_PROP_STR 0x00000001 2191 2192 /** 2193 * @brief Second item's property is longer. 2194 * 2195 * If told to compare property lengths 2196 * and the second is longer this bit will be set. 2197 */ 2198 #define COL_CMPOUT_PROP_LEN 0x00000002 2199 /** 2200 * @brief Second item's data is longer. 2201 * 2202 * If told to compare data lengths 2203 * and second is longer this bit will be set 2204 */ 2205 #define COL_CMPOUT_DATA_LEN 0x00000004 2206 /** 2207 * @brief Second item's data is greater. 2208 * 2209 * If told to compare data 2210 * and types are the same, then 2211 * if the second one is greater this bit will 2212 * be set. If data is binary flag is never set. 2213 */ 2214 #define COL_CMPOUT_DATA 0x00000008 2215 2216 /** 2217 * @} 2218 */ 2219 2220 /** 2221 * @defgroup dispvalues Disposition constants 2222 * 2223 * Possible dispositions for insert, extract and delete function(s). 2224 * Not all of these dispositions are implemented day one. 2225 * If disposition is not implemented the function 2226 * will return error ENOSYS. 2227 * 2228 * Other dispositions might be possible in future. 2229 * 2230 * @{ 2231 */ 2232 /** 2233 * @brief Relate to the end of the collection 2234 * 2235 * For "insert": 2236 * - Add property to the end of the collection. 2237 * 2238 * For "extract" or "delete": 2239 * - Extract or delete the last property in the collection. 2240 */ 2241 #define COL_DSP_END 0 2242 /** 2243 * @brief Relate to the beginning of the collection 2244 * 2245 * For "insert": 2246 * - Add property to the beginning of the collection right after the header. 2247 * 2248 * For "extract" or "delete": 2249 * - Extract or delete the first property in the collection. 2250 * This is the one right after the header. 2251 */ 2252 #define COL_DSP_FRONT 1 2253 /** 2254 * @brief Before the given property 2255 * 2256 * For "insert": 2257 * - Add property before the referenced property. 2258 * 2259 * For "extract" or "delete": 2260 * - Extract or delete the property that stands 2261 * before the referenced property in the collection. 2262 * If given property is the first in the collection 2263 * ENOENT is returned. 2264 */ 2265 #define COL_DSP_BEFORE 2 2266 /** 2267 * @brief After the given property 2268 * 2269 * For "insert": 2270 * - Add property immediately the referenced property. 2271 * 2272 * For "extract" or "delete": 2273 * - Extract or delete the property that stands 2274 * after the referenced property in the collection. 2275 * If given property is the last in the collection 2276 * ENOENT is returned. 2277 */ 2278 #define COL_DSP_AFTER 3 2279 /** 2280 * @brief Use index 2281 * 2282 * For "insert": 2283 * - The COL_DSP_INDEX adds the item as N-th item after header in the list. 2284 * Index is zero based. 2285 * If there are less than N items in the list the item is added to the end. 2286 * The index value of 0 means that the item will be added immediately 2287 * after the header. Index of 1 will mean that it is added after first data 2288 * item and so on. 2289 * 2290 * For "extract" or "delete": 2291 * - In case of extraction or deletion the N-th item of the collection 2292 * will be extracted or deleted. 2293 * Index is zero based. 2294 * If there are less than N+1 items in the list the function will return ENOENT. 2295 * 2296 */ 2297 #define COL_DSP_INDEX 4 2298 /** 2299 * @brief Use first among duplicates 2300 * 2301 * This mode applies only to the list of duplicate 2302 * properties that are going one after another. 2303 * 2304 * For "insert": 2305 * - Add property as a first dup of the given property. 2306 * The property name is taken from the item 2307 * and the value refprop is ignored. 2308 * 2309 * For "extract" or "delete": 2310 * - Delete or extract first duplicate property. 2311 * The property name is taken from the refprop. 2312 * The property will be extracted or deleted if found 2313 * regardless of whether there are any duplicates or not. 2314 */ 2315 #define COL_DSP_FIRSTDUP 5 2316 /** 2317 * @brief Use last among duplicates 2318 * 2319 * This mode applies only to the list of duplicate 2320 * properties that are going one after another. 2321 * 2322 * For "insert": 2323 * - Add property as the last dup of the given property. 2324 * The property name is taken from the item 2325 * and the value refprop is ignored. 2326 * 2327 * For "extract" or "delete": 2328 * - Delete or extract the last duplicate of the property. 2329 * The property name is taken from the refprop. 2330 * Extracts or deletes last duplicate property in the uninterrupted 2331 * sequence of properties with the same name. 2332 * The property will be extracted or deleted if found 2333 * regardless of whether there are any duplicates or not. 2334 */ 2335 #define COL_DSP_LASTDUP 6 2336 /** 2337 * @brief Use N-th among duplicates 2338 * 2339 * This mode applies only to the list of duplicate 2340 * properties that are going one after another. 2341 * 2342 * For "insert": 2343 * - Add property as a N-th dup of the given property. 2344 * The property name is taken from the item 2345 * and the value refprop is ignored. 2346 * Index is zero based. 2347 * The COL_DSP_NDUP is used in case of the multi value property 2348 * to add a new property with the same name into specific place 2349 * in the list of properties with the same name. 2350 * The index of 0 will mean to add the property before the first 2351 * instance of the property with the same name. 2352 * If the property does not exist ENOENT will be returned. 2353 * If the index is greater than the last property with the same 2354 * name the item will be added immediately after last 2355 * property with the same name. 2356 * 2357 * For "extract" or "delete": 2358 * - Delete or extract N-th duplicate property. 2359 * Index is zero based. 2360 * The property name is taken from the refprop. 2361 * If index is greater than number of duplicate 2362 * properties in the sequence ENOENT is returned. 2363 * 2364 */ 2365 #define COL_DSP_NDUP 7 2366 /** 2367 * @brief Use last among nonsequential duplicates 2368 * 2369 * This mode applies to the list of duplicates that might be scattered 2370 * across the collection 2371 * 2372 * For "insert": 2373 * - Add property as the last dup of the given property. 2374 * The property name is taken from the item 2375 * and the value refprop is ignored. 2376 * 2377 * For "extract" or "delete": 2378 * - Delete or extract the last duplicate of the property. 2379 * The property name is taken from the refprop. 2380 * Extracts or deletes last duplicate property in the uninterrupted 2381 * sequence of properties with the same name. 2382 * The property will be extracted or deleted if found 2383 * regardless of whether there are any duplicates or not. 2384 */ 2385 #define COL_DSP_LASTDUPNS 8 2386 /** 2387 * @brief Use N-th among nonsequential duplicates 2388 * 2389 * This mode applies only to the list of duplicate 2390 * properties that are going one after another. 2391 * 2392 * For "insert": 2393 * - Add property as a N-th dup of the given property. 2394 * The property name is taken from the item 2395 * and the value refprop is ignored. 2396 * Index is zero based. 2397 * The COL_DSP_NDUPNS is used in case of the multi value property 2398 * to add a new property with the same name into specific place 2399 * in the list of properties with the same name. 2400 * The index of 0 will mean to add the property before the first 2401 * instance of the property with the same name. 2402 * If the property does not exist ENOENT will be returned. 2403 * If the index is greater than the last property with the same 2404 * name the item will be added immediately after last 2405 * property with the same name. 2406 * 2407 * For "extract" or "delete": 2408 * - Delete or extract N-th duplicate property. 2409 * Index is zero based. 2410 * The property name is taken from the refprop. 2411 * If index is greater than number of duplicate 2412 * properties in the sequence ENOENT is returned. 2413 * 2414 */ 2415 #define COL_DSP_NDUPNS 9 2416 /** 2417 * @} 2418 */ 2419 2420 /** 2421 * @defgroup insflags Flags used in insert item functions 2422 * 2423 * Flags that can be used with insert functions. 2424 * 2425 * In future can more flags might be added. 2426 * 2427 * <b>NOTE:</b> Use of the duplicate checking flags is costly 2428 * since it requires a forward look up of the whole 2429 * collection before the item is inserted. 2430 * Do not use it until it is absolutely necessary. 2431 * 2432 * @{ 2433 */ 2434 /** @brief This is the default mode - no dup checks on insert */ 2435 #define COL_INSERT_NOCHECK 0 2436 /** 2437 * @brief Check for duplicate name and overwrite. 2438 * Position arguments are ignored. 2439 */ 2440 #define COL_INSERT_DUPOVER 1 2441 /** 2442 * @brief Check for duplicate name and type and overwrite. 2443 * Position arguments are ignored. 2444 */ 2445 #define COL_INSERT_DUPOVERT 2 2446 /** @brief Return error EEXIST if the entry with the same name exists. */ 2447 #define COL_INSERT_DUPERROR 3 2448 /** 2449 * @brief Return error EEXIST if the entry 2450 * with the same name and type exists. 2451 */ 2452 #define COL_INSERT_DUPERRORT 4 2453 /** @brief Check for duplicates, overwrite, 2454 * extract and then move to the position requested. 2455 */ 2456 #define COL_INSERT_DUPMOVE 5 2457 /** @brief Check for duplicate name and type, overwrite, 2458 * extract and then move to the position requested. 2459 */ 2460 #define COL_INSERT_DUPMOVET 6 2461 2462 /** 2463 * @} 2464 */ 2465 2466 2467 2468 /** 2469 * @brief Get item property. 2470 * 2471 * Get name of the property from the item. If the item is a header 2472 * the name of the property is the name of the collection. 2473 * The element that denotes the collection header has 2474 * type \ref COL_TYPE_COLLECTION. 2475 * Optionally the property length can be retrieved too. 2476 * 2477 * @param[in] ci Item to get property from. 2478 * If item is invalid the function 2479 * will cause a segment violation. 2480 * @param[out] property_len If not NULL the variable 2481 * will receive the length 2482 * of the property not counting 2483 * terminating 0. 2484 * 2485 * @return Property name. 2486 * 2487 */ 2488 const char *col_get_item_property(struct collection_item *ci, 2489 int *property_len); 2490 2491 /** 2492 * @brief Get item type. 2493 * 2494 * Get type from the item. 2495 * 2496 * @param[in] ci Item to get type from. 2497 * If item is invalid the function 2498 * will cause a segment violation. 2499 * 2500 * @return Item type. 2501 * 2502 */ 2503 int col_get_item_type(struct collection_item *ci); 2504 2505 /** 2506 * @brief Get value length from the item. 2507 * 2508 * Get value length from the item. For strings this includes 2509 * NULL terminating zero. 2510 * 2511 * @param[in] ci Item to get value length from. 2512 * If item is invalid the function 2513 * will cause a segment violation. 2514 * 2515 * @return Value length. 2516 * 2517 */ 2518 int col_get_item_length(struct collection_item *ci); 2519 2520 /** 2521 * @brief Get value from the item. 2522 * 2523 * Get value from the item. 2524 * 2525 * @param[in] ci Item to get value from. 2526 * If item is invalid the function 2527 * will cause a segment violation. 2528 * 2529 * @return Property value. 2530 * 2531 */ 2532 void *col_get_item_data(struct collection_item *ci); 2533 2534 /** 2535 * @brief Get hash value from the item. 2536 * 2537 * Get hash value from the item. The hash value is 2538 * 64-bit hash created from the property name. 2539 * It is done to optimize the searches. 2540 * 2541 * This function is exposed for some corner cases 2542 * that require low level operations, for example 2543 * for custom search callbacks to take advantage 2544 * of the internal hashes. 2545 * 2546 * @param[in] ci Item to get hash from. 2547 * If item is invalid the function 2548 * will cause a segment violation. 2549 * 2550 * @return Hash value. 2551 * 2552 */ 2553 uint64_t col_get_item_hash(struct collection_item *ci); 2554 2555 /** 2556 * @brief Calculate hash value for a string. 2557 * 2558 * Calculates hash value of the string using internal hashing 2559 * algorithm. Populates "length" with length 2560 * of the string not counting 0. 2561 * 2562 * This function is useful if you want to build a custom 2563 * search or collection sorting function. 2564 * 2565 * @param[in] string String to hash. If NULL hash is 0. 2566 * @param[in] sub_len If it is greater than zero 2567 * it is used to count how many 2568 * characters from string should 2569 * be included into hash calculation. 2570 * If 0 the actual length of the string 2571 * is determined and used. 2572 * @param[out] length Will receive the calculated length 2573 * of the provided string. 2574 * Length argument can be NULL. 2575 * 2576 * @return Hash value. 2577 */ 2578 uint64_t col_make_hash(const char *string, int sub_len, int *length); 2579 2580 2581 /** 2582 * @brief Compare two items. 2583 * 2584 * The second item is evaluated against the first. 2585 * Function returns 0 if two items are the same 2586 * and non-zero otherwise. 2587 * The \ref compflags "in_flags" is a bit mask that 2588 * defines how the items should be compared. 2589 * 2590 * If items are different they might be sorted following 2591 * some order. For example one can order items by name 2592 * but not by type. 2593 * If the result of the function is non-zero 2594 * the \ref outflags "out_flags" (if provided) will be 2595 * set to indicate if the second item is greater 2596 * then the first. 2597 * 2598 * @param[in] first First item to compare. 2599 * @param[in] second Second item to compare. 2600 * @param[in] in_flags See \ref compflags "comparison flags". 2601 * @param[out] out_flags See \ref outflags "output flags". 2602 * 2603 * 2604 * @return 0 if items are the same and nonzero otherwise. 2605 2606 */ 2607 int col_compare_items(struct collection_item *first, 2608 struct collection_item *second, 2609 unsigned in_flags, 2610 unsigned *out_flags); 2611 2612 2613 2614 /** 2615 * @brief Modify any item element. 2616 * 2617 * This function is useful if you want to modify the item that 2618 * you got as a result of \ref iterfunc "iterating" through 2619 * collection or by calling \ref col_get_item. 2620 * Previous type and data of the item is destroyed. 2621 * 2622 * If you want to rename an item provide a new name in the property 2623 * argument otherwise keep it NULL. 2624 * 2625 * If you want the data to remain unchanged use 0 as a length parameter. 2626 * 2627 * If the item is a reference or a collection and you attempt to change 2628 * the data, i.e. length is not 0, the call will return an error EINVAL. 2629 * If the item is a reference or a collection it can only be renamed. 2630 * 2631 * The are several convenience function that are wrappers 2632 * around this function. For more information 2633 * see \ref modwrap "item modification wrappers". 2634 * 2635 * @param[in] item Item to modify. 2636 * @param[in] property Property name. Use NULL to leave the property 2637 * unchanged. 2638 * @param[in] type See \ref coltypes "types" for more information. 2639 * @param[in] data New value. 2640 * @param[in] length New value. Use 0 to leave the value and its type 2641 * unchanged. 2642 * 2643 * @return 0 - Item was successfully modified. 2644 * @return ENOMEM - No memory. 2645 * @return EINVAL - The value of some of the arguments is invalid. 2646 * The attempt to modify an item which is 2647 * a reference to a collection or a collection 2648 * name. 2649 */ 2650 int col_modify_item(struct collection_item *item, 2651 const char *property, 2652 int type, 2653 const void *data, 2654 int length); 2655 2656 /** 2657 * @defgroup modwrap Item modification wrappers 2658 * 2659 * The functions in this section are convenience wrappers 2660 * around \ref col_modify_item. 2661 * They return same error codes. 2662 * 2663 * @{ 2664 */ 2665 2666 /** 2667 * @brief Modify item property. 2668 * 2669 * This function is a convenience wrapper around \ref col_modify_item. 2670 * It is equivalent to: col_modify_item(item, property, 0, NULL, 0); 2671 * 2672 */ 2673 int col_modify_item_property(struct collection_item *item, 2674 const char *property); 2675 2676 /** 2677 * @brief Modify item value to be a string. 2678 * 2679 * This function is a convenience wrapper around \ref col_modify_item. 2680 * It sets a value of the item to a provided string. 2681 * If property is not NULL it also renames the property. 2682 * If the length argument is not zero the string will be truncated to 2683 * this length. If the length is 0 the length will be calculated based 2684 * on the length of the actual string. 2685 * Original value is always destroyed. 2686 * 2687 * @return - same error values as \ref col_modify_item. 2688 */ 2689 int col_modify_str_item(struct collection_item *item, 2690 const char *property, 2691 const char *string, 2692 int length); 2693 /** 2694 * @brief Modify item value to be a binary blob. 2695 * 2696 * This function is a convenience wrapper around \ref col_modify_item. 2697 * It sets a value of the item to a provided binary buffer. 2698 * If property is not NULL it also renames the property. 2699 * Original value is always destroyed. 2700 * 2701 * @return - same error values as \ref col_modify_item. 2702 */ 2703 int col_modify_binary_item(struct collection_item *item, 2704 const char *property, 2705 void *binary_data, 2706 int length); 2707 /** 2708 * @brief Modify item value to be a Boolean. 2709 * 2710 * This function is a convenience wrapper around \ref col_modify_item. 2711 * It sets a value of the item to a provided logical value. 2712 * If property is not NULL it also renames the property. 2713 * Original value is always destroyed. 2714 * 2715 * @return - same error values as \ref col_modify_item. 2716 */ 2717 int col_modify_bool_item(struct collection_item *item, 2718 const char *property, 2719 unsigned char logical); 2720 /** 2721 * @brief Modify item value to be an integer. 2722 * 2723 * This function is a convenience wrapper around \ref col_modify_item. 2724 * It sets a value of the item to a provided integer value. 2725 * If property is not NULL it also renames the property. 2726 * Original value is always destroyed. 2727 * 2728 * @return - same error values as \ref col_modify_item. 2729 */ 2730 int col_modify_int_item(struct collection_item *item, 2731 const char *property, 2732 int32_t number); 2733 /** 2734 * @brief Modify item value to be a long integer. 2735 * 2736 * This function is a convenience wrapper around \ref col_modify_item. 2737 * It sets a value of the item to a provided long integer value. 2738 * If property is not NULL it also renames the property. 2739 * Original value is always destroyed. 2740 * 2741 * @return - same error values as \ref col_modify_item. 2742 */ 2743 int col_modify_long_item(struct collection_item *item, 2744 const char *property, 2745 int64_t number); 2746 /** 2747 * @brief Modify item value to be an unsigned long. 2748 * 2749 * This function is a convenience wrapper around \ref col_modify_item. 2750 * It sets a value of the item to a provided unsigned long value. 2751 * If property is not NULL it also renames the property. 2752 * Original value is always destroyed. 2753 * 2754 * @return - same error values as \ref col_modify_item. 2755 */ 2756 int col_modify_ulong_item(struct collection_item *item, 2757 const char *property, 2758 uint64_t number); 2759 /** 2760 * @brief Modify item value to be an unsigned integer. 2761 * 2762 * This function is a convenience wrapper around \ref col_modify_item. 2763 * It sets a value of the item to a provided unsigned integer value. 2764 * If property is not NULL it also renames the property. 2765 * Original value is always destroyed. 2766 * 2767 * @return - same error values as \ref col_modify_item. 2768 */ 2769 int col_modify_unsigned_item(struct collection_item *item, 2770 const char *property, 2771 uint32_t number); 2772 /** 2773 * @brief Modify item value to be a floating point. 2774 * 2775 * This function is a convenience wrapper around \ref col_modify_item. 2776 * It sets a value of the item to a provided floating point value. 2777 * If property is not NULL it also renames the property. 2778 * Original value is always destroyed. 2779 * 2780 * @return - same error values as \ref col_modify_item. 2781 */ 2782 int col_modify_double_item(struct collection_item *item, 2783 const char *property, 2784 double number); 2785 2786 /** 2787 * @} 2788 */ 2789 2790 /** 2791 * @brief Extract item from the collection. 2792 * 2793 * Function to find and remove an item from the collection. 2794 * Function does not destroy the item instead it returns a reference 2795 * to the item so it can be used later and inserted back into this or 2796 * other collection. 2797 * The function assumes that the caller knows the collection 2798 * the property is stored in. 2799 * The header of the collection can't be extracted with this function 2800 * but the reference to the collection can. 2801 * 2802 * Function allows specifying relative position of the item in the 2803 * collection. One can specify that he wants to extract an item 2804 * that is first in the collection or last, or after other item 2805 * in the collection. For more details see parameter definitions. 2806 * 2807 * After extracting the item from the collection the caller has to 2808 * either insert it back into some collection using \ref col_insert_item 2809 * or delete it using \ref col_delete_item. 2810 * 2811 * 2812 * @param[in] ci Collection object. 2813 * @param[in] subcollection Name of the sub collection to extract 2814 * item from. If NULL, the top level collection 2815 * is used. One can use "foo!bar!baz" 2816 * notation to identify the sub collection. 2817 * @param[in] disposition Constant that controls how the relative 2818 * position of the item to extract is determined. 2819 * For more information see \ref dispvalues 2820 * "disposition constants". 2821 * @param[in] refprop Name of the property to relate to. 2822 * This can be used to specify that function 2823 * should extract next item after the item 2824 * with this name. Leave NULL if the 2825 * disposition you are using does not 2826 * relate to an item in the collection. 2827 * @param[in] idx Index of the property to extract. 2828 * Useful for multi-value properties where 2829 * several properties have same name in a row. 2830 * @param[in] type Type filter. Only the item of the matching 2831 * type will be used. It can be a bit mask of 2832 * more than one type. Use 0 if you do not 2833 * need to filter by type. 2834 * @param[out] ret_ref Variable will receive the value of the 2835 * pointer to the extracted item. 2836 * 2837 * @return 0 - Item was successfully extracted. 2838 * @return ENOMEM - No memory. 2839 * @return EINVAL - The value of some of the arguments is invalid. 2840 * @return ENOENT - Sub collection is not found. 2841 * The position can't be determined. For example 2842 * extracting next item after item with name "foo" 2843 * will cause this error if item "foo" is the last 2844 * item in the collection. There are other cases 2845 * when this error can be returned but the common 2846 * theme is that something was not found. 2847 * @return ENOSYS Unknown disposition value. 2848 */ 2849 int col_extract_item(struct collection_item *ci, 2850 const char *subcollection, 2851 int disposition, 2852 const char *refprop, 2853 int idx, 2854 int type, 2855 struct collection_item **ret_ref); 2856 2857 /** 2858 * @brief Extract item from the current collection. 2859 * 2860 * Function is similar to the \ref col_extract_item. 2861 * It acts exactly the same as \ref col_extract_item when the 2862 * subcollection parameter of the \ref col_extract_item is set to NULL. 2863 * 2864 * @param[in] ci Collection object. 2865 * @param[in] disposition Constant that controls how the relative 2866 * position of the item to extract is determined. 2867 * For more information see \ref dispvalues 2868 * "disposition constants". 2869 * @param[in] refprop Name of the property to relate to. 2870 * This can be used to specify that function 2871 * should extract next item after the item 2872 * with this name. Leave NULL if the 2873 * disposition you are using does not 2874 * relate to an item in the collection. 2875 * @param[in] idx Index of the property to extract. 2876 * Useful for multi-value properties where 2877 * several properties have same name in a row. 2878 * @param[in] type Type filter. Only the item of the matching 2879 * type will be used. It can be a bit mask of 2880 * more than one type. Use 0 if you do not 2881 * need to filter by type. 2882 * @param[out] ret_ref Variable will receive the value of the 2883 * pointer to the extracted item. 2884 * 2885 * @return 0 - Item was successfully extracted. 2886 * @return ENOMEM - No memory. 2887 * @return EINVAL - The value of some of the arguments is invalid. 2888 * @return ENOENT - Sub collection is not found. 2889 * The position can't be determined. For example 2890 * extracting next item after item with name "foo" 2891 * will cause this error if item "foo" is the last 2892 * item in the collection. There are other cases 2893 * when this error can be returned but the common 2894 * theme is that something was not found. 2895 * @return ENOSYS Unknown disposition value. 2896 */ 2897 int col_extract_item_from_current(struct collection_item *ci, 2898 int disposition, 2899 const char *refprop, 2900 int idx, 2901 int type, 2902 struct collection_item **ret_ref); 2903 2904 /** 2905 * @brief Remove item from the collection. 2906 * 2907 * Function internally calls \ref col_extract_item and then 2908 * \ref col_delete_item for the extracted item. 2909 * 2910 * Function is similar to \ref col_delete_property function 2911 * but allows more specific information about what item (property) 2912 * to remove. 2913 * 2914 * The header will not be considered for deletion. 2915 * 2916 * @param[in] ci Collection object. 2917 * @param[in] subcollection Name of the sub collection to remove 2918 * item from. If NULL, the top level collection 2919 * is used. One can use "foo!bar!baz" 2920 * notation to identify the sub collection. 2921 * @param[in] disposition Constant that controls how the relative 2922 * position of the item to remove is determined. 2923 * For more information see \ref dispvalues 2924 * "disposition constants". 2925 * @param[in] refprop Name of the property to relate to. 2926 * This can be used to specify that function 2927 * should remove next item after the item 2928 * with this name. Leave NULL if the 2929 * disposition you are using does not 2930 * relate to an item in the collection. 2931 * @param[in] idx Index of the property to remove. 2932 * Useful for multi-value properties where 2933 * several properties have same name in a row. 2934 * @param[in] type Type filter. Only the item of the matching 2935 * type will be used. It can be a bit mask of 2936 * more than one type. Use 0 if you do not 2937 * need to filter by type. 2938 * 2939 * @return 0 - Item was successfully removed. 2940 * @return ENOMEM - No memory. 2941 * @return EINVAL - The value of some of the arguments is invalid. 2942 * @return ENOENT - Sub collection is not found. 2943 * The position can't be determined. For example 2944 * deleting next item after item with name "foo" 2945 * will cause this error if item "foo" is the last 2946 * item in the collection. There are other cases 2947 * when this error can be returned but the common 2948 * theme is that something was not found. 2949 * @return ENOSYS Unknown disposition value. 2950 */ 2951 int col_remove_item(struct collection_item *ci, 2952 const char *subcollection, 2953 int disposition, 2954 const char *refprop, 2955 int idx, 2956 int type); 2957 2958 /** 2959 * @brief Remove item from the collection. 2960 * 2961 * Function internally calls \ref col_extract_item and then 2962 * \ref col_delete_item for the extracted item. 2963 * 2964 * Function is similar to \ref col_delete_property function 2965 * but allows more specific information about what item (property) 2966 * to remove. 2967 * 2968 * The header will not be considered for deletion. 2969 * 2970 * @param[in] ci Collection object. 2971 * @param[in] subcollection Name of the sub collection to remove 2972 * item from. If NULL, the top level collection 2973 * is used. One can use "foo!bar!baz" 2974 * notation to identify the sub collection. 2975 * @param[in] disposition Constant that controls how the relative 2976 * position of the item to remove is determined. 2977 * For more information see \ref dispvalues 2978 * "disposition constants". 2979 * @param[in] refprop Name of the property to relate to. 2980 * This can be used to specify that function 2981 * should remove next item after the item 2982 * with this name. Leave NULL if the 2983 * disposition you are using does not 2984 * relate to an item in the collection. 2985 * @param[in] idx Index of the property to remove. 2986 * Useful for multi-value properties where 2987 * several properties have same name in a row. 2988 * @param[in] type Type filter. Only the item of the matching 2989 * type will be used. It can be a bit mask of 2990 * more than one type. Use 0 if you do not 2991 * need to filter by type. 2992 * @param[in] cb Callback to use. 2993 * @param[in] custom_data Caller defined data that can be passed 2994 * to the callback. 2995 * 2996 * @return 0 - Item was successfully removed. 2997 * @return ENOMEM - No memory. 2998 * @return EINVAL - The value of some of the arguments is invalid. 2999 * @return ENOENT - Sub collection is not found. 3000 * The position can't be determined. For example 3001 * deleting next item after item with name "foo" 3002 * will cause this error if item "foo" is the last 3003 * item in the collection. There are other cases 3004 * when this error can be returned but the common 3005 * theme is that something was not found. 3006 * @return ENOSYS Unknown disposition value. 3007 */ 3008 int col_remove_item_with_cb(struct collection_item *ci, 3009 const char *subcollection, 3010 int disposition, 3011 const char *refprop, 3012 int idx, 3013 int type, 3014 col_item_cleanup_fn cb, 3015 void *custom_data); 3016 3017 /** 3018 * @brief Remove item from the current collection. 3019 * 3020 * Function is similar to the \ref col_remove_item. 3021 * It acts exactly the same as \ref col_remove_item when the 3022 * subcollection parameter of the \ref col_remove_item is set to NULL. 3023 * 3024 * @param[in] ci Collection object. 3025 * @param[in] disposition Constant that controls how the relative 3026 * position of the item to remove is determined. 3027 * For more information see \ref dispvalues 3028 * "disposition constants". 3029 * @param[in] refprop Name of the property to relate to. 3030 * This can be used to specify that function 3031 * should remove next item after the item 3032 * with this name. Leave NULL if the 3033 * disposition you are using does not 3034 * relate to an item in the collection. 3035 * @param[in] idx Index of the property to remove. 3036 * Useful for multi-value properties where 3037 * several properties have same name in a row. 3038 * @param[in] type Type filter. Only the item of the matching 3039 * type will be used. It can be a bit mask of 3040 * more than one type. Use 0 if you do not 3041 * need to filter by type. 3042 * 3043 * @return 0 - Item was successfully removed. 3044 * @return ENOMEM - No memory. 3045 * @return EINVAL - The value of some of the arguments is invalid. 3046 * @return ENOENT - Sub collection is not found. 3047 * The position can't be determined. For example 3048 * deleting next item after item with name "foo" 3049 * will cause this error if item "foo" is the last 3050 * item in the collection. There are other cases 3051 * when this error can be returned but the common 3052 * theme is that something was not found. 3053 * @return ENOSYS Unknown disposition value. 3054 */ 3055 int col_remove_item_from_current(struct collection_item *ci, 3056 int disposition, 3057 const char *refprop, 3058 int idx, 3059 int type); 3060 3061 /** 3062 * @brief Insert item to the collection. 3063 * 3064 * <b>WARNING:</b> Only use this function to insert items 3065 * that were extracted using \ref col_extract_item or 3066 * \ref col_extract_item_from_current. 3067 * <b>NEVER</b> use it with items that were returned by: 3068 * - \ref col_get_item 3069 * - \ref addproperty "add property" functions 3070 * - \ref addprop_withref "add property with reference" functions 3071 * - \ref insertproperty "instert property" functions. 3072 * 3073 * The fundamental difference is that when you extracted item 3074 * using col_extract_item() it stops to be managed by a collection. 3075 * With such item you can: 3076 * - a) Insert this item into another (or same) collection 3077 * - b) Get item information using corresponding item management functions. 3078 * - c) Destroy item using col_delete_item(). 3079 * 3080 * You are required to do either a) or c) with such item. 3081 * 3082 * @param[in] ci Collection object. 3083 * @param[in] subcollection Name of the sub collection to insert 3084 * item into. If NULL, the top level collection 3085 * is used. One can use "foo!bar!baz" 3086 * notation to identify the sub collection. 3087 * @param[in] item Item to insert. 3088 * @param[in] disposition Constant that controls where to insert 3089 * the item. 3090 * For more information see \ref dispvalues 3091 * "disposition constants". 3092 * @param[in] refprop Name of the property to relate to. 3093 * This can be used to specify that function 3094 * should insert the item after the item 3095 * with this name. Leave NULL if the 3096 * disposition you are using does not 3097 * relate to an item in the collection. 3098 * @param[in] idx Index of the property to insert. 3099 * Useful for multi-value properties where 3100 * several properties have same name in a row. 3101 * @param[in] flags Flags that control naming issues. 3102 * See \ref insflags "insert flags" 3103 * for more details. 3104 * 3105 * @return 0 - Item was successfully extracted. 3106 * @return ENOMEM - No memory. 3107 * @return EINVAL - The value of some of the arguments is invalid. 3108 * @return ENOENT - Sub collection is not found. 3109 * The position can't be determined. For example 3110 * extracting next item after item with name "foo" 3111 * will cause this error if item "foo" is the last 3112 * item in the collection. There are other cases 3113 * when this error can be returned but the common 3114 * theme is that something was not found. 3115 * @return ENOSYS Unknown disposition value. 3116 * @return EEXIST If duplicate name/type checking is turned on 3117 * and duplicate name/type is detected. 3118 * 3119 */ 3120 int col_insert_item(struct collection_item *ci, 3121 const char *subcollection, 3122 struct collection_item *item, 3123 int disposition, 3124 const char *refprop, 3125 int idx, 3126 unsigned flags); 3127 3128 /** 3129 * @brief Insert item to the current collection. 3130 * 3131 * Function is equivalent to \ref col_insert_item with 3132 * subcollection parameter equal NULL. 3133 * 3134 * @param[in] ci Collection object. 3135 * @param[in] item Item to insert. 3136 * @param[in] disposition Constant that controls where to insert 3137 * the item. 3138 * For more information see \ref dispvalues 3139 * "disposition constants". 3140 * @param[in] refprop Name of the property to relate to. 3141 * This can be used to specify that function 3142 * should insert the item after the item 3143 * with this name. Leave NULL if the 3144 * disposition you are using does not 3145 * relate to an item in the collection. 3146 * @param[in] idx Index of the property to insert. 3147 * Useful for multi-value properties where 3148 * several properties have same name in a row. 3149 * @param[in] flags Flags that control naming issues. 3150 * See \ref insflags "insert flags" 3151 * for more details. 3152 * 3153 * @return 0 - Item was successfully extracted. 3154 * @return ENOMEM - No memory. 3155 * @return EINVAL - The value of some of the arguments is invalid. 3156 * @return ENOENT - Sub collection is not found. 3157 * The position can't be determined. For example 3158 * extracting next item after item with name "foo" 3159 * will cause this error if item "foo" is the last 3160 * item in the collection. There are other cases 3161 * when this error can be returned but the common 3162 * theme is that something was not found. 3163 * @return ENOSYS Unknown disposition value. 3164 * @return EEXIST If duplicate name/type checking is turned on 3165 * and duplicate name/type is detected. 3166 * 3167 */ 3168 int col_insert_item_into_current(struct collection_item *ci, 3169 struct collection_item *item, 3170 int disposition, 3171 const char *refprop, 3172 int idx, 3173 unsigned flags); 3174 3175 3176 3177 /** 3178 * @brief Delete extracted item. 3179 * 3180 * <b>NEVER</b> use this function to delete an item 3181 * that was not previously extracted from the collection. 3182 * 3183 * There is currently no function to create an item aside and 3184 * then insert it into the collection so the col_delete_item 3185 * has only one use. In future this may change. 3186 * 3187 * @param[in] item Item to delete. 3188 * 3189 */ 3190 void col_delete_item(struct collection_item *item); 3191 3192 /** 3193 * @brief Delete extracted item with callback. 3194 * 3195 * This function is similar to \ref col_delete_item but allows 3196 * passing a callback function so that value stored in the collection can 3197 * be properly distroyed. 3198 * 3199 * @param[in] item Item to delete. 3200 * @param[in] cb Callback to use. 3201 * @param[in] custom_data Caller defined data that can be passed 3202 to the callback. 3203 * 3204 */ 3205 void col_delete_item_with_cb(struct collection_item *item, 3206 col_item_cleanup_fn cb, 3207 void *custom_data); 3208 3209 3210 /** 3211 * @} 3212 */ 3213 3214 3215 /** 3216 * @defgroup iterfunc Iterator interface 3217 * 3218 * The functions in this section allow iterating 3219 * through a collection in a loop where the caller 3220 * implements the loop. It is different from the search and 3221 * traverse functions described in other sections because those 3222 * functions implement the loop themselves and call provided 3223 * callback in a specific situation. 3224 * 3225 * @{ 3226 */ 3227 3228 /** 3229 * @brief Bind iterator to a collection. 3230 * 3231 * This function creates an iterator object and binds it to the collection. 3232 * 3233 * @param[out] iterator Newly created iterator object. 3234 * @param[in] ci Collection to iterate. 3235 * @param[in] mode_flags Flags define how to traverse the collection. 3236 * For more information see \ref traverseconst 3237 * "constants defining traverse modes". 3238 * 3239 * @return 0 - Iterator was created successfully. 3240 * @return ENOMEM - No memory. 3241 * @return EINVAL - The value of some of the arguments is invalid. 3242 * 3243 */ 3244 int col_bind_iterator(struct collection_iterator **iterator, 3245 struct collection_item *ci, 3246 int mode_flags); 3247 3248 /** 3249 * @brief Unbind the iterator from the collection. 3250 * 3251 * @param[in] iterator Iterator object to free. 3252 */ 3253 void col_unbind_iterator(struct collection_iterator *iterator); 3254 3255 /** 3256 * @brief Iterate collection. 3257 * 3258 * Advance to next item in the collection. After the iterator is 3259 * bound it does not point to any item in the collection. 3260 * Use this function in the loop to step through all items 3261 * in the collection. See unit test for code examples. 3262 * 3263 * @param[in] iterator Iterator object to use. 3264 * @param[out] item Pointer to the collection item. 3265 * Do not destroy or alter this pointer 3266 * in any ways. To access the internals 3267 * of the item use \ref getitem "item management" 3268 * functions. 3269 * The value of the item will be set to NULL if 3270 * the end of the collection is reached. 3271 * 3272 * @return 0 - Item was successfully retrieved. 3273 * @return EINVAL - The value of some of the arguments is invalid. 3274 */ 3275 int col_iterate_collection(struct collection_iterator *iterator, 3276 struct collection_item **item); 3277 3278 /** 3279 * @brief Move up 3280 * 3281 * Stop processing this sub collection and move to the next item in the 3282 * collection some levels up. 3283 * 3284 * @param[in] iterator Iterator object to use. 3285 * @param[in] level Indicates how many levels up you want to jump. 3286 * If 0 - call is a no op. 3287 * If the depth is less then requested level 3288 * the iterator will get to the 0 level and 3289 * next call to \ref col_iterate_collection 3290 * will return NULL item. 3291 * 3292 * @return 0 - Iterator was successfully repositioned. 3293 * @return EINVAL - The value of some of the arguments is invalid. 3294 */ 3295 int col_iterate_up(struct collection_iterator *iterator, unsigned level); 3296 3297 /** 3298 * @brief Get current depth 3299 * 3300 * How deep are we relative to the top level? 3301 * This function will report depth that in some cases might look 3302 * misleading. The reason is that traverse flags affect the internal 3303 * level we are on at each moment. 3304 * For example the default traverse behavior is to show 3305 * references to the sub collections. 3306 * So when the item reference is returned the 3307 * depth automatically adjusted to level inside the sub collection. 3308 * So if function is called in this situation the level returned will 3309 * denote the level inside collection. 3310 * Now imagine that this collection is empty so the attempt to read 3311 * element will push you automatically one level up (in absence of the 3312 * \ref COL_TRAVERSE_END flag). If in this situation you encounter another 3313 * collection the reference will be returned and level automatically 3314 * adjusted to level inside the collection. 3315 * The point is that the level is reliable only after 3316 * a data item was returned. 3317 * To avoid this ambiguity another function \ref col_get_item_depth 3318 * was introduced. 3319 * 3320 * @param[in] iterator Iterator object to use. 3321 * @param[in] depth The variable will receive the depth 3322 * the iterator is on. The value is 0 3323 * if the iterator is on the top level. 3324 * 3325 * @return 0 - Success. 3326 * @return EINVAL - The value of some of the arguments is invalid. 3327 */ 3328 int col_get_iterator_depth(struct collection_iterator *iterator, int *depth); 3329 3330 /** 3331 * @brief Get depth of the last returned item. 3332 * 3333 * @param[in] iterator Iterator object to use. 3334 * @param[in] depth The variable will receive the depth 3335 * the iterator is on. 3336 * Item from the top level will have 3337 * depth equal to 0. The value of 0 3338 * will also be returned if no item 3339 * was read so far. 3340 * 3341 * @return 0 - Success. 3342 * @return EINVAL - The value of some of the arguments is invalid. 3343 */ 3344 int col_get_item_depth(struct collection_iterator *iterator, int *depth); 3345 3346 /** 3347 * @brief Pin iterator 3348 * 3349 * Pins down the iterator to loop around current point. 3350 * 3351 * This feature allows some search optimization. 3352 * The idea is to be able to put a 'pin' 3353 * into a specific place while iterating 3354 * the collection and make this place a new 3355 * "wrap around" place for the collection. 3356 * This means that next time you 3357 * iterate this collection you will start 3358 * iterating from the next item and 3359 * the item you got before setting pin will be 3360 * the last in your iteration cycle. 3361 * 3362 * Here is the example: 3363 * 3364 * Assume you have two collections that you need 3365 * to compare and perform some action on collection 3366 * 1 based on the presence of the item in collection 2. 3367 * - Collection1 = A, B, C, D, E, F 3368 * - Collection2 = A, C, F 3369 * 3370 * The usual approach is to try A from collection 1 3371 * against A, B, C from collection 2. "A" will be found 3372 * right away. But to find "F" it has to be compared 3373 * to "A" and "C" first. The fact that the collections 3374 * are to some extent ordered can in some cases 3375 * help to reduce the number of comparisons. 3376 * If we found "C" in the list we can put a "pin" 3377 * into the collection there causing the iterator 3378 * to warp at this "pin" point. Since "D" and "E" 3379 * are not in the second collection we will have 3380 * to make same amount of comparisons in traditional 3381 * or "pinned" case to not find them. 3382 * To find "F" in pinned case there will be just one 3383 * comparison. 3384 * - Traditional case = 1 + 3 + 2 + 3 + 3 + 3 = 15 3385 * - Pinned case = 1 + 3 + 1 + 3 + 3 + 1 = 12 3386 * 3387 * It is a 20% comparison reduction. 3388 * 3389 * @param[in] iterator Iterator object to use. 3390 */ 3391 void col_pin_iterator(struct collection_iterator *iterator); 3392 3393 /** 3394 * @brief Rewind iterator 3395 * 3396 * Rewinds iterator to the current pin point which is by 3397 * default the beginning of the collection until changed by 3398 * \ref col_pin_iterator function. 3399 * 3400 * @param[in] iterator Iterator object to use. 3401 */ 3402 void col_rewind_iterator(struct collection_iterator *iterator); 3403 3404 3405 /** 3406 * @} 3407 */ 3408 3409 /** 3410 * @} 3411 */ 3412 3413 #endif 3414