deps/libretro-common/include/formats/logiqx_dat.h

   1 /* Copyright  (C) 2010-2020 The RetroArch team
   2  *
   3  * ---------------------------------------------------------------------------------------
   4  * The following license statement only applies to this file (logiqx_dat.h).
   5  * ---------------------------------------------------------------------------------------
   6  *
   7  * Permission is hereby granted, free of charge,
   8  * to any person obtaining a copy of this software and associated documentation files (the "Software"),
   9  * to deal in the Software without restriction, including without limitation the rights to
  10  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software,
  11  * and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
  12  *
  13  * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
  14  *
  15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
  16  * INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  18  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
  19  * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  20  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  21  */
  22
  23 #ifndef __LIBRETRO_SDK_FORMAT_LOGIQX_DAT_H__
  24 #define __LIBRETRO_SDK_FORMAT_LOGIQX_DAT_H__
  25
  26 #include <retro_common_api.h>
  27 #include <retro_miscellaneous.h>
  28
  29 #include <boolean.h>
  30
  31 RETRO_BEGIN_DECLS
  32
  33 /* Trivial handler for DAT files in Logiqx XML format
  34  * (http://www.logiqx.com/). Provides bare minimum
  35  * functionality - predominantly concerned with obtaining
  36  * description text for specific arcade ROM images.
  37  *
  38  * Note: Also supports the following alternative DAT
  39  * formats, since they are functionally identical to
  40  * Logiqx XML (but with different element names):
  41  * > MAME List XML
  42  * > MAME 'Software List' */
  43
  44 /* Prevent direct access to logiqx_dat_t members */
  45 typedef struct logiqx_dat logiqx_dat_t;
  46
  47 /* Holds all metadata for a single game entry
  48  * in the DAT file (minimal at present - may be
  49  * expanded with individual internal ROM data
  50  * if required) */
  51 typedef struct
  52 {
  53    char name[PATH_MAX_LENGTH];
  54    char description[PATH_MAX_LENGTH];
  55    char year[8];
  56    char manufacturer[128];
  57    bool is_bios;
  58    bool is_runnable;
  59 } logiqx_dat_game_info_t;
  60
  61 /* Validation */
  62
  63 /* Performs rudimentary validation of the specified
  64  * Logiqx XML DAT file path (not rigorous - just
  65  * enough to prevent obvious errors).
  66  * Also provides access to file size (DAT files can
  67  * be very large, so it is useful to have this information
  68  * on hand - i.e. so we can check that the system has
  69  * enough free memory to load the file). */
  70 bool logiqx_dat_path_is_valid(const char *path, uint64_t *file_size);
  71
  72 /* File initialisation/de-initialisation */
  73
  74 /* Loads specified Logiqx XML DAT file from disk.
  75  * Returned logiqx_dat_t object must be free'd using
  76  * logiqx_dat_free().
  77  * Returns NULL if file is invalid or a read error
  78  * occurs. */
  79 logiqx_dat_t *logiqx_dat_init(const char *path);
  80
  81 /* Frees specified DAT file */
  82 void logiqx_dat_free(logiqx_dat_t *dat_file);
  83
  84 /* Game information access */
  85
  86 /* Sets/resets internal node pointer to the first
  87  * entry in the DAT file */
  88 void logiqx_dat_set_first(logiqx_dat_t *dat_file);
  89
  90 /* Fetches game information for the current entry
  91  * in the DAT file and increments the internal node
  92  * pointer.
  93  * Returns false if the end of the DAT file has been
  94  * reached (in which case 'game_info' will be invalid) */
  95 bool logiqx_dat_get_next(
  96       logiqx_dat_t *dat_file, logiqx_dat_game_info_t *game_info);
  97
  98 /* Fetches information for the specified game.
  99  * Returns false if game does not exist, or arguments
 100  * are invalid. */
 101 bool logiqx_dat_search(
 102       logiqx_dat_t *dat_file, const char *game_name,
 103       logiqx_dat_game_info_t *game_info);
 104
 105 RETRO_END_DECLS
 106
 107 #endif