1 /* $Header$ */ 2 3 /* 4 * Copyright (c) 1999, 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 vmhost.h - T3 VM host interface 12 Function 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. 19 Notes 20 21 Modified 22 07/29/99 MJRoberts - Creation 23 */ 24 25 #ifndef VMHOST_H 26 #define VMHOST_H 27 28 /* ------------------------------------------------------------------------ */ 29 /* 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 33 * own. 34 */ 35 36 /* level 0: minimum safety; read/write any file */ 37 const int VM_IO_SAFETY_MINIMUM = 0; 38 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; 41 42 /* level 2: read/write in current directory only */ 43 const int VM_IO_SAFETY_READWRITE_CUR = 2; 44 45 /* level 3: read from current directory only, no writing allowed */ 46 const int VM_IO_SAFETY_READ_CUR = 3; 47 48 /* level 4: maximum safety; no file reading or writing allowed */ 49 const int VM_IO_SAFETY_MAXIMUM = 4; 50 51 52 /* ------------------------------------------------------------------------ */ 53 /* 54 * get_image_name return codes 55 */ 56 enum vmhost_gin_t 57 { 58 /* 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) 65 */ 66 VMHOST_GIN_IGNORED, 67 68 /* 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 71 */ 72 VMHOST_GIN_CANCEL, 73 74 /* 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 77 * example) 78 */ 79 VMHOST_GIN_ERROR, 80 81 /* success */ 82 VMHOST_GIN_SUCCESS 83 }; 84 85 /* ------------------------------------------------------------------------ */ 86 /* 87 * T3 VM Host Application Interface. This is an abstract class; it must 88 * be implemented by each application that embeds the VM. 89 */ 90 class CVmHostIfc 91 { 92 public: ~CVmHostIfc()93 virtual ~CVmHostIfc() { } 94 95 /* 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. 99 */ 100 virtual int get_io_safety() = 0; 101 102 /* 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 106 * image 107 */ 108 virtual void set_io_safety(int level) = 0; 109 110 /* 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. 116 */ 117 virtual class CResLoader *get_cmap_res_loader() = 0; 118 119 /* 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 122 * file if necessary. 123 */ 124 virtual void set_image_name(const char *fname) = 0; 125 126 /* 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. 132 */ 133 virtual void set_res_dir(const char *fname) = 0; 134 135 /* 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. 141 */ 142 virtual int add_resfile(const char *fname) = 0; 143 144 /* 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. 148 */ 149 virtual int can_add_resfiles() = 0; 150 151 /* 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. 158 */ 159 virtual void add_resource(unsigned long ofs, unsigned long siz, 160 const char *res_name, size_t res_name_len, 161 int fileno) = 0; 162 163 /* 164 * Find a resource. Returns an osfildef* handle to the open resource 165 * file if the resource can be found; the file on return will have its 166 * seek position set to the first byte of the resource in the file, 167 * and *res_size will be set to the size in bytes of the resource 168 * data. If there is no such resource, returns null. 169 */ 170 virtual osfildef *find_resource(const char *resname, size_t resname_len, 171 unsigned long *res_size) = 0; 172 173 /* 174 * Get the external resource file path. If we should look for 175 * resource files in a different location than the image file, the 176 * host system can set this to a path that we should use to look for 177 * resource files. If this is null, the VM should simply look in 178 * the same directory that contains the image file. If the host 179 * system provides a path via this routine, the path string must 180 * have a trailing separator character if required, so that we can 181 * directly append a name to this path to form a valid 182 * fully-qualified filename. 183 */ 184 virtual const char *get_res_path() = 0; 185 186 /* 187 * Determine if a resource exists. Returns true if so, false if 188 * not. 189 */ 190 virtual int resfile_exists(const char *res_name, size_t res_name_len) = 0; 191 192 /* 193 * Ask the user to supply an image file name. We'll call this 194 * routine only if we can't obtain an image file from command line 195 * arguments or from an attachment to the executable. 196 */ 197 virtual vmhost_gin_t get_image_name(char *buf, size_t buflen) = 0; 198 }; 199 200 #endif /* VMHOST_H */ 201 202