Data Structures | Modules | Defines | Typedefs | Functions

COLLECTION interface

Data Structures

struct  collection_item
 Opaque structure that holds one property. More...
struct  collection_iterator
 Opaque iterator structure. More...

Modules

 Type definition constants
 Constants defining add modes
 Constants defining traverse modes
 Constants defining copy modes
 Constants defining sort order
 Add property functions
 Insert property functions
 Update property functions
 Item management
 Iterator interface

Defines

#define COL_CLASS_DEFAULT   0
 Default class for a free form collection.
#define COL_NOMATCH   0
 Value indicates that property is not found.
#define COL_MATCH   1
 Value indicates that property is found.

Typedefs

typedef int(* col_copy_cb )(struct collection_item *item, void *ext_data, int *skip)
 Copy item callback.
typedef int(* col_item_fn )(const char *property, int property_len, int type, void *data, int length, void *custom_dat, int *stop)
 Search Callback.

Functions

int col_create_collection (struct collection_item **ci, const char *name, unsigned cclass)
 Create a collection.
void col_destroy_collection (struct collection_item *ci)
 Destroy a collection.
int col_copy_collection_with_cb (struct collection_item **col_copy, struct collection_item *col_to_copy, const char *name_to_use, int copy_mode, col_copy_cb copy_cb, void *ext_data)
 Copy collection with data modification.
int col_copy_collection (struct collection_item **col_copy, struct collection_item *col_to_copy, const char *name_to_use, int copy_mode)
 Copy collection without data modification.
int col_add_collection_to_collection (struct collection_item *ci, const char *subcollection, const char *as_property, struct collection_item *ci_to_add, int mode)
 Add collection to collection.
int col_traverse_collection (struct collection_item *ci, int mode_flags, col_item_fn item_handler, void *custom_data)
 Traverse collection.
int col_get_item_and_do (struct collection_item *ci, const char *property_to_find, int type, int mode_flags, col_item_fn item_handler, void *custom_data)
 Search and do function.
int col_get_item (struct collection_item *ci, const char *property_to_find, int type, int mode_flags, struct collection_item **item)
 Search function to get an item.
int col_sort_collection (struct collection_item *col, unsigned cmp_flags, unsigned sort_flags)
 Sort collection.
int col_delete_property (struct collection_item *ci, const char *property_to_find, int type, int mode_flags)
 Delete property.
int col_is_item_in_collection (struct collection_item *ci, const char *property_to_find, int type, int mode_flags, int *found)
 Is property in the collection?
int col_get_collection_reference (struct collection_item *ci, struct collection_item **acceptor, const char *col_to_find)
 Get a reference to a collection.
int col_get_reference_from_item (struct collection_item *item, struct collection_item **acceptor)
 Get a reference from the item.
int col_get_collection_class (struct collection_item *ci, unsigned *cclass)
 Get collection class.
int col_set_collection_class (struct collection_item *ci, unsigned cclass)
 Set collection class.
int col_get_collection_count (struct collection_item *ci, unsigned *count)
 Get count of the elements.
int col_is_of_class (struct collection_item *ci, unsigned cclass)
 Check the class of collection.

Define Documentation

#define COL_MATCH   1

Value indicates that property is found.

Used in search functions.

#define COL_NOMATCH   0

Value indicates that property is not found.

Used in search functions.


Typedef Documentation

typedef int(* col_copy_cb)(struct collection_item *item, void *ext_data, int *skip)

Copy item callback.

Callback is used by the col_copy_collection_with_cb function. Function is called after the new item is created but not yet inserted into the target collection. The implementer of the callback can alter the item data or indicate to the caller that the item should be skipped.

Parameters:
[in] item Newly allocated item that will be inserted into the new collection.
[in] ext_data Data the application might want to pass to the callback.
[out] skip Pointer to a variable that indicates if the item should be skipped or not. Set this variable to any nonzero value and the item will be skipped.
Returns:
0 - Success
Function can return any error code. This code will be propagated through the internal functions and returned to the application.
typedef int(* col_item_fn)(const char *property, int property_len, int type, void *data, int length, void *custom_dat, int *stop)

Search Callback.

Signature of the callback that needs to be used when traversing a collection or looking for a specific item.

Parameters:
[in] property The name of the property will be passed in this parameter.
[in] property_len Length of the property name will be passed in this parameter.
[in] type Type of the data will be passed in this parameter.
[in] data Pointer to the data will be passed in this parameter.
[in] length Length of data will be passed in this parameter.
[in] custom_dat Custom data will be passed in this parameter.
[out] stop Pointer to a variable where the handler can put nonzero to stop traversing of the collection.
Returns:
0 - Success
Function can return any error code. This code will be propagated through the internal functions and returned to the application.

Function Documentation

int col_add_collection_to_collection ( struct collection_item ci,
const char *  subcollection,
const char *  as_property,
struct collection_item ci_to_add,
int  mode 
)

Add collection to collection.

Function adds one collection into another depending upon a specified mode.

Parameters:
[in] ci Root collection object.
[in] subcollection Name of the inner collection to add collection to. If NULL the collection is added to the root collection.
[in] as_property Name of the property that will constitute the reference. If NULL the name of the collection being added will be used. If specified the restrictions to the name characters and length apply. For more details about the name related restrictions see col_add_xxx_property functions.
[in] ci_to_add Collection to add.
[in] mode Specifies how the collection should be added.
Returns:
0 - Collection was added successfully.
ENOMEM - No memory.
EINVAL - The value of some of the arguments is invalid. The attempt to update a property which is a reference to a collection or a collection name.
ENOENT - Property to update is not found.
int col_copy_collection ( struct collection_item **  col_copy,
struct collection_item col_to_copy,
const char *  name_to_use,
int  copy_mode 
)

Copy collection without data modification.

Function creates a deep copy of the current collection. It wraps the col_copy_collection_with_cb function. The acceptable modes are defined here.

Parameters:
[out] col_copy Newly created collection object.
[in] col_to_copy Collection object that will be copied.
[in] name_to_use Name of the new collection.
[in] copy_mode How to copy.
Returns:
0 - Collection was copied successfully.
ENOMEM - No memory.
EINVAL - The value of some of the arguments is invalid.
int col_copy_collection_with_cb ( struct collection_item **  col_copy,
struct collection_item col_to_copy,
const char *  name_to_use,
int  copy_mode,
col_copy_cb  copy_cb,
void *  ext_data 
)

Copy collection with data modification.

Function create a deep copy of the current collection. Calls caller provided callback before copying each item's data. This is useful if the data needs to be resolved in some way. The best use is when the template is copied and the values in the template are resolved to the actual values. The acceptable modes are defined here.

Parameters:
[out] col_copy Newly created collection object.
[in] col_to_copy Collection object that will be copied.
[in] name_to_use Name of the new collection.
[in] copy_mode How to copy.
[in] copy_cb Pointer to a callback col_copy_cb. Can be NULL. In this case data is copied without modification.
[in] ext_data Data the application might want to pass to the callback.
Returns:
0 - Collection was copied successfully.
ENOMEM - No memory.
EINVAL - The value of some of the arguments is invalid.
Any error code returned by the callback.
int col_create_collection ( struct collection_item **  ci,
const char *  name,
unsigned  cclass 
)

Create a collection.

The function will create a collection. Each collection should have name and class.

Parameters:
[out] ci Newly allocated collection object.
[in] name The name is supposed to be a unique identifier of the collection. This is useful when the collections are stored within other collections or inside other aggregation objects. Caller is free to use any name. Name should consist of the ASCII characters with codes non less than space. Exclamation mark character is a special character and can't be used in name of collection or property.
Maximum allowed length is defined at compile time. The default value is 64k.
[in] cclass Class is used to relate the collection to a specific group of the collections of the same structure. This is very useful when you try to represent objects using collections and you want to check if the objects have same structure or not. There is no predefined name space for the collection classes. Defining classes is left to the application developers.
NOTE: If you decide to build an interface using collection library pick a range for the classes you are going to use and make sure that they do not collide with other interfaces built on top of the collection.
Returns:
0 - Collection was created successfully.
ENOMEM - No memory.
EINVAL - Invalid characters in the collection name.
EMSGSIZE - Collection name is too long.
int col_delete_property ( struct collection_item ci,
const char *  property_to_find,
int  type,
int  mode_flags 
)

Delete property.

Delete property from the collection. It is recommended 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. The col_delete_property function has some advantage only if it is not known where property 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 a sub collection "bar" which is in turn a part of a collection "foo".

Parameters:
[in] ci Collection to delete property from.
[in] property_to_find Property to delete.
[in] type Use type if names are not unique and you know the type of the value you want to delete. Otherwise set to 0.
[in] mode_flags The flags define how the collection should be searched. For more information see traverse constants.
Returns:
0 - Property was deleted successfully.
EINVAL - The value of some of the arguments is invalid.
ENOMEM - No memory.
ENOENT - Property not found.
void col_destroy_collection ( struct collection_item ci  ) 

Destroy a collection.

The function will destroy a collection.

Parameters:
[in] ci Collection object.
int col_get_collection_class ( struct collection_item ci,
unsigned *  cclass 
)

Get collection class.

The classes of the collections can be used to convey information about the collection's internal structure. Some interfaces built on top of the collection might impose restrictions on the collection structure. For example the interface can decide that it is going to deal with the collections that do not have sub collections and elements of the collections are always only strings. So the interface will define a class of the collection and create a function that would take the strings and create such a collection. Then other functions of that interface would check if the provided collection is of the specified class. If not the interface would reject the collection right away. If the collection is of the valid class the interface might call the validation function to make sure that this is really the case however it needs to validate it only once and lower level functions can rely on the class value of the collection without performing duplicate validation.

Parameters:
[in] ci Collection object.
[out] cclass Variable that will receive the value of the class.
Returns:
0 - Success.
EINVAL - The value of some of the arguments is invalid.
int col_get_collection_count ( struct collection_item ci,
unsigned *  count 
)

Get count of the elements.

It is useful to know how many items are there in the collection.

Parameters:
[in] ci Collection object.
[out] count Variable will receive the value of the number of the items in the collection. Collection header or references to external collections are counted as well. This means that every collection has at least one item - the header.
Returns:
0 - Success.
EINVAL - The value of some of the arguments is invalid.
int col_get_collection_reference ( struct collection_item ci,
struct collection_item **  acceptor,
const char *  col_to_find 
)

Get a reference to a collection.

Get a pointer to a collection included into another collection. If the col_to_find is NULL function returns a reference to the top level collection. Delete extracted collection after use to decrease reference count.

Parameters:
[in] ci Collection to search.
[out] acceptor Variable that accepts pointer to an extracted collection. Use col_destroy_collection to free returned object reference after use.
[in] col_to_find Collection to find. "foo!bar!baz" notation can be used.
Returns:
0 - Success.
EINVAL - The value of some of the arguments is invalid.
ENOMEM - No memory.
int col_get_item ( struct collection_item ci,
const char *  property_to_find,
int  type,
int  mode_flags,
struct collection_item **  item 
)

Search function to get an item.

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. Internally function is a wrapper around the col_get_item_and_do function.

Use item management functions to work with the item.

Parameters:
[in] ci Collection object to traverse.
[in] property_to_find Name of the property to find. Parameter supports "x!y" notation.
[in] type Type filter. Only properties of the given type will match. Can be 0 to indicate that all types should be evaluated.
[in] mode_flags How to traverse the collection. See details here.
[in] item Pointer to found item or NULL if item is not found.
Returns:
0 - No internal errors during search.
EINVAL - The value of some of the arguments is invalid.
ENOENT - The search criteria is incorrect.
ENOMEM - No memory.
int col_get_item_and_do ( struct collection_item ci,
const char *  property_to_find,
int  type,
int  mode_flags,
col_item_fn  item_handler,
void *  custom_data 
)

Search and do function.

Looks up an item in the collection based on the property and type. Actually it is a traverse function with special traversing logic. It traverses the whole collection but calls the supplied callback only for the items that match the search criteria. It is the responsibility of the caller to define how the callback is going to indicate that the item it was looking for is 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.

Parameters:
[in] ci Collection object to traverse.
[in] property_to_find Name of the property to find. Parameter supports "x!y" notation.
[in] type Type filter. Only properties of the given type will match. Can be 0 to indicate that all types should be evaluated.
[in] mode_flags How to traverse the collection. See details here.
[in] item_handler Function to call when the item is found.
[in] custom_data Custom data passed to the callback.
Returns:
0 - Operation completed successfully.
EINVAL - The value of some of the arguments is invalid.
ENOENT - The search criteria is incorrect.
ENOMEM - No memory.
Any error code returned by the callback.
int col_get_reference_from_item ( struct collection_item item,
struct collection_item **  acceptor 
)

Get a reference from the item.

Get a pointer to a collection from a current item if current item is a reference to the collection. If current item is not a reference to a collection an error will be returned. Delete extracted collection after use to decrease reference count.

Parameters:
[in] item Item to extract the reference from.
[out] acceptor Variable that accepts pointer to an extracted collection. Use col_destroy_collection to free returned object reference after use.
Returns:
0 - Success.
EINVAL - The value of some of the arguments is invalid.
int col_is_item_in_collection ( struct collection_item ci,
const char *  property_to_find,
int  type,
int  mode_flags,
int *  found 
)

Is property in the collection?

Convenience function to check if the property is indeed in the collection.

Parameters:
[in] ci Collection to search.
[in] property_to_find Property to find.
[in] type Use type if names are not unique and you know the type of the value you want to check. Otherwise set to 0.
[in] mode_flags The flags define how the collection should be searched. For more information see traverse constants.
[out] found The variable that will receive the result of the search. COL_NOMATCH - if not found COL_MATCH if found
Returns:
0 - Search completed successfully.
EINVAL - The value of some of the arguments is invalid.
ENOMEM - No memory.
int col_is_of_class ( struct collection_item ci,
unsigned  cclass 
)

Check the class of collection.

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.

Parameters:
[in] ci Collection object.
[in] cclass Class value to compare to to.
Returns:
0 - If any internal error or classes do not match.
1 - No error and classes do match.
int col_set_collection_class ( struct collection_item ci,
unsigned  cclass 
)

Set collection class.

Sometimes as a result of the collection modification the class of the collection can change.

Parameters:
[in] ci Collection object.
[in] cclass New class value.
Returns:
0 - Success.
EINVAL - The value of some of the arguments is invalid.
int col_sort_collection ( struct collection_item col,
unsigned  cmp_flags,
unsigned  sort_flags 
)

Sort collection.

If the sub collections are included in sorting each collection is sorted separately (this is not a global sort). It might be dangerous to sort sub collections if sub collection is not owned by the current collection. If it is a reference to an external collection there might be an issue. To skip the collections that externally referenced use COL_SORT_MYSUB flag. Keep in mind that if a collection is referenced more than once by other collection and that collection is sorted with sub collections the referenced collection will be sorted more than once.

NOTE: Current implementation of the sorting function is very simple and alternative implementations might be provided later.

Parameters:
[in] col Collection to sort.
[in] cmp_flags For more information see comparison flags.
[in] sort_flags For more information see sort flags.
Returns:
0 - No internal errors during sorting.
EINVAL - The value of some of the arguments is invalid.
int col_traverse_collection ( struct collection_item ci,
int  mode_flags,
col_item_fn  item_handler,
void *  custom_data 
)

Traverse collection.

Function to traverse the entire collection including (optionally) sub collections.

Parameters:
[in] ci Collection object to traverse.
[in] mode_flags How to traverse. See details here.
[in] item_handler Application supplied callback. It will be called for each item in the collection including headers.
[in] custom_data Custom data that application might want to pass to the callback.
Returns:
0 - Collection was traversed successfully.
ENOMEM - No memory.
EINVAL - The value of some of the arguments is invalid.
Any error code returned by the callback.
 All Data Structures