## Database

Database — Database of pre-defined templates

## Functions

void | lgl_db_init ()
void | ( *lglDbNotifyFunc ) ()
gulong | lgl_db_notify_add ()
void | lgl_db_notify_remove ()
GList * | lgl_db_get_paper_id_list ()
void | lgl_db_free_paper_id_list ()
GList * | lgl_db_get_paper_name_list ()
void | lgl_db_free_paper_name_list ()
lglPaper * | lgl_db_lookup_paper_from_id ()
lglPaper * | lgl_db_lookup_paper_from_name ()
gchar * | lgl_db_lookup_paper_id_from_name ()
gchar * | lgl_db_lookup_paper_name_from_id ()
gboolean | lgl_db_is_paper_id_known ()
gboolean | lgl_db_is_paper_id_other ()
GList * | lgl_db_get_category_id_list ()
void | lgl_db_free_category_id_list ()
GList * | lgl_db_get_category_name_list ()
void | lgl_db_free_category_name_list ()
lglCategory * | lgl_db_lookup_category_from_id ()
lglCategory * | lgl_db_lookup_category_from_name ()
gchar * | lgl_db_lookup_category_id_from_name ()
gchar * | lgl_db_lookup_category_name_from_id ()
gboolean | lgl_db_is_category_id_known ()
GList * | lgl_db_get_brand_list ()
void | lgl_db_free_brand_list ()
lglDbRegStatus | lgl_db_register_template ()
lglDbDeleteStatus | lgl_db_delete_template_by_brand_part ()
lglDbDeleteStatus | lgl_db_delete_template_by_name ()
gboolean | lgl_db_does_template_exist ()
gboolean | lgl_db_does_template_name_exist ()
GList * | lgl_db_get_template_name_list_all ()
GList * | lgl_db_get_similar_template_name_list ()
void | lgl_db_free_template_name_list ()
lglTemplate * | lgl_db_lookup_template_from_name ()
lglTemplate * | lgl_db_lookup_template_from_brand_part ()
GList * | lgl_db_get_vendor_name_list ()
void | lgl_db_free_vendor_name_list ()
gboolean | lgl_db_is_vendor_name_known ()
lglVendor * | lgl_db_lookup_vendor_from_name ()
void | lgl_db_print_known_papers ()
void | lgl_db_print_known_categories ()
void | lgl_db_print_known_templates ()
void | lgl_db_print_known_vendors ()

## Types and Values

enum | lglDbRegStatus
enum | lglDbDeleteStatus

## Includes

    #include <libglabels/lgl-db.h>

## Description

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

## Functions

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

## Types and Values

### enum lglDbRegStatus

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

#### Members

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

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

#### Members

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