Differences

This shows you the differences between two versions of the page.

--- blog:x68_launcher_2 [2020/08/22 20:09] – john
+++ blog:x68_launcher_2 [2020/08/23 19:20] (current) – [Control Flow (a simple main.c)] john
@@ Line 347: / Line 347: @@
 **Output**
-   * gamedata_t *
+   * gamedata_t *gamedata
 **Description**
+The function takes the head item of the //gamedata// linked-list and loops over all nodes until it finds an instance of a gamedata struct with the game ID //gameid//.
+We use this function to find a gamedata object when we only know a game ID. Once we have a games gamedata object, we can then use it to look up the additional metadata, since the gamedata object tells us whether it has that additional data file, and where it is located on the filesystem.
 **Example**
+<code "C">
+int gameid;
+gamedata_t *gamedata_head = NULL;
+gameid = 23;
+// Assuming the gamedata list is already populated...
+// Keep a record of the head of the list
+gamedata_head = gamedata;
+// Return the node which matches the given gameid
+gamedata = getGameid(gameid);
+if (gamedata != NULL){
+   printf("Game ID %d is %s\n", gameid, gamedata->name);
+}
+</code>
 ----
-=== gamedata_t * getLastGamedata() ===
+=== getLastGamedata() ===
-gamedata_t *gamedata
+**Input**
+   * gamedata_t *
+**Output**
+   * gamedata_t *gamedata
+**Description**
+This function loops over all items of the gamedata list, from the current position, until it reaches the end (defined as being the node where the //next// pointer is NULL). We use this to determine where to add a new item to the list.
+**Example**
+This is __only__ currently called within the //findDirs()// function and is used to immediately prior to adding a new item to the end of the list. This ensures the list is always extended in one direction and we never overwrite the current list node:
+<code "C">
+gamedata = getLastGamedata(gamedata);
+gamedata->next = (gamedata_t *) malloc(sizeof(gamedata_t));
+gamedata->next->game_id = 1234;
+gamedata->next->drive = drvNumToLetter(buffer.driveno);
+strcpy(gamedata->next->path, search_dirname);
+strcpy(gamedata->next->name, buffer.name);
+gamedata->next->has_dat = dirHasData(search_dirname);
+gamedata->next->next = NULL;
+</code>
 ----
-=== imagefile_t * getLastImage() ===
+=== getLastImage() ===
-imagefile_t *imagefile
+**Input**
+   * imagefile_t *imagefile
+**Output**
+   * imagefile_t *imagefile
+**Description**
+Works much the same as the getLastGamedata() function in that it traverses the image list from the current position until it finds the end (determined by the //next// value being NULL).
+**Example**
+This function is only called within getImageList() within data.c, and is used to build the list of image/artwork/screenshot files as set within a metadata file:
+<code "C">
+imagefile = getLastImage(imagefile);
+imagefile->next = (imagefile_t *) malloc(sizeof(imagefile_t));
+strcpy(imagefile->next->filename, p);
+imagefile->next->next = NULL;
+</code>
 ----
-=== gamedir_t * getLastGameDir() ===
+=== getLastGameDir() ===
+**Input**
+   * gamedir_t *gamedir
+**Output**
+   * gamedir_t *gamedir
+**Description**
+Behaves the same as //getLastGanedata()// and //getLastImage()// but for the game search directories as defined in the application config file. However, the list of game search directories is only parsed once, at startup, so this function remains unused.
+**Example**
-gamedir_t *gamedir
+__Not currently used.__
 ----
-=== int removeGamedata() ===
+=== removeGamedata() ===
-gamedata_t *gamedata, int verbose
+**Input**
+   * gamedata_t *gamedata
+   * int verbose
+**Output**
+   * int
+**Description**
+**Example**
 ----
-=== int removeImagefile() ===
+=== removeImagefile() ===
-imagefile_t *imagefile
+**Input**
+   * imagefile_t *imagefile
+**Output**
+   * int
+**Description**
+**Example**
 ----
-=== int sortGamedata() ===
+=== sortGamedata() ===
-gamedata_t *gamedata, int verbose
+**Input**
+   * gamedata_t *gamedata
+   * int verbose
+**Output**
+  * int
+**Description**
+**Example**
 ----
-=== int swapGamedata() ===
+=== swapGamedata() ===
-gamedata_t *gamedata1, gamedata_t *gamedata2
+**Input**
+   * gamedata_t *gamedata1
+   * gamedata_t *gamedata2
+**Output**
+   * int
+**Description**
+**Example**
 ----
-=== static int launchdatHandler() ===
+=== launchdatHandler() ===
-void* user, const char* section, const char* name, const char* value
+**Input**
+   * void* user
+   * const char* section
+   * const char* name
+   * const char* value
+**Output**
+   * int
+**Description**
+**Example**
 ----
-=== void launchdataDefaults() ===
+=== launchdataDefaults() ===
-launchdat_t *launchdat
+**Input**
+   * launchdat_t *launchdat
+**Description**
+**Example**
 ----
-=== void configDefaults() ===
+=== configDefaults() ===
-config_t *config
+**Input**
+   * config_t *config
+**Description**
+**Example**
 ----
-=== int getLaunchdata() ===
+=== getLaunchdata() ===
-gamedata_t *gamedata, launchdat_t *launchdat
+**Input**
+   * gamedata_t *gamedata
+   * launchdat_t *launchdat
+**Output**
+   * int
+**Description**
+**Example**
 ----
-=== static int configHandler() ===
+=== configHandler() ===
-void* user, const char* section, const char* name, const char* value
+**Input**
+   * void* user
+   * const char* section
+   * const char* name
+   * const char* value
+**Output**
+   * static int
+**Description**
+**Example**
 ----
-=== int getIni() ===
+=== getIni() ===
-config_t *config, int verbose
+**Input**
+   * config_t *config
+   * int verbose
+**Output**
+   * int
+**Description**
+**Example**
 ----
-=== int getImageList() ===
+=== getImageList() ===
-launchdat_t *launchdat, imagefile_t *imagefile
+**Input**
+   * launchdat_t *launchdat
+   * imagefile_t *imagefile
+**Output**
+   * int
+**Description**
+**Example**
 ----
-=== int getDirList() ===
+=== getDirList() ===
-config_t *config, gamedir_t *gamedir, int verbose
+**Input**
+   * config_t *config
+   * gamedir_t *gamedir
+   * int verbose
+**Output**
+   * int
+**Description**
+**Example**
 ----
@@ Line 449: / Line 657: @@
    * https://github.com/megatron-uk/x68klauncher/blob/master/src/ini.c
    * https://github.com/megatron-uk/x68klauncher/blob/master/src/ini.h
+The ini parsing library is a drop-in component from https://github.com/benhoyt/inih.
+The entire contents of __ini.c__ and __ini.h__ are from that project, only modified to disable or enable certain functionality.
+The ini parsing functions are used only by a small number of calls within __data.c__, they are not directly called by any other code within the application.
 ==== Example Configuration ====
+The configuration file for the application is (by default, via a constant in //data.h//) named __launcher.txt__ and is searched for in the same directory as the launcher application itself. A hardcoded path is not defined.
+The contents of an example config file could look as follows
 <code>
 [default]
 verbose=1
+savedirs=0
 gamedirs=A:\Games,A:\Games3
 </code>
+At a minimum the '//default//' section header and a //gamedirs// variable should be present.
 ==== Control Flow (a simple main.c) ====
@@ Line 468: / Line 689: @@
 gamedata_t *gamedata_head = NULL;   // Constant pointer to the start of the gamedata list
-// Create a new empty gamedata entry
+// Create a new empty gamedata entry which will hold all of
+// the games that we find
 gamedata = (gamedata_t *) malloc(sizeof(gamedata_t));
 gamedata->next = NULL;
-// Parse the gamedirs that are set
+// Create a new gamedir list to hold the game search directories
+// which are extracted from the application config file
 gamedir = (gamedir_t *) malloc(sizeof(gamedir_t));
 gamedir->next = NULL;
-// Create an instance of a config data
+// Create an instance of a config data, which will be filled
+// by parsing the application config ini file
 config = (config_t *) malloc(sizeof(config_t));
 config->dir = NULL;