1
/* $Header: d:/cvsroot/tads/TADS2/appctx.h,v 1.2 1999/05/17 02:52:14 MJRoberts Exp $ */
4
* Copyright (c) 1997, 2002 Michael J. Roberts. All Rights Reserved.
6
* Please see the accompanying license file, LICENSE.TXT, for information
7
* on using and copying this software.
11
appctx.h - Application container context definitions
13
Defines structures related to the TADS runtime application
17
9/05/98 CNebel - Spliced off from trd.h.
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.
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.
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.
46
typedef struct appctxdef appctxdef;
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.
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.
64
int (*get_game_name)(void *appctxdat, char *buf, size_t buflen);
65
void *get_game_name_ctx;
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).
73
void (*set_game_name)(void *appctxdat, const char *fname);
74
void *set_game_name_ctx;
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
81
void (*set_res_dir)(void *appctxdat, const char *fname);
82
void *set_res_dir_ctx;
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.
90
* fileno is the file number assigned by the host system in
91
* add_resfile. File number zero is always the .GAM file.
93
void (*set_resmap_seek)(void *appctxdat, unsigned long seekpos,
95
void *set_resmap_seek_ctx;
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.
108
void (*add_resource)(void *appctxdat, unsigned long ofs,
109
unsigned long siz, const char *nm, size_t nmlen,
111
void *add_resource_ctx;
114
* Add a resource link entry. 'fname' and 'fnamelen' give the name of
115
* a local file containing the resource data; 'resname' and
116
* 'resnamelen' give the name of the resource as it appears within the
117
* compiled game file. This creates a link from a .GAM resource name
118
* to a local filename, where the actual binary resource data reside,
119
* so that we can retrieve a resource by .GAM resource name without
120
* actually copying the data into the .GAM file. This is used mostly
121
* for debugging purposes: it allows the compiler to skip the step of
122
* copying the resource data into the .GAM file, but still allows the
123
* game to load resources by .GAM resource name, to create a testing
124
* environment that's consistent with the full build version (where the
125
* resources would actually be copied).
127
void (*add_resource_link)(void *appctxdat,
128
const char *fname, size_t fnamelen,
129
const char *resname, size_t resnamelen);
130
void *add_resource_link_ctx;
133
* Add a resource path. 'path' is a string giving a directory prefix
134
* in local system notation.
136
* This adds a directory to the list of directories that we'll search
137
* when we're looking for an individual resource as an external file
138
* (such as a ".jpg" image file or ".ogg" sound file). This can be
139
* called zero or more times; each call adds another directory to
140
* search after any previous directories. We'll always search the
141
* default directory first (this is the directory containing the game
142
* file); then we'll search directories added with this call in the
143
* order in which the directories were added.
145
void (*add_res_path)(void *appctxdat, const char *path, size_t len);
146
void *add_res_path_ctx;
149
* Find a resource entry. If the resource can be found, this must
150
* return an osfildef* handle to the resource, with its seek position
151
* set to the first byte of the resource data, and set *res_size to
152
* the size in bytes of the resource data in the file. If the
153
* resource cannot be found, returns null.
155
osfildef *(*find_resource)(void *appctxdat,
156
const char *resname, size_t resnamelen,
157
unsigned long *res_size);
158
void *find_resource_ctx;
161
* Add a resource file. The return value is a non-zero file number
162
* assigned by the host system; we'll use this number in subsequent
163
* calls to add_resource to add the resources from this file.
165
* After calling this routine to add the file, we'll parse the file
166
* and add any resources using add_resource.
168
int (*add_resfile)(void *appctxdat, const char *fname);
169
void *add_resfile_ctx;
172
* Determine if a resource exists. Returns true if the resource can
173
* be loaded, false if not. The resource name is in the standard
176
int (*resfile_exists)(void *appctxdat, const char *res_name,
177
size_t res_name_len);
178
void *resfile_exists_ctx;
181
* Resource file path. If we should look for resource files in a
182
* different location than the .GAM file, the host system can set
183
* this to a path that we should use to look for resource files. If
184
* it's null, we'll look in the directory that contains the .GAM
185
* file. Note that if the path is provided, it must be set up with
186
* a trailing path separator character, so that we can directly
187
* append a name to this path to form a valid fully-qualified
190
const char *ext_res_path;
193
* File safety level get/set. During initialization, we'll call the
194
* host system to tell it the file safety level selected by the user
195
* on the command line; if the host system is saving preference
196
* information, it should temporarily override its saved preferences
197
* and use the command line setting (and it may, if appropriate,
198
* want to save the command line setting as the saved preference
199
* setting, depending on how it handles preferences). During
200
* execution, any time the game tries to open a file (using the
201
* fopen built-in function), we'll call the host system to ask it
202
* for the current setting, and use this new setting rather than the
203
* original command line setting.
205
* Refer to bif.c for information on the meanings of the file safety
208
void (*set_io_safety_level)(void *ctx, int level);
209
int (*get_io_safety_level)(void *ctx);
210
void *io_safety_level_ctx;
213
* Name of run-time application for usage messages. If this is
214
* null, the default run-time application name will be used for
217
const char *usage_app_name;
added
removed
tads/tads2/appctx.h
