View source for Mupen64Plus v2.0 Core Config

[[Mupen64Plus v2.0 Core API v1.0|Mupen64Plus v2.0 API]]

= Mupen64Plus v2.0 Configuration API =

Most libmupen64plus functions return an <tt>m64p_error</tt> return code, which is an enumerated type defined in [[Mupen64Plus v2.0 headers#m64p_types.h|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.

{| border="1"
|Prototype
|'''<tt>m64p_error ConfigListSections(void *context, void (*SectionListCallback)(void * context, const char * SectionName))</tt>'''
|-
|Input Parameters
|'''<tt>context</tt>''' Void pointer to be passed to the SectionListCallback function<br />
'''<tt>SectionListCallback</tt>''' 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 '''<tt>SectionListCallback</tt>''' 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.
|}
<br />
{| border="1"
|Prototype
|'''<tt>m64p_error ConfigOpenSection(const char *SectionName, m64p_handle *ConfigSectionHandle)</tt>'''
|-
|Input Parameters
|'''<tt>SectionName</tt>''' 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 "[]".<br />
'''<tt>ConfigSectionHandle</tt>''' This is a handle (defined in [[Mupen64Plus v2.0 headers#m64p_types.h|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 '''<tt>SectionName</tt>''' and '''<tt>ConfigSectionHandle</tt>''' 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.
|}
<br />
{| border="1"
|Prototype
|'''<tt>m64p_error ConfigListParameters(m64p_handle ConfigSectionHandle, void *context, void (*ParameterListCallback)(void * context, const char *ParamName, m64p_type ParamType))</tt>'''
|-
|Input Parameters
|'''<tt>ConfigSectionHandle</tt>''' An <tt>m64p_handle</tt> given by the '''<tt>ConfigOpenSection</tt>''' function.<br />
'''<tt>context</tt>''' Void pointer to be passed to the ParameterListCallback function<br />
'''<tt>ParameterListCallback</tt>''' 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 '''<tt>ConfigSectionHandle</tt>''' and '''<tt>ParameterListCallback</tt>''' 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.
|}
<br />
{| border="1"
|Prototype
|'''<tt>int ConfigHasUnsavedChanges(const char *SectionName)</tt>'''
|-
|Input Parameters
|'''<tt>SectionName</tt>''' 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.<br />
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.

{| border="1"
|Prototype
|'''<tt>m64p_error ConfigDeleteSection(const char *SectionName)</tt>'''
|-
|Input Parameters
|'''<tt>SectionName</tt>''' 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 "[]".<br />
|-
|Requirements
|The Mupen64Plus library must already be initialized before calling this function.
|-
|Usage
|This function deletes a section from the Mupen64Plus configuration data.
|}
<br />
{| border="1"
|Prototype
|'''<tt>m64p_error ConfigSaveFile(void)</tt>'''
|-
|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.
|}
<br />
{| border="1"
|Prototype
|'''<tt>m64p_error ConfigSaveSection(const char *SectionName)</tt>'''
|-
|Input Parameters
|'''<tt>SectionName</tt>''' 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.<br />
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.
|}
<br />
{| border="1"
|Prototype
|'''<tt>m64p_error ConfigRevertChanges(const char *SectionName)</tt>'''
|-
|Input Parameters
|'''<tt>SectionName</tt>''' 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.<br />
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.

{| border="1"
|Prototype
|'''<tt>m64p_error ConfigSetParameter(m64p_handle ConfigSectionHandle, const char *ParamName, m64p_type ParamType, const void *ParamValue)</tt>'''
|-
|Input Parameters
|'''<tt>ConfigSectionHandle</tt>''' An <tt>m64p_handle</tt> given by the '''<tt>ConfigOpenSection</tt>''' function.<br />
'''<tt>ParamName</tt>''' 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.<br />
'''<tt>ParamType</tt>''' An <tt>m64p_type</tt> 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.<br />
'''<tt>ParamValue</tt>''' Pointer to data object containing the value of the parameter to be set.<br />
|-
|Requirements
|The Mupen64Plus library must already be initialized before calling this function.  The '''<tt>ConfigSectionHandle</tt>''', '''<tt>ParamName</tt>''' and '''<tt>ParamValue</tt>''' 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 '''<tt>ConfigSectionHandle</tt>'''.
|}
<br />
{| border="1"
|Prototype
|'''<tt>m64p_error ConfigSetParameterHelp(m64p_handle ConfigSectionHandle, const char *ParamName, const char *ParamHelp)</tt>'''
|-
|Input Parameters
|'''<tt>ConfigSectionHandle</tt>''' An <tt>m64p_handle</tt> given by the '''<tt>ConfigOpenSection</tt>''' function.<br />
'''<tt>ParamName</tt>''' 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.<br />
'''<tt>ParamHelp</tt>''' NULL-terminated string containing some human-readable information about the usage of this parameter.  Can be NULL.<br />
|-
|Requirements
|The Mupen64Plus library must already be initialized before calling this function.  The '''<tt>ConfigSectionHandle</tt>''' and '''<tt>ParamName</tt>''' 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 '''<tt>ConfigSectionHandle</tt>'''.
|}
<br />
{| border="1"
|Prototype
|'''<tt>m64p_error ConfigGetParameter(m64p_handle ConfigSectionHandle, const char *ParamName, m64p_type ParamType, void *ParamValue, int MaxSize)</tt>'''
|-
|Input Parameters
|'''<tt>ConfigSectionHandle</tt>''' An <tt>m64p_handle</tt> given by the '''<tt>ConfigOpenSection</tt>''' function.<br />
'''<tt>ParamName</tt>''' 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.<br />
'''<tt>ParamType</tt>''' An <tt>m64p_type</tt> 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'''.<br />
'''<tt>ParamValue</tt>''' Pointer to data object to receive the value of the parameter being retrieved.<br />
'''<tt>MaxSize</tt>''' Size (in bytes) of the data object that '''ParamValue''' points to.
|-
|Requirements
|The Mupen64Plus library must already be initialized before calling this function.  The '''<tt>ConfigSectionHandle</tt>''', '''<tt>ParamName</tt>''' and '''<tt>ParamValue</tt>''' pointers cannot be NULL.
|-
|Usage
|This function retrieves the value of one of the emulator's parameters in the section which is represented by '''<tt>ConfigSectionHandle</tt>'''.
|}
<br />
{| border="1"
|Prototype
|'''<tt>m64p_error ConfigExternalOpen(const char *FileName, m64p_handle *Handle)</tt>'''
|-
|Return Value
|M64ERR_SUCCESS if the config file was successfully opened.
|-
|Input Parameters
|'''<tt>FileName</tt>''' The path to the config file.<br />
'''<tt>Handle</tt>''' A pointer to a <tt>m64p_handle</tt>.
|-
|Requirements
|The Mupen64Plus library must already be initialized before calling this function. '''<tt>FileName</tt>''' cannot be NULL.
|-
|Usage
|This function opens an external config file and reads the contents into memory.
|}
<br />
{| border="1"
|Prototype
|'''<tt>m64p_error ConfigExternalClose(m64p_handle Handle)</tt>'''
|-
|Return Value
|M64ERR_SUCCESS if the config file was successfully closed.
|-
|Input Parameters
|'''<tt>Handle</tt>''' A <tt>m64p_handle</tt> that was previously passed to ConfigExternalOpen().
|-
|Requirements
|The Mupen64Plus library must already be initialized before calling this function. '''<tt>Handle</tt>''' should have already been passed to ConfigExternalOpen().
|-
|Usage
|This function opens an external config file and reads the contents into memory.
|}
<br />
{| border="1"
|Prototype
|'''<tt>m64p_error ConfigExternalGetParameter(m64p_handle Handle, const char *SectionName, const char *ParamName, char* ParamPtr, int ParamMaxLength)</tt>'''
|-
|Return Value
|M64ERR_SUCCESS if ParamName was found and ParamPtr is populated with the result.
|-
|Input Parameters
|'''<tt>Handle</tt>''' A <tt>m64p_handle</tt> that was previously passed to ConfigExternalOpen().<br />
'''<tt>SectionName</tt>''' NULL-terminated string containing the name of the section to retrieve the parameter from.<br />
'''<tt>ParamName</tt>''' NULL-terminated string containing the name of the parameter whose value is being retrieved.<br />
'''<tt>ParamPtr</tt>''' An allocated char array that is at least as large as ParamMaxLength. The result, if found will be copied into this array.<br />
'''<tt>ParamMaxLength</tt>''' The maximum number of bytes to be copied into ParamPtr.
|-
|Requirements
|The Mupen64Plus library must already be initialized before calling this function. '''<tt>Handle</tt>''' should have already been passed to ConfigExternalOpen. The '''<tt>SectionName</tt>''' and '''<tt>ParamName</tt>''' pointers cannot be NULL. ParamPtr must be a pre-allocated char array that is at least as large as ParamMaxLength.
|-
|Usage
|This functions allows a plugin to leverage the built-in ini parser to read any cfg/ini file.
|}
<br />
{| border="1"
|Prototype
|'''<tt>m64p_error ConfigGetParameterType(m64p_handle ConfigSectionHandle, const char *ParamName, m64p_type *ParamType)</tt>'''
|-
|Input Parameters
|'''<tt>ConfigSectionHandle</tt>''' An <tt>m64p_handle</tt> given by the '''<tt>ConfigOpenSection</tt>''' function.<br />
'''<tt>ParamName</tt>''' 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.<br />
'''<tt>ParamType</tt>''' Pointer to an <tt>m64p_type</tt> value to receive the type of the parameter indicated by '''<tt>ParamName</tt>'''.
|-
|Requirements
|The Mupen64Plus library must already be initialized before calling this function.  The '''<tt>ConfigSectionHandle</tt>''', '''<tt>ParamName</tt>''', and '''<tt>ParamType</tt>''' pointers cannot be NULL.
|-
|Usage
|This function retrieves the type of one of the emulator's parameters in the section which is represented by '''<tt>ConfigSectionHandle</tt>'''.  If there is no parameter with the given '''<tt>ParamName</tt>''', the error <tt>M64ERR_INPUT_NOT_FOUND</tt> will be returned.
|}
<br />
{| border="1"
|Prototype
|'''<tt>const char * ConfigGetParameterHelp(m64p_handle ConfigSectionHandle, const char *ParamName)</tt>'''
|-
|Return Value
|Pointer to a NULL-terminated string containing usage information for the '''<tt>ParamName</tt>''' parameter.  May be NULL.
|-
|Input Parameters
|'''<tt>ConfigSectionHandle</tt>''' An <tt>m64p_handle</tt> given by the '''<tt>ConfigOpenSection</tt>''' function.<br />
'''<tt>ParamName</tt>''' 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 '''<tt>ConfigSectionHandle</tt>''', and '''<tt>ParamName</tt>''' 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 '''<tt>ConfigSectionHandle</tt>'''.
|}

== 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 <tt>ConfigListParameters</tt> and are therefore guaranteed to exist.

<br />
{| border="1"
|Prototype
|'''<tt>m64p_error ConfigSetDefaultInt(m64p_handle ConfigSectionHandle, const char *ParamName, int ParamValue, const char *ParamHelp)</tt>'''<br />
'''<tt>m64p_error ConfigSetDefaultFloat(m64p_handle ConfigSectionHandle, const char *ParamName, float ParamValue, const char *ParamHelp)</tt>'''<br />
'''<tt>m64p_error ConfigSetDefaultBool(m64p_handle ConfigSectionHandle, const char *ParamName, int ParamValue, const char *ParamHelp)</tt>'''<br />
'''<tt>m64p_error ConfigSetDefaultString(m64p_handle ConfigSectionHandle, const char *ParamName, const char * ParamValue, const char *ParamHelp)</tt>'''
|-
|Input Parameters
|'''<tt>ConfigSectionHandle</tt>''' An <tt>m64p_handle</tt> given by the '''<tt>ConfigOpenSection</tt>''' function.<br />
'''<tt>ParamName</tt>''' 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.<br />
'''<tt>ParamValue</tt>''' Integer or null-terminated string pointer containing the value of the parameter to be set.<br />
'''<tt>ParamHelp</tt>''' 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 '''<tt>ConfigSectionHandle</tt>''' and '''<tt>ParamName</tt>''' 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 '''<tt>ParamName</tt>''' 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 '''<tt>ParamValue</tt>'''.
|}
<br />
{| border="1"
|Prototype
|
{|
|-
|'''<tt>int</tt>''' || '''<tt>ConfigGetParamInt(m64p_handle ConfigSectionHandle, const char *ParamName)</tt>'''
|-
|'''<tt>float</tt>''' || '''<tt>ConfigGetParamFloat(m64p_handle ConfigSectionHandle, const char *ParamName)</tt>'''
|-
|'''<tt>int</tt>''' || '''<tt>ConfigGetParamBool(m64p_handle ConfigSectionHandle, const char *ParamName)</tt>'''
|-
|'''<tt>const char *</tt>''' || '''<tt>ConfigGetParamString(m64p_handle ConfigSectionHandle, const char *ParamName)</tt>'''
|}
|-
|Input Parameters
|'''<tt>ConfigSectionHandle</tt>''' An <tt>m64p_handle</tt> given by the '''<tt>ConfigOpenSection</tt>''' function.<br />
'''<tt>ParamName</tt>''' 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 '''<tt>ConfigSectionHandle</tt>''' and '''<tt>ParamName</tt>''' pointers cannot be NULL.
|-
|Usage
|This function retrieves the value of one of the emulator's parameters in the section which is represented by '''<tt>ConfigSectionHandle</tt>''', and returns the value directly to the calling function.  If an errors occurs (such as if '''<tt>ConfigSectionHandle</tt>''' is invalid, or there is no configuration parameter named '''<tt>ParamName</tt>'''), then an error will be sent to the front-end via the <tt>DebugCallback()</tt> function, and either a 0 (zero) or an empty string will be returned.
|}

== OS-Abstraction Functions ==

{| border="1"
|Prototype
|'''<tt>const char * ConfigGetSharedDataFilepath(const char *filename)</tt>'''
|-
|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 <tt>DataPath</tt> parameter to the '''<tt>CoreStartup</tt>''' function, then in a directory given by the <tt>SharedDataPath</tt> 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).
|}
<br />
{| border="1"
|Prototype
|'''<tt>const char * ConfigGetUserConfigPath(void)</tt>'''
|-
|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.
|}
<br />
{| border="1"
|Prototype
|'''<tt>const char * ConfigGetUserDataPath(void)</tt>'''
|-
|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.
|}
<br />
{| border="1"
|Prototype
|'''<tt>const char * ConfigGetUserCachePath(void)</tt>'''
|-
|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.
|}