diff options
Diffstat (limited to 'common/collection/collection.h')
| -rw-r--r-- | common/collection/collection.h | 388 |
1 files changed, 372 insertions, 16 deletions
diff --git a/common/collection/collection.h b/common/collection/collection.h index 687f468d7..28622a505 100644 --- a/common/collection/collection.h +++ b/common/collection/collection.h @@ -48,6 +48,7 @@ Useful when traversing collections */ + /* Any data we deal with can't be longer than this */ /* FIXME - make it compile time option */ #define COL_MAX_DATA 65535 @@ -151,11 +152,11 @@ struct collection_iterator; * 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". + * 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 valet itself. You want to get + * retrieved. But in most cases you do not the wallet 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 @@ -163,13 +164,13 @@ struct collection_iterator; * 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 + * 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.valet". + * 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 @@ -181,14 +182,27 @@ struct collection_iterator; * use. */ -/* Function that creates an named collection */ +/* Function that creates a named collection */ int create_collection(struct collection_item **ci, const char *name, unsigned cclass); +/* Function that creates a named collection using a memory descriptor */ +/* FIXME - function is a placeholder. It is not implemented yet. + * will be added in future together with the definition of the + * descriptor structure. + * The purpose is to control the internal implementation of the collection + * a) Use hash table for faster searches if the collection is expected to be large. + * b) Define memory functions to use. + */ +/* +int create_collection_ex(struct collection_item **ci, const char *name, + unsigned cclass, struct cdescriptor *descrptor); +*/ + /* Function that destroys a collection */ void destroy_collection(struct collection_item *ci); -/* Family of functions that add properties to an event */ +/* 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 @@ -397,7 +411,7 @@ const void *get_item_data(struct collection_item *ci); /* If you want to modify the item that you got as a result of iterating through collection * or by calling 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 NULL as data parameter. + * 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. */ @@ -407,7 +421,14 @@ int modify_item(struct collection_item *item, void *data, int length); -/* Convenience functions that wrap modify_tem(). */ +/* Rename the item */ +int 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 modify_str_item(struct collection_item *item, const char *property, char *string, @@ -499,9 +520,10 @@ int get_collection_class(struct collection_item *item, /* Collection */ /* Get collection count */ int get_collection_count(struct collection_item *item, /* Collection */ unsigned *count); /* Number of elements in - this collection. - Each subcollection is - counted as 1 element. + * 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 */ @@ -510,5 +532,339 @@ int 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 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 index, /* 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 extract_item_from_current(struct collection_item *ci, /* Top collection */ + int disposition, /* Which to extract */ + const char *refprop, /* Property to relate to */ + int index, /* Index of the property to extract. See notes. */ + int type, /* Type filter */ + struct collection_item **ret_ref); /* Returns the reference back */ + +/* 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 get_item() or add_xxx_property_with_ref() or + * with insert_xxx_property_with_ref(). + * The fundamental difference is that when you extracted item + * using 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 get_item_xxx() functions. + * c) Destroy item using delete_item(). + * You are required to do either a) or c) with such item. + */ +int 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 index, /* 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 insert_item_into_current(struct collection_item *collection, + struct collection_item *item, + int disposition, + const char *refprop, + int index, + unsigned flags); + + + +/* Function to delete the item */ +void 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 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 index, /* Index of the property to add */ + unsigned flags, /* Flags that control naming issues */ + 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 + */ + struct collection_item **ret_ref); /* Returns the reference back */ + + +int 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 index, /* Index of the property to add */ + unsigned flags, /* Flags that control naming issues */ + const char *property, /* Name */ + char *string, /* String */ + int length); /* Length */ + +int 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 index, /* 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 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 index, /* Index of the property to add */ + unsigned flags, /* Flags that control naming issues */ + const char *property, /* Name */ + int number); /* Integer */ + + +int 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 index, /* Index of the property to add */ + unsigned flags, /* Flags that control naming issues */ + const char *property, /* Name */ + unsigned number); /* Unsigned */ + + +int 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 index, /* Index of the property to add */ + unsigned flags, /* Flags that control naming issues */ + const char *property, /* Name */ + long number); /* Long */ + +int 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 index, /* Index of the property to add */ + unsigned flags, /* Flags that control naming issues */ + const char *property, /* Name */ + unsigned long number); /* Unsigned long */ + +int 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 index, /* Index of the property to add */ + unsigned flags, /* Flags that control naming issues */ + const char *property, /* Name */ + double number); /* Double */ + +int 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 index, /* Index of the property to add */ + unsigned flags, /* Flags that control naming issues */ + const char *property, /* Name */ + unsigned char logical); /* Bool */ + + + +int 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 index, /* 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 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 index, /* 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 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 index, /* 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 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 index, /* 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 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 index, /* 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 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 index, /* 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 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 index, /* 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 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 index, /* 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 |