Database

## Database Database — Database of pre-defined templates |

## Synopsis

    #include <libglabels/db.h>

    enum                lglDbRegStatus;

    void                lgl_db_init                         (void);

    GList *             lgl_db_get_paper_id_list            (void);
    void                lgl_db_free_paper_id_list           (GList *ids);
    GList *             lgl_db_get_paper_name_list          (void);
    void                lgl_db_free_paper_name_list         (GList *names);
    lglPaper *          lgl_db_lookup_paper_from_id         (const gchar *id);
    lglPaper *          lgl_db_lookup_paper_from_name       (const gchar *name);
    gchar *             lgl_db_lookup_paper_id_from_name    (const gchar *name);
    gchar *             lgl_db_lookup_paper_name_from_id    (const gchar *id);
    gboolean            lgl_db_is_paper_id_known            (const gchar *id);
    gboolean            lgl_db_is_paper_id_other            (const gchar *id);

    GList *             lgl_db_get_category_id_list         (void);
    void                lgl_db_free_category_id_list        (GList *ids);
    GList *             lgl_db_get_category_name_list       (void);
    void                lgl_db_free_category_name_list      (GList *names);
    lglCategory *       lgl_db_lookup_category_from_id      (const gchar *id);
    lglCategory *       lgl_db_lookup_category_from_name    (const gchar *name);
    gchar *             lgl_db_lookup_category_id_from_name (const gchar *name);
    gchar *             lgl_db_lookup_category_name_from_id (const gchar *id);
    gboolean            lgl_db_is_category_id_known         (const gchar *id);

    GList *             lgl_db_get_brand_list               (const gchar *paper_id,
                                                             const gchar *category_id);
    void                lgl_db_free_brand_list              (GList *brands);

    lglDbRegStatus      lgl_db_register_template            (const lglTemplate *template);
    gboolean            lgl_db_does_template_exist          (const gchar *brand,
                                                             const gchar *part);
    gboolean            lgl_db_does_template_name_exist     (const gchar *name);
    GList *             lgl_db_get_template_name_list_unique
                                                            (const gchar *brand,
                                                             const gchar *paper_id,
                                                             const gchar *category_id);
    GList *             lgl_db_get_template_name_list_all   (const gchar *brand,
                                                             const gchar *paper_id,
                                                             const gchar *category_id);
    void                lgl_db_free_template_name_list      (GList *names);
    lglTemplate *       lgl_db_lookup_template_from_name    (const gchar *name);

    void                lgl_db_print_known_papers           (void);
    void                lgl_db_print_known_categories       (void);
    void                lgl_db_print_known_templates        (void);
    void                lgl_db_print_aliases                (const lglTemplate *template);

## Description

This section describes a set of functions to locate and add templates and related information in the LibGlabels template database.

## Details

### enum lglDbRegStatus

    typedef enum
    {
            LGL_DB_REG_OK                =  0,
            LGL_DB_REG_BAD_PAPER_ID      = -1,
            LGL_DB_REG_BRAND_PART_EXISTS = -2,
            LGL_DB_REG_FILE_WRITE_ERROR  = -3
    } lglDbRegStatus;

This enumeration defines a set of possible return values for `lgl_db_register_template()`.

`LGL_DB_REG_OK` | Registration successful.
`LGL_DB_REG_BAD_PAPER_ID` | Registration failed because paper id is unknown.
`LGL_DB_REG_BRAND_PART_EXISTS` | Registration failed because template with same brand and part name/number already exists.
`LGL_DB_REG_FILE_WRITE_ERROR` | Registration failed because an error while writing to disk.

### lgl_db_init ()

    void                lgl_db_init                         (void);

Initialize all libglabels subsystems. It is not necessary for an application to call `lgl_db_init()`, because libglabels will initialize on demand. An application programmer may choose to call `lgl_db_init()` at startup to minimize the impact of the first libglabels call on GUI response time.

This function initializes its paper definitions, category definitions, and its template database.. It will search both system and user template directories to locate this data.

### lgl_db_get_paper_id_list ()

    GList *             lgl_db_get_paper_id_list            (void);

Get a list of all paper ids known to libglabels.

Returns : | a list of paper ids.

### lgl_db_free_paper_id_list ()

    void                lgl_db_free_paper_id_list           (GList *ids);

Free up all storage associated with an id list obtained with `lgl_db_get_paper_id_list()`.

`ids` : | List of id strings to be freed.

### lgl_db_get_paper_name_list ()

    GList *             lgl_db_get_paper_name_list          (void);

Get a list of all localized paper names known to libglabels.

Returns : | a list of localized paper names.

### lgl_db_free_paper_name_list ()

    void                lgl_db_free_paper_name_list         (GList *names);

Free up all storage associated with a name list obtained with `lgl_db_get_paper_name_list()`.

`names` : | List of localized paper name strings to be freed.

### lgl_db_lookup_paper_from_id ()

    lglPaper *          lgl_db_lookup_paper_from_id         (const gchar *id);

Lookup paper definition from id string.

`id` : | paper id string
Returns : | pointer to a newly allocated lglPaper structure.

### lgl_db_lookup_paper_from_name ()

    lglPaper *          lgl_db_lookup_paper_from_name       (const gchar *name);

Lookup paper definition from localized paper name string.

`name` : | localized paper name string
Returns : | pointer to a newly allocated lglPaper structure.

### lgl_db_lookup_paper_id_from_name ()

    gchar *             lgl_db_lookup_paper_id_from_name    (const gchar *name);

Lookup paper name string from localized paper name string.

`name` : | localized paper name stringp
Returns : | pointer to a newly allocated id string.

### lgl_db_lookup_paper_name_from_id ()

    gchar *             lgl_db_lookup_paper_name_from_id    (const gchar *id);

Lookup localized paper name string from paper id string.

`id` : | paper id string
Returns : | pointer to a newly allocated localized paper name string.

### lgl_db_is_paper_id_known ()

    gboolean            lgl_db_is_paper_id_known            (const gchar *id);

Determine if given paper id is known to libglabels.

`id` : | paper id to test
Returns : | TRUE if id is known, otherwise FALSE.

### lgl_db_is_paper_id_other ()

    gboolean            lgl_db_is_paper_id_other            (const gchar *id);

Determine if given paper id is the special id "Other."

`id` : | paper id to test
Returns : | TRUE if id is "Other", otherwise FALSE.

### lgl_db_get_category_id_list ()

    GList *             lgl_db_get_category_id_list         (void);

Get a list of all category ids known to libglabels.

Returns : | a list of category ids.

### lgl_db_free_category_id_list ()

    void                lgl_db_free_category_id_list        (GList *ids);

Free up all storage associated with an id list obtained with `lgl_db_get_category_id_list()`.

`ids` : | List of id strings to be freed.

### lgl_db_get_category_name_list ()

    GList *             lgl_db_get_category_name_list       (void);

Get a list of all localized category names known to libglabels.

Returns : | a list of localized category names.

### lgl_db_free_category_name_list ()

    void                lgl_db_free_category_name_list      (GList *names);

Free up all storage associated with a name list obtained with `lgl_db_get_category_name_list()`.

`names` : | List of localized category name strings to be freed.

### lgl_db_lookup_category_from_id ()

    lglCategory *       lgl_db_lookup_category_from_id      (const gchar *id);

Lookup category definition from id string.

`id` : | category id string
Returns : | pointer to a newly allocated lglCategory structure.

### lgl_db_lookup_category_from_name ()

    lglCategory *       lgl_db_lookup_category_from_name    (const gchar *name);

Lookup category definition from localized category name string.

`name` : | localized category name string
Returns : | pointer to a newly allocated lglCategory structure.

### lgl_db_lookup_category_id_from_name ()

    gchar *             lgl_db_lookup_category_id_from_name (const gchar *name);

Lookup category name string from localized category name string.

`name` : | localized category name stringp
Returns : | pointer to a newly allocated id string.

### lgl_db_lookup_category_name_from_id ()

    gchar *             lgl_db_lookup_category_name_from_id (const gchar *id);

Lookup localized category name string from category id string.

`id` : | category id string
Returns : | pointer to a newly allocated localized category name string.

### lgl_db_is_category_id_known ()

    gboolean            lgl_db_is_category_id_known         (const gchar *id);

Determine if given category id is known to libglabels.

`id` : | category id to test
Returns : | TRUE if id is known, otherwise FALSE.

### lgl_db_get_brand_list ()

    GList *             lgl_db_get_brand_list               (const gchar *paper_id,
                                                             const gchar *category_id);

Get a list of all valid brands of templates in the template database. Results can be filtered by page size and/or template category. A list of valid page sizes can be obtained using `lgl_db_get_paper_id_list()`. A list of valid template categories can be obtained using `lgl_db_get_category_id_list()`.

`paper_id` : | If non NULL, limit results to given page size.
`category_id` : | If non NULL, limit results to given template category.
Returns : | a list of brands

### lgl_db_free_brand_list ()

    void                lgl_db_free_brand_list              (GList *brands);

Free up all storage associated with a list of template names obtained with `lgl_db_get_brand_list()`.

`brands` : | List of template brand strings to be freed.

### lgl_db_register_template ()

    lglDbRegStatus      lgl_db_register_template            (const lglTemplate *template);

Register a template. This function adds a template to the template database. The template will be stored in an individual XML file in the user template directory.

`template` : | Pointer to a template structure to add to database.
Returns : | Status of registration attempt (lglDbRegStatus)

### lgl_db_does_template_exist ()

    gboolean            lgl_db_does_template_exist          (const gchar *brand,
                                                             const gchar *part);

This function tests whether a template with the given brand and part name/number exists.

`brand` : | Brand name.
`part` : | Part name/number.
Returns : | TRUE if such a template exists in the database.

### lgl_db_does_template_name_exist ()

    gboolean            lgl_db_does_template_name_exist     (const gchar *name);

This function test whether a template with the given name exists.

`name` : | name string
Returns : | TRUE if such a template exists in the database.

### lgl_db_get_template_name_list_unique ()

    GList *             lgl_db_get_template_name_list_unique
                                                            (const gchar *brand,
                                                             const gchar *paper_id,
                                                             const gchar *category_id);

Get a list of valid names of unique templates in the template database. Results can be filtered by page size and/or template category. A list of valid page sizes can be obtained using `lgl_db_get_paper_id_list()`. A list of valid template categories can be obtained using `lgl_db_get_category_id_list()`.

This function differs from `lgl_db_get_template_name_list_all()`, because it does not return multiple names for the same template.

`brand` : | If non NULL, limit results to given brand
`paper_id` : | If non NULL, limit results to given page size.
`category_id` : | If non NULL, limit results to given template category.
Returns : | a list of template names.

### lgl_db_get_template_name_list_all ()

    GList *             lgl_db_get_template_name_list_all   (const gchar *brand,
                                                             const gchar *paper_id,
                                                             const gchar *category_id);

Get a list of all valid names and aliases of templates in the template database. Results can be filtered by page size and/or template category. A list of valid page sizes can be obtained using `lgl_db_get_paper_id_list()`. A list of valid template categories can be obtained using `lgl_db_get_category_id_list()`.

This function differs from `lgl_db_get_template_name_list_unique()`, because it will return multiple names for the same template.

`brand` : | If non NULL, limit results to given brand
`paper_id` : | If non NULL, limit results to given page size.
`category_id` : | If non NULL, limit results to given template category.
Returns : | a list of template names and aliases.

### lgl_db_free_template_name_list ()

    void                lgl_db_free_template_name_list      (GList *names);

Free up all storage associated with a list of template names obtained with `lgl_db_get_template_name_list_all()` or `lgl_db_get_template_name_list_unique()`.

`names` : | List of template name strings to be freed.

### lgl_db_lookup_template_from_name ()

    lglTemplate *       lgl_db_lookup_template_from_name    (const gchar *name);

Lookup template in template database from name string.

`name` : | name string
Returns : | pointer to a newly allocated lglTemplate structure.

### lgl_db_print_known_papers ()

    void                lgl_db_print_known_papers           (void);

For debugging purposes: print a list of all paper definitions known to libglabels.

### lgl_db_print_known_categories ()

    void                lgl_db_print_known_categories       (void);

For debugging purposes: print a list of all category definitions known to libglabels.

### lgl_db_print_known_templates ()

    void                lgl_db_print_known_templates        (void);

Print all known templates (for debugging purposes).

### lgl_db_print_aliases ()

    void                lgl_db_print_aliases                (const lglTemplate *template);

Print all aliases of a template (for debugging purposes).

`template` : | template