1 /* ScummVM - Graphic Adventure Engine 2 * 3 * ScummVM is the legal property of its developers, whose names 4 * are too numerous to list here. Please refer to the COPYRIGHT 5 * file distributed with this source distribution. 6 * 7 * This program is free software; you can redistribute it and/or 8 * modify it under the terms of the GNU General Public License 9 * as published by the Free Software Foundation; either version 2 10 * of the License, or (at your option) any later version. 11 * 12 * This program is distributed in the hope that it will be useful, 13 * but WITHOUT ANY WARRANTY; without even the implied warranty of 14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 15 * GNU General Public License for more details. 16 * 17 * You should have received a copy of the GNU General Public License 18 * along with this program; if not, write to the Free Software 19 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 20 * 21 */ 22 23 #ifndef GLK_TADS_TADS2_APPCTX 24 #define GLK_TADS_TADS2_APPCTX 25 26 #include "common/scummsys.h" 27 #include "glk/tads/os_frob_tads.h" 28 29 namespace Glk { 30 namespace TADS { 31 namespace TADS2 { 32 33 /** 34 * Application container context. The TADS run-time is a subsystem that 35 * can be invoked from different types of applications; in fact, even 36 * when only the standard stand-alone run-time is considered, multiple 37 * application containers must be supported because of differences 38 * between operating systems. The application container context is an 39 * optional mechanism that the main application can use to provide 40 * structured interaction between itself and the TADS run-time subsystem. 41 * 42 * The function pointers contained herein are intended to allow the 43 * run-time subsystem to call the host system to notify it of certain 44 * events, or obtain optional services from the host system. Any of 45 * these function pointers can be null, in which case the run-time 46 * subsystem will skip calling them. 47 * 48 * Note that each function has an associated callback context. This 49 * allows the host system to recover any necessary context information 50 * when the callback is invoked. 51 */ 52 struct appctxdef { 53 /** 54 * Get the .GAM file name. The run-time will call this only if it 55 * can't find a game file to load through some other means first. 56 * The run-time determines the game file first by looking at the 57 * command line, then by checking to see if a .GAM file is attached 58 * to the executable. If none of these checks yields a game, the 59 * run-time will call this routine to see if the host system wants 60 * to provide a game. This routine can be implemented on a GUI 61 * system, for example, to display a dialog prompting the user to 62 * select a game file to open. A trivial implementation of this 63 * routine (that merely returns false) is okay. 64 * 65 * This routine should return true (any non-zero value) if it 66 * provides the name of a file to open, false (zero) if not. 67 */ 68 int (*get_game_name)(void *appctxdat, char *buf, size_t buflen); 69 void *get_game_name_ctx; 70 71 /** 72 * Set the .GAM file name. When the run-time determines the name of 73 * the file it will use to read the game, it calls this routine. 74 * The host system should note the game filename if it will need to 75 * access the game file itself (for example, to load resources). 76 */ 77 void (*set_game_name)(void *appctxdat, const char *fname); 78 void *set_game_name_ctx; 79 80 /** 81 * Set the root path for individual resources. By default, we use the 82 * directory containing the game file, but this can be used to override 83 * that. 84 */ 85 void (*set_res_dir)(void *appctxdat, const char *fname); 86 void *set_res_dir_ctx; 87 88 /** 89 * Set the resource map address in the game file. If the .GAM 90 * reader encounters a resource map in the file, it calls this 91 * routine with the seek offset of the first resource. Each 92 * resource's address is given as an offset from this point. 93 * 94 * fileno is the file number assigned by the host system in 95 * add_resfile. File number zero is always the .GAM file. 96 */ 97 void (*set_resmap_seek)(void *appctxdat, unsigned long seekpos, int fileno); 98 void *set_resmap_seek_ctx; 99 100 /** 101 * Add a resource entry. The 'ofs' entry is the byte offset of the 102 * start of the resource, relative to the seek position previously 103 * set with set_resmap_seek. 'siz' is the size of the resource in 104 * bytes; the resource is stored as contiguous bytes starting at the 105 * given offset for the given size. Note that resources may be 106 * added before the resource map seek position is set, so the host 107 * system must simply store the resource information for later use. 108 * The 'fileno' is zero for the .GAM file, or the number assigned by 109 * the host system in add_resfile for other resource files. 110 */ 111 void (*add_resource)(void *appctxdat, unsigned long ofs, 112 unsigned long siz, const char *nm, size_t nmlen, 113 int fileno); 114 void *add_resource_ctx; 115 116 /** 117 * Add a resource link entry. 'fname' and 'fnamelen' give the name of 118 * a local file containing the resource data; 'resname' and 119 * 'resnamelen' give the name of the resource as it appears within the 120 * compiled game file. This creates a link from a .GAM resource name 121 * to a local filename, where the actual binary resource data reside, 122 * so that we can retrieve a resource by .GAM resource name without 123 * actually copying the data into the .GAM file. This is used mostly 124 * for debugging purposes: it allows the compiler to skip the step of 125 * copying the resource data into the .GAM file, but still allows the 126 * game to load resources by .GAM resource name, to create a testing 127 * environment that's consistent with the full build version (where the 128 * resources would actually be copied). 129 */ 130 void (*add_resource_link)(void *appctxdat, 131 const char *fname, size_t fnamelen, 132 const char *resname, size_t resnamelen); 133 void *add_resource_link_ctx; 134 135 /** 136 * Add a resource path. 'path' is a string giving a directory prefix 137 * in local system notation. 138 * 139 * This adds a directory to the list of directories that we'll search 140 * when we're looking for an individual resource as an external file 141 * (such as a ".jpg" image file or ".ogg" sound file). This can be 142 * called zero or more times; each call adds another directory to 143 * search after any previous directories. We'll always search the 144 * default directory first (this is the directory containing the game 145 * file); then we'll search directories added with this call in the 146 * order in which the directories were added. 147 */ 148 void (*add_res_path)(void *appctxdat, const char *path, size_t len); 149 void *add_res_path_ctx; 150 151 /** 152 * Find a resource entry. If the resource can be found, this must 153 * return an osfildef* handle to the resource, with its seek position 154 * set to the first byte of the resource data, and set *res_size to 155 * the size in bytes of the resource data in the file. If the 156 * resource cannot be found, returns null. 157 */ 158 osfildef *(*find_resource)(void *appctxdat, 159 const char *resname, size_t resnamelen, 160 unsigned long *res_size); 161 void *find_resource_ctx; 162 163 /** 164 * Add a resource file. The return value is a non-zero file number 165 * assigned by the host system; we'll use this number in subsequent 166 * calls to add_resource to add the resources from this file. 167 * 168 * After calling this routine to add the file, we'll parse the file 169 * and add any resources using add_resource. 170 */ 171 int (*add_resfile)(void *appctxdat, const char *fname); 172 void *add_resfile_ctx; 173 174 /** 175 * Determine if a resource exists. Returns true if the resource can 176 * be loaded, false if not. The resource name is in the standard 177 * URL-style format. 178 */ 179 int (*resfile_exists)(void *appctxdat, const char *res_name, 180 size_t res_name_len); 181 void *resfile_exists_ctx; 182 183 /** 184 * Resource file path. If we should look for resource files in a 185 * different location than the .GAM file, the host system can set 186 * this to a path that we should use to look for resource files. If 187 * it's null, we'll look in the directory that contains the .GAM 188 * file. Note that if the path is provided, it must be set up with 189 * a trailing path separator character, so that we can directly 190 * append a name to this path to form a valid fully-qualified 191 * filename. 192 */ 193 const char *ext_res_path; 194 195 /** 196 * File safety level get/set. During initialization, we'll call the 197 * host system to tell it the file safety level selected by the user on 198 * the command line; if the host system is saving preference 199 * information, it should temporarily override its saved preferences 200 * and use the command line setting (and it may, if appropriate, want 201 * to save the command line setting as the saved preference setting, 202 * depending on how it handles preferences). During execution, any 203 * time the game tries to open a file (using the fopen built-in 204 * function), we'll call the host system to ask it for the current 205 * setting, and use this new setting rather than the original command 206 * line setting. 207 * 208 * Refer to bif.c for information on the meanings of the file safety 209 * levels. 210 */ 211 void (*set_io_safety_level)(void *ctx, int read, int write); 212 void (*get_io_safety_level)(void *ctx, int *read, int *write); 213 void *io_safety_level_ctx; 214 215 /** 216 * Network safety level get/set. This is analogous to the file safety 217 * level scheme, but controls access to network resources. There are 218 * two components to the network safety setting: client and server. 219 * The client component controls the game's ability to open network 220 * connections to access information on remote machines, such as 221 * opening http connections to access web sites. The server component 222 * controls the game's ability to create servers of its own and accept 223 * incoming connections. Each component can be set to one of the 224 * following: 225 * 226 *. 0 = no restrictions (least "safety"): all network access granted 227 *. 1 = 'localhost' access only 228 *. 2 = no network access 229 * 230 * This only applies to the TADS 3 VM. TADS 2 doesn't support any 231 * network features, so this doesn't apply. 232 */ 233 void (*set_net_safety_level)(void *ctx, int client_level, int srv_level); 234 void (*get_net_safety_level)(void *ctx, int *client_level, int *srv_level); 235 void *net_safety_level_ctx; 236 237 /** 238 * Name of run-time application for usage messages. If this is 239 * null, the default run-time application name will be used for 240 * usage messages. 241 */ 242 const char *usage_app_name; 243 }; 244 245 } // End of namespace TADS2 246 } // End of namespace TADS 247 } // End of namespace Glk 248 249 #endif 250