gva-mame

gva-mame — MAME Communication Backend

Functions

Description

These functions define the interface for communication with MAME.

Functions

gva_mame_command ()

gint
gva_mame_command (const gchar *arguments,
                  gchar ***stdout_lines,
                  gchar ***stderr_lines,
                  GError **error);

Spawns MAME with arguments and blocks until the child process exits. The line-based output from the stdout and stderr pipes are written to stdout_lines and stderr_lines , respectively, as NULL-terminated string arrays. The function returns the exit status of the child process, or -1 if an error occurred while spawning the process.

Parameters

arguments

command line arguments

 

stdout_lines

return location for stdout lines, or NULL

 

stderr_lines

return location for stderr lines, or NULL

 

error

return locations for a GError, or NULL

 

Returns

exit status of the child process or -1 if an error occurred


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 .

Parameters

error

return location for a GError, or NULL

 

Returns

the MAME version, or NULL


gva_mame_get_version_int ()

guint
gva_mame_get_version_int (void);

Returns the MAME version as a whole number for easy comparison. For example, MAME version 0.123 is returned as 123.

Returns

the MAME version as an integer


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 .

Parameters

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 .

Parameters

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.

Parameters

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 .

Parameters

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 .

Parameters

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 .

Beware, this command spews many megabytes of XML data!

Parameters

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 .

Parameters

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 .

Parameters

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 .

Parameters

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 .

Parameters

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

Parameters

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 .

Parameters

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 .

Parameters

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 .

Parameters

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 .

Parameters

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.

Parameters

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 .

Parameters

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 .

Parameters

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 .

Parameters

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