source/mupen64plus-core/src/api/m64p_config.h

   1 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
   2  *   Mupen64plus-core - m64p_config.h                                      *
   3  *   Mupen64Plus homepage: http://code.google.com/p/mupen64plus/           *
   4  *   Copyright (C) 2009 Richard Goedeken                                   *
   5  *                                                                         *
   6  *   This program is free software; you can redistribute it and/or modify  *
   7  *   it under the terms of the GNU General Public License as published by  *
   8  *   the Free Software Foundation; either version 2 of the License, or     *
   9  *   (at your option) any later version.                                   *
  10  *                                                                         *
  11  *   This program is distributed in the hope that it will be useful,       *
  12  *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
  13  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
  14  *   GNU General Public License for more details.                          *
  15  *                                                                         *
  16  *   You should have received a copy of the GNU General Public License     *
  17  *   along with this program; if not, write to the                         *
  18  *   Free Software Foundation, Inc.,                                       *
  19  *   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.          *
  20  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
  21
  22 /* This header file defines typedefs for function pointers to the Core's
  23  * configuration handling functions.
  24  */
  25
  26 #if !defined(M64P_CONFIG_H)
  27 #define M64P_CONFIG_H
  28
  29 #include "m64p_types.h"
  30
  31 #ifdef __cplusplus
  32 extern "C" {
  33 #endif
  34
  35 /* ConfigListSections()
  36  *
  37  * This function is called to enumerate the list of Sections in the Mupen64Plus
  38  * configuration file. It is expected that there will be a section named "Core"
  39  * for core-specific configuration data, "Graphics" for common graphics options,
  40  * and one or more sections for each plugin library.
  41  */
  42 typedef m64p_error (*ptr_ConfigListSections)(void *, void (*)(void *, const char *));
  43 #if defined(M64P_CORE_PROTOTYPES)
  44 EXPORT m64p_error CALL ConfigListSections(void *, void (*)(void *, const char *));
  45 #endif
  46
  47 /* ConfigOpenSection()
  48  *
  49  * This function is used to give a configuration section handle to the front-end
  50  * which may be used to read or write configuration parameter values in a given
  51  * section of the configuration file.
  52  */
  53 typedef m64p_error (*ptr_ConfigOpenSection)(const char *, m64p_handle *);
  54 #if defined(M64P_CORE_PROTOTYPES)
  55 EXPORT m64p_error CALL ConfigOpenSection(const char *, m64p_handle *);
  56 #endif
  57
  58 /* ConfigListParameters()
  59  *
  60  * This function is called to enumerate the list of Parameters in a given
  61  * Section of the Mupen64Plus configuration file.
  62  */
  63 typedef m64p_error (*ptr_ConfigListParameters)(m64p_handle, void *, void (*)(void *, const char *, m64p_type));
  64 #if defined(M64P_CORE_PROTOTYPES)
  65 EXPORT m64p_error CALL ConfigListParameters(m64p_handle, void *, void (*)(void *, const char *, m64p_type));
  66 #endif
  67
  68 /* ConfigSaveFile()
  69  *
  70  * This function saves the entire current Mupen64Plus configuration to disk.
  71  */
  72 typedef m64p_error (*ptr_ConfigSaveFile)(void);
  73 #if defined(M64P_CORE_PROTOTYPES)
  74 EXPORT m64p_error CALL ConfigSaveFile(void);
  75 #endif
  76
  77 /* ConfigSaveSection()
  78  *
  79  * This function saves one section of the current Mupen64Plus configuration to disk.
  80  */
  81 typedef m64p_error (*ptr_ConfigSaveSection)(const char *);
  82 #if defined(M64P_CORE_PROTOTYPES)
  83 EXPORT m64p_error CALL ConfigSaveSection(const char *);
  84 #endif
  85
  86 /* ConfigHasUnsavedChanges()
  87  *
  88  * This function determines if a given Section (or all sections) of the Mupen64Plus Core configuration file has been modified since it was last saved or loaded.
  89  */
  90 typedef int (*ptr_ConfigHasUnsavedChanges)(const char *);
  91 #if defined(M64P_CORE_PROTOTYPES)
  92 EXPORT int CALL ConfigHasUnsavedChanges(const char *);
  93 #endif
  94
  95 /* ConfigDeleteSection()
  96  *
  97  * This function deletes a section from the Mupen64Plus configuration data.
  98  */
  99 typedef m64p_error (*ptr_ConfigDeleteSection)(const char *SectionName);
 100 #if defined(M64P_CORE_PROTOTYPES)
 101 EXPORT m64p_error CALL ConfigDeleteSection(const char *SectionName);
 102 #endif
 103
 104 /* ConfigRevertChanges()
 105  *
 106  * This function reverts changes previously made to one section of the configuration file, so that it will match with the configuration at the last time that it was loaded from or saved to disk.
 107  */
 108 typedef m64p_error (*ptr_ConfigRevertChanges)(const char *SectionName);
 109 #if defined(M64P_CORE_PROTOTYPES)
 110 EXPORT m64p_error CALL ConfigRevertChanges(const char *SectionName);
 111 #endif
 112
 113 /* ConfigSetParameter()
 114  *
 115  * This function sets the value of one of the emulator's configuration
 116  * parameters.
 117  */
 118 typedef m64p_error (*ptr_ConfigSetParameter)(m64p_handle, const char *, m64p_type, const void *);
 119 #if defined(M64P_CORE_PROTOTYPES)
 120 EXPORT m64p_error CALL ConfigSetParameter(m64p_handle, const char *, m64p_type, const void *);
 121 #endif
 122
 123 /* ConfigGetParameter()
 124  *
 125  * This function retrieves the value of one of the emulator's parameters.
 126  */
 127 typedef m64p_error (*ptr_ConfigGetParameter)(m64p_handle, const char *, m64p_type, void *, int);
 128 #if defined(M64P_CORE_PROTOTYPES)
 129 EXPORT m64p_error CALL ConfigGetParameter(m64p_handle, const char *, m64p_type, void *, int);
 130 #endif
 131
 132 /* ConfigGetParameterType()
 133  *
 134  * This function retrieves the type of one of the emulator's parameters.
 135  */
 136 typedef m64p_error (*ptr_ConfigGetParameterType)(m64p_handle, const char *, m64p_type *);
 137 #if defined(M64P_CORE_PROTOTYPES)
 138 EXPORT m64p_error CALL ConfigGetParameterType(m64p_handle, const char *, m64p_type *);
 139 #endif
 140
 141 /* ConfigGetParameterHelp()
 142  *
 143  * This function retrieves the help information about one of the emulator's
 144  * parameters.
 145  */
 146 typedef const char * (*ptr_ConfigGetParameterHelp)(m64p_handle, const char *);
 147 #if defined(M64P_CORE_PROTOTYPES)
 148 EXPORT const char * CALL ConfigGetParameterHelp(m64p_handle, const char *);
 149 #endif
 150
 151 /* ConfigSetDefault***()
 152  *
 153  * These functions are used to set the value of a configuration parameter if it
 154  * is not already present in the configuration file. This may happen if a new
 155  * user runs the emulator, or an upgraded module uses a new parameter, or the
 156  * user deletes his or her configuration file. If the parameter is already
 157  * present in the given section of the configuration file, then no action will
 158  * be taken and this function will return successfully.
 159  */
 160 typedef m64p_error (*ptr_ConfigSetDefaultInt)(m64p_handle, const char *, int, const char *);
 161 typedef m64p_error (*ptr_ConfigSetDefaultFloat)(m64p_handle, const char *, float, const char *);
 162 typedef m64p_error (*ptr_ConfigSetDefaultBool)(m64p_handle, const char *, int, const char *);
 163 typedef m64p_error (*ptr_ConfigSetDefaultString)(m64p_handle, const char *, const char *, const char *);
 164 #if defined(M64P_CORE_PROTOTYPES)
 165 EXPORT m64p_error CALL ConfigSetDefaultInt(m64p_handle, const char *, int, const char *);
 166 EXPORT m64p_error CALL ConfigSetDefaultFloat(m64p_handle, const char *, float, const char *);
 167 EXPORT m64p_error CALL ConfigSetDefaultBool(m64p_handle, const char *, int, const char *);
 168 EXPORT m64p_error CALL ConfigSetDefaultString(m64p_handle, const char *, const char *, const char *);
 169 #endif
 170
 171 /* ConfigGetParam***()
 172  *
 173  * These functions retrieve the value of one of the emulator's parameters in
 174  * the given section, and return the value directly to the calling function. If
 175  * an errors occurs (such as an invalid Section handle, or invalid
 176  * configuration parameter name), then an error will be sent to the front-end
 177  * via the DebugCallback() function, and either a 0 (zero) or an empty string
 178  * will be returned.
 179  */
 180 typedef int          (*ptr_ConfigGetParamInt)(m64p_handle, const char *);
 181 typedef float        (*ptr_ConfigGetParamFloat)(m64p_handle, const char *);
 182 typedef int          (*ptr_ConfigGetParamBool)(m64p_handle, const char *);
 183 typedef const char * (*ptr_ConfigGetParamString)(m64p_handle, const char *);
 184 #if defined(M64P_CORE_PROTOTYPES)
 185 EXPORT int          CALL ConfigGetParamInt(m64p_handle, const char *);
 186 EXPORT float        CALL ConfigGetParamFloat(m64p_handle, const char *);
 187 EXPORT int          CALL ConfigGetParamBool(m64p_handle, const char *);
 188 EXPORT const char * CALL ConfigGetParamString(m64p_handle, const char *);
 189 #endif
 190
 191 /* ConfigGetSharedDataFilepath()
 192  *
 193  * This function is provided to allow a plugin to retrieve a full pathname to a
 194  * given shared data file. This type of file is intended to be shared among
 195  * multiple users on a system, so it is likely to be read-only.
 196  */
 197 typedef const char * (*ptr_ConfigGetSharedDataFilepath)(const char *);
 198 #if defined(M64P_CORE_PROTOTYPES)
 199 EXPORT const char * CALL ConfigGetSharedDataFilepath(const char *);
 200 #endif
 201
 202 /* ConfigGetUserConfigPath()
 203  *
 204  * This function may be used by the plugins or front-end to get a path to the
 205  * directory for storing user-specific configuration files. This will be the
 206  * directory where "mupen64plus.cfg" is located.
 207  */
 208 typedef const char * (*ptr_ConfigGetUserConfigPath)(void);
 209 #if defined(M64P_CORE_PROTOTYPES)
 210 EXPORT const char * CALL ConfigGetUserConfigPath(void);
 211 #endif
 212
 213 /* ConfigGetUserDataPath()
 214  *
 215  * This function may be used by the plugins or front-end to get a path to the
 216  * directory for storing user-specific data files. This may be used to store
 217  * files such as screenshots, saved game states, or hi-res textures.
 218  */
 219 typedef const char * (*ptr_ConfigGetUserDataPath)(void);
 220 #if defined(M64P_CORE_PROTOTYPES)
 221 EXPORT const char * CALL ConfigGetUserDataPath(void);
 222 #endif
 223
 224 /* ConfigGetUserCachePath()
 225  *
 226  * This function may be used by the plugins or front-end to get a path to the
 227  * directory for storing cached user-specific data files. Files in this
 228  * directory may be deleted by the user to save space, so critical information
 229  * should not be stored here.  This directory may be used to store files such
 230  * as the ROM browser cache.
 231  */
 232 typedef const char * (*ptr_ConfigGetUserCachePath)(void);
 233 #if defined(M64P_CORE_PROTOTYPES)
 234 EXPORT const char * CALL ConfigGetUserCachePath(void);
 235 #endif
 236
 237 #ifdef __cplusplus
 238 }
 239 #endif
 240
 241 #endif /* #define M64P_CONFIG_H */
 242