## gva-mame

gva-mame — MAME Communication Backend

## Synopsis

    void                (*GvaMameCallback)                  (const gchar *name,
                                                             const gchar *game_data,
                                                             gpointer user_data);
    const gchar *       gva_mame_get_path_sep               (void);
    gchar *             gva_mame_get_version                (GError **error);
    guint               gva_mame_get_total_supported        (GError **error);
    gchar *             gva_mame_get_config_value           (const gchar *config_key,
                                                             GError **error);
    gboolean            gva_mame_has_config_value           (const gchar *config_key);
    gchar **            gva_mame_get_search_paths           (const gchar *config_key,
                                                             GError **error);
    GList *             gva_mame_get_input_files            (GError **error);
    GvaProcess *        gva_mame_list_xml                   (GError **error);
    gchar *             gva_mame_verify_roms                (const gchar *name,
                                                             GError **error);
    gchar *             gva_mame_verify_samples             (const gchar *name,
                                                             GError **error);
    GvaProcess *        gva_mame_verify_all_roms            (GError **error);
    GvaProcess *        gva_mame_verify_all_samples         (GError **error);
    gboolean            gva_mame_verify_parse               (const gchar *line,
                                                             gchar **out_name,
                                                             gchar **out_status);
    GvaProcess *        gva_mame_run_game                   (const gchar *name,
                                                             GError **error);
    GvaProcess *        gva_mame_record_game                (const gchar *name,
                                                             const gchar *inpname,
                                                             GError **error);
    GvaProcess *        gva_mame_playback_game              (const gchar *name,
                                                             const gchar *inpname,
                                                             GError **error);
    gchar *             gva_mame_get_save_state_file        (const gchar *name);
    void                gva_mame_delete_save_state          (const gchar *name);
    const gchar *       gva_mame_get_input_directory        (GError **error);
    const gchar *       gva_mame_get_snapshot_directory     (GError **error);
    const gchar *       gva_mame_get_state_directory        (GError **error);
    #define             gva_mame_supports_auto_save         ()
    #define             gva_mame_supports_full_screen       ()
    #define             gva_mame_supports_maximize          ()
    #define             gva_mame_supports_sound             ()
    #define             gva_mame_supports_window            ()

## Description

These functions define the interface for MAME communication backends. GNOME Video Arcade currently supports backends for xmame and sdlmame.

## Details

### GvaMameCallback ()

    void                (*GvaMameCallback)                  (const gchar *name,
                                                             const gchar *game_data,
                                                             gpointer user_data);

Specifies the type of function for passing results of an asynchronous operation to the user.

`name` : | a unique identifier, usually the game name
`game_data` : | data for `name`
`user_data` : | user-provided data

### gva_mame_get_path_sep ()

    const gchar *       gva_mame_get_path_sep               (void);

Returns the search path delimiter string. XMAME uses UNIX-style ':' whereas SDLMAME uses Window-style ';'.

Returns : | search path delimiter string

### gva_mame_get_version ()

    gchar *             gva_mame_get_version                (GError **error);

Returns the version of the MAME executable that GNOME Video Arcade is configured to use. If an error occurs, it returns `NULL` and sets `error`.

`error` : | return location for a GError, or `NULL`
Returns : | the MAME version, or `NULL`

### gva_mame_get_total_supported ()

    guint               gva_mame_get_total_supported        (GError **error);

Returns the number of games supported by the MAME executable that GNOME Video Arcade is configured to use. If an error occurs, it returns zero and sets `error`.

`error` : | return location for a GError, or `NULL`
Returns : | number of supported games, or zero

### gva_mame_get_config_value ()

    gchar *             gva_mame_get_config_value           (const gchar *config_key,
                                                             GError **error);

Runs "MAME -showconfig" and extracts from the output the value of `config_key`. If an error occurs, or if `config_key` is not found in MAME's configuration, the function returns `NULL` and sets `error`.

`config_key` : | a configuration key
`error` : | return location for a GError, or `NULL`
Returns : | the value of `config_key`, or `NULL`

### gva_mame_has_config_value ()

    gboolean            gva_mame_has_config_value           (const gchar *config_key);

Returns `TRUE` if the MAME configuration has a configuration value for `config_key`. The function does not report errors that occur in the course of spawning MAME, so false negatives are possible.

`config_key` : | a configuration key
Returns : | `TRUE` if a value for `config_key` exists, `FALSE` if no such value exists or if an error occurred

### gva_mame_get_search_paths ()

    gchar **            gva_mame_get_search_paths           (const gchar *config_key,
                                                             GError **error);

Returns the value of `config_key` as an ordered list of search paths. This is only appropriate for configuration keys containing a list of search paths, such as "rompath" or "samplepath". If an error occurs, or if `config_key` is not found in MAME's configuration, the function returns `NULL` and sets `error`.

`config_key` : | a configuration key
`error` : | return location for a GError, or `NULL`
Returns : | a newly-allocated `NULL`-terminated array of paths, or `NULL`. Use `g_strfreev()` to free it.

### gva_mame_get_input_files ()

    GList *             gva_mame_get_input_files            (GError **error);

Returns a list of GvaInputFile instances corresponding to files in the input directory. If an error occurs, it returns `NULL` and sets `error`.

`error` : | return location for a `GError`, or `NULL`
Returns : | a list of GvaInputFile instances, or `NULL`

### gva_mame_list_xml ()

    GvaProcess *        gva_mame_list_xml                   (GError **error);

Spawns a "MAME -listxml" child process and returns a GvaProcess so the output can be read asynchronously. If an error occurs while spawning, it returns `NULL` and sets `error`.

### Note

Beware, this command spews many megabytes of XML data!

`error` : | return location for a GError, or `NULL`
Returns : | a new GvaProcess, or `NULL`

### gva_mame_verify_roms ()

    gchar *             gva_mame_verify_roms                (const gchar *name,
                                                             GError **error);

Verifies the contents of the ROM set `name` and returns the status, which may be "good", "bad", "best available", "not found", or "not supported". If an error occurs, it returns `NULL` and sets `error`.

`name` : | the name of a ROM set
`error` : | return location for a GError, or `NULL`
Returns : | verification status, or `NULL`

### gva_mame_verify_samples ()

    gchar *             gva_mame_verify_samples             (const gchar *name,
                                                             GError **error);

Verifies the contents of the sample set `name` and returns the status, which may be "good", "bad", "best available", "not found", or "not supported". If an error occurs, it returns `NULL` and sets `error`.

`name` : | the name of a sample set
`error` : | return location for a GError, or `NULL`
Returns : | verification status, or `NULL`

### gva_mame_verify_all_roms ()

    GvaProcess *        gva_mame_verify_all_roms            (GError **error);

Spawns a "MAME -verifyroms" child process and returns a GvaProcess so the output can be read asynchronously. If an error occurs while spawning, it returns `NULL` and sets `error`.

`error` : | return location for a GError, or `NULL`
Returns : | a new GvaProcess, or `NULL`

### gva_mame_verify_all_samples ()

    GvaProcess *        gva_mame_verify_all_samples         (GError **error);

Spawns a "MAME -verifysamples" child process and returns a GvaProcess so the output can be read asynchronously. If an error occurs while spawning, it returns `NULL` and sets `error`.

`error` : | return location for a GError, or `NULL`
Returns : | a new GvaProcess, or `NULL`

### gva_mame_verify_parse ()

    gboolean            gva_mame_verify_parse               (const gchar *line,
                                                             gchar **out_name,
                                                             gchar **out_status);

Attempts to extract a status from a line of output generated by a "MAME -verifyroms" or "MAME -verifysamples" child process. If successful, it sets `out_name` to a newly-allocated string containing the game name and `out_status` to a newly-allocated string containing the verification status and returns `TRUE`.

Known status values are "good", "bad", "best available", "not found" and "not supported".

`line` : | output line from a MAME process
`out_name` : | return location for the game name, or `NULL`
`out_status` : | return location for the status, or `NULL`
Returns : | `TRUE` if the parse was successful, `FALSE` otherwise

### gva_mame_run_game ()

    GvaProcess *        gva_mame_run_game                   (const gchar *name,
                                                             GError **error);

Spawns a "MAME `name`" child process (with some additional user preferences) and returns a GvaProcess to track it. If an error occurs while spawning, it returns `NULL` and sets `error`.

`name` : | the name of the game to run
`error` : | return location for a GError, or `NULL`
Returns : | a new GvaProcess, or `NULL`

### gva_mame_record_game ()

    GvaProcess *        gva_mame_record_game                (const gchar *name,
                                                             const gchar *inpname,
                                                             GError **error);

Spawns a "MAME -record `inpname` `name`" child process (with some additional user preferences) and returns a GvaProcess to track it. If an error occurs while spawning, it returns `NULL` and sets `error`.

`name` : | the name of the game to run
`inpname` : | the name of a file to record keypresses to
`error` : | return location for a GError, or `NULL`
Returns : | a new GvaProcess, or `NULL`

### gva_mame_playback_game ()

    GvaProcess *        gva_mame_playback_game              (const gchar *name,
                                                             const gchar *inpname,
                                                             GError **error);

Spawns a "MAME -playback `inpname` `name`" child process (with some additional user preferences) and returns a GvaProcess to track it. If an error occurs while spawning, it returns `NULL` and sets `error`.

`name` : | the name of the game to play back
`inpname` : | the name of a file containing keypresses for `name`
`error` : | return location for a GError, or `NULL`
Returns : | a new GvaProcess, or `NULL`

### gva_mame_get_save_state_file ()

    gchar *             gva_mame_get_save_state_file        (const gchar *name);

Returns the name of the automatic save state file for `name`.

`name` : | the name of a game
Returns : | the name of the save state file

### gva_mame_delete_save_state ()

    void                gva_mame_delete_save_state          (const gchar *name);

Deletes the automatic save state file for `name`, if it exists.

`name` : | the name of a game

### gva_mame_get_input_directory ()

    const gchar *       gva_mame_get_input_directory        (GError **error);

Returns the value of the "input_directory" configuration key. The function caches the result to avoid excessive MAME invocations. If an error occurs, the function returns `NULL` and sets `error`.

`error` : | return location for a GError, or `NULL`
Returns : | the directory containing MAME input files, or `NULL`

### gva_mame_get_snapshot_directory ()

    const gchar *       gva_mame_get_snapshot_directory     (GError **error);

Returns the value of the "snapshot_directory" configuration key. The function caches the result to avoid excessive MAME invocations. If an error occurs, the function returns `NULL` and sets `error`.

`error` : | return location for a GError, or `NULL`
Returns : | the directory containing MAME snapshot files, or `NULL`

### gva_mame_get_state_directory ()

    const gchar *       gva_mame_get_state_directory        (GError **error);

Returns the value of the "state_directory" configuration key. The function caches the result to avoid excessive MAME invocations. If an error occurs, the function returns `NULL` and sets `error`.

`error` : | return location for a GError, or `NULL`
Returns : | the directory containing MAME save state files, or `NULL`

### gva_mame_supports_auto_save()

    #define             gva_mame_supports_auto_save()

Returns `TRUE` if the MAME executable that GNOME Video Arcade is configured to use supports an "autosave" option.

Returns : | `TRUE` if MAME supports the "autosave" option

### gva_mame_supports_full_screen()

    #define             gva_mame_supports_full_screen()

Returns `TRUE` if the MAME executable that GNOME Video Arcade is configured to use supports a "fullscreen" option.

Returns : | `TRUE` if MAME supports the "fullscreen" option

### gva_mame_supports_maximize()

    #define             gva_mame_supports_maximize()

Returns `TRUE` if the MAME executable that GNOME Video Arcade is configured to use supports a "maximize" option.

Returns : | `TRUE` if MAME supports the "maximize" option

### gva_mame_supports_sound()

    #define             gva_mame_supports_sound()

Returns `TRUE` if the MAME executable that GNOME Video Arcade is configured to use supports a "sound" option.

Returns : | `TRUE` if MAME supports the "sound" option

### gva_mame_supports_window()

    #define             gva_mame_supports_window()

Returns `TRUE` if the MAME executable that GNOME Video Arcade is configured to use supports a "window" option.

Returns : | `TRUE` if MAME supports the "window" option