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

<refnamediv>
<refname>EPATH Utilities</refname><refpurpose>Entity Path Utility Functions</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>

<synopsis>

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


int         <link linkend="string2entitypath">string2entitypath</link>               (const gchar *epathstr,
                                             	SaHpiEntityPathT *epathptr);
int         <link linkend="entitypath2string">entitypath2string</link>               (const SaHpiEntityPathT *epathptr,
                                             	gchar *epathstr,
                                             	gint strsize);
int         <link linkend="ep-concat">ep_concat</link>                       (SaHpiEntityPathT *dest,
                                             	const SaHpiEntityPathT *append);
int         <link linkend="set-epath-instance">set_epath_instance</link>              (SaHpiEntityPathT *ep,
                                             	SaHpiEntityTypeT et,
                                             	SaHpiEntityInstanceT ei);
int         <link linkend="append-root">append_root</link>                     (SaHpiEntityPathT *ep);
</synopsis>
</refsynopsisdiv>







<refsect1>
<title>Description</title>
<para>
This interface was created to manage entity paths with ease. It
lets you convert an SaHpi entity path to its canonical string form and
back, among other things like concatenating two entity paths. Plugin
developers will mostly want to use <link linkend="string2entitypath">string2entitypath</link>() since entity paths
are feeded to plugins in string form from the plugin configuration file
(/etc/openhpi/openhpi.conf).
</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="string2entitypath">string2entitypath ()</title>
<programlisting>
int	string2entitypath	(const gchar *epathstr,
				 SaHpiEntityPathT *epathptr);
</programlisting>
<para>
Converts an entity path canonical string into a
SaHpiEntityPathT structure.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>epathstr</parameter>&nbsp;:</term>
<listitem><simpara> IN. Pointer to canonical entity path string
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>epathptr</parameter>&nbsp;:</term>
<listitem><simpara> OUT. Pointer to HPI's entity path structure
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> 0 Successful return, -1 Error return
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="entitypath2string">entitypath2string ()</title>
<programlisting>
int	entitypath2string	(const SaHpiEntityPathT *epathptr,
				 gchar *epathstr,
				 gint strsize);
</programlisting>
<para>
Converts an entity path structure into its
canonical string version.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>epathptr</parameter>&nbsp;:</term>
<listitem><simpara> IN. Pointer to HPI's entity path structure
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>epathstr</parameter>&nbsp;:</term>
<listitem><simpara> OUT. Pointer to canonical entity path string
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>strsize</parameter>&nbsp;:</term>
<listitem><simpara> IN. Canonical string length
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> &gt;0 Number of characters written to canonical entity path string, 
-1 Error return
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="ep-concat">ep_concat ()</title>
<programlisting>
int	ep_concat	(SaHpiEntityPathT *dest,
			 const SaHpiEntityPathT *append);
</programlisting>
<para>
Concatenate two entity path structures (SaHpiEntityPathT).
<parameter>dest</parameter> is assumed to be the least significant entity path in the operation.
append will be truncated into <parameter>dest</parameter>, if it doesn't fit completely in the space
that <parameter>dest</parameter> has available relative to SAHPI_MAX_ENTITY_PATH.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>dest</parameter>&nbsp;:</term>
<listitem><simpara> IN,OUT Left-hand entity path. Gets appended with <parameter>append</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>append</parameter>&nbsp;:</term>
<listitem><simpara> IN Right-hand entity path. Pointer entity path to be appended.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> 0 on Success, -1 if dest is NULL.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="set-epath-instance">set_epath_instance ()</title>
<programlisting>
int	set_epath_instance	(SaHpiEntityPathT *ep,
				 SaHpiEntityTypeT et,
				 SaHpiEntityInstanceT ei);
</programlisting>
<para>
Set an instance number in the entity path given at the first
position (from least significant to most) the specified entity type is found.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>ep</parameter>&nbsp;:</term>
<listitem><simpara> Pointer to entity path to work on
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>et</parameter>&nbsp;:</term>
<listitem><simpara> entity type to look for
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>ei</parameter>&nbsp;:</term>
<listitem><simpara> entity instance to set when entity type is found
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> 0 on Success, -1 if the entity type was not found.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="append-root">append_root ()</title>
<programlisting>
int	append_root		(SaHpiEntityPathT *ep);
</programlisting>
<para>
Append the SAHPI_ENT_ROOT element to an entity path structure.
If an entity path already has a root element, the function returns without
making any changes and reporting success.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>ep</parameter>&nbsp;:</term>
<listitem><simpara> IN,OUT Pointer to entity path. SAHPI_ENT_ROOT will be appended to it.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> 0 on Success, -1 if ep is NULL.
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>
