LibGlabels 3.0 Reference Manual | ||||
---|---|---|---|---|
Top | Description |
#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
);
This section describes a set of functions to locate and add templates and related information in the LibGlabels template database.
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()
.
Registration successful. | |
Registration failed because paper id is unknown. | |
Registration failed because template with same brand and part name/number already exists. | |
Registration failed because an error while writing to disk. |
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()
.
Deletion successful. | |
Deletion failed because template with given brand and part name/number does not exist. | |
Deletion failed because given template is not a user defined template. | |
Deletion failed because of an error while attempting to remove template from disk. |
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.
void (*lglDbNotifyFunc) (gpointer user_data
);
Defines the type of notify callback function to be called when database changes.
|
Pointer to user data that is passed to the notify function. |
gulong lgl_db_notify_add (lglDbNotifyFunc func
,gpointer user_data
);
Register a notification callback function to be called when the database changes.
|
Callback function to be called when database changes. |
|
Passback user data to supply to callback function. |
Returns : |
an ID for this notification registration. |
void lgl_db_notify_remove (gulong id
);
Cancel a previous registration a notification callback function.
|
ID of notification registration to cancel (see lgl_db_notify_add() ). |
GList * lgl_db_get_paper_id_list (void
);
Get a list of all paper ids known to libglabels.
Returns : |
a list of paper ids. |
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()
.
|
List of id strings to be freed. |
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. |
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()
.
|
List of localized paper name strings to be freed. |
lglPaper * lgl_db_lookup_paper_from_id (const gchar *id
);
Lookup paper definition from id string.
|
paper id string |
Returns : |
pointer to a newly allocated lglPaper structure. |
lglPaper * lgl_db_lookup_paper_from_name (const gchar *name
);
Lookup paper definition from localized paper name string.
|
localized paper name string |
Returns : |
pointer to a newly allocated lglPaper structure. |
gchar * lgl_db_lookup_paper_id_from_name (const gchar *name
);
Lookup paper name string from localized paper name string.
|
localized paper name stringp |
Returns : |
pointer to a newly allocated id string. |
gchar * lgl_db_lookup_paper_name_from_id (const gchar *id
);
Lookup localized paper name string from paper id string.
|
paper id string |
Returns : |
pointer to a newly allocated localized paper name string. |
gboolean lgl_db_is_paper_id_known (const gchar *id
);
Determine if given paper id is known to libglabels.
|
paper id to test |
Returns : |
TRUE if id is known, otherwise FALSE. |
gboolean lgl_db_is_paper_id_other (const gchar *id
);
Determine if given paper id is the special id "Other."
|
paper id to test |
Returns : |
TRUE if id is "Other", otherwise FALSE. |
GList * lgl_db_get_category_id_list (void
);
Get a list of all category ids known to libglabels.
Returns : |
a list of category ids. |
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()
.
|
List of id strings to be freed. |
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. |
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()
.
|
List of localized category name strings to be freed. |
lglCategory * lgl_db_lookup_category_from_id (const gchar *id
);
Lookup category definition from id string.
|
category id string |
Returns : |
pointer to a newly allocated lglCategory structure. |
lglCategory * lgl_db_lookup_category_from_name (const gchar *name
);
Lookup category definition from localized category name string.
|
localized category name string |
Returns : |
pointer to a newly allocated lglCategory structure. |
gchar * lgl_db_lookup_category_id_from_name (const gchar *name
);
Lookup category name string from localized category name string.
|
localized category name stringp |
Returns : |
pointer to a newly allocated id string. |
gchar * lgl_db_lookup_category_name_from_id (const gchar *id
);
Lookup localized category name string from category id string.
|
category id string |
Returns : |
pointer to a newly allocated localized category name string. |
gboolean lgl_db_is_category_id_known (const gchar *id
);
Determine if given category id is known to libglabels.
|
category id to test |
Returns : |
TRUE if id is known, otherwise FALSE. |
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()
.
|
If non NULL, limit results to given page size. |
|
If non NULL, limit results to given template category. |
Returns : |
a list of brands |
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()
.
|
List of template brand strings to be freed. |
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.
|
Pointer to a template structure to add to database. |
Returns : |
Status of registration attempt (lglDbRegStatus) |
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 name or vendor of template to be deleted. |
|
Part name or number of template to be deleted. |
Returns : |
Status of registration attempt (lglDbDeleteStatus) |
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 of template to be deleted. |
Returns : |
Status of registration attempt (lglDbDeleteStatus) |
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 name. |
|
Part name/number. |
Returns : |
TRUE if such a template exists in the database. |
gboolean lgl_db_does_template_name_exist (const gchar *name
);
This function test whether a template with the given name exists.
|
name string |
Returns : |
TRUE if such a template exists in the database. |
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()
.
|
If non NULL, limit results to given brand |
|
If non NULL, limit results to given page size. |
|
If non NULL, limit results to given template category. |
Returns : |
a list of template names. |
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 of template under test. |
Returns : |
a list of template names. |
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()
.
|
List of template name strings to be freed. |
lglTemplate * lgl_db_lookup_template_from_name (const gchar *name
);
Lookup template in template database from name string.
|
name string |
Returns : |
pointer to a newly allocated lglTemplate structure. |
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 name string |
|
part name string |
Returns : |
pointer to a newly allocated lglTemplate structure. |
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. |
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()
.
|
List of localized vendor name strings to be freed. |
gboolean lgl_db_is_vendor_name_known (const gchar *name
);
Determine if given vendor id is known to libglabels.
|
vendor name to test |
Returns : |
TRUE if id is known, otherwise FALSE. |
lglVendor * lgl_db_lookup_vendor_from_name (const gchar *name
);
Lookup vendor definition from localized vendor name string.
|
localized vendor name string |
Returns : |
pointer to a newly allocated lglVendor structure. |
void lgl_db_print_known_papers (void
);
For debugging purposes: print a list of all paper definitions known to libglabels.
void lgl_db_print_known_categories (void
);
For debugging purposes: print a list of all category definitions known to libglabels.
void lgl_db_print_known_templates (void
);
Print all known templates (for debugging purposes).