diff options
Diffstat (limited to 'common/collection/collection.h')
| -rw-r--r-- | common/collection/collection.h | 327 |
1 files changed, 205 insertions, 122 deletions
diff --git a/common/collection/collection.h b/common/collection/collection.h index bccf3e3c..ddb74125 100644 --- a/common/collection/collection.h +++ b/common/collection/collection.h @@ -26,7 +26,8 @@ #define EOK 0 #endif -#define COL_TYPE_STRING 0x00000001 /* For elements of type string the trailing 0 is counted into the length. */ +#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 @@ -34,10 +35,18 @@ #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 /* The item of this type denotes a pointer to already existing external collection */ -#define COL_TYPE_END 0x10000000 /* Special type that denotes the end of the collection. Useful when traversing collection */ -#define COL_TYPE_ANY 0x0FFFFFFF /* Special type that denotes any. Useful when traversing collection */ +#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 */ /* Any data we deal with can't be longer than this */ /* FIXME - make it compile time option */ @@ -48,31 +57,53 @@ /* The modes that define how one collection can be added to another */ -#define COL_ADD_MODE_REFERENCE 0 /* One collection will contain a pointer of another */ -#define COL_ADD_MODE_EMBED 1 /* One collection will be donated to become a part of another collection. - * After that the donating connection handle should not be used or freed. - * It means that it can be donated only once. The donation attempt will - * fail if the collection is referenced by other collection. */ -#define COL_ADD_MODE_CLONE 2 /* Creates a deep copy of a collection with its sub collections */ +#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 */ /* Modes how the collection is traversed */ -#define COL_TRAVERSE_DEFAULT 0x00000000 /* No special flags - means it will go through all the items */ -#define COL_TRAVERSE_ONELEVEL 0x00000001 /* Flag to traverse only high level - ignored it IGNORE flag is specified */ -#define COL_TRAVERSE_END 0x00000002 /* Call handler once more when end of the collection is reached - good for processing nested collections */ - /* Flag is implied for iterator unless FLAT flag is specified */ -#define COL_TRAVERSE_IGNORE 0x00000004 /* Ignore sub collections at all as if there are none */ -#define COL_TRAVERSE_FLAT 0x00000008 /* Flatten the collection - FIXME - not implemented yet */ -/* Additional iterator flags - not respected by traverse functions */ -#define COL_TRAVERSE_SHOWSUB 0x00010000 /* Include header of the sub collections - respected by iterator */ - /* By default iterator returns just references and skips headers */ - /* Ignored if ONELEVEL flag is specified and not ignored */ - /* Ignored if FLAT flag is specified */ -#define COL_TRAVERSE_ONLYSUB 0x00020000 /* Show header of the sub collection instead of reference - respected by iterator */ - /* Ignored if ONELEVEL flag is specified and not ignored */ - /* Ignored if FLAT flag is specified */ - -/* FIXME - move to event level - this does not belong to collection */ +#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. + Implicit for iterators unless + the FLAT flag is specified */ +#define COL_TRAVERSE_IGNORE 0x00000004 /* Ignore sub collections as if none + is present */ +#define COL_TRAVERSE_FLAT 0x00000008 /* Flatten the collection. + FIXME: not implemented yet */ + +/* 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. */ + +/* FIXME: move to event level - this does not belong to collection */ /* Time stamp property name */ #define TS_NAME "stamp" /* Time property name */ @@ -105,49 +136,53 @@ struct collection_item; struct collection_iterator; #endif /* COLLECTION_PRIV_H */ -/* IMPORTANT - the collection is a set of items of different types. +/* 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 it is explicitly mentioned - * otherwise) assume that the collection_item * argument points to the header element. - * Passing in elements extracted from the middle of collection to the functions + * 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. + * 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 "valet" somewhere there. * You ask the bag you hold: "find my valet and give it to me". * get_item function will return you the item that is you "valet". - * You can then change something or just get information about the item you retrieved. - * But in most cases you do not the valet itself. You want to get something from the vallet - * 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 dotted notation to refer to an item (or property) - * You can search for "valet" and it will find any first instance of the "valet" in - * your luggage. But you might have two valets. One is yours and another is your significant other's. - * So you might say find "my.valet". It will find valet 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.valet". - * 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. + * You can then change something or just get information about the item you + * retrieved. But in most cases you do not the valet itself. You want to get + * something from the vallet 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 dotted notation to refer to an item (or + * property). You can search for "valet" and it will find any first instance of + * the "valet" in your luggage. But you might have two valets. One is yours and + * another is your significant other's. So you might say find "my.valet". + * It will find valet 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.valet". + * 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. */ /* Function that creates an named collection */ -int create_collection(struct collection_item **ci,char *name,unsigned class); +int create_collection(struct collection_item **ci, char *name,unsigned cclass); /* Function that destroys a collection */ void destroy_collection(struct collection_item *ci); @@ -155,88 +190,131 @@ void destroy_collection(struct collection_item *ci); /* Family of functions that add properties to an event */ /* See details about subcollection argument above. */ /* Family includes the following convinience functions: */ -/* Add a string property to collection. Length should include the null terminating 0 */ -int add_str_property(struct collection_item *ci,char *subcollection, char *property,char *string,int length); +/* Add a string property to collection. The length should include the + * terminating 0 */ +int add_str_property(struct collection_item *ci, char *subcollection, + char *property, char *string, int length); /* Add a binary property to collection. */ -int add_binary_property(struct collection_item *ci,char *subcollection, char *property,void *binary_data,int length); +int add_binary_property(struct collection_item *ci, char *subcollection, + char *property, void *binary_data, int length); /* Add an int property to collection. */ -int add_int_property(struct collection_item *ci,char *subcollection, char *property,int number); +int add_int_property(struct collection_item *ci, char *subcollection, + char *property, int number); /* Add an unsigned int property. */ -int add_unsigned_property(struct collection_item *ci,char *subcollection, char *property,unsigned int number); +int add_unsigned_property(struct collection_item *ci, char *subcollection, + char *property,unsigned int number); /* Add a long property. */ -int add_long_property(struct collection_item *ci,char *subcollection, char *property,long number); +int add_long_property(struct collection_item *ci, char *subcollection, + char *property, long number); /* Add an unsigned long property. */ -int add_ulong_property(struct collection_item *ci,char *subcollection, char *property,unsigned long number); +int add_ulong_property(struct collection_item *ci, char *subcollection, + char *property, unsigned long number); /* Add a double property. */ -int add_double_property(struct collection_item *ci,char *subcollection, char *property,double number); +int add_double_property(struct collection_item *ci, char *subcollection, + char *property,double number); /* Add a bool property. */ -int add_bool_property(struct collection_item *ci,char *subcollection, char *property,unsigned char logical); +int add_bool_property(struct collection_item *ci, char *subcollection, + char *property, unsigned char logical); /* Add any property */ -int add_any_property(struct collection_item *ci, /* Collection to find things in */ +int add_any_property(struct collection_item *ci, /* A collection of items */ char *subcollection, /* Subcollection */ char *property, /* Name */ - int type, /* Type of the passed in data */ - void *data, /* Pointer to the new data */ - int length); /* Length of the data. For strings should include trailing 0 */ - -/* The functions that add an item and immediately return you this item in the ret_ref parameter */ -int add_str_property_with_ref(struct collection_item *ci,char *subcollection, char *property,char *string,int length, + 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 add_str_property_with_ref(struct collection_item *ci, + char *subcollection, + char *property, char *string, int length, struct collection_item **ret_ref); -int add_binary_property_with_ref(struct collection_item *ci,char *subcollection, char *property,void *binary_data,int length, +int add_binary_property_with_ref(struct collection_item *ci, + char *subcollection, + char *property, void *binary_data, int length, struct collection_item **ret_ref); -int add_int_property_with_ref(struct collection_item *ci,char *subcollection, char *property,int number, +int add_int_property_with_ref(struct collection_item *ci, + char *subcollection, + char *property, int number, struct collection_item **ret_ref); -int add_unsigned_property_with_ref(struct collection_item *ci,char *subcollection, char *property,unsigned int number, +int add_unsigned_property_with_ref(struct collection_item *ci, + char *subcollection, + char *property,unsigned int number, struct collection_item **ret_ref); -int add_long_property_with_ref(struct collection_item *ci,char *subcollection, char *property,long number, +int add_long_property_with_ref(struct collection_item *ci, + char *subcollection, + char *property, long number, struct collection_item **ret_ref); -int add_ulong_property_with_ref(struct collection_item *ci,char *subcollection, char *property,unsigned long number, +int add_ulong_property_with_ref(struct collection_item *ci, + char *subcollection, + char *property, unsigned long number, struct collection_item **ret_ref); -int add_double_property_with_ref(struct collection_item *ci,char *subcollection, char *property,double number, - struct collection_item **ret_ref); -int add_bool_property_with_ref(struct collection_item *ci,char *subcollection, char *property,unsigned char logical, +int add_double_property_with_ref(struct collection_item *ci, + char *subcollection, + char *property, double number, struct collection_item **ret_ref); -int add_any_property_with_ref(struct collection_item *ci,char *subcollection,char *property,int type,void *data,int length, +int add_bool_property_with_ref(struct collection_item *ci, + char *subcollection, + char *property, unsigned char logical, + struct collection_item **ret_ref); +int add_any_property_with_ref(struct collection_item *ci, + char *subcollection, + char *property, int type, void *data, int length, struct collection_item **ret_ref); /* FIXME - does not belong here - move to other place */ /* Function to create a timestamp */ -/* Automatically adds/updates time and timestamp properties in the collection returning references */ +/* Automatically adds/updates time and timestamp properties in the + * collection returning references */ int set_timestamp(struct collection_item *ci, struct collection_item **timestr_ref, struct collection_item **timeint_ref); /* Update functions */ -/* All update functions search the property using the search algorithm described at the top of the header file. +/* All update functions search the property using the search algorithm + * described at the top of the header file. * Use same dotted notation to specify a property. */ -/* Update a string property in the collection. Length should include the null terminating 0 */ -int update_str_property(struct collection_item *ci, char *property,int mode_flags, char *string,int length); +/* Update a string property in the collection. + * Length should include the terminating 0 */ +int update_str_property(struct collection_item *ci, char *property, + int mode_flags, char *string,int length); /* Update a binary property in the collection. */ -int update_binary_property(struct collection_item *ci, char *property,int mode_flags, void *binary_data,int length); +int update_binary_property(struct collection_item *ci, char *property, + int mode_flags, void *binary_data,int length); /* Update an int property in the collection. */ -int update_int_property(struct collection_item *ci, char *property,int mode_flags, int number); +int update_int_property(struct collection_item *ci, char *property, + int mode_flags, int number); /* Update an unsigned int property. */ -int update_unsigned_property(struct collection_item *ci, char *property,int mode_flags, unsigned int number); +int update_unsigned_property(struct collection_item *ci, char *property, + int mode_flags, unsigned int number); /* Update a long property. */ -int update_long_property(struct collection_item *ci, char *property,int mode_flags ,long number); +int update_long_property(struct collection_item *ci, char *property, + int mode_flags, long number); /* Update an unsigned long property. */ -int update_ulong_property(struct collection_item *ci, char *property,int mode_flags, unsigned long number); +int update_ulong_property(struct collection_item *ci, char *property, + int mode_flags, unsigned long number); /* Update a double property. */ -int update_double_property(struct collection_item *ci, char *property,int mode_flags, double number); +int update_double_property(struct collection_item *ci, char *property, + int mode_flags, double number); /* Update a double property. */ -int update_bool_property(struct collection_item *ci, char *property,int mode_flags, unsigned char logical); +int update_bool_property(struct collection_item *ci, char *property, + int mode_flags, unsigned char logical); /* Update property in the collection */ -int update_property(struct collection_item *ci, /* Collection to find things in */ - char *property_to_find, /* Name to match */ - int type, /* Type of the passed in data */ - void *new_data, /* Pointer to the new data */ - int length, /* Length of the data. For strings should include trailing 0 */ - int mode_flags); /* How to traverse the collection */ +int update_property(struct collection_item *ci, /* A collection of items */ + 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 */ @@ -283,12 +361,12 @@ int traverse_collection(struct collection_item *ci, /* Collection to traverse the data passed in custom_data and see if the item was found and that the action was performed. */ -int get_item_and_do(struct collection_item *ci, /* Collection to find things in */ - char *property_to_find, /* Name to match */ - int type, /* Type filter */ - int mode_flags, /* How to traverse the collection */ - item_fn item_handler, /* Function to call when the item is found */ - void *custom_data); /* Custom data passed around */ +int get_item_and_do(struct collection_item *ci, /* A collection of items */ + char *property_to_find, /* Name to match */ + int type, /* Type filter */ + int mode_flags, /* How to traverse the collection */ + 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 @@ -354,7 +432,7 @@ int modify_double_item(struct collection_item *item, double number); /* Delete property from the collection */ -int delete_property(struct collection_item *ci, /* Collection to find things in */ +int delete_property(struct collection_item *ci, /* A collection of items */ char *property_to_find, /* Name to match */ int type, /* Type filter */ int mode_flags); /* How to traverse the collection */ @@ -381,18 +459,21 @@ int get_reference_from_item(struct collection_item *ci, /* Reference el /* Bind iterator to a collection */ -int 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 */ +int 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 unbind_iterator(struct collection_iterator *iterator); /* Get items from the collection one by one following the tree */ -int iterate_collection(struct collection_iterator *iterator, struct collection_item **item); +int 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.*/ -/* 'Level' parameter indicates how many levels up you want to jump. If 0 - call is a no op. +/* 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 than requested level function will return error EINVAL. */ int iterate_up(struct collection_iterator *iterator, int level); @@ -403,24 +484,26 @@ int get_iterator_depth(struct collection_iterator *iterator, int *depth); /* FIXME - Do we need to be able to rewind iterator? */ /* Set collection class */ -int set_collection_class(struct collection_item *item, /* Collection */ - unsigned class); /* Class of the collection */ +int set_collection_class(struct collection_item *item, /* Collection */ + unsigned cclass); /* Collection class */ /* Get collection class */ -int get_collection_class(struct collection_item *item, /* Collection */ - unsigned *class); /* Class of the collection */ +int get_collection_class(struct collection_item *item, /* Collection */ + unsigned *cclass); /* Collection class */ /* Get collection count */ -int get_collection_count(struct collection_item *item, /* Collection */ - unsigned *count); /* Count of elements in this collection. - * Each subcollection is counted as 1 element. - */ +int get_collection_count(struct collection_item *item, /* Collection */ + unsigned *count); /* Number of elements in + this collection. + Each subcollection is + counted as 1 element. + */ /* 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 is_of_class(struct collection_item *item, /* Collection */ - unsigned class); /* Class of the collection */ +int is_of_class(struct collection_item *item, /* Collection */ + unsigned cclass); /* Class of the collection */ |