1 /* $Header: d:/cvsroot/tads/TADS2/appctx.h,v 1.2 1999/05/17 02:52:14 MJRoberts Exp $ */ 2 3 /* 4 * Copyright (c) 1997, 2002 Michael J. Roberts. All Rights Reserved. 5 * 6 * Please see the accompanying license file, LICENSE.TXT, for information 7 * on using and copying this software. 8 */ 9 /* 10 Name 11 appctx.h - Application container context definitions 12 Function 13 Defines structures related to the TADS runtime application 14 Notes 15 16 Modified 17 9/05/98 CNebel - Spliced off from trd.h. 18 */ 19 20 #ifndef APPCTX_H 21 #define APPCTX_H 22 23 #ifdef __cplusplus 24 extern "C" { 25 #endif 26 27 /* 28 * Application container context. The TADS run-time is a subsystem that 29 * can be invoked from different types of applications; in fact, even 30 * when only the standard stand-alone run-time is considered, multiple 31 * application containers must be supported because of differences 32 * between operating systems. The application container context is an 33 * optional mechanism that the main application can use to provide 34 * structured interaction between itself and the TADS run-time subsystem. 35 * 36 * The function pointers contained herein are intended to allow the 37 * run-time subsystem to call the host system to notify it of certain 38 * events, or obtain optional services from the host system. Any of 39 * these function pointers can be null, in which case the run-time 40 * subsystem will skip calling them. 41 * 42 * Note that each function has an associated callback context. This 43 * allows the host system to recover any necessary context information 44 * when the callback is invoked. 45 */ 46 typedef struct appctxdef appctxdef; 47 struct appctxdef 48 { 49 /* 50 * Get the .GAM file name. The run-time will call this only if it 51 * can't find a game file to load through some other means first. 52 * The run-time determines the game file first by looking at the 53 * command line, then by checking to see if a .GAM file is attached 54 * to the executable. If none of these checks yields a game, the 55 * run-time will call this routine to see if the host system wants 56 * to provide a game. This routine can be implemented on a GUI 57 * system, for example, to display a dialog prompting the user to 58 * select a game file to open. A trivial implementation of this 59 * routine (that merely returns false) is okay. 60 * 61 * This routine should return true (any non-zero value) if it 62 * provides the name of a file to open, false (zero) if not. 63 */ 64 int (*get_game_name)(void *appctxdat, char *buf, size_t buflen); 65 void *get_game_name_ctx; 66 67 /* 68 * Set the .GAM file name. When the run-time determines the name of 69 * the file it will use to read the game, it calls this routine. 70 * The host system should note the game filename if it will need to 71 * access the game file itself (for example, to load resources). 72 */ 73 void (*set_game_name)(void *appctxdat, const char *fname); 74 void *set_game_name_ctx; 75 76 /* 77 * Set the root path for individual resources. By default, we use the 78 * directory containing the game file, but this can be used to override 79 * that. 80 */ 81 void (*set_res_dir)(void *appctxdat, const char *fname); 82 void *set_res_dir_ctx; 83 84 /* 85 * Set the resource map address in the game file. If the .GAM 86 * reader encounters a resource map in the file, it calls this 87 * routine with the seek offset of the first resource. Each 88 * resource's address is given as an offset from this point. 89 * 90 * fileno is the file number assigned by the host system in 91 * add_resfile. File number zero is always the .GAM file. 92 */ 93 void (*set_resmap_seek)(void *appctxdat, unsigned long seekpos, 94 int fileno); 95 void *set_resmap_seek_ctx; 96 97 /* 98 * Add a resource entry. The 'ofs' entry is the byte offset of the 99 * start of the resource, relative to the seek position previously 100 * set with set_resmap_seek. 'siz' is the size of the resource in 101 * bytes; the resource is stored as contiguous bytes starting at the 102 * given offset for the given size. Note that resources may be 103 * added before the resource map seek position is set, so the host 104 * system must simply store the resource information for later use. 105 * The 'fileno' is zero for the .GAM file, or the number assigned by 106 * the host system in add_resfile for other resource files. 107 */ 108 void (*add_resource)(void *appctxdat, unsigned long ofs, 109 unsigned long siz, const char *nm, size_t nmlen, 110 int fileno); 111 void *add_resource_ctx; 112 113 /* 114 * Find a resource entry. If the resource can be found, this must 115 * return an osfildef* handle to the resource, with its seek position 116 * set to the first byte of the resource data, and set *res_size to 117 * the size in bytes of the resource data in the file. If the 118 * resource cannot be found, returns null. 119 */ 120 osfildef *(*find_resource)(void *appctxdat, 121 const char *resname, size_t resnamelen, 122 unsigned long *res_size); 123 void *find_resource_ctx; 124 125 /* 126 * Add a resource file. The return value is a non-zero file number 127 * assigned by the host system; we'll use this number in subsequent 128 * calls to add_resource to add the resources from this file. 129 * 130 * After calling this routine to add the file, we'll parse the file 131 * and add any resources using add_resource. 132 */ 133 int (*add_resfile)(void *appctxdat, const char *fname); 134 void *add_resfile_ctx; 135 136 /* 137 * Determine if a resource exists. Returns true if the resource can 138 * be loaded, false if not. The resource name is in the standard 139 * URL-style format. 140 */ 141 int (*resfile_exists)(void *appctxdat, const char *res_name, 142 size_t res_name_len); 143 void *resfile_exists_ctx; 144 145 /* 146 * Resource file path. If we should look for resource files in a 147 * different location than the .GAM file, the host system can set 148 * this to a path that we should use to look for resource files. If 149 * it's null, we'll look in the directory that contains the .GAM 150 * file. Note that if the path is provided, it must be set up with 151 * a trailing path separator character, so that we can directly 152 * append a name to this path to form a valid fully-qualified 153 * filename. 154 */ 155 const char *ext_res_path; 156 157 /* 158 * File safety level get/set. During initialization, we'll call the 159 * host system to tell it the file safety level selected by the user 160 * on the command line; if the host system is saving preference 161 * information, it should temporarily override its saved preferences 162 * and use the command line setting (and it may, if appropriate, 163 * want to save the command line setting as the saved preference 164 * setting, depending on how it handles preferences). During 165 * execution, any time the game tries to open a file (using the 166 * fopen built-in function), we'll call the host system to ask it 167 * for the current setting, and use this new setting rather than the 168 * original command line setting. 169 * 170 * Refer to bif.c for information on the meanings of the file safety 171 * levels. 172 */ 173 void (*set_io_safety_level)(void *ctx, int level); 174 int (*get_io_safety_level)(void *ctx); 175 void *io_safety_level_ctx; 176 177 /* 178 * Name of run-time application for usage messages. If this is 179 * null, the default run-time application name will be used for 180 * usage messages. 181 */ 182 const char *usage_app_name; 183 }; 184 185 #ifdef __cplusplus 186 } 187 #endif 188 189 #endif 190