git.sur5r.net Git - glabels/blob - docs/libglabels/xml/db.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
   3                "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
   4
   5 <refentry id="libglabels-db">
   6 <refmeta>
   7 <refentrytitle role="top_of_page" id="libglabels-db.top_of_page">Database</refentrytitle>
   8 <manvolnum>3</manvolnum>
   9 <refmiscinfo>LIBGLABELS Library</refmiscinfo>
  10 </refmeta>
  11
  12 <refnamediv>
  13 <refname>Database</refname>
  14 <refpurpose>Database of pre-defined templates</refpurpose>
  15 </refnamediv>
  16
  17 <refsynopsisdiv id="libglabels-db.synopsis" role="synopsis">
  18 <title role="synopsis.title">Synopsis</title>
  19
  20 <synopsis>
  21
  22 #include &lt;libglabels/db.h&gt;
  23
  24 enum                <link linkend="lglDbRegStatus">lglDbRegStatus</link>;
  25
  26 <link linkend="void">void</link>                <link linkend="lgl-db-init">lgl_db_init</link>                         (void);
  27
  28 <link linkend="GList">GList</link> *             <link linkend="lgl-db-get-paper-id-list">lgl_db_get_paper_id_list</link>            (void);
  29 <link linkend="void">void</link>                <link linkend="lgl-db-free-paper-id-list">lgl_db_free_paper_id_list</link>           (<link linkend="GList">GList</link> *ids);
  30 <link linkend="GList">GList</link> *             <link linkend="lgl-db-get-paper-name-list">lgl_db_get_paper_name_list</link>          (void);
  31 <link linkend="void">void</link>                <link linkend="lgl-db-free-paper-name-list">lgl_db_free_paper_name_list</link>         (<link linkend="GList">GList</link> *names);
  32 <link linkend="lglPaper">lglPaper</link> *          <link linkend="lgl-db-lookup-paper-from-id">lgl_db_lookup_paper_from_id</link>         (const <link linkend="gchar">gchar</link> *id);
  33 <link linkend="lglPaper">lglPaper</link> *          <link linkend="lgl-db-lookup-paper-from-name">lgl_db_lookup_paper_from_name</link>       (const <link linkend="gchar">gchar</link> *name);
  34 <link linkend="gchar">gchar</link> *             <link linkend="lgl-db-lookup-paper-id-from-name">lgl_db_lookup_paper_id_from_name</link>    (const <link linkend="gchar">gchar</link> *name);
  35 <link linkend="gchar">gchar</link> *             <link linkend="lgl-db-lookup-paper-name-from-id">lgl_db_lookup_paper_name_from_id</link>    (const <link linkend="gchar">gchar</link> *id);
  36 <link linkend="gboolean">gboolean</link>            <link linkend="lgl-db-is-paper-id-known">lgl_db_is_paper_id_known</link>            (const <link linkend="gchar">gchar</link> *id);
  37 <link linkend="gboolean">gboolean</link>            <link linkend="lgl-db-is-paper-id-other">lgl_db_is_paper_id_other</link>            (const <link linkend="gchar">gchar</link> *id);
  38
  39 <link linkend="GList">GList</link> *             <link linkend="lgl-db-get-category-id-list">lgl_db_get_category_id_list</link>         (void);
  40 <link linkend="void">void</link>                <link linkend="lgl-db-free-category-id-list">lgl_db_free_category_id_list</link>        (<link linkend="GList">GList</link> *ids);
  41 <link linkend="GList">GList</link> *             <link linkend="lgl-db-get-category-name-list">lgl_db_get_category_name_list</link>       (void);
  42 <link linkend="void">void</link>                <link linkend="lgl-db-free-category-name-list">lgl_db_free_category_name_list</link>      (<link linkend="GList">GList</link> *names);
  43 <link linkend="lglCategory">lglCategory</link> *       <link linkend="lgl-db-lookup-category-from-id">lgl_db_lookup_category_from_id</link>      (const <link linkend="gchar">gchar</link> *id);
  44 <link linkend="lglCategory">lglCategory</link> *       <link linkend="lgl-db-lookup-category-from-name">lgl_db_lookup_category_from_name</link>    (const <link linkend="gchar">gchar</link> *name);
  45 <link linkend="gchar">gchar</link> *             <link linkend="lgl-db-lookup-category-id-from-name">lgl_db_lookup_category_id_from_name</link> (const <link linkend="gchar">gchar</link> *name);
  46 <link linkend="gchar">gchar</link> *             <link linkend="lgl-db-lookup-category-name-from-id">lgl_db_lookup_category_name_from_id</link> (const <link linkend="gchar">gchar</link> *id);
  47 <link linkend="gboolean">gboolean</link>            <link linkend="lgl-db-is-category-id-known">lgl_db_is_category_id_known</link>         (const <link linkend="gchar">gchar</link> *id);
  48
  49 <link linkend="GList">GList</link> *             <link linkend="lgl-db-get-brand-list">lgl_db_get_brand_list</link>               (const <link linkend="gchar">gchar</link> *paper_id,
  50                                                          const <link linkend="gchar">gchar</link> *category_id);
  51 <link linkend="void">void</link>                <link linkend="lgl-db-free-brand-list">lgl_db_free_brand_list</link>              (<link linkend="GList">GList</link> *brands);
  52
  53 <link linkend="lglDbRegStatus">lglDbRegStatus</link>      <link linkend="lgl-db-register-template">lgl_db_register_template</link>            (const <link linkend="lglTemplate">lglTemplate</link> *template);
  54 <link linkend="gboolean">gboolean</link>            <link linkend="lgl-db-does-template-exist">lgl_db_does_template_exist</link>          (const <link linkend="gchar">gchar</link> *brand,
  55                                                          const <link linkend="gchar">gchar</link> *part);
  56 <link linkend="gboolean">gboolean</link>            <link linkend="lgl-db-does-template-name-exist">lgl_db_does_template_name_exist</link>     (const <link linkend="gchar">gchar</link> *name);
  57 <link linkend="GList">GList</link> *             <link linkend="lgl-db-get-template-name-list-unique">lgl_db_get_template_name_list_unique</link>
  58                                                         (const <link linkend="gchar">gchar</link> *brand,
  59                                                          const <link linkend="gchar">gchar</link> *paper_id,
  60                                                          const <link linkend="gchar">gchar</link> *category_id);
  61 <link linkend="GList">GList</link> *             <link linkend="lgl-db-get-template-name-list-all">lgl_db_get_template_name_list_all</link>   (const <link linkend="gchar">gchar</link> *brand,
  62                                                          const <link linkend="gchar">gchar</link> *paper_id,
  63                                                          const <link linkend="gchar">gchar</link> *category_id);
  64 <link linkend="void">void</link>                <link linkend="lgl-db-free-template-name-list">lgl_db_free_template_name_list</link>      (<link linkend="GList">GList</link> *names);
  65 <link linkend="lglTemplate">lglTemplate</link> *       <link linkend="lgl-db-lookup-template-from-name">lgl_db_lookup_template_from_name</link>    (const <link linkend="gchar">gchar</link> *name);
  66
  67 <link linkend="void">void</link>                <link linkend="lgl-db-print-known-papers">lgl_db_print_known_papers</link>           (void);
  68 <link linkend="void">void</link>                <link linkend="lgl-db-print-known-categories">lgl_db_print_known_categories</link>       (void);
  69 <link linkend="void">void</link>                <link linkend="lgl-db-print-known-templates">lgl_db_print_known_templates</link>        (void);
  70 <link linkend="void">void</link>                <link linkend="lgl-db-print-aliases">lgl_db_print_aliases</link>                (const <link linkend="lglTemplate">lglTemplate</link> *template);
  71 </synopsis>
  72 </refsynopsisdiv>
  73
  74
  75
  76
  77
  78
  79
  80
  81
  82 <refsect1 id="libglabels-db.description" role="desc">
  83 <title role="desc.title">Description</title>
  84 <para>
  85 This section describes a set of functions to locate and add templates and related information in
  86 the LibGlabels template database.
  87 </para>
  88 </refsect1>
  89
  90 <refsect1 id="libglabels-db.details" role="details">
  91 <title role="details.title">Details</title>
  92 <refsect2 id="lglDbRegStatus" role="enum">
  93 <title>enum lglDbRegStatus</title>
  94 <indexterm zone="lglDbRegStatus"><primary sortas="lglDbRegStatus">lglDbRegStatus</primary></indexterm><programlisting>typedef enum
  95 {
  96         LGL_DB_REG_OK                =  0,
  97         LGL_DB_REG_BAD_PAPER_ID      = -1,
  98         LGL_DB_REG_BRAND_PART_EXISTS = -2,
  99         LGL_DB_REG_FILE_WRITE_ERROR  = -3
 100 } lglDbRegStatus;
 101 </programlisting>
 102 <para>
 103 This enumeration defines a set of possible return values for <link linkend="lgl-db-register-template"><function>lgl_db_register_template()</function></link>.
 104 </para><variablelist role="enum">
 105 <varlistentry id="LGL-DB-REG-OK--CAPS" role="constant">
 106 <term><literal>LGL_DB_REG_OK</literal></term>
 107 <listitem><simpara>Registration successful.
 108 </simpara></listitem>
 109 </varlistentry>
 110 <varlistentry id="LGL-DB-REG-BAD-PAPER-ID--CAPS" role="constant">
 111 <term><literal>LGL_DB_REG_BAD_PAPER_ID</literal></term>
 112 <listitem><simpara> Registration failed because paper id is unknown.
 113 </simpara></listitem>
 114 </varlistentry>
 115 <varlistentry id="LGL-DB-REG-BRAND-PART-EXISTS--CAPS" role="constant">
 116 <term><literal>LGL_DB_REG_BRAND_PART_EXISTS</literal></term>
 117 <listitem><simpara>Registration failed because template with same brand and part name/number already exists.
 118 </simpara></listitem>
 119 </varlistentry>
 120 <varlistentry id="LGL-DB-REG-FILE-WRITE-ERROR--CAPS" role="constant">
 121 <term><literal>LGL_DB_REG_FILE_WRITE_ERROR</literal></term>
 122 <listitem><simpara>Registration failed because an error while writing to disk.
 123 </simpara></listitem>
 124 </varlistentry>
 125 </variablelist></refsect2>
 126 <refsect2 id="lgl-db-init" role="function">
 127 <title>lgl_db_init ()</title>
 128 <indexterm zone="lgl-db-init"><primary sortas="lgl_db_init">lgl_db_init</primary></indexterm><programlisting><link linkend="void">void</link>                lgl_db_init                         (void);</programlisting>
 129 <para>
 130 Initialize all libglabels subsystems.  It is not necessary for an application to call
 131 <link linkend="lgl-db-init"><function>lgl_db_init()</function></link>, because libglabels will initialize on demand.  An application programmer may
 132 choose to call <link linkend="lgl-db-init"><function>lgl_db_init()</function></link> at startup to minimize the impact of the first libglabels call
 133 on GUI response time.
 134 </para>
 135 <para>
 136 This function initializes its paper definitions, category definitions, and its template
 137 database.. It will search both system and user template directories to locate
 138 this data.</para>
 139 <para>
 140 </para></refsect2>
 141 <refsect2 id="lgl-db-get-paper-id-list" role="function">
 142 <title>lgl_db_get_paper_id_list ()</title>
 143 <indexterm zone="lgl-db-get-paper-id-list"><primary sortas="lgl_db_get_paper_id_list">lgl_db_get_paper_id_list</primary></indexterm><programlisting><link linkend="GList">GList</link> *             lgl_db_get_paper_id_list            (void);</programlisting>
 144 <para>
 145 Get a list of all paper ids known to libglabels.</para>
 146 <para>
 147 </para><variablelist role="params">
 148 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a list of paper ids.
 149
 150 </simpara></listitem></varlistentry>
 151 </variablelist></refsect2>
 152 <refsect2 id="lgl-db-free-paper-id-list" role="function">
 153 <title>lgl_db_free_paper_id_list ()</title>
 154 <indexterm zone="lgl-db-free-paper-id-list"><primary sortas="lgl_db_free_paper_id_list">lgl_db_free_paper_id_list</primary></indexterm><programlisting><link linkend="void">void</link>                lgl_db_free_paper_id_list           (<link linkend="GList">GList</link> *ids);</programlisting>
 155 <para>
 156 Free up all storage associated with an id list obtained with
 157 <link linkend="lgl-db-get-paper-id-list"><function>lgl_db_get_paper_id_list()</function></link>.</para>
 158 <para>
 159 </para><variablelist role="params">
 160 <varlistentry><term><parameter>ids</parameter>&#160;:</term>
 161 <listitem><simpara> List of id strings to be freed.
 162 </simpara></listitem></varlistentry>
 163 </variablelist></refsect2>
 164 <refsect2 id="lgl-db-get-paper-name-list" role="function">
 165 <title>lgl_db_get_paper_name_list ()</title>
 166 <indexterm zone="lgl-db-get-paper-name-list"><primary sortas="lgl_db_get_paper_name_list">lgl_db_get_paper_name_list</primary></indexterm><programlisting><link linkend="GList">GList</link> *             lgl_db_get_paper_name_list          (void);</programlisting>
 167 <para>
 168 Get a list of all localized paper names known to libglabels.</para>
 169 <para>
 170 </para><variablelist role="params">
 171 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a list of localized paper names.
 172
 173 </simpara></listitem></varlistentry>
 174 </variablelist></refsect2>
 175 <refsect2 id="lgl-db-free-paper-name-list" role="function">
 176 <title>lgl_db_free_paper_name_list ()</title>
 177 <indexterm zone="lgl-db-free-paper-name-list"><primary sortas="lgl_db_free_paper_name_list">lgl_db_free_paper_name_list</primary></indexterm><programlisting><link linkend="void">void</link>                lgl_db_free_paper_name_list         (<link linkend="GList">GList</link> *names);</programlisting>
 178 <para>
 179 Free up all storage associated with a name list obtained with
 180 <link linkend="lgl-db-get-paper-name-list"><function>lgl_db_get_paper_name_list()</function></link>.</para>
 181 <para>
 182 </para><variablelist role="params">
 183 <varlistentry><term><parameter>names</parameter>&#160;:</term>
 184 <listitem><simpara> List of localized paper name strings to be freed.
 185 </simpara></listitem></varlistentry>
 186 </variablelist></refsect2>
 187 <refsect2 id="lgl-db-lookup-paper-from-id" role="function">
 188 <title>lgl_db_lookup_paper_from_id ()</title>
 189 <indexterm zone="lgl-db-lookup-paper-from-id"><primary sortas="lgl_db_lookup_paper_from_id">lgl_db_lookup_paper_from_id</primary></indexterm><programlisting><link linkend="lglPaper">lglPaper</link> *          lgl_db_lookup_paper_from_id         (const <link linkend="gchar">gchar</link> *id);</programlisting>
 190 <para>
 191 Lookup paper definition from id string.</para>
 192 <para>
 193 </para><variablelist role="params">
 194 <varlistentry><term><parameter>id</parameter>&#160;:</term>
 195 <listitem><simpara> paper id string
 196 </simpara></listitem></varlistentry>
 197 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> pointer to a newly allocated <link linkend="lglPaper"><type>lglPaper</type></link> structure.
 198
 199 </simpara></listitem></varlistentry>
 200 </variablelist></refsect2>
 201 <refsect2 id="lgl-db-lookup-paper-from-name" role="function">
 202 <title>lgl_db_lookup_paper_from_name ()</title>
 203 <indexterm zone="lgl-db-lookup-paper-from-name"><primary sortas="lgl_db_lookup_paper_from_name">lgl_db_lookup_paper_from_name</primary></indexterm><programlisting><link linkend="lglPaper">lglPaper</link> *          lgl_db_lookup_paper_from_name       (const <link linkend="gchar">gchar</link> *name);</programlisting>
 204 <para>
 205 Lookup paper definition from localized paper name string.</para>
 206 <para>
 207 </para><variablelist role="params">
 208 <varlistentry><term><parameter>name</parameter>&#160;:</term>
 209 <listitem><simpara> localized paper name string
 210 </simpara></listitem></varlistentry>
 211 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> pointer to a newly allocated <link linkend="lglPaper"><type>lglPaper</type></link> structure.
 212
 213 </simpara></listitem></varlistentry>
 214 </variablelist></refsect2>
 215 <refsect2 id="lgl-db-lookup-paper-id-from-name" role="function">
 216 <title>lgl_db_lookup_paper_id_from_name ()</title>
 217 <indexterm zone="lgl-db-lookup-paper-id-from-name"><primary sortas="lgl_db_lookup_paper_id_from_name">lgl_db_lookup_paper_id_from_name</primary></indexterm><programlisting><link linkend="gchar">gchar</link> *             lgl_db_lookup_paper_id_from_name    (const <link linkend="gchar">gchar</link> *name);</programlisting>
 218 <para>
 219 Lookup paper name string from localized paper name string.</para>
 220 <para>
 221 </para><variablelist role="params">
 222 <varlistentry><term><parameter>name</parameter>&#160;:</term>
 223 <listitem><simpara> localized paper name stringp
 224 </simpara></listitem></varlistentry>
 225 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> pointer to a newly allocated id string.
 226
 227 </simpara></listitem></varlistentry>
 228 </variablelist></refsect2>
 229 <refsect2 id="lgl-db-lookup-paper-name-from-id" role="function">
 230 <title>lgl_db_lookup_paper_name_from_id ()</title>
 231 <indexterm zone="lgl-db-lookup-paper-name-from-id"><primary sortas="lgl_db_lookup_paper_name_from_id">lgl_db_lookup_paper_name_from_id</primary></indexterm><programlisting><link linkend="gchar">gchar</link> *             lgl_db_lookup_paper_name_from_id    (const <link linkend="gchar">gchar</link> *id);</programlisting>
 232 <para>
 233 Lookup localized paper name string from paper id string.</para>
 234 <para>
 235 </para><variablelist role="params">
 236 <varlistentry><term><parameter>id</parameter>&#160;:</term>
 237 <listitem><simpara> paper id string
 238 </simpara></listitem></varlistentry>
 239 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> pointer to a newly allocated localized paper name string.
 240
 241 </simpara></listitem></varlistentry>
 242 </variablelist></refsect2>
 243 <refsect2 id="lgl-db-is-paper-id-known" role="function">
 244 <title>lgl_db_is_paper_id_known ()</title>
 245 <indexterm zone="lgl-db-is-paper-id-known"><primary sortas="lgl_db_is_paper_id_known">lgl_db_is_paper_id_known</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            lgl_db_is_paper_id_known            (const <link linkend="gchar">gchar</link> *id);</programlisting>
 246 <para>
 247 Determine if given paper id is known to libglabels.</para>
 248 <para>
 249 </para><variablelist role="params">
 250 <varlistentry><term><parameter>id</parameter>&#160;:</term>
 251 <listitem><simpara> paper id to test
 252 </simpara></listitem></varlistentry>
 253 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> TRUE if id is known, otherwise FALSE.
 254
 255 </simpara></listitem></varlistentry>
 256 </variablelist></refsect2>
 257 <refsect2 id="lgl-db-is-paper-id-other" role="function">
 258 <title>lgl_db_is_paper_id_other ()</title>
 259 <indexterm zone="lgl-db-is-paper-id-other"><primary sortas="lgl_db_is_paper_id_other">lgl_db_is_paper_id_other</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            lgl_db_is_paper_id_other            (const <link linkend="gchar">gchar</link> *id);</programlisting>
 260 <para>
 261 Determine if given paper id is the special id "Other."</para>
 262 <para>
 263 </para><variablelist role="params">
 264 <varlistentry><term><parameter>id</parameter>&#160;:</term>
 265 <listitem><simpara> paper id to test
 266 </simpara></listitem></varlistentry>
 267 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> TRUE if id is "Other", otherwise FALSE.
 268
 269 </simpara></listitem></varlistentry>
 270 </variablelist></refsect2>
 271 <refsect2 id="lgl-db-get-category-id-list" role="function">
 272 <title>lgl_db_get_category_id_list ()</title>
 273 <indexterm zone="lgl-db-get-category-id-list"><primary sortas="lgl_db_get_category_id_list">lgl_db_get_category_id_list</primary></indexterm><programlisting><link linkend="GList">GList</link> *             lgl_db_get_category_id_list         (void);</programlisting>
 274 <para>
 275 Get a list of all category ids known to libglabels.</para>
 276 <para>
 277 </para><variablelist role="params">
 278 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a list of category ids.
 279
 280 </simpara></listitem></varlistentry>
 281 </variablelist></refsect2>
 282 <refsect2 id="lgl-db-free-category-id-list" role="function">
 283 <title>lgl_db_free_category_id_list ()</title>
 284 <indexterm zone="lgl-db-free-category-id-list"><primary sortas="lgl_db_free_category_id_list">lgl_db_free_category_id_list</primary></indexterm><programlisting><link linkend="void">void</link>                lgl_db_free_category_id_list        (<link linkend="GList">GList</link> *ids);</programlisting>
 285 <para>
 286 Free up all storage associated with an id list obtained with
 287 <link linkend="lgl-db-get-category-id-list"><function>lgl_db_get_category_id_list()</function></link>.</para>
 288 <para>
 289 </para><variablelist role="params">
 290 <varlistentry><term><parameter>ids</parameter>&#160;:</term>
 291 <listitem><simpara> List of id strings to be freed.
 292 </simpara></listitem></varlistentry>
 293 </variablelist></refsect2>
 294 <refsect2 id="lgl-db-get-category-name-list" role="function">
 295 <title>lgl_db_get_category_name_list ()</title>
 296 <indexterm zone="lgl-db-get-category-name-list"><primary sortas="lgl_db_get_category_name_list">lgl_db_get_category_name_list</primary></indexterm><programlisting><link linkend="GList">GList</link> *             lgl_db_get_category_name_list       (void);</programlisting>
 297 <para>
 298 Get a list of all localized category names known to libglabels.</para>
 299 <para>
 300 </para><variablelist role="params">
 301 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a list of localized category names.
 302
 303 </simpara></listitem></varlistentry>
 304 </variablelist></refsect2>
 305 <refsect2 id="lgl-db-free-category-name-list" role="function">
 306 <title>lgl_db_free_category_name_list ()</title>
 307 <indexterm zone="lgl-db-free-category-name-list"><primary sortas="lgl_db_free_category_name_list">lgl_db_free_category_name_list</primary></indexterm><programlisting><link linkend="void">void</link>                lgl_db_free_category_name_list      (<link linkend="GList">GList</link> *names);</programlisting>
 308 <para>
 309 Free up all storage associated with a name list obtained with
 310 <link linkend="lgl-db-get-category-name-list"><function>lgl_db_get_category_name_list()</function></link>.</para>
 311 <para>
 312 </para><variablelist role="params">
 313 <varlistentry><term><parameter>names</parameter>&#160;:</term>
 314 <listitem><simpara> List of localized category name strings to be freed.
 315 </simpara></listitem></varlistentry>
 316 </variablelist></refsect2>
 317 <refsect2 id="lgl-db-lookup-category-from-id" role="function">
 318 <title>lgl_db_lookup_category_from_id ()</title>
 319 <indexterm zone="lgl-db-lookup-category-from-id"><primary sortas="lgl_db_lookup_category_from_id">lgl_db_lookup_category_from_id</primary></indexterm><programlisting><link linkend="lglCategory">lglCategory</link> *       lgl_db_lookup_category_from_id      (const <link linkend="gchar">gchar</link> *id);</programlisting>
 320 <para>
 321 Lookup category definition from id string.</para>
 322 <para>
 323 </para><variablelist role="params">
 324 <varlistentry><term><parameter>id</parameter>&#160;:</term>
 325 <listitem><simpara> category id string
 326 </simpara></listitem></varlistentry>
 327 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> pointer to a newly allocated <link linkend="lglCategory"><type>lglCategory</type></link> structure.
 328
 329 </simpara></listitem></varlistentry>
 330 </variablelist></refsect2>
 331 <refsect2 id="lgl-db-lookup-category-from-name" role="function">
 332 <title>lgl_db_lookup_category_from_name ()</title>
 333 <indexterm zone="lgl-db-lookup-category-from-name"><primary sortas="lgl_db_lookup_category_from_name">lgl_db_lookup_category_from_name</primary></indexterm><programlisting><link linkend="lglCategory">lglCategory</link> *       lgl_db_lookup_category_from_name    (const <link linkend="gchar">gchar</link> *name);</programlisting>
 334 <para>
 335 Lookup category definition from localized category name string.</para>
 336 <para>
 337 </para><variablelist role="params">
 338 <varlistentry><term><parameter>name</parameter>&#160;:</term>
 339 <listitem><simpara> localized category name string
 340 </simpara></listitem></varlistentry>
 341 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> pointer to a newly allocated <link linkend="lglCategory"><type>lglCategory</type></link> structure.
 342
 343 </simpara></listitem></varlistentry>
 344 </variablelist></refsect2>
 345 <refsect2 id="lgl-db-lookup-category-id-from-name" role="function">
 346 <title>lgl_db_lookup_category_id_from_name ()</title>
 347 <indexterm zone="lgl-db-lookup-category-id-from-name"><primary sortas="lgl_db_lookup_category_id_from_name">lgl_db_lookup_category_id_from_name</primary></indexterm><programlisting><link linkend="gchar">gchar</link> *             lgl_db_lookup_category_id_from_name (const <link linkend="gchar">gchar</link> *name);</programlisting>
 348 <para>
 349 Lookup category name string from localized category name string.</para>
 350 <para>
 351 </para><variablelist role="params">
 352 <varlistentry><term><parameter>name</parameter>&#160;:</term>
 353 <listitem><simpara> localized category name stringp
 354 </simpara></listitem></varlistentry>
 355 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> pointer to a newly allocated id string.
 356
 357 </simpara></listitem></varlistentry>
 358 </variablelist></refsect2>
 359 <refsect2 id="lgl-db-lookup-category-name-from-id" role="function">
 360 <title>lgl_db_lookup_category_name_from_id ()</title>
 361 <indexterm zone="lgl-db-lookup-category-name-from-id"><primary sortas="lgl_db_lookup_category_name_from_id">lgl_db_lookup_category_name_from_id</primary></indexterm><programlisting><link linkend="gchar">gchar</link> *             lgl_db_lookup_category_name_from_id (const <link linkend="gchar">gchar</link> *id);</programlisting>
 362 <para>
 363 Lookup localized category name string from category id string.</para>
 364 <para>
 365 </para><variablelist role="params">
 366 <varlistentry><term><parameter>id</parameter>&#160;:</term>
 367 <listitem><simpara> category id string
 368 </simpara></listitem></varlistentry>
 369 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> pointer to a newly allocated localized category name string.
 370
 371 </simpara></listitem></varlistentry>
 372 </variablelist></refsect2>
 373 <refsect2 id="lgl-db-is-category-id-known" role="function">
 374 <title>lgl_db_is_category_id_known ()</title>
 375 <indexterm zone="lgl-db-is-category-id-known"><primary sortas="lgl_db_is_category_id_known">lgl_db_is_category_id_known</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            lgl_db_is_category_id_known         (const <link linkend="gchar">gchar</link> *id);</programlisting>
 376 <para>
 377 Determine if given category id is known to libglabels.</para>
 378 <para>
 379 </para><variablelist role="params">
 380 <varlistentry><term><parameter>id</parameter>&#160;:</term>
 381 <listitem><simpara> category id to test
 382 </simpara></listitem></varlistentry>
 383 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> TRUE if id is known, otherwise FALSE.
 384
 385 </simpara></listitem></varlistentry>
 386 </variablelist></refsect2>
 387 <refsect2 id="lgl-db-get-brand-list" role="function">
 388 <title>lgl_db_get_brand_list ()</title>
 389 <indexterm zone="lgl-db-get-brand-list"><primary sortas="lgl_db_get_brand_list">lgl_db_get_brand_list</primary></indexterm><programlisting><link linkend="GList">GList</link> *             lgl_db_get_brand_list               (const <link linkend="gchar">gchar</link> *paper_id,
 390                                                          const <link linkend="gchar">gchar</link> *category_id);</programlisting>
 391 <para>
 392 Get a list of all valid brands of templates in the template database.
 393 Results can be filtered by page size and/or template category.  A list of valid page
 394 sizes can be obtained using <link linkend="lgl-db-get-paper-id-list"><function>lgl_db_get_paper_id_list()</function></link>.  A list of valid template
 395 categories can be obtained using <link linkend="lgl-db-get-category-id-list"><function>lgl_db_get_category_id_list()</function></link>.</para>
 396 <para>
 397 </para><variablelist role="params">
 398 <varlistentry><term><parameter>paper_id</parameter>&#160;:</term>
 399 <listitem><simpara> If non NULL, limit results to given page size.
 400 </simpara></listitem></varlistentry>
 401 <varlistentry><term><parameter>category_id</parameter>&#160;:</term>
 402 <listitem><simpara> If non NULL, limit results to given template category.
 403 </simpara></listitem></varlistentry>
 404 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a list of brands
 405 </simpara></listitem></varlistentry>
 406 </variablelist></refsect2>
 407 <refsect2 id="lgl-db-free-brand-list" role="function">
 408 <title>lgl_db_free_brand_list ()</title>
 409 <indexterm zone="lgl-db-free-brand-list"><primary sortas="lgl_db_free_brand_list">lgl_db_free_brand_list</primary></indexterm><programlisting><link linkend="void">void</link>                lgl_db_free_brand_list              (<link linkend="GList">GList</link> *brands);</programlisting>
 410 <para>
 411 Free up all storage associated with a list of template names obtained with
 412 <link linkend="lgl-db-get-brand-list"><function>lgl_db_get_brand_list()</function></link>.</para>
 413 <para>
 414 </para><variablelist role="params">
 415 <varlistentry><term><parameter>brands</parameter>&#160;:</term>
 416 <listitem><simpara> List of template brand strings to be freed.
 417 </simpara></listitem></varlistentry>
 418 </variablelist></refsect2>
 419 <refsect2 id="lgl-db-register-template" role="function">
 420 <title>lgl_db_register_template ()</title>
 421 <indexterm zone="lgl-db-register-template"><primary sortas="lgl_db_register_template">lgl_db_register_template</primary></indexterm><programlisting><link linkend="lglDbRegStatus">lglDbRegStatus</link>      lgl_db_register_template            (const <link linkend="lglTemplate">lglTemplate</link> *template);</programlisting>
 422 <para>
 423 Register a template.  This function adds a template to the template database.
 424 The template will be stored in an individual XML file in the user template directory.</para>
 425 <para>
 426 </para><variablelist role="params">
 427 <varlistentry><term><parameter>template</parameter>&#160;:</term>
 428 <listitem><simpara>  Pointer to a template structure to add to database.
 429 </simpara></listitem></varlistentry>
 430 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> Status of registration attempt (<link linkend="lglDbRegStatus"><type>lglDbRegStatus</type></link>)
 431 </simpara></listitem></varlistentry>
 432 </variablelist></refsect2>
 433 <refsect2 id="lgl-db-does-template-exist" role="function">
 434 <title>lgl_db_does_template_exist ()</title>
 435 <indexterm zone="lgl-db-does-template-exist"><primary sortas="lgl_db_does_template_exist">lgl_db_does_template_exist</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            lgl_db_does_template_exist          (const <link linkend="gchar">gchar</link> *brand,
 436                                                          const <link linkend="gchar">gchar</link> *part);</programlisting>
 437 <para>
 438 This function tests whether a template with the given brand and part name/number exists.</para>
 439 <para>
 440 </para><variablelist role="params">
 441 <varlistentry><term><parameter>brand</parameter>&#160;:</term>
 442 <listitem><simpara> Brand name.
 443 </simpara></listitem></varlistentry>
 444 <varlistentry><term><parameter>part</parameter>&#160;:</term>
 445 <listitem><simpara>  Part name/number.
 446 </simpara></listitem></varlistentry>
 447 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>  TRUE if such a template exists in the database.
 448 </simpara></listitem></varlistentry>
 449 </variablelist></refsect2>
 450 <refsect2 id="lgl-db-does-template-name-exist" role="function">
 451 <title>lgl_db_does_template_name_exist ()</title>
 452 <indexterm zone="lgl-db-does-template-name-exist"><primary sortas="lgl_db_does_template_name_exist">lgl_db_does_template_name_exist</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            lgl_db_does_template_name_exist     (const <link linkend="gchar">gchar</link> *name);</programlisting>
 453 <para>
 454 This function test whether a template with the given name exists.</para>
 455 <para>
 456 </para><variablelist role="params">
 457 <varlistentry><term><parameter>name</parameter>&#160;:</term>
 458 <listitem><simpara> name string
 459 </simpara></listitem></varlistentry>
 460 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> TRUE if such a template exists in the database.
 461
 462 </simpara></listitem></varlistentry>
 463 </variablelist></refsect2>
 464 <refsect2 id="lgl-db-get-template-name-list-unique" role="function">
 465 <title>lgl_db_get_template_name_list_unique ()</title>
 466 <indexterm zone="lgl-db-get-template-name-list-unique"><primary sortas="lgl_db_get_template_name_list_unique">lgl_db_get_template_name_list_unique</primary></indexterm><programlisting><link linkend="GList">GList</link> *             lgl_db_get_template_name_list_unique
 467                                                         (const <link linkend="gchar">gchar</link> *brand,
 468                                                          const <link linkend="gchar">gchar</link> *paper_id,
 469                                                          const <link linkend="gchar">gchar</link> *category_id);</programlisting>
 470 <para>
 471 Get a list of valid names of unique templates in the template database.  Results
 472 can be filtered by page size and/or template category.  A list of valid page sizes
 473 can be obtained using <link linkend="lgl-db-get-paper-id-list"><function>lgl_db_get_paper_id_list()</function></link>.  A list of valid template categories
 474 can be obtained using <link linkend="lgl-db-get-category-id-list"><function>lgl_db_get_category_id_list()</function></link>.
 475 </para>
 476 <para>
 477 This function differs from <link linkend="lgl-db-get-template-name-list-all"><function>lgl_db_get_template_name_list_all()</function></link>, because it does not
 478 return multiple names for the same template.</para>
 479 <para>
 480 </para><variablelist role="params">
 481 <varlistentry><term><parameter>brand</parameter>&#160;:</term>
 482 <listitem><simpara>     If non NULL, limit results to given brand
 483 </simpara></listitem></varlistentry>
 484 <varlistentry><term><parameter>paper_id</parameter>&#160;:</term>
 485 <listitem><simpara> If non NULL, limit results to given page size.
 486 </simpara></listitem></varlistentry>
 487 <varlistentry><term><parameter>category_id</parameter>&#160;:</term>
 488 <listitem><simpara> If non NULL, limit results to given template category.
 489 </simpara></listitem></varlistentry>
 490 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a list of template names.
 491 </simpara></listitem></varlistentry>
 492 </variablelist></refsect2>
 493 <refsect2 id="lgl-db-get-template-name-list-all" role="function">
 494 <title>lgl_db_get_template_name_list_all ()</title>
 495 <indexterm zone="lgl-db-get-template-name-list-all"><primary sortas="lgl_db_get_template_name_list_all">lgl_db_get_template_name_list_all</primary></indexterm><programlisting><link linkend="GList">GList</link> *             lgl_db_get_template_name_list_all   (const <link linkend="gchar">gchar</link> *brand,
 496                                                          const <link linkend="gchar">gchar</link> *paper_id,
 497                                                          const <link linkend="gchar">gchar</link> *category_id);</programlisting>
 498 <para>
 499 Get a list of all valid names and aliases of templates in the template database.
 500 Results can be filtered by page size and/or template category.  A list of valid page
 501 sizes can be obtained using <link linkend="lgl-db-get-paper-id-list"><function>lgl_db_get_paper_id_list()</function></link>.  A list of valid template
 502 categories can be obtained using <link linkend="lgl-db-get-category-id-list"><function>lgl_db_get_category_id_list()</function></link>.
 503 </para>
 504 <para>
 505 This function differs from <link linkend="lgl-db-get-template-name-list-unique"><function>lgl_db_get_template_name_list_unique()</function></link>, because it will
 506 return multiple names for the same template.</para>
 507 <para>
 508 </para><variablelist role="params">
 509 <varlistentry><term><parameter>brand</parameter>&#160;:</term>
 510 <listitem><simpara>     If non NULL, limit results to given brand
 511 </simpara></listitem></varlistentry>
 512 <varlistentry><term><parameter>paper_id</parameter>&#160;:</term>
 513 <listitem><simpara> If non NULL, limit results to given page size.
 514 </simpara></listitem></varlistentry>
 515 <varlistentry><term><parameter>category_id</parameter>&#160;:</term>
 516 <listitem><simpara> If non NULL, limit results to given template category.
 517 </simpara></listitem></varlistentry>
 518 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a list of template names and aliases.
 519 </simpara></listitem></varlistentry>
 520 </variablelist></refsect2>
 521 <refsect2 id="lgl-db-free-template-name-list" role="function">
 522 <title>lgl_db_free_template_name_list ()</title>
 523 <indexterm zone="lgl-db-free-template-name-list"><primary sortas="lgl_db_free_template_name_list">lgl_db_free_template_name_list</primary></indexterm><programlisting><link linkend="void">void</link>                lgl_db_free_template_name_list      (<link linkend="GList">GList</link> *names);</programlisting>
 524 <para>
 525 Free up all storage associated with a list of template names obtained with
 526 <link linkend="lgl-db-get-template-name-list-all"><function>lgl_db_get_template_name_list_all()</function></link> or <link linkend="lgl-db-get-template-name-list-unique"><function>lgl_db_get_template_name_list_unique()</function></link>.</para>
 527 <para>
 528 </para><variablelist role="params">
 529 <varlistentry><term><parameter>names</parameter>&#160;:</term>
 530 <listitem><simpara> List of template name strings to be freed.
 531 </simpara></listitem></varlistentry>
 532 </variablelist></refsect2>
 533 <refsect2 id="lgl-db-lookup-template-from-name" role="function">
 534 <title>lgl_db_lookup_template_from_name ()</title>
 535 <indexterm zone="lgl-db-lookup-template-from-name"><primary sortas="lgl_db_lookup_template_from_name">lgl_db_lookup_template_from_name</primary></indexterm><programlisting><link linkend="lglTemplate">lglTemplate</link> *       lgl_db_lookup_template_from_name    (const <link linkend="gchar">gchar</link> *name);</programlisting>
 536 <para>
 537 Lookup template in template database from name string.</para>
 538 <para>
 539 </para><variablelist role="params">
 540 <varlistentry><term><parameter>name</parameter>&#160;:</term>
 541 <listitem><simpara> name string
 542 </simpara></listitem></varlistentry>
 543 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> pointer to a newly allocated <link linkend="lglTemplate"><type>lglTemplate</type></link> structure.
 544
 545 </simpara></listitem></varlistentry>
 546 </variablelist></refsect2>
 547 <refsect2 id="lgl-db-print-known-papers" role="function">
 548 <title>lgl_db_print_known_papers ()</title>
 549 <indexterm zone="lgl-db-print-known-papers"><primary sortas="lgl_db_print_known_papers">lgl_db_print_known_papers</primary></indexterm><programlisting><link linkend="void">void</link>                lgl_db_print_known_papers           (void);</programlisting>
 550 <para>
 551 For debugging purposes: print a list of all paper definitions known to
 552 libglabels.</para>
 553 <para>
 554 </para></refsect2>
 555 <refsect2 id="lgl-db-print-known-categories" role="function">
 556 <title>lgl_db_print_known_categories ()</title>
 557 <indexterm zone="lgl-db-print-known-categories"><primary sortas="lgl_db_print_known_categories">lgl_db_print_known_categories</primary></indexterm><programlisting><link linkend="void">void</link>                lgl_db_print_known_categories       (void);</programlisting>
 558 <para>
 559 For debugging purposes: print a list of all category definitions known to
 560 libglabels.</para>
 561 <para>
 562 </para></refsect2>
 563 <refsect2 id="lgl-db-print-known-templates" role="function">
 564 <title>lgl_db_print_known_templates ()</title>
 565 <indexterm zone="lgl-db-print-known-templates"><primary sortas="lgl_db_print_known_templates">lgl_db_print_known_templates</primary></indexterm><programlisting><link linkend="void">void</link>                lgl_db_print_known_templates        (void);</programlisting>
 566 <para>
 567 Print all known templates (for debugging purposes).</para>
 568 <para>
 569 </para></refsect2>
 570 <refsect2 id="lgl-db-print-aliases" role="function">
 571 <title>lgl_db_print_aliases ()</title>
 572 <indexterm zone="lgl-db-print-aliases"><primary sortas="lgl_db_print_aliases">lgl_db_print_aliases</primary></indexterm><programlisting><link linkend="void">void</link>                lgl_db_print_aliases                (const <link linkend="lglTemplate">lglTemplate</link> *template);</programlisting>
 573 <para>
 574 Print all aliases of a template (for debugging purposes).</para>
 575 <para>
 576 </para><variablelist role="params">
 577 <varlistentry><term><parameter>template</parameter>&#160;:</term>
 578 <listitem><simpara> template
 579 </simpara></listitem></varlistentry>
 580 </variablelist></refsect2>
 581
 582 </refsect1>
 583
 584
 585
 586
 587 </refentry>