4
* Copyright (c) 1999, 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
vmhost.h - T3 VM host interface
13
The host interface defines a set of services that the VM obtains from
14
its host application environment. The VM uses the host interface to
15
obtain these services so that the VM doesn't have to make too many
16
assumptions about the larger application of which it is a subsystem.
17
Every application containing the VM must provide the VM with an
18
implementation of this interface.
22
07/29/99 MJRoberts - Creation
28
/* ------------------------------------------------------------------------ */
30
* I/O Safety Levels. These are defined as integers, not an enum,
31
* because they form a hierarchy; a higher value imposes all of the
32
* restrictions of all lower values, plus additional restrictions of its
36
/* level 0: minimum safety; read/write any file */
37
const int VM_IO_SAFETY_MINIMUM = 0;
39
/* level 1: read any file, write only to files in the current directory */
40
const int VM_IO_SAFETY_READ_ANY_WRITE_CUR = 1;
42
/* level 2: read/write in current directory only */
43
const int VM_IO_SAFETY_READWRITE_CUR = 2;
45
/* level 3: read from current directory only, no writing allowed */
46
const int VM_IO_SAFETY_READ_CUR = 3;
48
/* level 4: maximum safety; no file reading or writing allowed */
49
const int VM_IO_SAFETY_MAXIMUM = 4;
52
/* ------------------------------------------------------------------------ */
54
* get_image_name return codes
59
* get_image_name() call ignored - this is returned if the host
60
* system doesn't have a way of asking the user for an image name,
61
* so the caller must rely on whatever other way it has of finding
62
* the image name (which usually means that it can't find a image
63
* name at all, given that it would only call get_image_name() when
64
* it can't otherwise find the name)
69
* user chose not to supply an image name - this is returned when,
70
* for example, the user cancelled out of a file selector dialog
75
* error - the host system can't prompt for a filename because of
76
* some kind of error (not enough memory to load a dialog, for
85
/* ------------------------------------------------------------------------ */
87
* T3 VM Host Application Interface. This is an abstract class; it must
88
* be implemented by each application that embeds the VM.
93
virtual ~CVmHostIfc() { }
96
* Get the file I/O safety level. This allows the host application
97
* to control the file operations that a program running under the
98
* VM may perform. See the VM_IO_SAFETY_xxx values above.
100
virtual int get_io_safety() = 0;
103
* set the I/O safety level - this should only be done in response
104
* to a user preference setting (such as via a command-line option),
105
* never as a result of some programmatic operation by the executing
108
virtual void set_io_safety(int level) = 0;
111
* Get the resource loader for character mapping tables. This
112
* resource loader should be set up to load resources out of the VM
113
* executable or out of the directory containing the VM executable,
114
* since these resources are associated with the VM itself, not the
115
* T3 program executing under the VM.
117
virtual class CResLoader *get_cmap_res_loader() = 0;
120
* Set the image file name. The VM calls this after it learns the
121
* name of the image file so that the host system can access the
124
virtual void set_image_name(const char *fname) = 0;
127
* Set the root directory path for individual resources (such as
128
* individual image and sound resources) that we don't find in the
129
* image file or any attached resource collection file. If this is
130
* never called, the directory containing the image file should be used
131
* as the resource root directory.
133
virtual void set_res_dir(const char *fname) = 0;
136
* Add a resource collection file. The return value is a non-zero file
137
* number assigned by the host system; the VM uses this number in
138
* subsequent calls to add_resource() to add resources from this file.
139
* The VM cannot add any resources for a file until it first adds the
140
* file with this routine.
142
virtual int add_resfile(const char *fname) = 0;
145
* Determine if additional resource files are supported - if this
146
* returns true, add_resfile() can be used, otherwise add_resfile()
147
* will have no effect.
149
virtual int can_add_resfiles() = 0;
152
* Add a resource map entry. 'ofs' is the byte offset of the start
153
* of the resource within the file, and 'siz' is the size in bytes
154
* of the resource data. The resource is stored as contiguous bytes
155
* starting at the given file offset and running for the given size.
156
* The 'fileno' is zero for the image file, or the number assigned
157
* by the host system in add_resfile() for other resource files.
159
virtual void add_resource(unsigned long ofs, unsigned long siz,
160
const char *res_name, size_t res_name_len,
164
* Add a resource link map entry. This creates an association between
165
* a compiled resource name and a filename in the local file system.
166
* This is used primarily for debugging purposes, so that the compiler
167
* can avoid copying the resource data, instead simply placing a link
168
* for each resource to its local file copy.
170
virtual void add_resource(const char *fname, size_t fnamelen,
171
const char *res_name, size_t res_name_len) = 0;
174
* Find a resource. Returns an osfildef* handle to the open resource
175
* file if the resource can be found; the file on return will have its
176
* seek position set to the first byte of the resource in the file,
177
* and *res_size will be set to the size in bytes of the resource
178
* data. If there is no such resource, returns null.
180
virtual osfildef *find_resource(const char *resname, size_t resname_len,
181
unsigned long *res_size) = 0;
184
* Get the external resource file path. If we should look for
185
* resource files in a different location than the image file, the
186
* host system can set this to a path that we should use to look for
187
* resource files. If this is null, the VM should simply look in
188
* the same directory that contains the image file. If the host
189
* system provides a path via this routine, the path string must
190
* have a trailing separator character if required, so that we can
191
* directly append a name to this path to form a valid
192
* fully-qualified filename.
194
virtual const char *get_res_path() = 0;
197
* Determine if a resource exists. Returns true if so, false if
200
virtual int resfile_exists(const char *res_name, size_t res_name_len) = 0;
203
* Ask the user to supply an image file name. We'll call this
204
* routine only if we can't obtain an image file from command line
205
* arguments or from an attachment to the executable.
207
virtual vmhost_gin_t get_image_name(char *buf, size_t buflen) = 0;
210
* Get a special system filename path. This is essentially a wrapper
211
* for os_get_special_path() that encapsulates the information needed
212
* for that function. The 'id' value has the same meaning as in
213
* os_get_special_path() (see tads2/osifc.h).
215
virtual void get_special_file_path(char *buf, size_t buflen, int id) = 0;
218
#endif /* VMHOST_H */
added
removed
tads/tads3/vmhost.h
