1.1 --- a/sourcepawn/include/sp_vm_api.h Tue Nov 07 23:26:40 2006 +0000
1.2 +++ b/sourcepawn/include/sp_vm_api.h Wed Nov 08 06:24:28 2006 +0000
1.3 @@ -3,11 +3,295 @@
1.4
1.5 #include <stdio.h>
1.6 #include "sp_vm_types.h"
1.7 -#include "sp_vm_context.h"
1.8
1.9 namespace SourcePawn
1.10 {
1.11 - class IPluginContext;
1.12 + class IVirtualMachine;
1.13 +
1.14 + class IPluginDebugInfo
1.15 + {
1.16 + public:
1.17 + /**
1.18 + * Given a code pointer, finds the file it is associated with.
1.19 + *
1.20 + * @param addr Code address offset.
1.21 + * @param filename Pointer to store filename pointer in.
1.22 + */
1.23 + virtual int LookupFile(ucell_t addr, const char **filename) =0;
1.24 +
1.25 + /**
1.26 + * Given a code pointer, finds the function it is associated with.
1.27 + *
1.28 + * @param addr Code address offset.
1.29 + * @param name Pointer to store function name pointer in.
1.30 + */
1.31 + virtual int LookupFunction(ucell_t addr, const char **name) =0;
1.32 +
1.33 + /**
1.34 + * Given a code pointer, finds the line it is associated with.
1.35 + *
1.36 + * @param addr Code address offset.
1.37 + * @param line Pointer to store line number in.
1.38 + */
1.39 + virtual int LookupLine(ucell_t addr, uint32_t *line) =0;
1.40 + };
1.41 +
1.42 + class IPluginContext
1.43 + {
1.44 + public:
1.45 + virtual ~IPluginContext() { };
1.46 + public:
1.47 + /**
1.48 + * Returns the parent IVirtualMachine.
1.49 + *
1.50 + * @return Parent virtual machine pointer.
1.51 + */
1.52 + virtual IVirtualMachine *GetVirtualMachine() =0;
1.53 +
1.54 + /**
1.55 + * Returns the child sp_context_t structure.
1.56 + *
1.57 + * @return Child sp_context_t structure.
1.58 + */
1.59 + virtual sp_context_t *GetContext() =0;
1.60 +
1.61 + /**
1.62 + * Returns true if the plugin is in debug mode.
1.63 + *
1.64 + * @return True if in debug mode, false otherwise.
1.65 + */
1.66 + virtual bool IsDebugging() =0;
1.67 +
1.68 + /**
1.69 + * Installs a debug break and returns the old one, if any.
1.70 + * This will fail if the plugin is not debugging.
1.71 + *
1.72 + * @param newpfn New function pointer.
1.73 + * @param oldpfn Pointer to retrieve old function pointer.
1.74 + */
1.75 + virtual int SetDebugBreak(SPVM_DEBUGBREAK newpfn, SPVM_DEBUGBREAK *oldpfn) =0;
1.76 +
1.77 + /**
1.78 + * Returns debug info.
1.79 + *
1.80 + * @return IPluginDebugInfo, or NULL if no debug info found.
1.81 + */
1.82 + virtual IPluginDebugInfo *GetDebugInfo() =0;
1.83 +
1.84 + /**
1.85 + * Allocs memory on the secondary stack of a plugin.
1.86 + * Note that although called a heap, it is in fact a stack.
1.87 + *
1.88 + * @param cells Number of cells to allocate.
1.89 + * @param local_adddr Will be filled with data offset to heap.
1.90 + * @param phys_addr Physical address to heap memory.
1.91 + */
1.92 + virtual int HeapAlloc(unsigned int cells, cell_t *local_addr, cell_t **phys_addr) =0;
1.93 +
1.94 + /**
1.95 + * Pops a heap address off the heap stack. Use this to free memory allocated with
1.96 + * SP_HeapAlloc().
1.97 + * Note that in SourcePawn, the heap is in fact a bottom-up stack. Deallocations
1.98 + * with this native should be performed in precisely the REVERSE order.
1.99 + *
1.100 + * @param local_addr Local address to free.
1.101 + */
1.102 + virtual int HeapPop(cell_t local_addr) =0;
1.103 +
1.104 + /**
1.105 + * Releases a heap address using a different method than SP_HeapPop().
1.106 + * This allows you to release in any order. However, if you allocate N
1.107 + * objects, release only some of them, then begin allocating again,
1.108 + * you cannot go back and starting freeing the originals.
1.109 + * In other words, for each chain of allocations, if you start deallocating,
1.110 + * then allocating more in a chain, you must only deallocate from the current
1.111 + * allocation chain. This is basically HeapPop() except on a larger scale.
1.112 + *
1.113 + * @param local_addr Local address to free.
1.114 + */
1.115 + virtual int HeapRelease(cell_t local_addr) =0;
1.116 +
1.117 + /**
1.118 + * Finds a native by name.
1.119 + *
1.120 + * @param name Name of native.
1.121 + * @param index Optionally filled with native index number.
1.122 + */
1.123 + virtual int FindNativeByName(const char *name, uint32_t *index) =0;
1.124 +
1.125 + /**
1.126 + * Gets native info by index.
1.127 + *
1.128 + * @param index Index number of native.
1.129 + * @param native Optionally filled with pointer to native structure.
1.130 + */
1.131 + virtual int GetNativeByIndex(uint32_t index, sp_native_t **native) =0;
1.132 +
1.133 + /**
1.134 + * Gets the number of natives.
1.135 + *
1.136 + * @return Filled with the number of natives.
1.137 + */
1.138 + virtual uint32_t GetNativesNum() =0;
1.139 +
1.140 + /**
1.141 + * Finds a public function by name.
1.142 + *
1.143 + * @param name Name of public
1.144 + * @param index Optionally filled with public index number.
1.145 + */
1.146 + virtual int FindPublicByName(const char *name, uint32_t *index) =0;
1.147 +
1.148 + /**
1.149 + * Gets public function info by index.
1.150 + *
1.151 + * @param index Public function index number.
1.152 + * @param public Optionally filled with pointer to public structure.
1.153 + */
1.154 + virtual int GetPublicByIndex(uint32_t index, sp_public_t **publicptr) =0;
1.155 +
1.156 + /**
1.157 + * Gets the number of public functions.
1.158 + *
1.159 + * @return Filled with the number of public functions.
1.160 + */
1.161 + virtual uint32_t GetPublicsNum() =0;
1.162 +
1.163 + /**
1.164 + * Gets public variable info by index.
1.165 + * @param index Public variable index number.
1.166 + * @param pubvar Optionally filled with pointer to pubvar structure.
1.167 + */
1.168 + virtual int GetPubvarByIndex(uint32_t index, sp_pubvar_t **pubvar) =0;
1.169 +
1.170 + /**
1.171 + * Finds a public variable by name.
1.172 + *
1.173 + * @param name Name of pubvar
1.174 + * @param index Optionally filled with pubvar index number.
1.175 + */
1.176 + virtual int FindPubvarByName(const char *name, uint32_t *index) =0;
1.177 +
1.178 + /**
1.179 + * Gets the addresses of a public variable.
1.180 + *
1.181 + * @param index Index of public variable.
1.182 + * @param local_addr Address to store local address in.
1.183 + * @param phys_addr Address to store physically relocated in.
1.184 + */
1.185 + virtual int GetPubvarAddrs(uint32_t index, cell_t *local_addr, cell_t **phys_addr) =0;
1.186 +
1.187 + /**
1.188 + * Returns the number of public variables.
1.189 + *
1.190 + * @return Number of public variables.
1.191 + */
1.192 + virtual uint32_t GetPubVarsNum() =0;
1.193 +
1.194 + /**
1.195 + * Round-about method of converting a plugin reference to a physical address
1.196 + *
1.197 + * @param local_addr Local address in plugin.
1.198 + * @param phys_addr Optionally filled with relocated physical address.
1.199 + */
1.200 + virtual int LocalToPhysAddr(cell_t local_addr, cell_t **phys_addr) =0;
1.201 +
1.202 + /**:TODO: FIX ALL PACKED STUFF COMMENTS!
1.203 + * Converts a local address to a physical string.
1.204 + * Note that SourcePawn does not support packed strings, as such this function is
1.205 + * 'cell to char' only.
1.206 + *
1.207 + * @param local_addr Local address in plugin.
1.208 + * @param addr Destination output pointer.
1.209 + */
1.210 + virtual int LocalToString(cell_t local_addr, char **addr) =0;
1.211 +
1.212 + /**
1.213 + * Converts a physical string to a local address.
1.214 + * Note that SourcePawn does not support packed strings.
1.215 + *
1.216 + * @param local_addr Local address in plugin.
1.217 + * @param chars Number of chars to write, including NULL terminator.
1.218 + * @param source Source string to copy.
1.219 + */
1.220 + virtual int StringToLocal(cell_t local_addr, size_t chars, const char *source) =0;
1.221 +
1.222 + /**
1.223 + * Pushes a cell onto the stack. Increases the parameter count by one.
1.224 + *
1.225 + * @param value Cell value.
1.226 + */
1.227 + virtual int PushCell(cell_t value) =0;
1.228 +
1.229 + /**
1.230 + * Pushes an array of cells onto the stack. Increases the parameter count by one.
1.231 + * If the function returns an error it will fail entirely, releasing anything allocated in the process.
1.232 + * Note that this does not release the heap, so you should release it after
1.233 + * calling Execute().
1.234 + *
1.235 + * @param local_addr Filled with local address to release.
1.236 + * @param phys_addr Optionally filled with physical address of new array.
1.237 + * @param array Cell array to copy.
1.238 + * @param numcells Number of cells in the array to copy.
1.239 + */
1.240 + virtual int PushCellArray(cell_t *local_addr, cell_t **phys_addr, cell_t array[], unsigned int numcells) =0;
1.241 +
1.242 + /**
1.243 + * Pushes a string onto the stack (by reference) and increases the parameter count by one.
1.244 + * Note that this does not release the heap, so you should release it after
1.245 + * calling Execute().
1.246 + *
1.247 + * @param local_addr Filled with local address to release.
1.248 + * @param phys_addr Optionally filled with physical address of new array.
1.249 + * @param string Source string to push.
1.250 + */
1.251 + virtual int PushString(cell_t *local_addr, cell_t **phys_addr, const char *string) =0;
1.252 +
1.253 + /**
1.254 + * Individually pushes each cell of an array of cells onto the stack. Increases the
1.255 + * parameter count by the number of cells pushed.
1.256 + * If the function returns an error it will fail entirely, releasing anything allocated in the process.
1.257 + *
1.258 + * @param array Array of cells to read from.
1.259 + * @param numcells Number of cells to read.
1.260 + */
1.261 + virtual int PushCellsFromArray(cell_t array[], unsigned int numcells) =0;
1.262 +
1.263 + /**
1.264 + * Binds a list of native names and their function pointers to a context.
1.265 + * If num is 0, the list is read until an entry with a NULL name is reached.
1.266 + * All natives are assigned a status of SP_NATIVE_OKAY by default.
1.267 + * If overwrite is non-zero, already registered natives will be overwritten.
1.268 + *
1.269 + * @param natives Array of natives.
1.270 + * @param num Number of natives in array.
1.271 + * @param overwrite Toggles overwrite.
1.272 + */
1.273 + virtual int BindNatives(sp_nativeinfo_t *natives, unsigned int num, int overwrite) =0;
1.274 +
1.275 + /**
1.276 + * Binds a single native. Overwrites any existing bind.
1.277 + * If the context does not contain the native that will be binded the function will return
1.278 + * with a SP_ERROR_OT_FOUND error.
1.279 + *
1.280 + * @param native Pointer to native.
1.281 + * @param status Status value to set (should be SP_NATIVE_OKAY).
1.282 + */
1.283 + virtual int BindNative(sp_nativeinfo_t *native, uint32_t status) =0;
1.284 +
1.285 + /**
1.286 + * Binds a single native to any non-registered or pending native.
1.287 + * Status is automatically set to pending.
1.288 + *
1.289 + * @param native Native to bind.
1.290 + */
1.291 + virtual int BindNativeToAny(SPVM_NATIVE_FUNC native) =0;
1.292 +
1.293 + /**
1.294 + * Executes a public function.
1.295 + */
1.296 + virtual int Execute(uint32_t public_func, cell_t *result) =0;
1.297 + };
1.298
1.299 /**
1.300 * Contains helper functions used by VMs and the host app
