<!-- This comment will put IE 6, 7 and 8 in quirks mode -->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>libcollection: COLLECTION interface</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javaScript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body onload='searchBox.OnSelectItem(0);'>
<!-- Generated by Doxygen 1.6.1 -->
<script type="text/javascript"><!--
var searchBox = new SearchBox("searchBox", "search",false,'Search');
--></script>
<div class="navigation" id="top">
<div class="tabs">
<ul>
<li><a href="index.html"><span>Main Page</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
<li>
<div id="MSearchBox" class="MSearchBoxInactive">
<img id="MSearchSelect" src="search/search.png"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
alt=""/>
<input type="text" id="MSearchField" value="Search" accesskey="S"
onfocus="searchBox.OnSearchFieldFocus(true)"
onblur="searchBox.OnSearchFieldFocus(false)"
onkeyup="searchBox.OnSearchFieldChange(event)"/>
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
</div>
</li>
</ul>
</div>
</div>
<div class="contents">
<h1>COLLECTION interface</h1><table border="0" cellpadding="0" cellspacing="0">
<tr><td colspan="2"><h2>Data Structures</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">struct </td><td class="memItemRight" valign="bottom"><a class="el" href="structcollection__item.html">collection_item</a></td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Opaque structure that holds one property. <a href="structcollection__item.html#_details">More...</a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">struct </td><td class="memItemRight" valign="bottom"><a class="el" href="structcollection__iterator.html">collection_iterator</a></td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Opaque iterator structure. <a href="structcollection__iterator.html#_details">More...</a><br/></td></tr>
<tr><td colspan="2"><h2>Modules</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="group__coltypes.html">Type definition constants</a></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="group__addmodes.html">Constants defining add modes</a></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="group__traverseconst.html">Constants defining traverse modes</a></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="group__copyconst.html">Constants defining copy modes</a></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="group__sortconst.html">Constants defining sort order</a></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="group__addproperty.html">Add property functions</a></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="group__insertproperty.html">Insert property functions</a></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="group__updateproperty.html">Update property functions</a></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="group__getitem.html">Item management</a></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="group__iterfunc.html">Iterator interface</a></td></tr>
<tr><td colspan="2"><h2>Defines</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="anchor" id="ga5d9a4b4d7baefe4775fa9debc87fc11b"></a><!-- doxytag: member="collection::COL_CLASS_DEFAULT" ref="ga5d9a4b4d7baefe4775fa9debc87fc11b" args="" -->
#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__collection.html#ga5d9a4b4d7baefe4775fa9debc87fc11b">COL_CLASS_DEFAULT</a> 0</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Default class for a free form collection. <br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__collection.html#ga2865fc24b390b3bee5f2ad4d7e8e0652">COL_NOMATCH</a> 0</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Value indicates that property is not found. <a href="#ga2865fc24b390b3bee5f2ad4d7e8e0652"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__collection.html#ga448f7b47b8b38071151e423376bed04e">COL_MATCH</a> 1</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Value indicates that property is found. <a href="#ga448f7b47b8b38071151e423376bed04e"></a><br/></td></tr>
<tr><td colspan="2"><h2>Typedefs</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">typedef int(* </td><td class="memItemRight" valign="bottom"><a class="el" href="group__collection.html#ga41b6585d54932c2bcf2e0a66e81b399b">col_copy_cb</a> )(struct <a class="el" href="structcollection__item.html">collection_item</a> *item, void *ext_data, int *skip)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Copy item callback. <a href="#ga41b6585d54932c2bcf2e0a66e81b399b"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">typedef int(* </td><td class="memItemRight" valign="bottom"><a class="el" href="group__collection.html#ga4c948890067f648ca67a0966f8c2f207">col_item_fn</a> )(const char *property, int property_len, int type, void *data, int length, void *custom_dat, int *stop)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Search Callback. <a href="#ga4c948890067f648ca67a0966f8c2f207"></a><br/></td></tr>
<tr><td colspan="2"><h2>Functions</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__collection.html#ga0424c5ebb4d22459d84c54d3b1e75398">col_create_collection</a> (struct <a class="el" href="structcollection__item.html">collection_item</a> **ci, const char *name, unsigned cclass)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Create a collection. <a href="#ga0424c5ebb4d22459d84c54d3b1e75398"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="group__collection.html#gaff7d954b85cdbd5cce3db119d49a4ee3">col_destroy_collection</a> (struct <a class="el" href="structcollection__item.html">collection_item</a> *ci)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Destroy a collection. <a href="#gaff7d954b85cdbd5cce3db119d49a4ee3"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__collection.html#ga7fee94086cba10ded5f880cf402111ab">col_copy_collection_with_cb</a> (struct <a class="el" href="structcollection__item.html">collection_item</a> **col_copy, struct <a class="el" href="structcollection__item.html">collection_item</a> *col_to_copy, const char *name_to_use, int copy_mode, <a class="el" href="group__collection.html#ga41b6585d54932c2bcf2e0a66e81b399b">col_copy_cb</a> copy_cb, void *ext_data)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Copy collection with data modification. <a href="#ga7fee94086cba10ded5f880cf402111ab"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__collection.html#ga697b88b157620292cd86dd719cfad8bc">col_copy_collection</a> (struct <a class="el" href="structcollection__item.html">collection_item</a> **col_copy, struct <a class="el" href="structcollection__item.html">collection_item</a> *col_to_copy, const char *name_to_use, int copy_mode)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Copy collection without data modification. <a href="#ga697b88b157620292cd86dd719cfad8bc"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__collection.html#ga6de43f852bc7ffc39e810ccb12c4081b">col_add_collection_to_collection</a> (struct <a class="el" href="structcollection__item.html">collection_item</a> *ci, const char *subcollection, const char *as_property, struct <a class="el" href="structcollection__item.html">collection_item</a> *ci_to_add, int mode)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Add collection to collection. <a href="#ga6de43f852bc7ffc39e810ccb12c4081b"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__collection.html#ga06dfa8daeccb4820468833dd93cce387">col_traverse_collection</a> (struct <a class="el" href="structcollection__item.html">collection_item</a> *ci, int mode_flags, <a class="el" href="group__collection.html#ga4c948890067f648ca67a0966f8c2f207">col_item_fn</a> item_handler, void *custom_data)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Traverse collection. <a href="#ga06dfa8daeccb4820468833dd93cce387"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__collection.html#ga7eda0c854d3d85f6190d945c357e4055">col_get_item_and_do</a> (struct <a class="el" href="structcollection__item.html">collection_item</a> *ci, const char *property_to_find, int type, int mode_flags, <a class="el" href="group__collection.html#ga4c948890067f648ca67a0966f8c2f207">col_item_fn</a> item_handler, void *custom_data)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Search and do function. <a href="#ga7eda0c854d3d85f6190d945c357e4055"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__collection.html#gaca7cf872ff4092f06d300cfd6f32689f">col_get_item</a> (struct <a class="el" href="structcollection__item.html">collection_item</a> *ci, const char *property_to_find, int type, int mode_flags, struct <a class="el" href="structcollection__item.html">collection_item</a> **item)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Search function to get an item. <a href="#gaca7cf872ff4092f06d300cfd6f32689f"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__collection.html#gad709c29b6558c451c27ae04ab60a21ab">col_sort_collection</a> (struct <a class="el" href="structcollection__item.html">collection_item</a> *col, unsigned cmp_flags, unsigned sort_flags)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Sort collection. <a href="#gad709c29b6558c451c27ae04ab60a21ab"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__collection.html#ga5131d6b4f5e41cc3d63771452ef1d29b">col_delete_property</a> (struct <a class="el" href="structcollection__item.html">collection_item</a> *ci, const char *property_to_find, int type, int mode_flags)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Delete property. <a href="#ga5131d6b4f5e41cc3d63771452ef1d29b"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__collection.html#gaf48f62ad40e86acd2a9a168bf9ef83bc">col_is_item_in_collection</a> (struct <a class="el" href="structcollection__item.html">collection_item</a> *ci, const char *property_to_find, int type, int mode_flags, int *found)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Is property in the collection? <a href="#gaf48f62ad40e86acd2a9a168bf9ef83bc"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__collection.html#ga3ee62f91857cae73ba59c9ae3a976cb0">col_get_collection_reference</a> (struct <a class="el" href="structcollection__item.html">collection_item</a> *ci, struct <a class="el" href="structcollection__item.html">collection_item</a> **acceptor, const char *col_to_find)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Get a reference to a collection. <a href="#ga3ee62f91857cae73ba59c9ae3a976cb0"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__collection.html#ga3bc108d3494549ac1fc28990ba36095d">col_get_reference_from_item</a> (struct <a class="el" href="structcollection__item.html">collection_item</a> *item, struct <a class="el" href="structcollection__item.html">collection_item</a> **acceptor)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Get a reference from the item. <a href="#ga3bc108d3494549ac1fc28990ba36095d"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__collection.html#ga2db80d3e5569dcb0b80ff54553d84ffd">col_get_collection_class</a> (struct <a class="el" href="structcollection__item.html">collection_item</a> *ci, unsigned *cclass)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Get collection class. <a href="#ga2db80d3e5569dcb0b80ff54553d84ffd"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__collection.html#ga8ca7a1139fd2ff2e209e1d8f4a6e1c7c">col_set_collection_class</a> (struct <a class="el" href="structcollection__item.html">collection_item</a> *ci, unsigned cclass)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Set collection class. <a href="#ga8ca7a1139fd2ff2e209e1d8f4a6e1c7c"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__collection.html#ga285e0c6b882793d96ab43b04f16127d6">col_get_collection_count</a> (struct <a class="el" href="structcollection__item.html">collection_item</a> *ci, unsigned *count)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Get count of the elements. <a href="#ga285e0c6b882793d96ab43b04f16127d6"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__collection.html#ga9bd038169eefbc5b481afc568db41820">col_is_of_class</a> (struct <a class="el" href="structcollection__item.html">collection_item</a> *ci, unsigned cclass)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Check the class of collection. <a href="#ga9bd038169eefbc5b481afc568db41820"></a><br/></td></tr>
</table>
<hr/><h2>Define Documentation</h2>
<a class="anchor" id="ga448f7b47b8b38071151e423376bed04e"></a><!-- doxytag: member="collection.h::COL_MATCH" ref="ga448f7b47b8b38071151e423376bed04e" args="" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">#define COL_MATCH 1</td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Value indicates that property is found. </p>
<p>Used in search functions. </p>
</div>
</div>
<a class="anchor" id="ga2865fc24b390b3bee5f2ad4d7e8e0652"></a><!-- doxytag: member="collection.h::COL_NOMATCH" ref="ga2865fc24b390b3bee5f2ad4d7e8e0652" args="" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">#define COL_NOMATCH 0</td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Value indicates that property is not found. </p>
<p>Used in search functions. </p>
</div>
</div>
<hr/><h2>Typedef Documentation</h2>
<a class="anchor" id="ga41b6585d54932c2bcf2e0a66e81b399b"></a><!-- doxytag: member="collection.h::col_copy_cb" ref="ga41b6585d54932c2bcf2e0a66e81b399b" args=")(struct collection_item *item, void *ext_data, int *skip)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">typedef int(* <a class="el" href="group__collection.html#ga41b6585d54932c2bcf2e0a66e81b399b">col_copy_cb</a>)(struct <a class="el" href="structcollection__item.html">collection_item</a> *item, void *ext_data, int *skip)</td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Copy item callback. </p>
<p>Callback is used by the <a class="el" href="group__collection.html#ga7fee94086cba10ded5f880cf402111ab">col_copy_collection_with_cb</a> 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.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>item</em> </td><td>Newly allocated item that will be inserted into the new collection. </td></tr>
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>ext_data</em> </td><td>Data the application might want to pass to the callback. </td></tr>
<tr><td valign="top"><tt>[out]</tt> </td><td valign="top"><em>skip</em> </td><td>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. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 - Success </dd>
<dd>
Function can return any error code. This code will be propagated through the internal functions and returned to the application. </dd></dl>
</div>
</div>
<a class="anchor" id="ga4c948890067f648ca67a0966f8c2f207"></a><!-- doxytag: member="collection.h::col_item_fn" ref="ga4c948890067f648ca67a0966f8c2f207" args=")(const char *property, int property_len, int type, void *data, int length, void *custom_dat, int *stop)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">typedef int(* <a class="el" href="group__collection.html#ga4c948890067f648ca67a0966f8c2f207">col_item_fn</a>)(const char *property, int property_len, int type, void *data, int length, void *custom_dat, int *stop)</td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Search Callback. </p>
<p>Signature of the callback that needs to be used when traversing a collection or looking for a specific item.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>property</em> </td><td>The name of the property will be passed in this parameter. </td></tr>
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>property_len</em> </td><td>Length of the property name will be passed in this parameter. </td></tr>
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>type</em> </td><td>Type of the data will be passed in this parameter. </td></tr>
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>data</em> </td><td>Pointer to the data will be passed in this parameter. </td></tr>
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>length</em> </td><td>Length of data will be passed in this parameter. </td></tr>
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>custom_dat</em> </td><td>Custom data will be passed in this parameter. </td></tr>
<tr><td valign="top"><tt>[out]</tt> </td><td valign="top"><em>stop</em> </td><td>Pointer to a variable where the handler can put nonzero to stop traversing of the collection. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 - Success </dd>
<dd>
Function can return any error code. This code will be propagated through the internal functions and returned to the application. </dd></dl>
</div>
</div>
<hr/><h2>Function Documentation</h2>
<a class="anchor" id="ga6de43f852bc7ffc39e810ccb12c4081b"></a><!-- doxytag: member="collection.h::col_add_collection_to_collection" ref="ga6de43f852bc7ffc39e810ccb12c4081b" args="(struct collection_item *ci, const char *subcollection, const char *as_property, struct collection_item *ci_to_add, int mode)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int col_add_collection_to_collection </td>
<td>(</td>
<td class="paramtype">struct <a class="el" href="structcollection__item.html">collection_item</a> * </td>
<td class="paramname"> <em>ci</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"> <em>subcollection</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"> <em>as_property</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">struct <a class="el" href="structcollection__item.html">collection_item</a> * </td>
<td class="paramname"> <em>ci_to_add</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"> <em>mode</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Add collection to collection. </p>
<p>Function adds one collection into another depending upon a specified <a class="el" href="group__addmodes.html">mode</a>.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>ci</em> </td><td>Root collection object. </td></tr>
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>subcollection</em> </td><td>Name of the inner collection to add collection to. If NULL the collection is added to the root collection. </td></tr>
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>as_property</em> </td><td>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 <a class="el" href="group__addproperty.html">col_add_xxx_property</a> functions. </td></tr>
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>ci_to_add</em> </td><td>Collection to add. </td></tr>
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>mode</em> </td><td>Specifies <a class="el" href="group__addmodes.html">how</a> the collection should be added.</td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 - Collection was added successfully. </dd>
<dd>
ENOMEM - No memory. </dd>
<dd>
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. </dd>
<dd>
ENOENT - Property to update is not found. </dd></dl>
</div>
</div>
<a class="anchor" id="ga697b88b157620292cd86dd719cfad8bc"></a><!-- doxytag: member="collection.h::col_copy_collection" ref="ga697b88b157620292cd86dd719cfad8bc" args="(struct collection_item **col_copy, struct collection_item *col_to_copy, const char *name_to_use, int copy_mode)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int col_copy_collection </td>
<td>(</td>
<td class="paramtype">struct <a class="el" href="structcollection__item.html">collection_item</a> ** </td>
<td class="paramname"> <em>col_copy</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">struct <a class="el" href="structcollection__item.html">collection_item</a> * </td>
<td class="paramname"> <em>col_to_copy</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"> <em>name_to_use</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"> <em>copy_mode</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Copy collection without data modification. </p>
<p>Function creates a deep copy of the current collection. It wraps the <a class="el" href="group__collection.html#ga7fee94086cba10ded5f880cf402111ab">col_copy_collection_with_cb</a> function. The acceptable modes are defined <a class="el" href="group__copyconst.html">here</a>.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"><tt>[out]</tt> </td><td valign="top"><em>col_copy</em> </td><td>Newly created collection object. </td></tr>
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>col_to_copy</em> </td><td>Collection object that will be copied. </td></tr>
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>name_to_use</em> </td><td>Name of the new collection. </td></tr>
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>copy_mode</em> </td><td>How to <a class="el" href="group__copyconst.html">copy</a>.</td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 - Collection was copied successfully. </dd>
<dd>
ENOMEM - No memory. </dd>
<dd>
EINVAL - The value of some of the arguments is invalid. </dd></dl>
</div>
</div>
<a class="anchor" id="ga7fee94086cba10ded5f880cf402111ab"></a><!-- doxytag: member="collection.h::col_copy_collection_with_cb" ref="ga7fee94086cba10ded5f880cf402111ab" args="(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)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int col_copy_collection_with_cb </td>
<td>(</td>
<td class="paramtype">struct <a class="el" href="structcollection__item.html">collection_item</a> ** </td>
<td class="paramname"> <em>col_copy</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">struct <a class="el" href="structcollection__item.html">collection_item</a> * </td>
<td class="paramname"> <em>col_to_copy</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"> <em>name_to_use</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"> <em>copy_mode</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="group__collection.html#ga41b6585d54932c2bcf2e0a66e81b399b">col_copy_cb</a> </td>
<td class="paramname"> <em>copy_cb</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">void * </td>
<td class="paramname"> <em>ext_data</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Copy collection with data modification. </p>
<p>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 <a class="el" href="group__copyconst.html">here</a>.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"><tt>[out]</tt> </td><td valign="top"><em>col_copy</em> </td><td>Newly created collection object. </td></tr>
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>col_to_copy</em> </td><td>Collection object that will be copied. </td></tr>
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>name_to_use</em> </td><td>Name of the new collection. </td></tr>
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>copy_mode</em> </td><td>How to <a class="el" href="group__copyconst.html">copy</a>. </td></tr>
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>copy_cb</em> </td><td>Pointer to a callback <a class="el" href="group__collection.html#ga41b6585d54932c2bcf2e0a66e81b399b">col_copy_cb</a>. Can be NULL. In this case data is copied without modification. </td></tr>
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>ext_data</em> </td><td>Data the application might want to pass to the callback.</td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 - Collection was copied successfully. </dd>
<dd>
ENOMEM - No memory. </dd>
<dd>
EINVAL - The value of some of the arguments is invalid. </dd>
<dd>
Any error code returned by the callback. </dd></dl>
</div>
</div>
<a class="anchor" id="ga0424c5ebb4d22459d84c54d3b1e75398"></a><!-- doxytag: member="collection.h::col_create_collection" ref="ga0424c5ebb4d22459d84c54d3b1e75398" args="(struct collection_item **ci, const char *name, unsigned cclass)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int col_create_collection </td>
<td>(</td>
<td class="paramtype">struct <a class="el" href="structcollection__item.html">collection_item</a> ** </td>
<td class="paramname"> <em>ci</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"> <em>name</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">unsigned </td>
<td class="paramname"> <em>cclass</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Create a collection. </p>
<p>The function will create a collection. Each collection should have name and class.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"><tt>[out]</tt> </td><td valign="top"><em>ci</em> </td><td>Newly allocated collection object. </td></tr>
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>name</em> </td><td>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.<br/>
Maximum allowed length is defined at compile time. The default value is 64k. </td></tr>
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>cclass</em> </td><td>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.<br/>
<b>NOTE:</b> 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.</td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 - Collection was created successfully. </dd>
<dd>
ENOMEM - No memory. </dd>
<dd>
EINVAL - Invalid characters in the collection name. </dd>
<dd>
EMSGSIZE - Collection name is too long. </dd></dl>
</div>
</div>
<a class="anchor" id="ga5131d6b4f5e41cc3d63771452ef1d29b"></a><!-- doxytag: member="collection.h::col_delete_property" ref="ga5131d6b4f5e41cc3d63771452ef1d29b" args="(struct collection_item *ci, const char *property_to_find, int type, int mode_flags)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int col_delete_property </td>
<td>(</td>
<td class="paramtype">struct <a class="el" href="structcollection__item.html">collection_item</a> * </td>
<td class="paramname"> <em>ci</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"> <em>property_to_find</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"> <em>type</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"> <em>mode_flags</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Delete property. </p>
<p>Delete property from the collection. It is recommended to use a more efficient function <a class="el" href="group__getitem.html#ga771d46d58ced79e7cd4804b5c01f7971">col_remove_item</a> 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".</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>ci</em> </td><td>Collection to delete property from. </td></tr>
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>property_to_find</em> </td><td>Property to delete. </td></tr>
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>type</em> </td><td>Use type if names are not unique and you know the type of the value you want to delete. Otherwise set to 0. </td></tr>
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>mode_flags</em> </td><td>The flags define how the collection should be searched. For more information see <a class="el" href="group__traverseconst.html">traverse constants</a>.</td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 - Property was deleted successfully. </dd>
<dd>
EINVAL - The value of some of the arguments is invalid. </dd>
<dd>
ENOMEM - No memory. </dd>
<dd>
ENOENT - Property not found. </dd></dl>
</div>
</div>
<a class="anchor" id="gaff7d954b85cdbd5cce3db119d49a4ee3"></a><!-- doxytag: member="collection.h::col_destroy_collection" ref="gaff7d954b85cdbd5cce3db119d49a4ee3" args="(struct collection_item *ci)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void col_destroy_collection </td>
<td>(</td>
<td class="paramtype">struct <a class="el" href="structcollection__item.html">collection_item</a> * </td>
<td class="paramname"> <em>ci</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Destroy a collection. </p>
<p>The function will destroy a collection.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>ci</em> </td><td>Collection object. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a class="anchor" id="ga2db80d3e5569dcb0b80ff54553d84ffd"></a><!-- doxytag: member="collection.h::col_get_collection_class" ref="ga2db80d3e5569dcb0b80ff54553d84ffd" args="(struct collection_item *ci, unsigned *cclass)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int col_get_collection_class </td>
<td>(</td>
<td class="paramtype">struct <a class="el" href="structcollection__item.html">collection_item</a> * </td>
<td class="paramname"> <em>ci</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">unsigned * </td>
<td class="paramname"> <em>cclass</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Get collection class. </p>
<p>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.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>ci</em> </td><td>Collection object. </td></tr>
<tr><td valign="top"><tt>[out]</tt> </td><td valign="top"><em>cclass</em> </td><td>Variable that will receive the value of the class. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 - Success. </dd>
<dd>
EINVAL - The value of some of the arguments is invalid. </dd></dl>
</div>
</div>
<a class="anchor" id="ga285e0c6b882793d96ab43b04f16127d6"></a><!-- doxytag: member="collection.h::col_get_collection_count" ref="ga285e0c6b882793d96ab43b04f16127d6" args="(struct collection_item *ci, unsigned *count)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int col_get_collection_count </td>
<td>(</td>
<td class="paramtype">struct <a class="el" href="structcollection__item.html">collection_item</a> * </td>
<td class="paramname"> <em>ci</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">unsigned * </td>
<td class="paramname"> <em>count</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Get count of the elements. </p>
<p>It is useful to know how many items are there in the collection.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>ci</em> </td><td>Collection object. </td></tr>
<tr><td valign="top"><tt>[out]</tt> </td><td valign="top"><em>count</em> </td><td>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.</td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 - Success. </dd>
<dd>
EINVAL - The value of some of the arguments is invalid. </dd></dl>
</div>
</div>
<a class="anchor" id="ga3ee62f91857cae73ba59c9ae3a976cb0"></a><!-- doxytag: member="collection.h::col_get_collection_reference" ref="ga3ee62f91857cae73ba59c9ae3a976cb0" args="(struct collection_item *ci, struct collection_item **acceptor, const char *col_to_find)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int col_get_collection_reference </td>
<td>(</td>
<td class="paramtype">struct <a class="el" href="structcollection__item.html">collection_item</a> * </td>
<td class="paramname"> <em>ci</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">struct <a class="el" href="structcollection__item.html">collection_item</a> ** </td>
<td class="paramname"> <em>acceptor</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"> <em>col_to_find</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Get a reference to a collection. </p>
<p>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.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>ci</em> </td><td>Collection to search. </td></tr>
<tr><td valign="top"><tt>[out]</tt> </td><td valign="top"><em>acceptor</em> </td><td>Variable that accepts pointer to an extracted collection. Use <a class="el" href="group__collection.html#gaff7d954b85cdbd5cce3db119d49a4ee3">col_destroy_collection</a> to free returned object reference after use. </td></tr>
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>col_to_find</em> </td><td>Collection to find. "foo!bar!baz" notation can be used.</td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 - Success. </dd>
<dd>
EINVAL - The value of some of the arguments is invalid. </dd>
<dd>
ENOMEM - No memory. </dd></dl>
</div>
</div>
<a class="anchor" id="gaca7cf872ff4092f06d300cfd6f32689f"></a><!-- doxytag: member="collection.h::col_get_item" ref="gaca7cf872ff4092f06d300cfd6f32689f" args="(struct collection_item *ci, const char *property_to_find, int type, int mode_flags, struct collection_item **item)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int col_get_item </td>
<td>(</td>
<td class="paramtype">struct <a class="el" href="structcollection__item.html">collection_item</a> * </td>
<td class="paramname"> <em>ci</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"> <em>property_to_find</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"> <em>type</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"> <em>mode_flags</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">struct <a class="el" href="structcollection__item.html">collection_item</a> ** </td>
<td class="paramname"> <em>item</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Search function to get an item. </p>
<p>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 <a class="el" href="group__collection.html#ga7eda0c854d3d85f6190d945c357e4055">col_get_item_and_do</a> function.</p>
<p>Use <a class="el" href="group__getitem.html">item management</a> functions to work with the item.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>ci</em> </td><td>Collection object to traverse. </td></tr>
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>property_to_find</em> </td><td>Name of the property to find. Parameter supports "x!y" notation. </td></tr>
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>type</em> </td><td>Type filter. Only properties of the given type will match. Can be 0 to indicate that all types should be evaluated. </td></tr>
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>mode_flags</em> </td><td>How to traverse the collection. See details <a class="el" href="group__traverseconst.html">here</a>. </td></tr>
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>item</em> </td><td>Pointer to found item or NULL if item is not found.</td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 - No internal errors during search. </dd>
<dd>
EINVAL - The value of some of the arguments is invalid. </dd>
<dd>
ENOENT - The search criteria is incorrect. </dd>
<dd>
ENOMEM - No memory. </dd></dl>
</div>
</div>
<a class="anchor" id="ga7eda0c854d3d85f6190d945c357e4055"></a><!-- doxytag: member="collection.h::col_get_item_and_do" ref="ga7eda0c854d3d85f6190d945c357e4055" args="(struct collection_item *ci, const char *property_to_find, int type, int mode_flags, col_item_fn item_handler, void *custom_data)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int col_get_item_and_do </td>
<td>(</td>
<td class="paramtype">struct <a class="el" href="structcollection__item.html">collection_item</a> * </td>
<td class="paramname"> <em>ci</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"> <em>property_to_find</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"> <em>type</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"> <em>mode_flags</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="group__collection.html#ga4c948890067f648ca67a0966f8c2f207">col_item_fn</a> </td>
<td class="paramname"> <em>item_handler</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">void * </td>
<td class="paramname"> <em>custom_data</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Search and do function. </p>
<p>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.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>ci</em> </td><td>Collection object to traverse. </td></tr>
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>property_to_find</em> </td><td>Name of the property to find. Parameter supports "x!y" notation. </td></tr>
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>type</em> </td><td>Type filter. Only properties of the given type will match. Can be 0 to indicate that all types should be evaluated. </td></tr>
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>mode_flags</em> </td><td>How to traverse the collection. See details <a class="el" href="group__traverseconst.html">here</a>. </td></tr>
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>item_handler</em> </td><td>Function to call when the item is found. </td></tr>
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>custom_data</em> </td><td>Custom data passed to the callback.</td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 - Operation completed successfully. </dd>
<dd>
EINVAL - The value of some of the arguments is invalid. </dd>
<dd>
ENOENT - The search criteria is incorrect. </dd>
<dd>
ENOMEM - No memory. </dd>
<dd>
Any error code returned by the callback. </dd></dl>
</div>
</div>
<a class="anchor" id="ga3bc108d3494549ac1fc28990ba36095d"></a><!-- doxytag: member="collection.h::col_get_reference_from_item" ref="ga3bc108d3494549ac1fc28990ba36095d" args="(struct collection_item *item, struct collection_item **acceptor)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int col_get_reference_from_item </td>
<td>(</td>
<td class="paramtype">struct <a class="el" href="structcollection__item.html">collection_item</a> * </td>
<td class="paramname"> <em>item</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">struct <a class="el" href="structcollection__item.html">collection_item</a> ** </td>
<td class="paramname"> <em>acceptor</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Get a reference from the item. </p>
<p>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.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>item</em> </td><td>Item to extract the reference from. </td></tr>
<tr><td valign="top"><tt>[out]</tt> </td><td valign="top"><em>acceptor</em> </td><td>Variable that accepts pointer to an extracted collection. Use <a class="el" href="group__collection.html#gaff7d954b85cdbd5cce3db119d49a4ee3">col_destroy_collection</a> to free returned object reference after use.</td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 - Success. </dd>
<dd>
EINVAL - The value of some of the arguments is invalid. </dd></dl>
</div>
</div>
<a class="anchor" id="gaf48f62ad40e86acd2a9a168bf9ef83bc"></a><!-- doxytag: member="collection.h::col_is_item_in_collection" ref="gaf48f62ad40e86acd2a9a168bf9ef83bc" args="(struct collection_item *ci, const char *property_to_find, int type, int mode_flags, int *found)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int col_is_item_in_collection </td>
<td>(</td>
<td class="paramtype">struct <a class="el" href="structcollection__item.html">collection_item</a> * </td>
<td class="paramname"> <em>ci</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"> <em>property_to_find</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"> <em>type</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"> <em>mode_flags</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int * </td>
<td class="paramname"> <em>found</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Is property in the collection? </p>
<p>Convenience function to check if the property is indeed in the collection.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>ci</em> </td><td>Collection to search. </td></tr>
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>property_to_find</em> </td><td>Property to find. </td></tr>
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>type</em> </td><td>Use type if names are not unique and you know the type of the value you want to check. Otherwise set to 0. </td></tr>
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>mode_flags</em> </td><td>The flags define how the collection should be searched. For more information see <a class="el" href="group__traverseconst.html">traverse constants</a>. </td></tr>
<tr><td valign="top"><tt>[out]</tt> </td><td valign="top"><em>found</em> </td><td>The variable that will receive the result of the search. COL_NOMATCH - if not found COL_MATCH if found</td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 - Search completed successfully. </dd>
<dd>
EINVAL - The value of some of the arguments is invalid. </dd>
<dd>
ENOMEM - No memory. </dd></dl>
</div>
</div>
<a class="anchor" id="ga9bd038169eefbc5b481afc568db41820"></a><!-- doxytag: member="collection.h::col_is_of_class" ref="ga9bd038169eefbc5b481afc568db41820" args="(struct collection_item *ci, unsigned cclass)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int col_is_of_class </td>
<td>(</td>
<td class="paramtype">struct <a class="el" href="structcollection__item.html">collection_item</a> * </td>
<td class="paramname"> <em>ci</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">unsigned </td>
<td class="paramname"> <em>cclass</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Check the class of collection. </p>
<p>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.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>ci</em> </td><td>Collection object. </td></tr>
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>cclass</em> </td><td>Class value to compare to to.</td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 - If any internal error or classes do not match. </dd>
<dd>
1 - No error and classes do match. </dd></dl>
</div>
</div>
<a class="anchor" id="ga8ca7a1139fd2ff2e209e1d8f4a6e1c7c"></a><!-- doxytag: member="collection.h::col_set_collection_class" ref="ga8ca7a1139fd2ff2e209e1d8f4a6e1c7c" args="(struct collection_item *ci, unsigned cclass)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int col_set_collection_class </td>
<td>(</td>
<td class="paramtype">struct <a class="el" href="structcollection__item.html">collection_item</a> * </td>
<td class="paramname"> <em>ci</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">unsigned </td>
<td class="paramname"> <em>cclass</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Set collection class. </p>
<p>Sometimes as a result of the collection modification the class of the collection can change.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>ci</em> </td><td>Collection object. </td></tr>
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>cclass</em> </td><td>New class value.</td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 - Success. </dd>
<dd>
EINVAL - The value of some of the arguments is invalid. </dd></dl>
</div>
</div>
<a class="anchor" id="gad709c29b6558c451c27ae04ab60a21ab"></a><!-- doxytag: member="collection.h::col_sort_collection" ref="gad709c29b6558c451c27ae04ab60a21ab" args="(struct collection_item *col, unsigned cmp_flags, unsigned sort_flags)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int col_sort_collection </td>
<td>(</td>
<td class="paramtype">struct <a class="el" href="structcollection__item.html">collection_item</a> * </td>
<td class="paramname"> <em>col</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">unsigned </td>
<td class="paramname"> <em>cmp_flags</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">unsigned </td>
<td class="paramname"> <em>sort_flags</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Sort collection. </p>
<p>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 <a class="el" href="group__sortconst.html#gac52bef3d16eb7c7370f0d0e20beed811">COL_SORT_MYSUB</a> 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.</p>
<p>NOTE: Current implementation of the sorting function is very simple and alternative implementations might be provided later.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>col</em> </td><td>Collection to sort. </td></tr>
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>cmp_flags</em> </td><td>For more information see <a class="el" href="group__compflags.html">comparison flags</a>. </td></tr>
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>sort_flags</em> </td><td>For more information see <a class="el" href="group__sortconst.html">sort flags</a>.</td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 - No internal errors during sorting. </dd>
<dd>
EINVAL - The value of some of the arguments is invalid. </dd></dl>
</div>
</div>
<a class="anchor" id="ga06dfa8daeccb4820468833dd93cce387"></a><!-- doxytag: member="collection.h::col_traverse_collection" ref="ga06dfa8daeccb4820468833dd93cce387" args="(struct collection_item *ci, int mode_flags, col_item_fn item_handler, void *custom_data)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int col_traverse_collection </td>
<td>(</td>
<td class="paramtype">struct <a class="el" href="structcollection__item.html">collection_item</a> * </td>
<td class="paramname"> <em>ci</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"> <em>mode_flags</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="group__collection.html#ga4c948890067f648ca67a0966f8c2f207">col_item_fn</a> </td>
<td class="paramname"> <em>item_handler</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">void * </td>
<td class="paramname"> <em>custom_data</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Traverse collection. </p>
<p>Function to traverse the entire collection including (optionally) sub collections.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>ci</em> </td><td>Collection object to traverse. </td></tr>
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>mode_flags</em> </td><td>How to traverse. See details <a class="el" href="group__traverseconst.html">here</a>. </td></tr>
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>item_handler</em> </td><td>Application supplied callback. It will be called for each item in the collection including headers. </td></tr>
<tr><td valign="top"><tt>[in]</tt> </td><td valign="top"><em>custom_data</em> </td><td>Custom data that application might want to pass to the callback.</td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 - Collection was traversed successfully. </dd>
<dd>
ENOMEM - No memory. </dd>
<dd>
EINVAL - The value of some of the arguments is invalid. </dd>
<dd>
Any error code returned by the callback. </dd></dl>
</div>
</div>
</div>
<!--- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark"> </span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark"> </span>Data Structures</a></div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<hr size="1"/><address style="text-align: right;"><small>Generated on 25 Jun 2011 for libcollection by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.6.1 </small></address>
</body>
</html>
distrib
>
CentOS
>
6
>
i386
>
media
>
updates
>
by-pkgid
>
5d98b2995a46d456a9243853c7259619
>
files
>
21
