source/mupen64plus-core/doc/emuwiki-api-doc/Mupen64Plus_v2.0_Core_Config.txt

   1 [[Mupen64Plus v2.0 Core API v1.0|Mupen64Plus v2.0 API]]
   2
   3 = Mupen64Plus v2.0 Configuration API =
   4
   5 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.
   6
   7 == Selector Functions ==
   8 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.
   9
  10 {| border="1"
  11 |Prototype
  12 |'''<tt>m64p_error ConfigListSections(void *context, void (*SectionListCallback)(void * context, const char * SectionName))</tt>'''
  13 |-
  14 |Input Parameters
  15 |'''<tt>context</tt>''' Void pointer to be passed to the SectionListCallback function<br />
  16 '''<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.
  17 |-
  18 |Requirements
  19 |The Mupen64Plus library must already be initialized before calling this function.  The '''<tt>SectionListCallback</tt>''' pointer cannot be NULL.
  20 |-
  21 |Usage
  22 |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.
  23 |}
  24 <br />
  25 {| border="1"
  26 |Prototype
  27 |'''<tt>m64p_error ConfigOpenSection(const char *SectionName, m64p_handle *ConfigSectionHandle)</tt>'''
  28 |-
  29 |Input Parameters
  30 |'''<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 />
  31 '''<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.
  32 |-
  33 |Requirements
  34 |The Mupen64Plus library must already be initialized before calling this function.  The '''<tt>SectionName</tt>''' and '''<tt>ConfigSectionHandle</tt>''' pointers cannot be NULL.
  35 |-
  36 |Usage
  37 |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.
  38 |}
  39 <br />
  40 {| border="1"
  41 |Prototype
  42 |'''<tt>m64p_error ConfigListParameters(m64p_handle ConfigSectionHandle, void *context, void (*ParameterListCallback)(void * context, const char *ParamName, m64p_type ParamType))</tt>'''
  43 |-
  44 |Input Parameters
  45 |'''<tt>ConfigSectionHandle</tt>''' An <tt>m64p_handle</tt> given by the '''<tt>ConfigOpenSection</tt>''' function.<br />
  46 '''<tt>context</tt>''' Void pointer to be passed to the ParameterListCallback function<br />
  47 '''<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.
  48 |-
  49 |Requirements
  50 |The Mupen64Plus library must already be initialized before calling this function.  The '''<tt>ConfigSectionHandle</tt>''' and '''<tt>ParameterListCallback</tt>''' pointers cannot be NULL.
  51 |-
  52 |Usage
  53 |This function is called to enumerate the list of Parameters in a given Section of the Mupen64Plus Core configuration file.
  54 |}
  55 <br />
  56 {| border="1"
  57 |Prototype
  58 |'''<tt>int ConfigHasUnsavedChanges(const char *SectionName)</tt>'''
  59 |-
  60 |Input Parameters
  61 |'''<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.
  62 |-
  63 |Requirements
  64 |The Mupen64Plus library must already be initialized before calling this function.<br />
  65 This function was added in the Config API version 2.2.0.
  66 |-
  67 |Usage
  68 |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.
  69 |}
  70
  71 == Modifier Functions ==
  72 These functions are used for deleting parts of the configuration list or saving the configuration data to disk.
  73
  74 {| border="1"
  75 |Prototype
  76 |'''<tt>m64p_error ConfigDeleteSection(const char *SectionName)</tt>'''
  77 |-
  78 |Input Parameters
  79 |'''<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 />
  80 |-
  81 |Requirements
  82 |The Mupen64Plus library must already be initialized before calling this function.
  83 |-
  84 |Usage
  85 |This function deletes a section from the Mupen64Plus configuration data.
  86 |}
  87 <br />
  88 {| border="1"
  89 |Prototype
  90 |'''<tt>m64p_error ConfigSaveFile(void)</tt>'''
  91 |-
  92 |Input Parameters
  93 |N/A
  94 |-
  95 |Requirements
  96 |The Mupen64Plus library must already be initialized before calling this function.
  97 |-
  98 |Usage
  99 |This function saves the Mupen64Plus configuration file to disk.
 100 |}
 101 <br />
 102 {| border="1"
 103 |Prototype
 104 |'''<tt>m64p_error ConfigSaveSection(const char *SectionName)</tt>'''
 105 |-
 106 |Input Parameters
 107 |'''<tt>SectionName</tt>''' Name of the Mupen64Plus configuration section to save.  This name is case-insensitive.
 108 |-
 109 |Requirements
 110 |The Mupen64Plus library must already be initialized before calling this function.  The named section must exist in the current configuration.<br />
 111 This function was added in the Config API version 2.1.0.
 112 |-
 113 |Usage
 114 |This function saves one section of the current Mupen64Plus configuration to disk, while leaving the other sections unmodified.
 115 |}
 116 <br />
 117 {| border="1"
 118 |Prototype
 119 |'''<tt>m64p_error ConfigRevertChanges(const char *SectionName)</tt>'''
 120 |-
 121 |Input Parameters
 122 |'''<tt>SectionName</tt>''' Name of the Mupen64Plus configuration section to modify.  This name is case-insensitive.  This pointer cannot be NULL.
 123 |-
 124 |Requirements
 125 |The Mupen64Plus library must already be initialized before calling this function.  The named section must exist in the current configuration.<br />
 126 This function was added in the Config API version 2.2.0.
 127 |-
 128 |Usage
 129 |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.
 130 |}
 131
 132 == Generic Get/Set Functions ==
 133 These functions should be used for reading or writing configuration values in most cases.
 134
 135 {| border="1"
 136 |Prototype
 137 |'''<tt>m64p_error ConfigSetParameter(m64p_handle ConfigSectionHandle, const char *ParamName, m64p_type ParamType, const void *ParamValue)</tt>'''
 138 |-
 139 |Input Parameters
 140 |'''<tt>ConfigSectionHandle</tt>''' An <tt>m64p_handle</tt> given by the '''<tt>ConfigOpenSection</tt>''' function.<br />
 141 '''<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 />
 142 '''<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 />
 143 '''<tt>ParamValue</tt>''' Pointer to data object containing the value of the parameter to be set.<br />
 144 |-
 145 |Requirements
 146 |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.
 147 |-
 148 |Usage
 149 |This function sets the value of one of the emulator's configuration parameters in the section which is represented by '''<tt>ConfigSectionHandle</tt>'''.
 150 |}
 151 <br />
 152 {| border="1"
 153 |Prototype
 154 |'''<tt>m64p_error ConfigGetParameter(m64p_handle ConfigSectionHandle, const char *ParamName, m64p_type ParamType, void *ParamValue, int MaxSize)</tt>'''
 155 |-
 156 |Input Parameters
 157 |'''<tt>ConfigSectionHandle</tt>''' An <tt>m64p_handle</tt> given by the '''<tt>ConfigOpenSection</tt>''' function.<br />
 158 '''<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 />
 159 '''<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 />
 160 '''<tt>ParamValue</tt>''' Pointer to data object to receive the value of the parameter being retrieved.<br />
 161 '''<tt>MaxSize</tt>''' Size (in bytes) of the data object that '''ParamValue''' points to.
 162 |-
 163 |Requirements
 164 |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.
 165 |-
 166 |Usage
 167 |This function retrieves the value of one of the emulator's parameters in the section which is represented by '''<tt>ConfigSectionHandle</tt>'''.
 168 |}
 169 <br />
 170 {| border="1"
 171 |Prototype
 172 |'''<tt>m64p_error ConfigGetParameterType(m64p_handle ConfigSectionHandle, const char *ParamName, m64p_type *ParamType)</tt>'''
 173 |-
 174 |Input Parameters
 175 |'''<tt>ConfigSectionHandle</tt>''' An <tt>m64p_handle</tt> given by the '''<tt>ConfigOpenSection</tt>''' function.<br />
 176 '''<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 />
 177 '''<tt>ParamType</tt>''' Pointer to an <tt>m64p_type</tt> value to receive the type of the parameter indicated by '''<tt>ParamName</tt>'''.
 178 |-
 179 |Requirements
 180 |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.
 181 |-
 182 |Usage
 183 |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.
 184 |}
 185 <br />
 186 {| border="1"
 187 |Prototype
 188 |'''<tt>const char * ConfigGetParameterHelp(m64p_handle ConfigSectionHandle, const char *ParamName)</tt>'''
 189 |-
 190 |Return Value
 191 |Pointer to a NULL-terminated string containing usage information for the '''<tt>ParamName</tt>''' parameter.  May be NULL.
 192 |-
 193 |Input Parameters
 194 |'''<tt>ConfigSectionHandle</tt>''' An <tt>m64p_handle</tt> given by the '''<tt>ConfigOpenSection</tt>''' function.<br />
 195 '''<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.
 196 |-
 197 |Requirements
 198 |The Mupen64Plus library must already be initialized before calling this function.  The '''<tt>ConfigSectionHandle</tt>''', and '''<tt>ParamName</tt>''' pointers cannot be NULL.
 199 |-
 200 |Usage
 201 |This function retrieves the help information about one of the emulator's parameters in the section which is represented by '''<tt>ConfigSectionHandle</tt>'''.
 202 |}
 203
 204 == Special Get/Set Functions ==
 205 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.
 206
 207 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.
 208
 209 <br />
 210 {| border="1"
 211 |Prototype
 212 |'''<tt>m64p_error ConfigSetDefaultInt(m64p_handle ConfigSectionHandle, const char *ParamName, int ParamValue, const char *ParamHelp)</tt>'''<br />
 213 '''<tt>m64p_error ConfigSetDefaultFloat(m64p_handle ConfigSectionHandle, const char *ParamName, float ParamValue, const char *ParamHelp)</tt>'''<br />
 214 '''<tt>m64p_error ConfigSetDefaultBool(m64p_handle ConfigSectionHandle, const char *ParamName, int ParamValue, const char *ParamHelp)</tt>'''<br />
 215 '''<tt>m64p_error ConfigSetDefaultString(m64p_handle ConfigSectionHandle, const char *ParamName, const char * ParamValue, const char *ParamHelp)</tt>'''
 216 |-
 217 |Input Parameters
 218 |'''<tt>ConfigSectionHandle</tt>''' An <tt>m64p_handle</tt> given by the '''<tt>ConfigOpenSection</tt>''' function.<br />
 219 '''<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 />
 220 '''<tt>ParamValue</tt>''' Integer or null-terminated string pointer containing the value of the parameter to be set.<br />
 221 '''<tt>ParamHelp</tt>''' NULL-terminated string containing some human-readable information about the usage of this parameter.  Can be NULL.
 222
 223 |-
 224 |Requirements
 225 |The Mupen64Plus library must already be initialized before calling this function.  The '''<tt>ConfigSectionHandle</tt>''' and '''<tt>ParamName</tt>''' pointers cannot be NULL.
 226 |-
 227 |Usage
 228 |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>'''.
 229 |}
 230 <br />
 231 {| border="1"
 232 |Prototype
 233 |
 234 {|
 235 |-
 236 |'''<tt>int</tt>''' || '''<tt>ConfigGetParamInt(m64p_handle ConfigSectionHandle, const char *ParamName)</tt>'''
 237 |-
 238 |'''<tt>float</tt>''' || '''<tt>ConfigGetParamFloat(m64p_handle ConfigSectionHandle, const char *ParamName)</tt>'''
 239 |-
 240 |'''<tt>int</tt>''' || '''<tt>ConfigGetParamBool(m64p_handle ConfigSectionHandle, const char *ParamName)</tt>'''
 241 |-
 242 |'''<tt>const char *</tt>''' || '''<tt>ConfigGetParamString(m64p_handle ConfigSectionHandle, const char *ParamName)</tt>'''
 243 |}
 244 |-
 245 |Input Parameters
 246 |'''<tt>ConfigSectionHandle</tt>''' An <tt>m64p_handle</tt> given by the '''<tt>ConfigOpenSection</tt>''' function.<br />
 247 '''<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.
 248 |-
 249 |Requirements
 250 |The Mupen64Plus library must already be initialized before calling this function.  The '''<tt>ConfigSectionHandle</tt>''' and '''<tt>ParamName</tt>''' pointers cannot be NULL.
 251 |-
 252 |Usage
 253 |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.
 254 |}
 255
 256 == OS-Abstraction Functions ==
 257
 258 {| border="1"
 259 |Prototype
 260 |'''<tt>const char * ConfigGetSharedDataFilepath(const char *filename)</tt>'''
 261 |-
 262 |Return Value
 263 |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.
 264 |-
 265 |Requirements
 266 |The Mupen64Plus library must already be initialized before calling this function.
 267 |-
 268 |Usage
 269 |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).
 270 |}
 271 <br />
 272 {| border="1"
 273 |Prototype
 274 |'''<tt>const char * ConfigGetUserConfigPath(void)</tt>'''
 275 |-
 276 |Return Value
 277 |Pointer to a NULL-terminated string containing the directory path to user-specific configuration files.
 278 |-
 279 |Requirements
 280 |The Mupen64Plus library must already be initialized before calling this function.
 281 |-
 282 |Usage
 283 |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.
 284 |}
 285 <br />
 286 {| border="1"
 287 |Prototype
 288 |'''<tt>const char * ConfigGetUserDataPath(void)</tt>'''
 289 |-
 290 |Return Value
 291 |Pointer to a NULL-terminated string containing the directory path to user-specific data files.
 292 |-
 293 |Requirements
 294 |The Mupen64Plus library must already be initialized before calling this function.
 295 |-
 296 |Usage
 297 |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.
 298 |}
 299 <br />
 300 {| border="1"
 301 |Prototype
 302 |'''<tt>const char * ConfigGetUserCachePath(void)</tt>'''
 303 |-
 304 |Return Value
 305 |Pointer to a NULL-terminated string containing the directory path to user-specific caching data files.
 306 |-
 307 |Requirements
 308 |The Mupen64Plus library must already be initialized before calling this function.
 309 |-
 310 |Usage
 311 |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.
 312 |}
 313