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

## Synopsis

    #include <libglabels/lgl-db.h>

    enum                lglDbRegStatus;
    enum                lglDbDeleteStatus;

    void                lgl_db_init                         (void);

    void                (*lglDbNotifyFunc)                  (gpointer user_data);
    gulong              lgl_db_notify_add                   (lglDbNotifyFunc func,
                                                             gpointer user_data);
    void                lgl_db_notify_remove                (gulong id);

    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);
    lglDbDeleteStatus   lgl_db_delete_template_by_brand_part
                                                            (const gchar *brand,
                                                             const gchar *part);
    lglDbDeleteStatus   lgl_db_delete_template_by_name      (const gchar *name);
    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_all   (const gchar *brand,
                                                             const gchar *paper_id,
                                                             const gchar *category_id);
    GList *             lgl_db_get_similar_template_name_list
                                                            (const gchar *name);
    void                lgl_db_free_template_name_list      (GList *names);
    lglTemplate *       lgl_db_lookup_template_from_name    (const gchar *name);
    lglTemplate *       lgl_db_lookup_template_from_brand_part
                                                            (const gchar *brand,
                                                             const gchar *part);

    GList *             lgl_db_get_vendor_name_list         (void);
    void                lgl_db_free_vendor_name_list        (GList *names);
    gboolean            lgl_db_is_vendor_name_known         (const gchar *name);
    lglVendor *         lgl_db_lookup_vendor_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_known_vendors          (void);

## 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.

### enum lglDbDeleteStatus

    typedef enum {
            LGL_DB_DELETE_OK                =  0,
            LGL_DB_DELETE_DOES_NOT_EXIST    = -1,
            LGL_DB_DELETE_NOT_USER_DEFINED  = -2,
            LGL_DB_DELETE_FILE_ERROR        = -3
    } lglDbDeleteStatus;

This enumeration defines a set of possible return values for `lgl_db_delete_template_by_name()` or `lgl_db_delete_template_by_brand_part()`.

`LGL_DB_DELETE_OK` | Deletion successful.
`LGL_DB_DELETE_DOES_NOT_EXIST` | Deletion failed because template with given brand and part name/number does not exist.
`LGL_DB_DELETE_NOT_USER_DEFINED` | Deletion failed because given template is not a user defined template.
`LGL_DB_DELETE_FILE_ERROR` | Deletion failed because of an error while attempting to remove template from 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, vendor definitions, and its template database. It will search both system and user template directories to locate this data.

### lglDbNotifyFunc ()

    void                (*lglDbNotifyFunc)                  (gpointer user_data);

Defines the type of notify callback function to be called when database changes.

`user_data` : | Pointer to user data that is passed to the notify function.

### lgl_db_notify_add ()

    gulong              lgl_db_notify_add                   (lglDbNotifyFunc func,
                                                             gpointer user_data);

Register a notification callback function to be called when the database changes.

`func` : | Callback function to be called when database changes.
`user_data` : | Passback user data to supply to callback function.
Returns : | an ID for this notification registration.

### lgl_db_notify_remove ()

    void                lgl_db_notify_remove                (gulong id);

Cancel a previous registration a notification callback function.

`id` : | ID of notification registration to cancel (see `lgl_db_notify_add()`).

### 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_delete_template_by_brand_part ()

    lglDbDeleteStatus   lgl_db_delete_template_by_brand_part
                                                            (const gchar *brand,
                                                             const gchar *part);

Delete a user defined template. This function deletes a template from the template database. The individual XML file in the user template directory will also be removed.

`brand` : | Brand name or vendor of template to be deleted.
`part` : | Part name or number of template to be deleted.
Returns : | Status of registration attempt (lglDbDeleteStatus)

### lgl_db_delete_template_by_name ()

    lglDbDeleteStatus   lgl_db_delete_template_by_name      (const gchar *name);

Delete a user defined template. This function deletes a template from the template database. The individual XML file in the user template directory will also be removed.

`name` : | Name of template to be deleted.
Returns : | Status of registration attempt (lglDbDeleteStatus)

### 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_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 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()`.

`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_similar_template_name_list ()

    GList *             lgl_db_get_similar_template_name_list
                                                            (const gchar *name);

Get a list of all valid names of templates in the template database that have the same size and layout characteristics as the given template.

`name` : | Name of template under test.
Returns : | a list of template names.

### 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()`.

`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_lookup_template_from_brand_part ()

    lglTemplate *       lgl_db_lookup_template_from_brand_part
                                                            (const gchar *brand,
                                                             const gchar *part);

Lookup template in template database from brand and part strings.

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

### lgl_db_get_vendor_name_list ()

    GList *             lgl_db_get_vendor_name_list         (void);

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

Returns : | a list of localized vendor names.

### lgl_db_free_vendor_name_list ()

    void                lgl_db_free_vendor_name_list        (GList *names);

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

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

### lgl_db_is_vendor_name_known ()

    gboolean            lgl_db_is_vendor_name_known         (const gchar *name);

Determine if given vendor id is known to libglabels.

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

### lgl_db_lookup_vendor_from_name ()

    lglVendor *         lgl_db_lookup_vendor_from_name      (const gchar *name);

Lookup vendor definition from localized vendor name string.

`name` : | localized vendor name string
Returns : | pointer to a newly allocated lglVendor 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_known_vendors ()

    void                lgl_db_print_known_vendors          (void);

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