X68000 Game Launcher - #2: Filesystem tools, data scraping & config loader

X68000 Game Launcher - #2: Filesystem tools, data scraping & config loader

This is an old revision of the document!

This library uses the following common header fragment:

#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include <dos.h>
 
#include "newlib_fixes.h"
#include "data.h"
#include "fstools.h"

We also have a few constants:

#define FS_VERBOSE	0	// Enable/disable fstools verbose/debug output
#define DIR_BUFFER_SIZE	65	// Size of array for accepting directory paths
#define MAX_DRIVES	26	// Maximum number of drive letters
#define DRIVE_LETTERS	{'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', 'N', 'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z' }

Hopefully most of those make sense.

The only interesting piece of information here is the newlib_fixes.h header. This contains some fixes to functions that were included in the Lydux GCC standard C library. The following functions in the standard C library are replaced:

extern int _dos_files(struct dos_filbuf *, const char *, int);
extern int _dos_nfiles(struct dos_filbuf *);
extern int _dos_exfiles(struct dos_exfilbuf *, const char *, int);
extern int _dos_exnfiles(struct dos_exfilbuf *);

The only reason those fixes are here is that the versions in the standard C library are mis-labelled. No other changes are applied.

The fstools.c library contains additional calls built on top of basic Hudson68k IO calls and C library system calls to search directory paths, extract drive letters from path names, store the current path whilst changing drives, etc.

The main function which is called from outside the library is findDirs() which is called by the main application control loop.

int dirFromPath(char path, char buffer)

Input

char *path - The full path to be extracted
char *buffer - An empty string buffer into which the directory name will be copied

Output

Returns 0 on success, -1 on error.

Description

Splits a fully qualified path, such as “A:\Games” and returns the “Games” part. Also copes with multi-level paths, such as “A:\Stuff\Games\Games_All”, returning “Stuff\Games\Games_All”.

This is implemented since we have to change drive and directory seperately (Hudson68k provides two seperate calls).

Example

int status;
char buffer[99];
 
status = dirFromPath("A:\\Games", buffer);
if (status == 0){
   printf("Dirname is: %s", buffer);
}

int dirHasData(char *path)

Input

char *path - The directory to check

Output

Returns 1 if a file containing metadata for the launcher application is found within a given directory. Otherwise returns 0.

Description

If we add some method of adding additional data to a game (year of release, genre, some screenshots or artwork), we need a method of storing this information. We could use a central database or record file, but it would be much easier to have a simple text file included with each game. We'll define what that file should be, and what it should contain elsewhere (in data.h), for now we just assume that the name will be fixed, and we try to open it with the Hudson68k equivalent call _dos_open(). If the call succeeds, then we return a value to indicate it. We don't do anything with the contents of the file here.

Example

int status;
 
status = dirHasData("Games\\Arkanoid2");
if (status){
   printf("This directory has additional metadata file!\n");
}

int drvLetterToNum(char drive_letter)

Inputs

char drive_letter - Upper case single character; “A”, “B”, etc.

Output

Returns an integer representing the drive letter. 0 == A, 1 == B, etc.

Description

The Hudson68k system calls for changing drives actually uses numbers, so we need a method for mapping the drive letter part of a path into an integer which can be used in those calls. This uses the DRIVE_LETTERS constant defined in the header.

Example

int drv_num;
char drv_letter;
 
drv_letter = "A";
 
drv_num = drvLetterToNum(drv_letter);
printf("Drive number for %c: is %d\n", drv_letter, drv_num);

char drvNumToLetter(int drive_number)

Input

int drive_number - A number representing a drive; 0, 1, 2, etc.

Output

Returns a single upper-case character for the drive; A == 0, B == 1, etc.

Description

Exactly the inverse behaviour of drvLetterToNum().

Example

int drv_num;
char drv_letter;
 
drv_num = 0;
 
drv_letter = drvNumToLetter(drv_num);
printf("Drive number for %c: is %d\n", drv_letter, drv_num);

int isDir(char *path)

Input

char *path - A string representing a directory path without the drive prefix; e.g. “Stuff\Games”

Output

Returns 1 if the path is a directory, returns 0 if the path is actually a file or other non-directory object.

Description

The C library for X68000 as distributed with the Lydux GCC toolchain is missing some of the standard directory/file functions as you would expect in a mainly-posix library; namely missing stat, dirent and equivalent.

Normally you would use opendir(“path”) to determine if a path was a directory or not, but that isn't present here. Instead we use the Hudson68k system call _dos_open(), which is normally used to open a file. Instead if you try to open a directory with this call an error value of _DOSE_ISDIR is returned, that's an easy way to tell if a path is a file or a directory.

Anywhere in our code we can now use isDir(“path”) and get a 1 if it is a dir, 0 if not.

Example

int status;
 
status = isDir("A:\\This\\is\\not\\a\\folder");
if (status == 1){
   printf("Directory\n");
} else {
   printf("Not a directory\n");
}

int findDirs(char path, gamedata_t gamedata, int startnum)

Input

char *path - A string representing a fully qualified path; e.g. “A:\Stuff\Games”
gamedata_t *gamedata - A linked list of structs, each one defining a “found” game
int startnum - Each “found” game is given a unique ID, if findDirs() is called multiple times, we can pass the starting number of the next batch of ID's.

Returns

An integer representing the number of immediate sub-directories found in the searchpath path.

Description

This is the main function which is called from outside of the library. Most notably, we'll need to call the findDirs() function for each path that we define as potentially holding game folders; e.g.

int found1, found2, found3, found;
found1 = found2 = found3 = found = 0;
 
found1 = findDirs("A:\\Games", gamedata, found);
found += found1;
 
found2 = findDirs("A:\\Games2", gamedata, found);
found += found2;
 
found3 = findDirs("C:\\Games4", gamedata, found);
found += found3;

We go into the structure of gamedata_t structs further down the page, but for now, it's sufficient to know that it's a linked list of all the individual game subdirectories that we find. Any new subdirectory found is added on to the list at the end.

We use all of the previous functions here, finding if paths are valid, if subdirectories have metadata files in them, etc. The results of that are used to determine if a valid game folder has been found and if a new object should be added to the gamedata list.

Finally, after we run out of directory entries to search we return a count of how many subdirectories/gamedata objects have been found and created. We can then use the linked list of gamedata objects elsewhere in our application.

This function library has the following constants defined:

#define SAVEFILE		"launcher.txt"		// A text file holding the list of all found directories
#define INIFILE			"launcher.ini"		// the ini file holding settings for the main application
#define GAMEDAT			"launch.dat"		// the name of the data file in the game dir to load
#define DEFAULT_GENRE		"Unknown Genre"		// Default genre
#define DEFAULT_YEAR 		0			// Default year
#define DEFAULT_START		"!start.bat"		// Default replacement for !start.bat is... erm... !start.bat
#define DEFAULT_PUBLISHER	""			// Default publisher
#define DEFAULT_DEVELOPER	""			// Default developer
#define MAX_IMAGES		16			// max number of images we try to load
#define IMAGE_BUFFER_SIZE	256			// Maximum size of game screenshot string (8 + 22 + overhead) 
#define MAX_DIRS		16			// Maximum number of game search paths - 16 sounds... okay?

More importantly, it also defines the following custom data structure types:

gamedata_t

typedef struct gamedata {
	int gameid;		// Unique ID for this game - assigned at scan time
	char drive;		// Drive letter
	char path[65];		// Full drive and path name; e.g. A:\Games\FinalFight
	char name[22];		// Just the directory name; e.g. FinalFight
	int has_dat;		// Flag to indicate __launch.dat was found in the game directory
	struct gamedata *next;	// Pointer to next gamedata entry
} __attribute__((__packed__)) __attribute__((aligned (2))) gamedata_t;

launchdat_t

typedef struct launchdat {
	char realname[32];	// A 'friendly' name to display the game as, instead of just the directory name
	char genre[32];		// A string to represent the genre, in case we want to filter by genre
	int year;		// Year the game was released
	char publisher[32];	// The name of the publisher
	char developer[32];	// The name of the developer
	char start[22];		// Override the use of start.bat with an alternate executable
	char images[IMAGE_BUFFER_SIZE];		// String containing all the image filenames
} __attribute__((__packed__)) __attribute__((aligned (2))) launchdat_t;

imagefile_t

typedef struct imagefile {
	char filename[22];	// Filename of an image
	struct imagefile *next;	// Pointer to the next image file for this game
} __attribute__((__packed__)) __attribute__((aligned (2))) imagefile_t;

gamedir_t

typedef struct gamedir {
	char path[65];		// Path to search for games
	struct gamedir *next;	// Link to the next search path
} __attribute__((__packed__)) __attribute__((aligned (2))) gamedir_t;

config_t

typedef struct config {
	int verbose;		// Verbose/debug flag
	int save;		// Save the list of all games to a text file
	char dirs[1024];	// String containing all game dirs to search - it will then be parsed into a list below:
	struct gamedir *dir;	// List of all the game search dirs
} __attribute__((__packed__)) __attribute__((aligned (2))) config_t;

[default]
verbose=1
gamedirs=A:\Games,A:\Games3

Control Flow (a simple main.c)

Here's the minimal content of a simple control programme which reads our configuration file from disk, extracts the search directories and scrapes them for content (sub-directories and metadata files).

int scrape_dirs;                    // Number of directories being scraped
int found, found_tmp;	            // Number of gamedirs/games found
config_t *config = NULL;	    // Configuration data as defined in our INIFILE
gamedir_t *gamedir = NULL;	    // List of the game search directories, as defined in our INIFILE
gamedata_t *gamedata = NULL;	    // An initial gamedata record for the first game directory we read
gamedata_t *gamedata_head = NULL;   // Constant pointer to the start of the gamedata list
 
// Create a new empty gamedata entry
gamedata = (gamedata_t *) malloc(sizeof(gamedata_t));
gamedata->next = NULL;
 
// Parse the gamedirs that are set
gamedir = (gamedir_t *) malloc(sizeof(gamedir_t));
gamedir->next = NULL;
 
// Create an instance of a config data
config = (config_t *) malloc(sizeof(config_t));
config->dir = NULL;
 
// Open our config file and parse the settings inside
status = getIni(config, verbose);
if (status != 0){
    printf("Unable to parse config file!\n");
    return -1;
} 
 
// The list of directories should be at least 3 characters long (A:\)....
if (strlen(config->dirs) > 3){
    status = getDirList(config, gamedir, config->verbose);
    if (status < 1){
        printf("None of your defined directories could be found - check their paths?\n");
        return -1;
    }
} else {
    printf("No valid search directories defined in config file - set some?\n");
    return -1;
}
 
// Turn the comma seperated list of paths in our config into a list of game directories
gamedir = config->dir;
while (gamedir->next != NULL){
    gamedir = gamedir->next;
    scrape_dirs++;
}
 
// Scrape each gamedir for subdirectories containing games
gamedir = config->dir;
while (gamedir->next != NULL){
    gamedir = gamedir->next;
    found_tmp = 0;
    // Run our findDirs() function to find all first-level subdirectories in this path 
    // and check for additional metadata in each folder.
    found_tmp = findDirs(gamedir->path, gamedata, found);
    found = found + found_tmp;
    printf("Found %d games in %s", found_tmp, gamedir->path);
}
 
if (found < 1){
    printf("Sorry, no games found!\n");
    return -1
}
 
// Sort the list into A-Z
sortGamedata(gamedata, config->verbose);

At this point, presuming we've set some valid search directories, our gamedata linked-list will have an entry for each sub folder that we've found and may (or may not) have a flag set to indicate that the game has additional metadata (which may or may not include name, publisher, year, genre and a list of screenshots or other artwork).

We could potentially have dozens, if not hundreds of data objects in memory now… and it's best that we find some way of displaying this information in a way that befits a proper game browser. We need to get some graphics from disk and into memory. We need a bitmap image loader….

<< Back (#1: Design & Logical Structure) | (#3: Bitmap file loader) Next >>

Table of Contents

X68000 Game Launcher - #2: Filesystem tools, data scraping & config loader

fstools.c / fstools.h

int dirFromPath(char path, char buffer)

int dirHasData(char *path)

int drvLetterToNum(char drive_letter)

char drvNumToLetter(int drive_number)

int isDir(char *path)

int findDirs(char path, gamedata_t gamedata, int startnum)

data.c / data.h

gamedata_t

launchdat_t

imagefile_t

gamedir_t

config_t

ini.c / ini.h

Example Configuration

Control Flow (a simple main.c)

Target-Earth

Table of Contents

X68000 Game Launcher - #2: Filesystem tools, data scraping & config loader

fstools.c / fstools.h

int dirFromPath(char *path, char *buffer)

int dirHasData(char *path)

int drvLetterToNum(char drive_letter)

char drvNumToLetter(int drive_number)

int isDir(char *path)

int findDirs(char *path, gamedata_t *gamedata, int startnum)

data.c / data.h

gamedata_t

launchdat_t

imagefile_t

gamedir_t

config_t

ini.c / ini.h

Example Configuration

Control Flow (a simple main.c)

int dirFromPath(char path, char buffer)

int findDirs(char path, gamedata_t gamedata, int startnum)