<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<refentry id="EphyNodeDb">
<refmeta>
<refentrytitle role="top_of_page" id="EphyNodeDb.top_of_page">EphyNodeDb</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>EPIPHANY Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>EphyNodeDb</refname>
<refpurpose>Data tree</refpurpose>
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>

<refsynopsisdiv id="EphyNodeDb.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>
                    <link linkend="EphyNodeDb-struct">EphyNodeDb</link>;
<link linkend="EphyNodeDb">EphyNodeDb</link>*         <link linkend="ephy-node-db-new">ephy_node_db_new</link>                    (const <link linkend="char">char</link> *name);
<link linkend="gboolean">gboolean</link>            <link linkend="ephy-node-db-load-from-file">ephy_node_db_load_from_file</link>         (<link linkend="EphyNodeDb">EphyNodeDb</link> *db,
                                                         const <link linkend="char">char</link> *xml_file,
                                                         const <link linkend="xmlChar">xmlChar</link> *xml_root,
                                                         const <link linkend="xmlChar">xmlChar</link> *xml_version);
<link linkend="int">int</link>                 <link linkend="ephy-node-db-write-to-xml-safe">ephy_node_db_write_to_xml_safe</link>      (<link linkend="EphyNodeDb">EphyNodeDb</link> *db,
                                                         const <link linkend="xmlChar">xmlChar</link> *filename,
                                                         const <link linkend="xmlChar">xmlChar</link> *root,
                                                         const <link linkend="xmlChar">xmlChar</link> *version,
                                                         const <link linkend="xmlChar">xmlChar</link> *comment,
                                                         <link linkend="EphyNode">EphyNode</link> *node,
                                                         ...);
const <link linkend="char">char</link>*         <link linkend="ephy-node-db-get-name">ephy_node_db_get_name</link>               (<link linkend="EphyNodeDb">EphyNodeDb</link> *db);
<link linkend="gboolean">gboolean</link>            <link linkend="ephy-node-db-is-immutable">ephy_node_db_is_immutable</link>           (<link linkend="EphyNodeDb">EphyNodeDb</link> *db);
<link linkend="void">void</link>                <link linkend="ephy-node-db-set-immutable">ephy_node_db_set_immutable</link>          (<link linkend="EphyNodeDb">EphyNodeDb</link> *db,
                                                         <link linkend="gboolean">gboolean</link> immutable);
<link linkend="EphyNode">EphyNode</link>*           <link linkend="ephy-node-db-get-node-from-id">ephy_node_db_get_node_from_id</link>       (<link linkend="EphyNodeDb">EphyNodeDb</link> *db,
                                                         <link linkend="guint">guint</link> id);
</synopsis>
</refsynopsisdiv>

<refsect1 id="EphyNodeDb.object-hierarchy" role="object_hierarchy">
<title role="object_hierarchy.title">Object Hierarchy</title>
<synopsis>
  <link linkend="GObject">GObject</link>
   +----EphyNodeDb
</synopsis>

</refsect1>





<refsect1 id="EphyNodeDb.properties" role="properties">
<title role="properties.title">Properties</title>
<synopsis>
  &quot;<link linkend="EphyNodeDb--immutable">immutable</link>&quot;                <link linkend="gboolean">gboolean</link>              : Read / Write
  &quot;<link linkend="EphyNodeDb--name">name</link>&quot;                     <link linkend="gchar">gchar</link>*                : Read / Write / Construct Only
</synopsis>
</refsect1>



<refsect1 id="EphyNodeDb.description" role="desc">
<title role="desc.title">Description</title>
<para>
An <link linkend="EphyNodeDb"><type>EphyNodeDb</type></link> is a database for arbitrary data organized in a tree.
</para>
<para>
Each database is stored along with its name in a global set of databases.
Databases can be created using <link linkend="ephy-node-db-new"><function>ephy_node_db_new()</function></link> and retrieved using
<link linkend="ephy-node-db-get-by-name"><function>ephy_node_db_get_by_name()</function></link>.
</para>
<para>
Each <link linkend="EphyNode"><type>EphyNode</type></link> inside an <link linkend="EphyNodeDb"><type>EphyNodeDb</type></link> is identified by a unique node ID. By
keeping a handle on the ID, one can use <link linkend="ephy-node-db-get-node-from-id"><function>ephy_node_db_get_node_from_id()</function></link> to
retrieve its corresponding <link linkend="EphyNode"><type>EphyNode</type></link>.
</para>
<para>
<link linkend="EphyNodeDb"><type>EphyNodeDb</type></link><!-- -->s can be saved to disk using <link linkend="ephy-node-db-write-to-xml-safe"><function>ephy_node_db_write_to_xml_safe()</function></link>
and restored using <link linkend="ephy-node-db-load-from-file"><function>ephy_node_db_load_from_file()</function></link>.
</para>
</refsect1>

<refsect1 id="EphyNodeDb.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="EphyNodeDb-struct" role="struct">
<title>EphyNodeDb</title>
<indexterm zone="EphyNodeDb-struct"><primary>EphyNodeDb</primary></indexterm><programlisting>typedef struct _EphyNodeDb EphyNodeDb;</programlisting>
<para>

</para></refsect2>
<refsect2 id="ephy-node-db-new" role="function">
<title>ephy_node_db_new ()</title>
<indexterm zone="ephy-node-db-new"><primary>ephy_node_db_new</primary></indexterm><programlisting><link linkend="EphyNodeDb">EphyNodeDb</link>*         ephy_node_db_new                    (const <link linkend="char">char</link> *name);</programlisting>
<para>
Creates and returns a new <link linkend="EphyNodeDb"><type>EphyNodeDb</type></link>, named <parameter>name</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>name</parameter>&nbsp;:</term>
<listitem><simpara> the name of the new <link linkend="EphyNodeDb"><type>EphyNodeDb</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the new <link linkend="EphyNodeDb"><type>EphyNodeDb</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="ephy-node-db-load-from-file" role="function">
<title>ephy_node_db_load_from_file ()</title>
<indexterm zone="ephy-node-db-load-from-file"><primary>ephy_node_db_load_from_file</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            ephy_node_db_load_from_file         (<link linkend="EphyNodeDb">EphyNodeDb</link> *db,
                                                         const <link linkend="char">char</link> *xml_file,
                                                         const <link linkend="xmlChar">xmlChar</link> *xml_root,
                                                         const <link linkend="xmlChar">xmlChar</link> *xml_version);</programlisting>
<para>
Populates <parameter>db</parameter> with data from <parameter>xml_file</parameter>. The node database will be populated
with everything inside of the <parameter>xml_root</parameter> tag from <parameter>xml_file</parameter>. If <parameter>xml_version</parameter>
is different from the version attribute of the <parameter>xml_root</parameter> element, this
function will fail.
</para>
<para>
The data will most probably have been stored using
<link linkend="ephy-node-db-write-to-xml-safe"><function>ephy_node_db_write_to_xml_safe()</function></link>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>db</parameter>&nbsp;:</term>
<listitem><simpara> a new <link linkend="EphyNodeDb"><type>EphyNodeDb</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>xml_file</parameter>&nbsp;:</term>
<listitem><simpara> the filename from which <parameter>db</parameter> will be populated
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>xml_root</parameter>&nbsp;:</term>
<listitem><simpara> the root element in <parameter>xml_file</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>xml_version</parameter>&nbsp;:</term>
<listitem><simpara> the required version attribute in the <parameter>xml_root</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if successful
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="ephy-node-db-write-to-xml-safe" role="function">
<title>ephy_node_db_write_to_xml_safe ()</title>
<indexterm zone="ephy-node-db-write-to-xml-safe"><primary>ephy_node_db_write_to_xml_safe</primary></indexterm><programlisting><link linkend="int">int</link>                 ephy_node_db_write_to_xml_safe      (<link linkend="EphyNodeDb">EphyNodeDb</link> *db,
                                                         const <link linkend="xmlChar">xmlChar</link> *filename,
                                                         const <link linkend="xmlChar">xmlChar</link> *root,
                                                         const <link linkend="xmlChar">xmlChar</link> *version,
                                                         const <link linkend="xmlChar">xmlChar</link> *comment,
                                                         <link linkend="EphyNode">EphyNode</link> *node,
                                                         ...);</programlisting>
<para>
Writes <parameter>db</parameter>'s data to an XML file for storage. The data can be retrieved in
the future using <link linkend="ephy-node-db-load-from-file"><function>ephy_node_db_load_from_file()</function></link>.
</para>
<para>
The function arguments are straightforward until <parameter>node</parameter>, at which point some
explanation is necessary.
</para>
<para>
The variable argument list starts at <parameter>node</parameter>, which is an <link linkend="EphyNode"><type>EphyNode</type></link> containing
data to write to <parameter>filename</parameter>. The next argument is an integer specifying the
number of <quote>exception</quote> nodes. After this integer, that number of
<link linkend="EphyNode"><type>EphyNode</type></link> arguments should be given. Each of these <quote>exception</quote>
nodes determines which data out of <parameter>node</parameter> will <emphasis>not</emphasis> be
written to <parameter>filename</parameter>.
</para>
<para>
To insert all of an <link linkend="EphyNode"><type>EphyNode</type></link>'s contents without exception, simply give the
integer <link linkend="0:CAPS"><literal>0</literal></link> after <parameter>node</parameter>.
</para>
<para>
The remainder of this function's arguments will be groups of such <link linkend="EphyNode"><type>EphyNode</type></link> -
integer - (list of <link linkend="EphyNode"><type>EphyNode</type></link><!-- -->s). Finally, the last argument must be
<link linkend="NULL:CAPS"><literal>NULL</literal></link>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>db</parameter>&nbsp;:</term>
<listitem><simpara> an <link linkend="EphyNodeDb"><type>EphyNodeDb</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>filename</parameter>&nbsp;:</term>
<listitem><simpara> the XML file in which <parameter>db</parameter>'s data will be stored
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>root</parameter>&nbsp;:</term>
<listitem><simpara> the desired root element in <parameter>filename</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>version</parameter>&nbsp;:</term>
<listitem><simpara> the version attribute to the <parameter>root</parameter> element
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>comment</parameter>&nbsp;:</term>
<listitem><simpara> a comment to place directly inside the <parameter>root</parameter> element of <parameter>filename</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>node</parameter>&nbsp;:</term>
<listitem><simpara> The first node of data to write
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&nbsp;:</term>
<listitem><simpara> number of exceptions, list of their <link linkend="EphyNodes"><type>EphyNodes</type></link>, and more such
	     sequences, followed by <link linkend="NULL:CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <link linkend="0:CAPS"><literal>0</literal></link> on success or a negative number on failure
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="ephy-node-db-get-name" role="function">
<title>ephy_node_db_get_name ()</title>
<indexterm zone="ephy-node-db-get-name"><primary>ephy_node_db_get_name</primary></indexterm><programlisting>const <link linkend="char">char</link>*         ephy_node_db_get_name               (<link linkend="EphyNodeDb">EphyNodeDb</link> *db);</programlisting>
<para>
</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>db</parameter>&nbsp;:</term>
<listitem><simpara> an <link linkend="EphyNodeDb"><type>EphyNodeDb</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the name of <parameter>db</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="ephy-node-db-is-immutable" role="function">
<title>ephy_node_db_is_immutable ()</title>
<indexterm zone="ephy-node-db-is-immutable"><primary>ephy_node_db_is_immutable</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            ephy_node_db_is_immutable           (<link linkend="EphyNodeDb">EphyNodeDb</link> *db);</programlisting>
<para>
</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>db</parameter>&nbsp;:</term>
<listitem><simpara> an <link linkend="EphyNodeDb"><type>EphyNodeDb</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <parameter>db</parameter> is immutable
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="ephy-node-db-set-immutable" role="function">
<title>ephy_node_db_set_immutable ()</title>
<indexterm zone="ephy-node-db-set-immutable"><primary>ephy_node_db_set_immutable</primary></indexterm><programlisting><link linkend="void">void</link>                ephy_node_db_set_immutable          (<link linkend="EphyNodeDb">EphyNodeDb</link> *db,
                                                         <link linkend="gboolean">gboolean</link> immutable);</programlisting>
<para>
If <parameter>immutable</parameter> is <link linkend="TRUE:CAPS"><literal>TRUE</literal></link>, sets <parameter>db</parameter> immutable (read-only). Otherwise, sets <parameter>db</parameter>
to be read-write.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>db</parameter>&nbsp;:</term>
<listitem><simpara> an <link linkend="EphyNodeDb"><type>EphyNodeDb</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>immutable</parameter>&nbsp;:</term>
<listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> to make <parameter>db</parameter> immutable
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="ephy-node-db-get-node-from-id" role="function">
<title>ephy_node_db_get_node_from_id ()</title>
<indexterm zone="ephy-node-db-get-node-from-id"><primary>ephy_node_db_get_node_from_id</primary></indexterm><programlisting><link linkend="EphyNode">EphyNode</link>*           ephy_node_db_get_node_from_id       (<link linkend="EphyNodeDb">EphyNodeDb</link> *db,
                                                         <link linkend="guint">guint</link> id);</programlisting>
<para>
Returns the <link linkend="EphyNode"><type>EphyNode</type></link> with id <parameter>id</parameter> from <parameter>db</parameter>, or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if no such id exists.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>db</parameter>&nbsp;:</term>
<listitem><simpara> an <link linkend="EphyNodeDb"><type>EphyNodeDb</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>id</parameter>&nbsp;:</term>
<listitem><simpara> an id specifying an <link linkend="EphyNode"><type>EphyNode</type></link> in <parameter>db</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> an <link linkend="EphyNode"><type>EphyNode</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>
<refsect1 id="EphyNodeDb.property-details" role="property_details">
<title role="property_details.title">Property Details</title>
<refsect2 id="EphyNodeDb--immutable"><title>The <literal>&quot;immutable&quot;</literal> property</title>
<indexterm zone="EphyNodeDb--immutable"><primary>EphyNodeDb:immutable</primary></indexterm><programlisting>  &quot;immutable&quot;                <link linkend="gboolean">gboolean</link>              : Read / Write</programlisting>
<para>
<link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if no <link linkend="EphyNode"><type>EphyNode</type></link><!-- -->s can be added, removed or modified from this
<link linkend="EphyNodeDb"><type>EphyNodeDb</type></link>
</para><para>Default value: FALSE</para>
</refsect2>
<refsect2 id="EphyNodeDb--name"><title>The <literal>&quot;name&quot;</literal> property</title>
<indexterm zone="EphyNodeDb--name"><primary>EphyNodeDb:name</primary></indexterm><programlisting>  &quot;name&quot;                     <link linkend="gchar">gchar</link>*                : Read / Write / Construct Only</programlisting>
<para>
A string identifier unique to this <link linkend="EphyNodeDb"><type>EphyNodeDb</type></link>
</para><para>Default value: NULL</para>
</refsect2>

</refsect1>




</refentry>
