## Database

Database — Database related functions

## Stability Level

Unstable, unless otherwise indicated

## Functions

GQuark | font_manager_database_error_quark ()
const gchar * | font_manager_database_get_type_name ()
gchar * | font_manager_database_get_file ()
FontManagerDatabase * | font_manager_database_new ()
void | font_manager_database_open ()
void | font_manager_database_begin_transaction ()
void | font_manager_database_commit_transaction ()
void | font_manager_database_execute_query ()
gint | font_manager_database_get_version ()
void | font_manager_database_set_version ()
void | font_manager_database_vacuum ()
void | font_manager_database_initialize ()
void | font_manager_database_attach ()
void | font_manager_database_detach ()
JsonObject * | font_manager_database_get_object ()
FontManagerDatabaseIterator * | font_manager_database_iterator ()
FontManagerDatabaseIterator * | font_manager_database_iterator_new ()
gboolean | font_manager_database_iterator_next ()
sqlite3_stmt * | font_manager_database_iterator_get ()
FontManagerDatabase * | font_manager_get_database ()
gboolean | font_manager_update_database_sync ()
void | font_manager_update_database ()
gboolean | font_manager_update_database_finish ()
void | font_manager_get_matching_families_and_fonts ()

## Properties

char * | file | Read / Write

## Types and Values

#define | FONT_MANAGER_CURRENT_DATABASE_VERSION
#define | FONT_MANAGER_TYPE_DATABASE
#define | FONT_MANAGER_TYPE_DATABASE_ITERATOR
enum | FontManagerDatabaseError
#define | FONT_MANAGER_TYPE_DATABASE_ERROR
struct | FontManagerDatabase
enum | FontManagerDatabaseType
#define | FONT_MANAGER_TYPE_DATABASE_TYPE
| FontManagerDatabaseIterator

## Object Hierarchy

        GEnum
        ├── FontManagerDatabaseError
        ╰── FontManagerDatabaseType
        GObject
        ├── FontManagerDatabase
        ╰── FontManagerDatabaseIterator

## Includes

    #include <font-manager-database.h>

## Description

Database class and related functions.

The current design uses a three separate database files. The first holds information required for basic font identification, the second holds all the metadata extracted from the font file itself and the third has information related to orthography support.

These are then attached to the "base" database for access.

## Functions

### font_manager_database_error_quark ()

    GQuark
    font_manager_database_error_quark ();

### font_manager_database_get_type_name ()

    const gchar *
    font_manager_database_get_type_name (FontManagerDatabaseType type);

#### Parameters

type | FontManagerDatabaseType |

#### Returns

Database type name

### font_manager_database_get_file ()

    gchar *
    font_manager_database_get_file (FontManagerDatabaseType type);

#### Parameters

type | FontManagerDatabaseType |

#### Returns

A newly allocated string or `NULL`.

[nullable]

### font_manager_database_new ()

    FontManagerDatabase *
    font_manager_database_new (void);

#### Returns

FontManagerDatabase.

[transfer full]

### font_manager_database_open ()

    void
    font_manager_database_open (FontManagerDatabase *self,
                                GError **error);

Open database.

Note: It is not necessary to call this function in normal usage. The methods provided by this class will open the database if needed.

#### Parameters

self | FontManagerDatabase |
error | GError or `NULL` to ignore errors. | [nullable]

### font_manager_database_begin_transaction ()

    void
    font_manager_database_begin_transaction
                                   (FontManagerDatabase *self,
                                    GError **error);

Begin a transaction, this should be paired with `font_manager_database_commit_transaction()`.

#### Parameters

self | FontManagerDatabase |
error | GError or `NULL` to ignore errors. | [nullable]

### font_manager_database_commit_transaction ()

    void
    font_manager_database_commit_transaction
                                   (FontManagerDatabase *self,
                                    GError **error);

End a transaction. It is an error to call this function without having previously called `font_manager_database_begin_transaction()`.

#### Parameters

self | FontManagerDatabase |
error | GError or `NULL` to ignore errors. | [nullable]

### font_manager_database_execute_query ()

    void
    font_manager_database_execute_query (FontManagerDatabase *self,
                                         const gchar *sql,
                                         GError **error);

#### Parameters

self | FontManagerDatabase |
sql | Valid SQL query |
error | GError or `NULL` to ignore errors. | [nullable]

### font_manager_database_get_version ()

    gint
    font_manager_database_get_version (FontManagerDatabase *self,
                                       GError **error);

#### Parameters

self | FontManagerDatabase |
error | GError or `NULL` to ignore errors. | [nullable]

#### Returns

Database schema version or -1 on error.

### font_manager_database_set_version ()

    void
    font_manager_database_set_version (FontManagerDatabase *self,
                                       int version,
                                       GError **error);

Set database schema version.

#### Parameters

self | FontManagerDatabase |
version | version number |
error | GError or `NULL` to ignore errors. | [nullable]

### font_manager_database_vacuum ()

    void
    font_manager_database_vacuum (FontManagerDatabase *self,
                                  GError **error);

Run sqlite3 VACUUM command on currently selected database.

#### Parameters

self | FontManagerDatabase |
error | GError or `NULL` to ignore errors. | [nullable]

### font_manager_database_initialize ()

    void
    font_manager_database_initialize (FontManagerDatabase *self,
                                      FontManagerDatabaseType type,
                                      GError **error);

Ensures database is at latest schema version. Creates required tables if needed.

#### Parameters

self | FontManagerDatabase instance |
type | FontManagerDatabaseType |
error | GError or `NULL` to ignore errors. | [nullable]

### font_manager_database_attach ()

    void
    font_manager_database_attach (FontManagerDatabase *self,
                                  FontManagerDatabaseType type,
                                  GError **error);

Attaches speficied database.

#### Parameters

self | FontManagerDatabase instance |
type | FontManagerDatabaseType |
error | GError or `NULL` to ignore errors. | [nullable]

### font_manager_database_detach ()

    void
    font_manager_database_detach (FontManagerDatabase *self,
                                  FontManagerDatabaseType type,
                                  GError **error);

Detaches speficied database.

#### Parameters

self | FontManagerDatabase instance |
type | FontManagerDatabaseType |
error | GError or `NULL` to ignore errors. | [nullable]

### font_manager_database_get_object ()

    JsonObject *
    font_manager_database_get_object (FontManagerDatabase *self,
                                      const gchar *sql,
                                      GError **error);

#### Parameters

self | FontManagerDatabase |
sql | SQL query |
error | GError or `NULL` to ignore errors |

#### Returns

JsonObject representation of first result, `NULL` if there were no results or there was an error.

[transfer full][nullable]

### font_manager_database_iterator ()

    FontManagerDatabaseIterator *
    font_manager_database_iterator (FontManagerDatabase *self);

#### Parameters

self | FontManagerDatabase |

#### Returns

FontManagerDatabaseIterator. Free the return object using `g_object_unref()`.

[transfer full]

### font_manager_database_iterator_new ()

    FontManagerDatabaseIterator *
    font_manager_database_iterator_new (FontManagerDatabase *db);

#### Parameters

db | FontManagerDatabase |

#### Returns

A newly created FontManagerDatabaseIterator. Free the returned object using `g_object_unref()`.

[transfer full]

### font_manager_database_iterator_next ()

    gboolean
    font_manager_database_iterator_next (FontManagerDatabaseIterator *self);

### font_manager_database_iterator_get ()

    sqlite3_stmt *
    font_manager_database_iterator_get (FontManagerDatabaseIterator *self);

[skip]

#### Parameters

self | FontManagerDatabase |

#### Returns

sqlite3_stmt.

[transfer none]

### font_manager_get_database ()

    FontManagerDatabase *
    font_manager_get_database (FontManagerDatabaseType type,
                               GError **error);

Convenience function which initializes the database and sets default options.

#### Parameters

type | FontManagerDatabaseType |
error | GError or `NULL` to ignore errors. | [nullable]

#### Returns

The requested FontManagerDatabase or `NULL` on error. Free the returned object using ``g_object_unref()``.

[transfer full][nullable]

### font_manager_update_database_sync ()

    gboolean
    font_manager_update_database_sync (FontManagerDatabase *db,
                                       FontManagerDatabaseType type,
                                       JsonObject *available_fonts,
                                       FontManagerStringSet *available_files,
                                       FontManagerProgressCallback progress,
                                       GCancellable *cancellable,
                                       GError **error);

Update application database as needed.

#### Parameters

db | FontManagerDatabase instance |
type | FontManagerDatabaseType |
available_fonts | JsonObject returned by font_manager_list_available_fonts |
available_files | FontManagerStringSet containing filepaths for all available font files |
progress | FontManagerProgressCallback. | [scope call][nullable]
cancellable | GCancellable or `NULL`. | [nullable]
error | GError or `NULL` to ignore errors. | [nullable]

#### Returns

`TRUE` on success

### font_manager_update_database ()

    void
    font_manager_update_database (FontManagerDatabase *db,
                                  FontManagerDatabaseType type,
                                  JsonObject *available_fonts,
                                  FontManagerStringSet *available_files,
                                  FontManagerProgressCallback progress,
                                  GCancellable *cancellable,
                                  GAsyncReadyCallback callback,
                                  gpointer user_data);

Update application database as needed.

#### Parameters

db | FontManagerDatabase instance |
type | FontManagerDatabaseType |
available_fonts | JsonObject returned by font_manager_list_available_fonts |
available_files | FontManagerStringSet containing filepaths for all available font files |
progress | FontManagerProgressCallback. | [scope call][nullable]
cancellable | GCancellable or `NULL`. | [nullable]
callback | GAsyncReadyCallback or `NULL`. | [nullable][scope async]
user_data | user data passed to callback or `NULL`. | [nullable]

### font_manager_update_database_finish ()

    gboolean
    font_manager_update_database_finish (GAsyncResult *result,
                                         GError **error);

#### Parameters

result | GAsyncResult |
error | GError or `NULL` to ignore errors. | [nullable]

#### Returns

`TRUE` on success

### font_manager_get_matching_families_and_fonts ()

    void
    font_manager_get_matching_families_and_fonts
                                   (FontManagerDatabase *db,
                                    FontManagerStringSet *families,
                                    FontManagerStringSet *fonts,
                                    const gchar *sql,
                                    GError **error);

Query MUST return two result columns. The first containing the family name and the second containing the font description.

#### Parameters

db | FontManagerDatabase |
families | FontManagerStringSet |
fonts | FontManagerStringSet |
sql | SQL query to execute |
error | GError or `NULL` to ignore errors |

## Types and Values

### FONT_MANAGER_CURRENT_DATABASE_VERSION

    #define FONT_MANAGER_CURRENT_DATABASE_VERSION 17

### FONT_MANAGER_TYPE_DATABASE

    #define FONT_MANAGER_TYPE_DATABASE (font_manager_database_get_type ())

### FONT_MANAGER_TYPE_DATABASE_ITERATOR

    #define FONT_MANAGER_TYPE_DATABASE_ITERATOR (font_manager_database_iterator_get_type())

### enum FontManagerDatabaseError

These errors map directly to SQLite error codes. See https://sqlite.org/rescode.html for more detailed information.

#### Members

FONT_MANAGER_DATABASE_ERROR_OK | SQLITE_OK |
FONT_MANAGER_DATABASE_ERROR_ERROR | SQLITE_ERROR |
FONT_MANAGER_DATABASE_ERROR_INTERNAL | SQLITE_INTERNAL |
FONT_MANAGER_DATABASE_ERROR_PERM | SQLITE_PERM |
FONT_MANAGER_DATABASE_ERROR_ABORT | SQLITE_ABORT |
FONT_MANAGER_DATABASE_ERROR_BUSY | SQLITE_BUSY |
FONT_MANAGER_DATABASE_ERROR_LOCKED | SQLITE_LOCKED |
FONT_MANAGER_DATABASE_ERROR_NOMEM | SQLITE_NOMEM |
FONT_MANAGER_DATABASE_ERROR_READONLY | SQLITE_READONLY |
FONT_MANAGER_DATABASE_ERROR_INTERRUPT | SQLITE_INTERRUPT |
FONT_MANAGER_DATABASE_ERROR_IOERR | SQLITE_IOERR |
FONT_MANAGER_DATABASE_ERROR_CORRUPT | SQLITE_CORRUPT |
FONT_MANAGER_DATABASE_ERROR_NOTFOUND | SQLITE_NOTFOUND |
FONT_MANAGER_DATABASE_ERROR_FULL | SQLITE_FULL |
FONT_MANAGER_DATABASE_ERROR_CANTOPEN | SQLITE_CANTOPEN |
FONT_MANAGER_DATABASE_ERROR_PROTOCOL | SQLITE_PROTOCOL |
FONT_MANAGER_DATABASE_ERROR_EMPTY | SQLITE_EMPTY |
FONT_MANAGER_DATABASE_ERROR_SCHEMA | SQLITE_SCHEMA |
FONT_MANAGER_DATABASE_ERROR_TOOBIG | SQLITE_TOOBIG |
FONT_MANAGER_DATABASE_ERROR_CONSTRAINT | SQLITE_CONSTRAINT |
FONT_MANAGER_DATABASE_ERROR_MISMATCH | SQLITE_MISMATCH |
FONT_MANAGER_DATABASE_ERROR_MISUSE | SQLITE_MISUSE |
FONT_MANAGER_DATABASE_ERROR_NOLFS | SQLITE_NOLFS |
FONT_MANAGER_DATABASE_ERROR_AUTH | SQLITE_AUTH |
FONT_MANAGER_DATABASE_ERROR_FORMAT | SQLITE_FORMAT |
FONT_MANAGER_DATABASE_ERROR_RANGE | SQLITE_RANGE |
FONT_MANAGER_DATABASE_ERROR_NOTADB | SQLITE_NOTADB |
FONT_MANAGER_DATABASE_ERROR_NOTICE | SQLITE_NOTICE |
FONT_MANAGER_DATABASE_ERROR_WARNING | SQLITE_WARNING |
FONT_MANAGER_DATABASE_ERROR_ROW | SQLITE_ROW |
FONT_MANAGER_DATABASE_ERROR_DONE | SQLITE_DONE |

### FONT_MANAGER_TYPE_DATABASE_ERROR

    #define FONT_MANAGER_TYPE_DATABASE_ERROR (font_manager_database_error_get_type ())

### struct FontManagerDatabase

    struct FontManagerDatabase;

### enum FontManagerDatabaseType

#### Members

FONT_MANAGER_DATABASE_TYPE_BASE | Base database file |
FONT_MANAGER_DATABASE_TYPE_FONT | Font style information |
FONT_MANAGER_DATABASE_TYPE_METADATA | Font metadata |
FONT_MANAGER_DATABASE_TYPE_ORTHOGRAPHY | Orthography data |

### FONT_MANAGER_TYPE_DATABASE_TYPE

    #define FONT_MANAGER_TYPE_DATABASE_TYPE (font_manager_database_type_get_type ())

### FontManagerDatabaseIterator

    typedef struct _FontManagerDatabaseIterator FontManagerDatabaseIterator;

## Property Details

### The `“file”` property

      “file”                     char *

Filepath to database.

Owner: FontManagerDatabase

Flags: Read / Write

Default value: NULL