<refentry id="openhpi-Resource-UID-Utilities">
<refmeta>
<refentrytitle>Resource UID Utilities</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>OPENHPI Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Resource UID Utilities</refname><refpurpose>Resource Unique ID Utility Functions</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>

<synopsis>

#include &lt;SaHpi.h&gt;
#include &lt;glib.h&gt;


SaErrorT    <link linkend="oh-uid-initialize">oh_uid_initialize</link>			(void);
guint       <link linkend="oh-uid-from-entity-path">oh_uid_from_entity_path</link>	(SaHpiEntityPathT *ep);
guint       <link linkend="oh-uid-remove">oh_uid_remove</link>                   	(guint uid);
guint       <link linkend="oh-uid-lookup">oh_uid_lookup</link>                   	(SaHpiEntityPathT *ep);
guint       <link linkend="oh-entity-path-lookup">oh_entity_path_lookup</link>          (guint *id,
                                             	SaHpiEntityPathT *ep);
</synopsis>
</refsynopsisdiv>







<refsect1>
<title>Description</title>
<para>
This interface helps in generating a unique Resource Id based on an entity
path provided. You can also look up entity paths by uid and vice versa.
</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="oh-uid-initialize">oh_uid_initialize ()</title>
<programlisting>
SaErrorT	oh_uid_initialize	(void);
</programlisting>
<para>
UID utils initialization routine
This functions must be called before any other uid_utils
are made.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> success 0, failure -1.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="oh-uid-from-entity-path">oh_uid_from_entity_path ()</title>
<programlisting>
guint		oh_uid_from_entity_path	(SaHpiEntityPathT *ep);
</programlisting>
<para>
Returns a unique uid to be used as a resource id based upon an specified
entity path.
This functions returns a unique value to be used as
an uid/resourceID base upon a unique entity path specified
by <parameter>ep</parameter>.  If the entity path already exists a return code 
of -1 is returned.  Before returning this call updates the
uid map file saved on disk.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>ep</parameter>&nbsp;:</term>
<listitem><simpara> value to be removed from used
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> positive unsigned int, failure is -1.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="oh-uid-remove">oh_uid_remove ()</title>
<programlisting>
guint		oh_uid_remove	(guint uid);
</programlisting>
<para>
This functions removes the uid/entity path
pair from use and removes the use of the uid forever.
An new uid may be requested for this entity path
in the future. <link linkend="oh-uid-from-entity-path">oh_uid_from_entity_path</link>() writes
the entire uid/entity path pairings to file before 
returning. <link linkend="oh-uid-remove">oh_uid_remove</link>() deletes the pairing from file.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>uid</parameter>&nbsp;:</term>
<listitem><simpara> value to be removed from used
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> success 0, failure -1.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="oh-uid-lookup">oh_uid_lookup ()</title>
<programlisting>
guint		oh_uid_lookup	(SaHpiEntityPathT *ep);
</programlisting>
<para>
Fetches resourceID/uid based on entity path in <parameter>ep</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>ep</parameter>&nbsp;:</term>
<listitem><simpara> pointer to entity path used to identify resourceID/uid
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> success returns resourceID/uid, failure is -1.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="oh-entity-path-lookup">oh_entity_path_lookup ()</title>
<programlisting>
guint		oh_entity_path_lookup	(guint *id,
					 SaHpiEntityPathT *ep);
</programlisting>
<para>
Fetches entity path based upon resource id, <parameter>id</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>id</parameter>&nbsp;:</term>
<listitem><simpara> pointer to resource_id/uid indenifying entity path
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>ep</parameter>&nbsp;:</term>
<listitem><simpara> pointer to memory to fill in with entity path
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> success 0, failed -1.
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>
