<refentry id="streamtuner-st-category-api">
<refmeta>
<refentrytitle>STCategory</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>STREAMTUNER Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>STCategory</refname><refpurpose>a structure for defining a category.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>

<synopsis>



struct      <link linkend="STCategory">STCategory</link>;
<link linkend="gboolean">gboolean</link>    (<link linkend="STCategoryURLCallback">*STCategoryURLCallback</link>)        (<link linkend="STCategory">STCategory</link> *category);
<link linkend="STCategory">STCategory</link>* <link linkend="st-category-new">st_category_new</link>                 (void);
<link linkend="void">void</link>        <link linkend="st-category-free">st_category_free</link>                (<link linkend="STCategory">STCategory</link> *category);
</synopsis>
</refsynopsisdiv>









<refsect1>
<title>Description</title>
<para>

</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="STCategory"/>struct STCategory</title>
<indexterm><primary>STCategory</primary></indexterm><programlisting>struct STCategory {

  char				*name;
  char				*label;
  char				*url_postfix;
  STCategoryURLCallback		url_cb;
};
</programlisting>
<para>

</para><variablelist role="struct">
<varlistentry>
<term><link linkend="char">char</link> *<structfield>name</structfield></term>
<listitem><simpara>the category internal name.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="char">char</link> *<structfield>label</structfield></term>
<listitem><simpara>the category human-readable name.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="char">char</link> *<structfield>url_postfix</structfield></term>
<listitem><simpara>the category URL postfix.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="STCategoryURLCallback">STCategoryURLCallback</link> <structfield>url_cb</structfield></term>
<listitem><simpara>a function which will be called when the category is about to
be reloaded.

</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="STCategoryURLCallback"/>STCategoryURLCallback ()</title>
<indexterm><primary>STCategoryURLCallback</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>    (*STCategoryURLCallback)        (<link linkend="STCategory">STCategory</link> *category);</programlisting>
<para>
Specifies the type of function to be stored in the
<structfield>url_cb</structfield> member of the <link linkend="STCategory"><type>STCategory</type></link>
structure. The function will be called before reloading <parameter>category</parameter>,
and may update its <structfield>label</structfield> and
<structfield>url_postfix</structfield> members.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>category</parameter>&nbsp;:</term>
<listitem><simpara> the category which is about to be reloaded.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the function should return <literal>FALSE</literal> if the reload
should be cancelled.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="st-category-new"/>st_category_new ()</title>
<indexterm><primary>st_category_new</primary></indexterm><programlisting><link linkend="STCategory">STCategory</link>* st_category_new                 (void);</programlisting>
<para>
Creates a new <link linkend="STCategory"><type>STCategory</type></link>. The structure members are initialized to
<literal>NULL</literal>, and at least the <structfield>name</structfield> and
<structfield>label</structfield> members must be filled manually.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a new <link linkend="STCategory"><type>STCategory</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="st-category-free"/>st_category_free ()</title>
<indexterm><primary>st_category_free</primary></indexterm><programlisting><link linkend="void">void</link>        st_category_free                (<link linkend="STCategory">STCategory</link> *category);</programlisting>
<para>
Destroys <parameter>category</parameter> (<link linkend="g-free"><function>g_free()</function></link> will be called on the
<structfield>name</structfield>, <structfield>label</structfield>
and <structfield>url_postfix</structfield> members).</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>category</parameter>&nbsp;:</term>
<listitem><simpara> the <link linkend="STCategory"><type>STCategory</type></link> to destroy.
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>



<refsect1>
<title>See Also</title>
<para>
<link linkend="STHandlerEvent"><type>STHandlerEvent</type></link>, <link linkend="st-handler-set-stock-categories"><function>st_handler_set_stock_categories()</function></link>
</para>
</refsect1>

</refentry>
