Difference between revisions of "Mupen64Plus v2.0 Core Config"

From Mupen64Plus Wiki
Jump to: navigation, search
(Created page with "Mupen64Plus v2.0 API = Mupen64Plus v2.0 Configuration API = Most libmupen64plus functions return an <tt>m64p_error</tt> return code, which...")
(No difference)

Revision as of 21:47, 21 July 2015

Mupen64Plus v2.0 API

Mupen64Plus v2.0 Configuration API

Most libmupen64plus functions return an m64p_error return code, which is an enumerated type defined in m64p_types.h. Front-end code should check the return value of each call to a libmupen64plus function.

Selector Functions

These functions are used by the front-end to discover the sections in the configuration file, open a section, discover parameters within a section, and find out if a section has been changed.

Prototype m64p_error ConfigListSections(void *context, void (*SectionListCallback)(void * context, const char * SectionName))
Input Parameters context Void pointer to be passed to the SectionListCallback function

SectionListCallback Pointer to function in front-end for receiving the name of every section in the Mupen64Plus Core configuration data. This function will be called once for each section in the core configuration data structure, and then the ConfigListSections() function will return.

Requirements The Mupen64Plus library must already be initialized before calling this function. The SectionListCallback pointer cannot be NULL.
Usage This function is called to enumerate the list of Sections in the Mupen64Plus Core configuration file. It is expected that there will be a section named "Core" for core-specific configuration data, "Graphics" for common graphics options, and one section for each plugin library.


Prototype m64p_error ConfigOpenSection(const char *SectionName, m64p_handle *ConfigSectionHandle)
Input Parameters SectionName Name of the Mupen64Plus configuration section to open. This name is case-insensitive. If no section exists with the given name, a new one will be created with no parameters. This name may consist of any ASCII characters between 32 and 127 except brackets "[]".

ConfigSectionHandle This is a handle (defined in m64p_types.h) which is required to be used for subsequent calls to core configuration functions to list, retrieve, or set configuration parameters.

Requirements The Mupen64Plus library must already be initialized before calling this function. The SectionName and ConfigSectionHandle pointers cannot be NULL.
Usage This function is used to give a configuration section handle to the front-end which may be used to read or write configuration parameter values in a given section of the configuration file.


Prototype m64p_error ConfigListParameters(m64p_handle ConfigSectionHandle, void *context, void (*ParameterListCallback)(void * context, const char *ParamName, m64p_type ParamType))
Input Parameters ConfigSectionHandle An m64p_handle given by the ConfigOpenSection function.

context Void pointer to be passed to the ParameterListCallback function
ParameterListCallback Pointer to function in front-end for receiving the name of every parameter in the given section of the Mupen64Plus Core configuration data. This function will be called once for each parameter in the section, and then the ConfigListParameters() function will return.

Requirements The Mupen64Plus library must already be initialized before calling this function. The ConfigSectionHandle and ParameterListCallback pointers cannot be NULL.
Usage This function is called to enumerate the list of Parameters in a given Section of the Mupen64Plus Core configuration file.


Prototype int ConfigHasUnsavedChanges(const char *SectionName)
Input Parameters SectionName Name of the Mupen64Plus configuration section to check for unsaved changes. This name is case-insensitive. If this pointer is NULL or points to an empty string, then all sections are checked.
Requirements The Mupen64Plus library must already be initialized before calling this function.

This function was added in the Config API version 2.2.0.

Usage This function is called to determine if a given Section (or all sections) of the Mupen64Plus Core configuration file has been modified since it was last saved. A return value of 0 means there are no unsaved changes, while a 1 will be returned if there are unsaved changes.

Modifier Functions

These functions are used for deleting parts of the configuration list or saving the configuration data to disk.

Prototype m64p_error ConfigDeleteSection(const char *SectionName)
Input Parameters SectionName Name of the Mupen64Plus configuration section to delete. This name is case-insensitive. This name may consist of any ASCII characters between 32 and 127 except brackets "[]".
Requirements The Mupen64Plus library must already be initialized before calling this function.
Usage This function deletes a section from the Mupen64Plus configuration data.


Prototype m64p_error ConfigSaveFile(void)
Input Parameters N/A
Requirements The Mupen64Plus library must already be initialized before calling this function.
Usage This function saves the Mupen64Plus configuration file to disk.


Prototype m64p_error ConfigSaveSection(const char *SectionName)
Input Parameters SectionName Name of the Mupen64Plus configuration section to save. This name is case-insensitive.
Requirements The Mupen64Plus library must already be initialized before calling this function. The named section must exist in the current configuration.

This function was added in the Config API version 2.1.0.

Usage This function saves one section of the current Mupen64Plus configuration to disk, while leaving the other sections unmodified.


Prototype m64p_error ConfigRevertChanges(const char *SectionName)
Input Parameters SectionName Name of the Mupen64Plus configuration section to modify. This name is case-insensitive. This pointer cannot be NULL.
Requirements The Mupen64Plus library must already be initialized before calling this function. The named section must exist in the current configuration.

This function was added in the Config API version 2.2.0.

Usage This function reverts changes previously made to one section of the current Mupen64Plus configuration file, so that it will match with the configuration at the last time that it was loaded from or saved to disk.

Generic Get/Set Functions

These functions should be used for reading or writing configuration values in most cases.

Prototype m64p_error ConfigSetParameter(m64p_handle ConfigSectionHandle, const char *ParamName, m64p_type ParamType, const void *ParamValue)
Input Parameters ConfigSectionHandle An m64p_handle given by the ConfigOpenSection function.

ParamName NULL-terminated string containing the name of the parameter whose value is being set. This name is case-insensitive. This name may consist of any ASCII characters between 32 and 127 except the equals and hash signs, and may not end in a space.
ParamType An m64p_type value giving the type of the data object that ParamValue points to. If this is different from the native data representation used by the core, it will be converted into the type used by the core.
ParamValue Pointer to data object containing the value of the parameter to be set.

Requirements The Mupen64Plus library must already be initialized before calling this function. The ConfigSectionHandle, ParamName and ParamValue pointers cannot be NULL.
Usage This function sets the value of one of the emulator's configuration parameters in the section which is represented by ConfigSectionHandle.


|Prototype |m64p_error ConfigSetParameterHelp(m64p_handle ConfigSectionHandle, const char *ParamName, const char *ParamHelp) |- |Input Parameters |ConfigSectionHandle An m64p_handle given by the ConfigOpenSection function.
ParamName NULL-terminated string containing the name of the parameter whose help string is being set. This name is case-insensitive. This name may consist of any ASCII characters between 32 and 127 except the equals and hash signs, and may not end in a space.
ParamHelp NULL-terminated string containing some human-readable information about the usage of this parameter. Can be NULL.
|- |Requirements |The Mupen64Plus library must already be initialized before calling this function. The ConfigSectionHandle and ParamName pointers cannot be NULL. |- |Usage |This function sets the help string of one of the emulator's configuration parameters in the section which is represented by ConfigSectionHandle. |}

Prototype m64p_error ConfigGetParameter(m64p_handle ConfigSectionHandle, const char *ParamName, m64p_type ParamType, void *ParamValue, int MaxSize)
Input Parameters ConfigSectionHandle An m64p_handle given by the ConfigOpenSection function.

ParamName NULL-terminated string containing the name of the parameter whose value is being retrieved. This name is case-insensitive. This name may consist of any ASCII characters between 32 and 127 except the equals and hash signs, and may not end in a space.
ParamType An m64p_type value giving the type of the data object that ParamValue points to. If this is different from the native data representation used by the core, it will be converted into the type given by ParamType.
ParamValue Pointer to data object to receive the value of the parameter being retrieved.
MaxSize Size (in bytes) of the data object that ParamValue points to.

Requirements The Mupen64Plus library must already be initialized before calling this function. The ConfigSectionHandle, ParamName and ParamValue pointers cannot be NULL.
Usage This function retrieves the value of one of the emulator's parameters in the section which is represented by ConfigSectionHandle.


Prototype m64p_error ConfigGetParameterType(m64p_handle ConfigSectionHandle, const char *ParamName, m64p_type *ParamType)
Input Parameters ConfigSectionHandle An m64p_handle given by the ConfigOpenSection function.

ParamName Pointer to a NULL-terminated string containing the name of the parameter whose type is being retrieved. This name is case-insensitive. This name may consist of any ASCII characters between 32 and 127 except the equals and hash signs, and may not end in a space.
ParamType Pointer to an m64p_type value to receive the type of the parameter indicated by ParamName.

Requirements The Mupen64Plus library must already be initialized before calling this function. The ConfigSectionHandle, ParamName, and ParamType pointers cannot be NULL.
Usage This function retrieves the type of one of the emulator's parameters in the section which is represented by ConfigSectionHandle. If there is no parameter with the given ParamName, the error M64ERR_INPUT_NOT_FOUND will be returned.


Prototype const char * ConfigGetParameterHelp(m64p_handle ConfigSectionHandle, const char *ParamName)
Return Value Pointer to a NULL-terminated string containing usage information for the ParamName parameter. May be NULL.
Input Parameters ConfigSectionHandle An m64p_handle given by the ConfigOpenSection function.

ParamName NULL-terminated string containing the name of the parameter for which usage information is being retrieved. This name is case-insensitive. This name may consist of any ASCII characters between 32 and 127 except the equals and hash signs, and may not end in a space.

Requirements The Mupen64Plus library must already be initialized before calling this function. The ConfigSectionHandle, and ParamName pointers cannot be NULL.
Usage This function retrieves the help information about one of the emulator's parameters in the section which is represented by ConfigSectionHandle.

Special Get/Set Functions

These parameterized Get/SetDefault functions are provided for simplifying the task of handling default values within a single module. Each code module using the Core's configuration API should set the default values for all configuration parameters used by that module during its Startup() function. This allows the software to set up the default values automatically rather than storing them in a separate "default config file" which has proven problematic in the past. This also solves the problem which occurs when an upgraded module contains a new config parameter not present in the previous release.

The special Get functions return the configuration value directly rather than writing them through a pointer and returning an error code. For this reason, these parameterized Get functions should only be used within a module which 'owns' the configuration section and set up its default values in the Startup() function. Because these functions cannot signal an error to the caller, a front-end should not use these functions to retrieve configuration values for the core or the plugins, unless the names of the parameters have been enumerated with ConfigListParameters and are therefore guaranteed to exist.


Prototype m64p_error ConfigSetDefaultInt(m64p_handle ConfigSectionHandle, const char *ParamName, int ParamValue, const char *ParamHelp)

m64p_error ConfigSetDefaultFloat(m64p_handle ConfigSectionHandle, const char *ParamName, float ParamValue, const char *ParamHelp)
m64p_error ConfigSetDefaultBool(m64p_handle ConfigSectionHandle, const char *ParamName, int ParamValue, const char *ParamHelp)
m64p_error ConfigSetDefaultString(m64p_handle ConfigSectionHandle, const char *ParamName, const char * ParamValue, const char *ParamHelp)

Input Parameters ConfigSectionHandle An m64p_handle given by the ConfigOpenSection function.

ParamName NULL-terminated string containing the name of the parameter whose value is being set. This name is case-insensitive. This name may consist of any ASCII characters between 32 and 127 except the equals and hash signs, and may not end in a space.
ParamValue Integer or null-terminated string pointer containing the value of the parameter to be set.
ParamHelp NULL-terminated string containing some human-readable information about the usage of this parameter. Can be NULL.

Requirements The Mupen64Plus library must already be initialized before calling this function. The ConfigSectionHandle and ParamName pointers cannot be NULL.
Usage This function is used to set the value of a configuration parameter if it is not already present in the configuration file. This may happen if a new user runs the emulator, or an upgraded module uses a new parameter, or the user deletes his or her configuration file. If a parameter named ParamName is already present in the given section of the configuration file, then no action will be taken and this function will return successfully. Otherwise, a new parameter will be created its value will be assigned to ParamValue.


Prototype
int ConfigGetParamInt(m64p_handle ConfigSectionHandle, const char *ParamName)
float ConfigGetParamFloat(m64p_handle ConfigSectionHandle, const char *ParamName)
int ConfigGetParamBool(m64p_handle ConfigSectionHandle, const char *ParamName)
const char * ConfigGetParamString(m64p_handle ConfigSectionHandle, const char *ParamName)
Input Parameters ConfigSectionHandle An m64p_handle given by the ConfigOpenSection function.

ParamName NULL-terminated string containing the name of the parameter whose value is being retrieved. This name is case-insensitive. This name may consist of any ASCII characters between 32 and 127 except the equals and hash signs, and may not end in a space.

Requirements The Mupen64Plus library must already be initialized before calling this function. The ConfigSectionHandle and ParamName pointers cannot be NULL.
Usage This function retrieves the value of one of the emulator's parameters in the section which is represented by ConfigSectionHandle, and returns the value directly to the calling function. If an errors occurs (such as if ConfigSectionHandle is invalid, or there is no configuration parameter named ParamName), then an error will be sent to the front-end via the DebugCallback() function, and either a 0 (zero) or an empty string will be returned.

OS-Abstraction Functions

Prototype const char * ConfigGetSharedDataFilepath(const char *filename)
Return Value Pointer to a NULL-terminated string containing a full directory path and filename to a given shared data file, or NULL if this file was not found.
Requirements The Mupen64Plus library must already be initialized before calling this function.
Usage It is common for shared data files on Unix systems to be installed in different places on different systems. Therefore, this core function is provided to allow a plugin to retrieve a full pathname to a given shared data file. This type of file is intended to be shared among multiple users on a system, so it is likely to be read-only. Examples of these types of files include: the .ini files for Rice Video and Glide64, the font and Mupen64Plus.ini files for the core, and the cheat code files for the front-end. This function will first search in a directory given via the DataPath parameter to the CoreStartup function, then in a directory given by the SharedDataPath core configuration parameter, then in a directory which may be supplied at compile time through a Makefile or configure script option, and finally in some common system locations (such as /usr/share/mupen64plus and /usr/local/share/mupen64plus on Unix systems).


Prototype const char * ConfigGetUserConfigPath(void)
Return Value Pointer to a NULL-terminated string containing the directory path to user-specific configuration files.
Requirements The Mupen64Plus library must already be initialized before calling this function.
Usage This function may be used by the plugins or front-end to get a path to the directory for storing user-specific configuration files. This will be the directory where the configuration file "mupen64plus.cfg" is located.


Prototype const char * ConfigGetUserDataPath(void)
Return Value Pointer to a NULL-terminated string containing the directory path to user-specific data files.
Requirements The Mupen64Plus library must already be initialized before calling this function.
Usage This function may be used by the plugins or front-end to get a path to the directory for storing user-specific data files. This may be used to store files such as screenshots, saved game states, or hi-res textures.


Prototype const char * ConfigGetUserCachePath(void)
Return Value Pointer to a NULL-terminated string containing the directory path to user-specific caching data files.
Requirements The Mupen64Plus library must already be initialized before calling this function.
Usage This function may be used by the plugins or front-end to get a path to the directory for storing user-specific caching data files. Files in this directory may be deleted by the user to save space, so critical information should not be stored here. This directory may be used to store files such as the ROM browser cache.
Retrieved from "https://mupen64plus.org/wiki/index.php?title=Mupen64Plus_v2.0_Core_Config&oldid=8"