## gva-util gva-util — Miscellaneous Utilities |

## Synopsis

    gchar *             gva_choose_inpname                  (const gchar *game);
    gchar *             gva_find_data_file                  (const gchar *basename);
    GvaDebugFlags       gva_get_debug_flags                 (void);
    enum                GvaDebugFlags;
    const gchar *       gva_get_last_version                (void);
    gchar *             gva_get_monospace_font_name         (void);
    GSettings *         gva_get_settings                    (void);
    SoupSession *       gva_get_soup_session                (void);
    void                gva_get_time_elapsed                (GTimeVal *start_time,
                                                             GTimeVal *time_elapsed);
    const gchar *       gva_get_user_data_dir               (void);
    void                gva_help_display                    (GtkWindow *parent,
                                                             const gchar *link_id);
    void                gva_save_window_state               (GtkWindow *window,
                                                             const gchar *width_key,
                                                             const gchar *height_key,
                                                             const gchar *maximized_key,
                                                             const gchar *x_key,
                                                             const gchar *y_key);
    gchar *             gva_search_collate_key              (const gchar *string);
    gboolean            gva_spawn_with_pipes                (const gchar *command_line,
                                                             GPid *child_pid,
                                                             gint *standard_input,
                                                             gint *standard_output,
                                                             gint *standard_error,
                                                             GError **error);

## Description

These are miscellaneous utility functions that are used throughout the application.

## Details

### gva_choose_inpname ()

    gchar *             gva_choose_inpname                  (const gchar *game);

Returns the name of a MAME input file for `game` that does not already exist. For example, given the game "pacman" the function will return the first filename that does not already exist: "pacman.inp", "pacman-1.inp", "pacman-2.inp", etc.

`game` : | the name of a game
Returns : | a newly-allocated input filename for `game`

### gva_find_data_file ()

    gchar *             gva_find_data_file                  (const gchar *basename);

Searches for a file named `basename` in a number of standard system-wide directories and returns a newly-allocated string containing the path to the first match. The string should be freed with `g_free()`. If no match is found the function returns `NULL`.

`basename` : | the base name of the file to search for
Returns : | the pathname of the first match, or `NULL` if no match was found

### gva_get_debug_flags ()

    GvaDebugFlags       gva_get_debug_flags                 (void);

Returns a set of bit flags indicating what kinds of debugging messages are enabled through the GVA_DEBUG environment variable.

Returns : | bitwise combination of GvaDebugFlags values

### enum GvaDebugFlags

    typedef enum
    {
            GVA_DEBUG_NONE  = 0,
            GVA_DEBUG_MAME  = 1 << (G_LOG_LEVEL_USER_SHIFT + 0),
            GVA_DEBUG_SQL   = 1 << (G_LOG_LEVEL_USER_SHIFT + 1),
            GVA_DEBUG_IO    = 1 << (G_LOG_LEVEL_USER_SHIFT + 2),
            GVA_DEBUG_INP   = 1 << (G_LOG_LEVEL_USER_SHIFT + 3),
            GVA_DEBUG_GST   = 1 << (G_LOG_LEVEL_USER_SHIFT + 4),
            GVA_DEBUG_HTTP  = 1 << (G_LOG_LEVEL_USER_SHIFT + 5)
    } GvaDebugFlags;

These flags indicate which types of debugging messages will be triggered at runtime. Debugging messages can be triggered by setting the GVA_DEBUG environment variable to a colon-separated list of "mame", "sql", "io", "inp", "gst" and "http".

`GVA_DEBUG_NONE` | Print no messages.
`GVA_DEBUG_MAME` | Print shell commands invoking MAME.
`GVA_DEBUG_SQL` | Print SQL commands to the game database.
`GVA_DEBUG_IO` | Print all communication between GVA and MAME.
`GVA_DEBUG_INP` | Print information about input files.
`GVA_DEBUG_GST` | Print GStreamer activity.
`GVA_DEBUG_HTTP` | Print HTTP communication.

### gva_get_last_version ()

    const gchar *       gva_get_last_version                (void);

Returns the most recently run version of GNOME Video Arcade prior to the current run. This is used to detect GNOME Video Arcade upgrades.

Returns : | the most recently run version of GNOME Video Arcade

### gva_get_monospace_font_name ()

    gchar *             gva_get_monospace_font_name         (void);

Returns the user's preferred fixed-width font name. The return value is a newly-allocated string and should be freed with `g_free()`.

Returns : | the name of a fixed-width font

### gva_get_settings ()

    GSettings *         gva_get_settings                    (void);

Returns the GSettings object loaded with the schema for GNOME Video Arcade.

Returns : | the GSettings object for GNOME Video Arcade

### gva_get_soup_session ()

    SoupSession *       gva_get_soup_session                (void);

Returns a SoupSessionAsync configured to cache responses.

Returns : | the SoupSession object for GNOME Video Arcade

### gva_get_time_elapsed ()

    void                gva_get_time_elapsed                (GTimeVal *start_time,
                                                             GTimeVal *time_elapsed);

Writes the time elapsed since `start_time` to `time_elapsed`. Set the start time by calling `g_get_current_time()`.

`start_time` : | a start time
`time_elapsed` : | location to put the time elasped

### gva_get_user_data_dir ()

    const gchar *       gva_get_user_data_dir               (void);

Returns the directory where user-specific application data is stored. The function also creates the directory the first time it is called.

Returns : | user-specific application data directory

### gva_help_display ()

    void                gva_help_display                    (GtkWindow *parent,
                                                             const gchar *link_id);

Opens the user documentation to the section given by `link_id`, or to the table of contents if `link_id` is `NULL`. If the user documentation cannot be opened, it presents a dialog describing the error. The dialog is set as transient to `parent` if `parent` is `NULL`.

`parent` : | a parent GtkWindow or `NULL`
`link_id` : | help section to present or `NULL`

### gva_save_window_state ()

    void                gva_save_window_state               (GtkWindow *window,
                                                             const gchar *width_key,
                                                             const gchar *height_key,
                                                             const gchar *maximized_key,
                                                             const gchar *x_key,
                                                             const gchar *y_key);

Writes the dimensions, position and maximize state of `window` to the given GSettings keys. If a key name argument is `NULL`, the function will skip writing a value to that setting.

`window` : | a GtkWindow
`width_key` : | name of the window width integer setting, or `NULL`
`height_key` : | name of the window height integer setting, or `NULL`
`maximized_key` : | name of the window maximized boolean setting, or `NULL`
`x_key` : | name of the window X-position integer setting, or `NULL`
`y_key` : | name of the window Y-position integer setting, or `NULL`

### gva_search_collate_key ()

    gchar *             gva_search_collate_key              (const gchar *string);

Converts a string into a collation key that can be compared with other collation keys produced by the same function using `strcmp()`.

Specifically, the function filters out spaces and punctuation from `string` for easier comparison with what a human is likely to type in an interactive search. e.g. Typing "mspacman" will match "Ms. Pac-Man".

`string` : | a string
Returns : | a newly-allocated collation key

### gva_spawn_with_pipes ()

    gboolean            gva_spawn_with_pipes                (const gchar *command_line,
                                                             GPid *child_pid,
                                                             gint *standard_input,
                                                             gint *standard_output,
                                                             gint *standard_error,
                                                             GError **error);

Convenience function that passes `command_line` to `g_shell_parse_argv()`, and passes the resulting argument list to `g_spawn_async_with_pipes()`. If an error occurs, it results `FALSE` and sets `error`.

`command_line` : | a command line
`child_pid` : | return location for child process ID, or `NULL`
`standard_input` : | return location for file descriptor to write to child's stdin, or `NULL`
`standard_output` : | return location for file descriptor to write to child's stdout, or `NULL`
`standard_error` : | return location for file descriptor to write to child's stderr, or `NULL`
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` if successful, `FALSE` if an error occurred