collection.h

/*
    COLLECTION LIBRARY

    Header file for collection interface.

    Copyright (C) Dmitri Pal <dpal@redhat.com> 2009

    Collection Library is free software: you can redistribute it and/or modify
    it under the terms of the GNU Lesser General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    Collection Library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU Lesser General Public License for more details.

    You should have received a copy of the GNU Lesser General Public License
    along with Collection Library.  If not, see <http://www.gnu.org/licenses/>.
*/

#ifndef COLLECTION_H
#define COLLECTION_H

#include <stdint.h>

#ifndef EOK
#define EOK 0
#endif

#define COL_TYPE_STRING          0x00000001 /* For elements of type string the
                                               lenght includes the trailing 0 */
#define COL_TYPE_BINARY          0x00000002
#define COL_TYPE_INTEGER         0x00000004
#define COL_TYPE_UNSIGNED        0x00000008
#define COL_TYPE_LONG            0x00000010
#define COL_TYPE_ULONG           0x00000020
#define COL_TYPE_DOUBLE          0x00000040
#define COL_TYPE_BOOL            0x00000080
#define COL_TYPE_COLLECTION      0x00000100 /* The item of this type denotes
                                               that starting element of a
                                               collection */
#define COL_TYPE_COLLECTIONREF   0x00000200 /* An item of this type is a pointer
                                               to an existing external
                                               collection */
#define COL_TYPE_END             0x10000000 /* Special type that denotes the end
                                               of the collection. Useful when
                                               traversing collections */
#define COL_TYPE_ANY             0x0FFFFFFF /* Special type that denotes any.
                                               Useful when traversing
                                               collections */


/* Default class for a free form collection */
#define COL_CLASS_DEFAULT      0

/* The modes that define how one collection can be added to another */

#define COL_ADD_MODE_REFERENCE 0    /* The collection will contain a pointer
                                     * to another */
#define COL_ADD_MODE_EMBED     1    /* The collection will become part of
                                     * another collection.
                                     * After this operation the handle should
                                     * not be used or freed.
                                     * Can't be done more than once.
                                     * If the collection is referenced by
                                     * another collection, the operation will
                                     * fail. */
#define COL_ADD_MODE_CLONE     2    /* Creates a deep copy of a collection with
                                     * its sub collections */
#define COL_ADD_MODE_FLAT      3    /* Creates a deep copy of a collection with
                                     * its sub collections flattening and NOT
                                     * resolving duplicates.
                                     */
#define COL_ADD_MODE_FLATDOT   4    /* Creates a deep copy of a collection with
                                     * its sub collections flattening and NOT
                                     * resolving duplicates. Names are contructed
                                     * in dotted notation.
                                     * For example the subcollection
                                     * named "sub" containing "foo" and
                                     * "bar" will be flattened as:
                                     * "sub.foo", "sub.bar".
                                     */

/* Modes how the collection is traversed */
#define COL_TRAVERSE_DEFAULT  0x00000000  /* Traverse all items */
#define COL_TRAVERSE_ONELEVEL 0x00000001  /* Flag to traverse only top level
                                           * ignored if the IGNORE flag is
                                           * specified */
#define COL_TRAVERSE_END      0x00000002  /* Call the handler once more when the
                                           * end of the collection is reached.
                                           * Good for processing nested
                                           * collections.
                                           */
#define COL_TRAVERSE_IGNORE   0x00000004  /* Ignore sub collections as if none
                                           * is present */
#define COL_TRAVERSE_FLAT     0x00000008  /* Flatten the collection. */


/* Additional iterator flags
 * NOTE: ignored by traverse functions */
#define COL_TRAVERSE_SHOWSUB  0x00010000  /* Include headers of sub collections
                                           * By default iterators return just
                                           * references and skips headers.
                                           * Ignored if the ONELEVEL flag is
                                           * specified and not ignored.
                                           * Ignored if the FLAT flag is
                                           * specified. */
#define COL_TRAVERSE_ONLYSUB  0x00020000  /* Show the header of the sub
                                           * collection instead of reference.
                                           * Ignored if the ONELEVEL flag is
                                           * specified and not ignored.
                                           * Ignored if the FLAT flag is
                                           * specified. */

/* NOTE COL_TRAVERSE_FLAT, COL_TRAVERSE_SHOWSUB, COL_TRAVERSE_ONLYSUB
 * are mutually exclusive flags. If combined together
 * results will be unpredictable.
 * DO NOT MIX THEM IN ONE ITERATOR.
 */


/* Modes accepted by copy collection function */
#define COL_COPY_NORMAL         0    /* Deep copy. Referenced collections
                                      * of the donor are copied as sub
                                      * collections.
                                      */
#define COL_COPY_FLAT           1    /* Deep copy. Collection is flattend. */
#define COL_COPY_FLATDOT        2    /* Deep copy. Collection is flattend.
                                      * Names are concatenated with dot.
                                      */
#define COL_COPY_KEEPREF        3    /* Deep copy but leave references
                                      * as references.
                                      */
#define COL_COPY_TOP            4    /* Copy only top level
                                      */

/* Match values */
#define COL_NOMATCH 0
#define COL_MATCH   1

/* Deapth for iteraor depth allocation block */
#define STACK_DEPTH_BLOCK   15

/* Public declaration of the private data */
#ifndef COLLECTION_PRIV_H
/* Structure that holds one property. */
struct collection_item;

/* Your implementation can assume that following members
 * will always be members of the collection_item.
 * but you should use get_item_xxx functions to get them.
 *   char *property;
 *   int property_len;
 *   int type;
 *   int length;
 *   void *data;
 */


/* Internal iterator structure */
struct collection_iterator;
#endif /* COLLECTION_PRIV_H */

/* IMPORTANT - the collection is a set of items of different type.
 * There is always a header item in any collection that starts the collection.
 * Most of the functions in the interface (unless explicitly stated otherwise)
 * assume that the collection_item * argument points to the header element.
 * Passing in elements extracted from the middle of a collection to functions
 * that expect header elements is illegal. There might be not enough checking
 * at the moment but this will be enforced in future versions of the library.

 * IMPORTANT - To better understand how collections work imagine travel bags.
 * They usually come in different sizes and one can put a bag in a bag when
 * they put away to the shelf in a garage or closet. Collection is such bag
 * except that you can put other bags into each other even if they are not
 * empty.
 * When you put items into a bag you do not see the contents of the bag.
 * You just hold the bag. How many other bags inside this bag you do not know.
 * But you might know that you put a "wallet" somewhere there.
 * You ask the bag you hold: "find my wallet and give it to me".
 * get_item function will return you the item that is your "wallet".
 * You can then change something or just get information about the item you
 * retrieved. But in most cases you do not the wallet itself. You want to get
 * something from the wallet or put something into it. IMO money would be an
 * obvious choice. To do this you use update_xxx_property functions.
 * There might be a bag somewhere deep and you might want to add something to
 * it. add_xxx_property_xxx functions allow you to specify sub collection you
 * want the item to be added to. If this sub collection argument is NULL top
 * level collection is assumed.
 * The search in the collections users a "x!y!z" notation to refer to an item (or
 * property). You can search for "wallet" and it will find any first instance of
 * the "wallet" in your luggage. But you might have two wallets. One is yours and
 * another is your significant other's. So you might say find "my!wallet".
 * It will find wallet in your bad (collection) named "my". This collection can
 * be many levels deep inside other collections. You do not need to know the
 * full path to get to it. But if you have the full path you can use the fill
 * path like this "luggage!newbags!my!wallet".
 * It is useful to be able to put bags into bags as well as get them out of each
 * other. When the collection is created the header keeps a reference count on
 * how many copies of the collection are known to the world. So one can put a
 * collection into collection and give up its access to it (embed) of still hold
 * to the reference. By embedding the collection the caller effectively gives
 * up its responsibility to destroy the collection after it is used.
 * By extracting reference from an internal collection the caller gains access
 * to the collection directly and thus has responsibility to destroy it after
 * use.
 * Characters with codes less than space in ASCII table are illegal for property
 * names.
 * Character '!' also illegal in property name and reserved for "x!y!z" notation.
 */

/* Function that creates a named collection */
int col_create_collection(struct collection_item **ci,
                          const char *name,
                          unsigned cclass);

/* Function that destroys a collection */
void col_destroy_collection(struct collection_item *ci);

/* Family of functions that add properties to a collection */
/* See details about subcollection argument above. */
/* Family includes the following convinience functions: */
/* Add a string property to collection. The length should include the
 * terminating 0 */
int col_add_str_property(struct collection_item *ci,
                         const char *subcollection,
                         const char *property,
                         const char *string,
                         int length);
/* Add a binary property to collection.  */
int col_add_binary_property(struct collection_item *ci,
                            const char *subcollection,
                            const char *property,
                            void *binary_data,
                            int length);
/* Add an int property to collection. */
int col_add_int_property(struct collection_item *ci,
                         const char *subcollection,
                         const char *property,
                         int number);
/* Add an unsigned int property. */
int col_add_unsigned_property(struct collection_item *ci,
                              const char *subcollection,
                              const char *property,
                              unsigned int number);
/* Add a long property. */
int col_add_long_property(struct collection_item *ci,
                          const char *subcollection,
                          const char *property,
                          long number);
/* Add an unsigned long property. */
int col_add_ulong_property(struct collection_item *ci,
                           const char *subcollection,
                           const char *property,
                           unsigned long number);
/* Add a double property. */
int col_add_double_property(struct collection_item *ci,
                            const char *subcollection,
                            const char *property,
                            double number);
/* Add a bool property. */
int col_add_bool_property(struct collection_item *ci,
                          const char *subcollection,
                          const char *property,
                          unsigned char logical);

/* Add any property */
int col_add_any_property(struct collection_item *ci,    /* A collection of items */
                         const char *subcollection,     /* Subcollection */
                         const char *property,          /* Name */
                         int type,                      /* Data type */
                         void *data,                    /* Pointer to the data */
                         int length);                   /* Length of the data. For
                                                         * strings it includes the
                                                         * trailing 0 */

/* The functions that add an item and immediately return you this item
 * in the ret_ref parameter */
int col_add_str_property_with_ref(struct collection_item *ci,
                                  const char *subcollection,
                                  const char *property,
                                  char *string, int length,
                                  struct collection_item **ret_ref);
int col_add_binary_property_with_ref(struct collection_item *ci,
                                     const char *subcollection,
                                     const char *property,
                                     void *binary_data, int length,
                                     struct collection_item **ret_ref);
int col_add_int_property_with_ref(struct collection_item *ci,
                                  const char *subcollection,
                                  const char *property, int number,
                                  struct collection_item **ret_ref);
int col_add_unsigned_property_with_ref(struct collection_item *ci,
                                       const char *subcollection,
                                       const char *property, unsigned int number,
                                       struct collection_item **ret_ref);
int col_add_long_property_with_ref(struct collection_item *ci,
                                   const char *subcollection,
                                   const char *property, long number,
                                   struct collection_item **ret_ref);
int col_add_ulong_property_with_ref(struct collection_item *ci,
                                    const char *subcollection,
                                    const char *property, unsigned long number,
                                    struct collection_item **ret_ref);
int col_add_double_property_with_ref(struct collection_item *ci,
                                     const char *subcollection,
                                     const char *property, double number,
                                     struct collection_item **ret_ref);
int col_add_bool_property_with_ref(struct collection_item *ci,
                                   const char *subcollection,
                                   const char *property, unsigned char logical,
                                   struct collection_item **ret_ref);
int col_add_any_property_with_ref(struct collection_item *ci,
                                  const char *subcollection,
                                  const char *property,
                                  int type, void *data, int length,
                                  struct collection_item **ret_ref);

/* Update functions */
/* All update functions search the property using the search algorithm
 * described at the top of the header file.
 * Use same "x!y" notation to specify a property.
 */
/* Update a string property in the collection.
 * Length should include the terminating 0  */
int col_update_str_property(struct collection_item *ci,
                            const char *property,
                            int mode_flags,
                            char *string,
                            int length);
/* Update a binary property in the collection.  */
int col_update_binary_property(struct collection_item *ci,
                               const char *property,
                               int mode_flags,
                               void *binary_data,
                               int length);
/* Update an int property in the collection. */
int col_update_int_property(struct collection_item *ci,
                            const char *property,
                            int mode_flags,
                            int number);
/* Update an unsigned int property. */
int col_update_unsigned_property(struct collection_item *ci,
                                 const char *property,
                                 int mode_flags,
                                 unsigned int number);
/* Update a long property. */
int col_update_long_property(struct collection_item *ci,
                             const char *property,
                             int mode_flags,
                             long number);
/* Update an unsigned long property. */
int col_update_ulong_property(struct collection_item *ci,
                              const char *property,
                              int mode_flags,
                              unsigned long number);
/* Update a double property. */
int col_update_double_property(struct collection_item *ci,
                               const char *property,
                               int mode_flags,
                               double number);
/* Update a double property. */
int col_update_bool_property(struct collection_item *ci,
                             const char *property,
                             int mode_flags,
                             unsigned char logical);

/* Update property in the collection */
int col_update_property(struct collection_item *ci,   /* A collection of items */
                        const char *property_to_find, /* Name to match */
                        int type,                     /* Data type */
                        void *new_data,               /* Pointer to the data */
                        int length,                   /* Length of the data. For
                                                       * strings, it includes the
                                                       * trailing 0 */
                        int mode_flags);              /* How to traverse the collection  */


/* Add collection to collection */
int col_add_collection_to_collection(struct collection_item *ci,            /* Collection handle to with we add
                                                                             * another collection */
                                 const char *sub_collection_name,           /* Name of the sub collection
                                                                             * to which collection needs to be
                                                                             * added as a property.
                                                                             * If NULL high level collection is assumed. */
                                 const char *as_property,                   /* Name of the collection property.
                                                                             * If NULL, same property as the name of
                                                                             * the collection being added will be used. */
                                 struct collection_item *collection_to_add, /* Collection to add */
                                 int mode);                                 /* How this collection needs to be added */

/* Create a deep copy of the current collection.
 * Wraps the function below.
 * The acceptable modes are defined at the top.
 */
int col_copy_collection(struct collection_item **collection_copy,
                        struct collection_item *collection_to_copy,
                        const char *name_to_use,
                        int copy_mode);

/* Callback used in the next function */
typedef int (*col_copy_cb)(struct collection_item *item,
                           void *ext_data,
                           int *skip);

/* Create a deep copy of the current collection.
 * Calls caller provided callback before
 * copying each item's data.
 * The acceptable modes are defined at the top.
 */
int col_copy_collection_with_cb(struct collection_item **collection_copy,
                                struct collection_item *collection_to_copy,
                                const char *name_to_use,
                                int copy_mode,
                                col_copy_cb copy_cb,
                                void *ext_data);

/* Signature of the callback that needs to be used when
   traversing a collection or looking for a specific item */
typedef int (*col_item_fn)(const char *property,   /* The name of the property will be passed in this parameter. */
                           int property_len, /* Length of the property name will be passed in this parameter. */
                           int type,         /* Type of the data will be passed in this parameter */
                           void *data,       /* Pointer to the data will be passed in this parameter */
                           int length,       /* Length of data will be passed in this parameter */
                           void *custom_dat, /* Custom data will be passed in this parameter */
                           int *stop);       /* Pointer to variable where the handler can put non zero to stop processing */

/* Function to traverse the entire collection including optionally sub collections */
int col_traverse_collection(struct collection_item *ci,    /* Collection to traverse */
                            int mode_flags,                /* Flags defining how to traverse */
                            col_item_fn item_handler,      /* Handler called for each item */
                            void *custom_data);            /* Custom data passed around */

/* Search function. Looks up an item in the collection based on the property.
 * Actually it is a traverse function with special traversing logic.
 * It is the responsibility of the handler to set something in the custom data
 * to indicate that the item was found.
 * Function will not return error if the item is not found.
 * It is the responsibility of the calling application to check
 * the data passed in custom_data and see if the item was found and
 * that the action was performed.
 */
int col_get_item_and_do(struct collection_item *ci,  /* A collection of items */
                        const char *property_to_find,/* Name to match */
                        int type,                    /* Type filter */
                        int mode_flags,              /* How to traverse the collection */
                        col_item_fn item_handler,    /* Function to call when the item is found */
                        void *custom_data);          /* Custom data passed around */

/* Convenience function to get individual item */
/* Caller should be aware that this is not a copy of the item
 * but the pointer to actual item stored in the collection.
 * The returned pointer should never be altered or freed by caller of the function.
 * The caller should be sure that the collection does not go out of scope
 * while the pointer to its data is in use.
 * Working with the internals of the collection item structure directly
 * may cause problems in future if the internal implementation changes.
 * The caller needs to be aware that function does not return
 * error if item is not found. The caller needs to check if
 * item is not NULL to determine whether something was found.
 */
int col_get_item(struct collection_item *ci,       /* Collection to find things in */
                 const char *property_to_find,     /* Name to match */
                 int type,                         /* Type filter */
                 int mode_flags,                   /* How to traverse the collection */
                 struct collection_item **item);   /* Found item */

/* Group of functions that allows retrieving individual elements of the collection_item
 * hiding the internal implementation.
 */
const char *col_get_item_property(struct collection_item *ci, int *property_len);
int col_get_item_type(struct collection_item *ci);
int col_get_item_length(struct collection_item *ci);
void *col_get_item_data(struct collection_item *ci);
uint64_t col_get_item_hash(struct collection_item *ci);

/* Calculates hash of the string using internal hashing
 * algorithm. Populates "length" with length
 * of the string not counting 0.
 * Length argument can be NULL.
 * If sub_len is greater than zero
 * this value is used to count how many characters
 * from string should be included into hash
 * calculation.
 */
uint64_t col_make_hash(const char *string, int sub_len, int *length);

/* Compare two items.
 * The second item is evaluated against the first.
 * Function returns 0 if two items are the same
 * and non-zero otherwise.
 * The in_flags is a bit mask that defines
 * how the items should be compared.
 * See below the list of conbstants
 * defined for this purpose.
 * If items are different they might be orderable
 * or not. For example one can order items by name
 * but not by type.
 * If the result of the function is non-zero
 * the out_flags (if provided) will be
 * set to indicate if the second item is greater
 * then the first.
 */
int col_compare_items(struct collection_item *first,
                      struct collection_item *second,
                      unsigned in_flags,
                      unsigned *out_flags);

/********* Possible valies for input flags ********/
/* How to compare properties?
 * The following 4 flags are mutually exclusive
 */
#define COL_CMPIN_PROP_EQU    0x000000004 /* Properties should be same */
#define COL_CMPIN_PROP_BEG    0x000000005 /* Properties start same */
#define COL_CMPIN_PROP_MID    0x000000006 /* One is substring of another */
#define COL_CMPIN_PROP_END    0x000000007 /* One property ends with another */

/* Make sure that there is a dot.
 * Useful with _BEG, _MID and _END flags to check that the there is
 * a dot (if present) in the right place (before, after or both).
 * For example the first item is named "foo.bar" and the second
 * is "bar". Using _END the "bar" will be found but if _DOT flag is
 * used too the function will also check if there was a "." before the found
 * string in this case.
 * Ignored in case of _EQU.
 */
#define COL_CMPIN_PROP_DOT     0x000000008

/* Compare property lenghts */
#define COL_CMPIN_PROP_LEN     0x000000010

/* Compare types */
#define COL_CMPIN_TYPE         0x000000020

/* Compare data len */
#define COL_CMPIN_DATA_LEN     0x000000040

/* Compare data (up to the length of the second one)
 * if type is the same. If type is different
 * function will assume data is different
 * without performing actual comparison.
 */
#define COL_CMPIN_DATA         0x000000080

/********* Possible values for output flags *********/
/* If _EQU was specified and the property of the second item
 * is greater the following bit will be set
 */
#define COL_CMPOUT_PROP_STR    0x00000001
/* If we were told to compare property lengths
 * and second is longer this bit will be set
 */
#define COL_CMPOUT_PROP_LEN    0x00000002
/* If we were told to compare data lengths
 * and second is longer this bit will be set
 */
#define COL_CMPOUT_DATA_LEN    0x00000004
/* If we were told to compare data
 * and types are the same then
 * if the second one is greater this bit will
 * be set. If data is binary flag is never set
 */
#define COL_CMPOUT_DATA    0x00000008


/* Sort collection.
 * cmp_flags are the same as in_flags for the compare
 * function. The sort_flags is an OR of the costants
 * defined below.
 * If the subcollections are included in sorting
 * each collection is sorted separately (this is not a global sort).
 * It might be dangerous to sort subcollections if
 * subcollection is not owned by current collection.
 * If it is a reference to an external collection
 * there might be an issue. To skip the collections that
 * externally referenced use MYSUB flag.
 * Keep in mind that if the collection
 * has two references to the same other
 * collection it is impossible to detect
 * this situation. If MYSUB is used in this
 * case such collection will be ignored
 * If MYSUB is not used the collection
 * will be sorted more than once.
 */
int col_sort_collection(struct collection_item *col,
                        unsigned cmp_flags,
                        unsigned sort_flags);

/* Sort flags */
#define COL_SORT_ASC    0x00000000
#define COL_SORT_DESC   0x00000001
#define COL_SORT_SUB    0x00000002
#define COL_SORT_MYSUB  0x00000004

/* If you want to modify the item that you got as a result of iterating through collection
 * or by calling col_get_item(). If you want to rename item provide a new name in the property
 * argument. If you want the data to remain unchanged use 0 as length parameter.
 * If item is a reference or collection the call will return error.
 * Previous type and data of the item is destroyed.
 */
int col_modify_item(struct collection_item *item,
                    const char *property,
                    int type,
                    const void *data,
                    int length);

/* Rename the item */
int col_modify_item_property(struct collection_item *item,
                             const char *property);

/* Convenience functions that wrap modify_item().
 * They always assign new value.
 * To rename the property just use modify_item_property();
 */
int col_modify_str_item(struct collection_item *item,
                        const char *property,
                        const char *string,
                        int length);
int col_modify_binary_item(struct collection_item *item,
                           const char *property,
                           void *binary_data,
                           int length);
int col_modify_bool_item(struct collection_item *item,
                         const char *property,
                         unsigned char logical);
int col_modify_int_item(struct collection_item *item,
                        const char *property,
                        int number);
int col_modify_long_item(struct collection_item *item,
                         const char *property,
                         long number);
int col_modify_ulong_item(struct collection_item *item,
                          const char *property,
                          unsigned long number);
int col_modify_unsigned_item(struct collection_item *item,
                             const char *property,
                             unsigned number);
int col_modify_double_item(struct collection_item *item,
                           const char *property,
                           double number);

/* Delete property from the collection. */
/* It is recomended to use a more efficient function
 * col_remove_item() for the same purpose if
 * the property is unique or if the collection
 * has a known structure.
 * This function has some advantage only
 * if it is not known where propery
 * resides and what is the structure of the collection.
 * In this case "foo.bar.baz" notation
 * can be used in the property_to_find argument to find
 * and delete the property "baz" that is in sub collection "bar"
 * which is in turn a part of collection "foo".
 */
int col_delete_property(struct collection_item *ci,    /* A collection of items */
                        const char *property_to_find,  /* Name to match */
                        int type,                      /* Type filter */
                        int mode_flags);               /* How to traverse the collection  */


/* Convenience function to check if the property is indeed in the collection */
int col_is_item_in_collection(struct collection_item *ci,   /* Collection to find things in */
                              const char *property_to_find, /* Name to match */
                              int type,                     /* Type filter */
                              int mode_flags,               /* How to traverse the collection */
                              int *found);                  /* Boolean that turns to nonzero if the match is found */


/* Get collection - get a pointer to a collection included into another collection.
 * If the collection_to_find is NULL function reterns a reference to the top level collection.
 * Delete extracted collection after use to decrease reference count.
 */
int col_get_collection_reference(struct collection_item *ci,          /* High level collection */
                                 struct collection_item **acceptor,   /* The pointer that will accept extracted handle */
                                 const char *collection_to_find);     /* Name to of the collection */

/* Get collection - if current item is a reference get a real collection from it. */
/* Delete extracted collection after use to decrease reference count. */
int col_get_reference_from_item(struct collection_item *ci,          /* Reference element of the high level collection */
                                struct collection_item **acceptor);  /* The pointer that will accept extracted handle */

/* Bind iterator to a collection */
int col_bind_iterator(struct collection_iterator **iterator, /* The iterator to bind */
                      struct collection_item *ci,            /* Collection to bind iterator to */
                      int mode_flags);                       /* How the collection needs to be iterated */

/* Unbind the iterator from the collection */
void col_unbind_iterator(struct collection_iterator *iterator);

/* Get items from the collection one by one following the tree */
int col_iterate_collection(struct collection_iterator *iterator,
                           struct collection_item **item);

/* Stop processing this subcollection and move to the next item in the
 * collection 'level' levels up.
 * The 'Level' parameter indicates how many levels up you want to jump.
 * If 0 - call is a no op.
 * If the depth is less then requested level the iterator will
 * get to the 0 level and next call to col_iterate_collection
 * will return NULL item.
 */
int col_iterate_up(struct collection_iterator *iterator, unsigned level);

/* How deep are we relative to the top level.
 * This function might report depth that might look misleading.
 * The reason is that traverse flags affect the internal
 * level we are on at each moment.
 * For example the default traverse behavior is to show
 * references to the sub collections.
 * So when the item reference is returned the
 * depth automatically adjusted to level inside the sub collection.
 * So if function is called in this situation the level returned will
 * denote the level inside collection.
 * Now imagine that this collection is empty so the attempt to read
 * element will push you automatically one level up (in absence of the
 * COL_TRAVERSE_END flag). If in this situation you encounter another
 * collection the reference will be returned and level automatically
 * adjusted to level inside the collection.
 * The point is that the level is reliable only after
 * a data item was returned.
 * To avoid this ambiguity another function is introduced.
 * See below.
*/
int col_get_iterator_depth(struct collection_iterator *iterator, int *depth);

/* Returns item depth for the last read item.
 * Returns 0 if no item has been read yet.
 */
int col_get_item_depth(struct collection_iterator *iterator, int *depth);

/* Pins down the iterator to loop around current point */
void col_pin_iterator(struct collection_iterator *iterator);

/* Rewinds iterator to the beginning */
void col_rewind_iterator(struct collection_iterator *iterator);

/* Set collection class */
int col_set_collection_class(struct collection_item *item, /* Collection */
                             unsigned cclass);             /* Collection class */

/* Get collection class */
int col_get_collection_class(struct collection_item *item, /* Collection */
                             unsigned *cclass);            /* Collection class */


/* Get collection count */
int col_get_collection_count(struct collection_item *item, /* Collection */
                             unsigned *count);             /* Number of elements in
                                                            * this collection.
                                                            * Each subcollection is
                                                            * counted as 1 element.
                                                            * Header is also counted.
                                                            */

/* Convenience function to check if the collection is of the specific class */
/* In case of internal error assumes that collection is not of the right class */
int col_is_of_class(struct collection_item *item,  /* Collection */
                    unsigned cclass);              /* Class of the collection */


/*
 * Series of collection functions that allow using collection as a stack or a FIFO
 */


/* Extract the item from the collection */
/* The header will not be considered for extraction. */
int col_extract_item(struct collection_item *ci,        /* Top collection */
                     const char *subcollection,         /* Sub collection */
                     int disposition,                   /* Which to extract */
                     const char *refprop,               /* Property to relate to */
                     int idx,                           /* Index of the property to extract. See notes. */
                     int type,                          /* Type filter */
                     struct collection_item **ret_ref); /* Returns the reference back */

/* Similar extraction function as above just considers only one level. */
int col_extract_item_from_current(struct collection_item *ci,        /* Top collection */
                                  int disposition,                   /* Which to extract */
                                  const char *refprop,               /* Property to relate to */
                                  int idx,                           /* Index of the property to extract. See notes. */
                                  int type,                          /* Type filter */
                                  struct collection_item **ret_ref); /* Returns the reference back */

/* Remove item (property) from collection.
 * It is similar to delete_property function but allows more specific
 * information about what item (property) to remove.
 * The header will not be considered for deletion.
 */
int col_remove_item(struct collection_item *ci,        /* Top collection */
                    const char *subcollection,         /* Sub collection */
                    int disposition,                   /* Which to remove */
                    const char *refprop,               /* Property to relate to */
                    int idx,                           /* Index of the property to remove. See notes. */
                    int type);                         /* Type filter */

/* Similar function as above just considers only one level. */
int col_remove_item_from_current(struct collection_item *ci,        /* Top collection */
                                 int disposition,                   /* Which to remove */
                                 const char *refprop,               /* Property to relate to */
                                 int idx,                           /* Index of the property to remove. See notes. */
                                 int type);                         /* Type filter */


/* Insert item to the collection */
/* WARNING: Only use this function to insert items
 * that were extracted using extract_item().
 * NEVER use it with items that were returned
 * by col_get_item() or col_add_xxx_property_with_ref() or
 * with col_insert_xxx_property_with_ref().
 * The fundamental difference is that when you extracted item
 * using col_extract_item() it stops to be managed by a collection.
 * With such item you can:
 * a) Insert this item into another (or same) collection
 * b) Get item information using col_get_item_xxx() functions.
 * c) Destroy item using col_delete_item().
 * You are required to do either a) or c) with such item.
 */
int col_insert_item(struct collection_item *collection, /* Top collection */
                    const char *subcollection,          /* Sub collection */
                    struct collection_item *item,       /* Item to insert */
                    int disposition,                    /* What should be the position of the item */
                    const char *refprop,                /* Property to relate to */
                    int idx,                            /* Index of the property to extract. See notes. */
                    unsigned flags);                    /* Flags that control naming issues */

/* Insert the item into the top level collection (similar to the function above)
 * but does not provide access to the sub collection.
 */
int col_insert_item_into_current(struct collection_item *collection,
                                 struct collection_item *item,
                                 int disposition,
                                 const char *refprop,
                                 int idx,
                                 unsigned flags);



/* Function to delete the item */
void col_delete_item(struct collection_item *item);

/* Possible dispositions for insert, extract and delete function(s).
 * Not all of these dispositions are implemented day one.
 * If disposition is not implemented the function
 * will return error ENOSYS.
 */
#define COL_DSP_END             0 /* Add property to the end of the collection */
                                  /* Extract or delete last property in collection */
#define COL_DSP_FRONT           1 /* Add property to the top of the collection */
                                  /* Extract or delete firat property in collection */
#define COL_DSP_BEFORE          2 /* Add property before other named property */
                                  /* Extract or delete property that is before given
                                   * property. If the given property is first
                                   * in the list ENOENT is returned.
                                   */
#define COL_DSP_AFTER           3 /* Add property immediately after other named property */
                                  /* Delete or extract property immediately after given
                                   * property. If the given property is last in the list
                                   * ENOENT is returned.
                                   */
#define COL_DSP_INDEX           4 /* Add, extract or delete property using index.
                                   * See notes below.
                                   */
/* NOTE ABOUT USING: COL_DSP_INDEX. */
/* The COL_DSP_INDEX adds the item as N-th item after header in the list.
 * Index is zero based.
 * If there are less than N items in the list the item is added to the end.
 * The index value of 0 means that the item will be added immediately
 * after the header. Index of 1 will mean that it is added after first data item and so on.
 *
 * In case of extraction or deletion the N-th item of the collection
 * will be extracted or deleted.
 * Index is zero based.
 * If there are less than N+1 items in the list the function will return ENOENT.
 */

/* The following three dispositions operate only with list of duplicate
 * properties that are going one after another.
 * In case of addition the property name is taken from the item
 * and the value refprop is ignored.
 * In case of extraction or deletion the property name is taken
 * from the refprop.
 */
#define COL_DSP_FIRSTDUP        5 /* Add property as a first dup of the given property */
                                  /* In case of extraction or deletion extracts or deletes
                                   * given property.
                                   */
#define COL_DSP_LASTDUP         6 /* Add property as a last dup of the given property */
                                  /* In case of extraction or deletion extracts or deletes
                                   * last duplicate property in the uninterrupted sequence of
                                   * properties with the same name.
                                   */
#define COL_DSP_NDUP            7 /* Add property as a N-th dup (0- based) of the given property. */
                                  /* In case of extraction or deletion extracts or deletes
                                   * N-th (0-based) duplicate of the given property.
                                   * If index is greater than number of duplicate
                                   * properties in sequence ENOENT is returned.
                                   * See more details below.
                                   */

/* Other dispositions might be possible in future. */

/* The COL_DSP_NDUP is used in case of the multi value property
 * to add a new property with the same name into specific place
 * in the list of properties with the same name.
 * The index of 0 will mean to add the property before the first instance of the property with the same name.
 * If the property does not exist ENOENT will be returned.
 * If the index is greater than the last property with the same name the item will be added
 * immediately after last property with the same name.
 */

/* Flags that can be used with insert functions */
#define COL_INSERT_NOCHECK      0   /* This is the default mode - no dup checks on insert */
#define COL_INSERT_DUPOVER      1   /* Check for dup name and overwrite - position ignored */
#define COL_INSERT_DUPOVERT     2   /* Check for dup name and type and overwrite - position ignored */
#define COL_INSERT_DUPERROR     3   /* Return error EEXIST if the entry with the same name exists */
#define COL_INSERT_DUPERRORT    4   /* Return error EEXIST if the entry with the same name and type exists */
#define COL_INSERT_DUPMOVE      5   /* Check for dups, overwrite, extracts and
                                     * then move to the position requested */
#define COL_INSERT_DUPMOVET     6   /* Check for dup name and type, overwrite, extracts
                                     * and then move to the position requested */

/* In future can be made more complex */

/* NOTE ABOUT FLAGS: Use of the DUP checking flags is costly since it requires a forward look up of the whole
 * collection before the item is inserted. Do not use it until it is absolutely necessary.
 */



/* The attributes in the collection are always added to the end.
 * The family of the insert_xxx(functions) provides
 * much more flexibility than add_xxx_property_xxx() functions.
 */

/* Insert property with reference */
int col_insert_property_with_ref(struct collection_item *ci,        /* A collection of items */
                                 const char *subcollection,         /* Sub collection */
                                 int disposition,                   /* Where to insert */
                                 const char *refprop,               /* Property to relate to */
                                 int idx,                           /* Index of the property to add */
                                 unsigned flags,                    /* Flags that control naming issues */
                                 const char *property,              /* Name */
                                 int type,                          /* Data type */
                                 const void *data,                  /* Pointer to the data */
                                 int length,                        /* Length of the data. For
                                                                     * strings it includes the
                                                                     * trailing 0
                                                                     */
                                 struct collection_item **ret_ref); /* Returns the reference back */


int col_insert_str_property(struct collection_item *ci,        /* A collection of items */
                            const char *subcollection,         /* Sub collection */
                            int disposition,                   /* Where to insert */
                            const char *refprop,               /* Property to relate to */
                            int idx,                           /* Index of the property to add */
                            unsigned flags,                    /* Flags that control naming issues */
                            const char *property,              /* Name */
                            const char *string,                /* String */
                            int length);                       /* Length */

int col_insert_binary_property(struct collection_item *ci,        /* A collection of items */
                               const char *subcollection,         /* Sub collection */
                               int disposition,                   /* Where to insert */
                               const char *refprop,               /* Property to relate to */
                               int idx,                           /* Index of the property to add */
                               unsigned flags,                    /* Flags that control naming issues */
                               const char *property,              /* Name */
                               void *binary_data,                 /* Binary data */
                               int length);                       /* Length */


int col_insert_int_property(struct collection_item *ci,        /* A collection of items */
                            const char *subcollection,         /* Sub collection */
                            int disposition,                   /* Where to insert */
                            const char *refprop,               /* Property to relate to */
                            int idx,                           /* Index of the property to add */
                            unsigned flags,                    /* Flags that control naming issues */
                            const char *property,              /* Name */
                            int number);                       /* Integer */


int col_insert_unsinged_property(struct collection_item *ci,        /* A collection of items */
                                 const char *subcollection,         /* Sub collection */
                                 int disposition,                   /* Where to insert */
                                 const char *refprop,               /* Property to relate to */
                                 int idx,                           /* Index of the property to add */
                                 unsigned flags,                    /* Flags that control naming issues */
                                 const char *property,              /* Name */
                                 unsigned number);                  /* Unsigned */


int col_insert_long_property(struct collection_item *ci,        /* A collection of items */
                             const char *subcollection,         /* Sub collection */
                             int disposition,                   /* Where to insert */
                             const char *refprop,               /* Property to relate to */
                             int idx,                           /* Index of the property to add */
                             unsigned flags,                    /* Flags that control naming issues */
                             const char *property,              /* Name */
                             long number);                      /* Long */

int col_insert_ulong_property(struct collection_item *ci,        /* A collection of items */
                              const char *subcollection,         /* Sub collection */
                              int disposition,                   /* Where to insert */
                              const char *refprop,               /* Property to relate to */
                              int idx,                           /* Index of the property to add */
                              unsigned flags,                    /* Flags that control naming issues */
                              const char *property,              /* Name */
                              unsigned long number);             /* Unsigned long */

int col_insert_double_property(struct collection_item *ci,        /* A collection of items */
                               const char *subcollection,         /* Sub collection */
                               int disposition,                   /* Where to insert */
                               const char *refprop,               /* Property to relate to */
                               int idx,                           /* Index of the property to add */
                               unsigned flags,                    /* Flags that control naming issues */
                               const char *property,              /* Name */
                               double number);                    /* Double */

int col_insert_bool_property(struct collection_item *ci,        /* A collection of items */
                             const char *subcollection,         /* Sub collection */
                             int disposition,                   /* Where to insert */
                             const char *refprop,               /* Property to relate to */
                             int idx,                           /* Index of the property to add */
                             unsigned flags,                    /* Flags that control naming issues */
                             const char *property,              /* Name */
                             unsigned char logical);            /* Bool */



int col_insert_str_property_with_ref(struct collection_item *ci,        /* A collection of items */
                                     const char *subcollection,         /* Sub collection */
                                     int disposition,                   /* Where to insert */
                                     const char *refprop,               /* Property to relate to */
                                     int idx,                           /* Index of the property to add */
                                     unsigned flags,                    /* Flags that control naming issues */
                                     const char *property,              /* Name */
                                     char *string,                      /* String */
                                     int length,                        /* Length */
                                     struct collection_item **ret_ref); /* Returns the reference back */

int col_insert_binary_property_with_ref(struct collection_item *ci,        /* A collection of items */
                                        const char *subcollection,         /* Sub collection */
                                        int disposition,                   /* Where to insert */
                                        const char *refprop,               /* Property to relate to */
                                        int idx,                           /* Index of the property to add */
                                        unsigned flags,                    /* Flags that control naming issues */
                                        const char *property,              /* Name */
                                        void *binary_data,                 /* Binary data */
                                        int length,                        /* Length */
                                        struct collection_item **ret_ref); /* Returns the reference back */


int col_insert_int_property_with_ref(struct collection_item *ci,        /* A collection of items */
                                     const char *subcollection,         /* Sub collection */
                                     int disposition,                   /* Where to insert */
                                     const char *refprop,               /* Property to relate to */
                                     int idx,                           /* Index of the property to add */
                                     unsigned flags,                    /* Flags that control naming issues */
                                     const char *property,              /* Name */
                                     int number,                        /* Integer */
                                     struct collection_item **ret_ref); /* Returns the reference back */


int col_insert_unsinged_property_with_ref(struct collection_item *ci,        /* A collection of items */
                                          const char *subcollection,         /* Sub collection */
                                          int disposition,                   /* Where to insert */
                                          const char *refprop,               /* Property to relate to */
                                          int idx,                           /* Index of the property to add */
                                          unsigned flags,                    /* Flags that control naming issues */
                                          const char *property,              /* Name */
                                          unsigned number,                   /* Unsigned */
                                          struct collection_item **ret_ref); /* Returns the reference back */

int col_insert_long_property_with_ref(struct collection_item *ci,        /* A collection of items */
                                      const char *subcollection,         /* Sub collection */
                                      int disposition,                   /* Where to insert */
                                      const char *refprop,               /* Property to relate to */
                                      int idx,                           /* Index of the property to add */
                                      unsigned flags,                    /* Flags that control naming issues */
                                      const char *property,              /* Name */
                                      long number,                       /* Long */
                                      struct collection_item **ret_ref); /* Returns the reference back */

int col_insert_ulong_property_with_ref(struct collection_item *ci,        /* A collection of items */
                                       const char *subcollection,         /* Sub collection */
                                       int disposition,                   /* Where to insert */
                                       const char *refprop,               /* Property to relate to */
                                       int idx,                           /* Index of the property to add */
                                       unsigned flags,                    /* Flags that control naming issues */
                                       const char *property,              /* Name */
                                       unsigned long number,              /* Unsigned long */
                                       struct collection_item **ret_ref); /* Returns the reference back */

int col_insert_double_property_with_ref(struct collection_item *ci,        /* A collection of items */
                                        const char *subcollection,         /* Sub collection */
                                        int disposition,                   /* Where to insert */
                                        const char *refprop,               /* Property to relate to */
                                        int idx,                           /* Index of the property to add */
                                        unsigned flags,                    /* Flags that control naming issues */
                                        const char *property,              /* Name */
                                        double number,                     /* Double */
                                        struct collection_item **ret_ref); /* Returns the reference back */

int col_insert_bool_property_with_ref(struct collection_item *ci,        /* A collection of items */
                                      const char *subcollection,         /* Sub collection */
                                      int disposition,                   /* Where to insert */
                                      const char *refprop,               /* Property to relate to */
                                      int idx,                           /* Index of the property to add */
                                      unsigned flags,                    /* Flags that control naming issues */
                                      const char *property,              /* Name */
                                      unsigned char logical,             /* Bool */
                                      struct collection_item **ret_ref); /* Returns the reference back */


#endif