1.1 --- a/public/sourcepawn/sp_vm_api.h Fri Jul 11 06:51:21 2008 +0000
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,1231 +0,0 @@
1.4 -/**
1.5 - * vim: set ts=4 :
1.6 - * =============================================================================
1.7 - * SourcePawn
1.8 - * Copyright (C) 2004-2008 AlliedModders LLC. All rights reserved.
1.9 - * =============================================================================
1.10 - *
1.11 - * This program is free software; you can redistribute it and/or modify it under
1.12 - * the terms of the GNU General Public License, version 3.0, as published by the
1.13 - * Free Software Foundation.
1.14 - *
1.15 - * This program is distributed in the hope that it will be useful, but WITHOUT
1.16 - * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
1.17 - * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
1.18 - * details.
1.19 - *
1.20 - * You should have received a copy of the GNU General Public License along with
1.21 - * this program. If not, see <http://www.gnu.org/licenses/>.
1.22 - *
1.23 - * As a special exception, AlliedModders LLC gives you permission to link the
1.24 - * code of this program (as well as its derivative works) to "Half-Life 2," the
1.25 - * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software
1.26 - * by the Valve Corporation. You must obey the GNU General Public License in
1.27 - * all respects for all other code used. Additionally, AlliedModders LLC grants
1.28 - * this exception to all derivative works. AlliedModders LLC defines further
1.29 - * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),
1.30 - * or <http://www.sourcemod.net/license.php>.
1.31 - *
1.32 - * Version: $Id$
1.33 - */
1.34 -
1.35 -#ifndef _INCLUDE_SOURCEPAWN_VM_API_H_
1.36 -#define _INCLUDE_SOURCEPAWN_VM_API_H_
1.37 -
1.38 -/**
1.39 - * @file sp_vm_api.h
1.40 - * @brief Contains all of the object structures used in the SourcePawn API.
1.41 - */
1.42 -
1.43 -#include <stdio.h>
1.44 -#include "sp_vm_types.h"
1.45 -
1.46 -/** SourcePawn Engine API Version */
1.47 -#define SOURCEPAWN_ENGINE_API_VERSION 4
1.48 -#define SOURCEPAWN_ENGINE2_API_VERSION 1
1.49 -
1.50 -#if !defined SOURCEMOD_BUILD
1.51 -#define SOURCEMOD_BUILD
1.52 -#endif
1.53 -
1.54 -#if defined SOURCEMOD_BUILD
1.55 -namespace SourceMod
1.56 -{
1.57 - struct IdentityToken_t;
1.58 -};
1.59 -#endif
1.60 -
1.61 -struct sp_context_s;
1.62 -typedef struct sp_context_s sp_context_t;
1.63 -
1.64 -namespace SourcePawn
1.65 -{
1.66 - class IVirtualMachine;
1.67 -
1.68 - /* Parameter flags */
1.69 - #define SM_PARAM_COPYBACK (1<<0) /**< Copy an array/reference back after call */
1.70 -
1.71 - /* String parameter flags (separate from parameter flags) */
1.72 - #define SM_PARAM_STRING_UTF8 (1<<0) /**< String should be UTF-8 handled */
1.73 - #define SM_PARAM_STRING_COPY (1<<1) /**< String should be copied into the plugin */
1.74 - #define SM_PARAM_STRING_BINARY (1<<2) /**< String should be handled as binary data */
1.75 -
1.76 -#if defined SOURCEMOD_BUILD
1.77 - /**
1.78 - * @brief Pseudo-NULL reference types.
1.79 - */
1.80 - enum SP_NULL_TYPE
1.81 - {
1.82 - SP_NULL_VECTOR = 0, /**< Float[3] reference */
1.83 - SP_NULL_STRING = 1, /**< const String[1] reference */
1.84 - };
1.85 -#endif
1.86 -
1.87 - /**
1.88 - * @brief Represents what a function needs to implement in order to be callable.
1.89 - */
1.90 - class ICallable
1.91 - {
1.92 - public:
1.93 - /**
1.94 - * @brief Pushes a cell onto the current call.
1.95 - *
1.96 - * @param cell Parameter value to push.
1.97 - * @return Error code, if any.
1.98 - */
1.99 - virtual int PushCell(cell_t cell) =0;
1.100 -
1.101 - /**
1.102 - * @brief Pushes a cell by reference onto the current call.
1.103 - * NOTE: On Execute, the pointer passed will be modified if copyback is enabled.
1.104 - * NOTE: By reference parameters are cached and thus are not read until execution.
1.105 - * This means you cannot push a pointer, change it, and push it again and expect
1.106 - * two different values to come out.
1.107 - *
1.108 - * @param cell Address containing parameter value to push.
1.109 - * @param flags Copy-back flags.
1.110 - * @return Error code, if any.
1.111 - */
1.112 - virtual int PushCellByRef(cell_t *cell, int flags=SM_PARAM_COPYBACK) =0;
1.113 -
1.114 - /**
1.115 - * @brief Pushes a float onto the current call.
1.116 - *
1.117 - * @param number Parameter value to push.
1.118 - * @return Error code, if any.
1.119 - */
1.120 - virtual int PushFloat(float number) =0;
1.121 -
1.122 - /**
1.123 - * @brief Pushes a float onto the current call by reference.
1.124 - * NOTE: On Execute, the pointer passed will be modified if copyback is enabled.
1.125 - * NOTE: By reference parameters are cached and thus are not read until execution.
1.126 - * This means you cannot push a pointer, change it, and push it again and expect
1.127 - * two different values to come out.
1.128 - *
1.129 - * @param number Parameter value to push.
1.130 - & @param flags Copy-back flags.
1.131 - * @return Error code, if any.
1.132 - */
1.133 - virtual int PushFloatByRef(float *number, int flags=SM_PARAM_COPYBACK) =0;
1.134 -
1.135 - /**
1.136 - * @brief Pushes an array of cells onto the current call.
1.137 - *
1.138 - * On Execute, the pointer passed will be modified if non-NULL and copy-back
1.139 - * is enabled.
1.140 - *
1.141 - * By reference parameters are cached and thus are not read until execution.
1.142 - * This means you cannot push a pointer, change it, and push it again and expect
1.143 - * two different values to come out.
1.144 - *
1.145 - * @param inarray Array to copy, NULL if no initial array should be copied.
1.146 - * @param cells Number of cells to allocate and optionally read from the input array.
1.147 - * @param flags Whether or not changes should be copied back to the input array.
1.148 - * @return Error code, if any.
1.149 - */
1.150 - virtual int PushArray(cell_t *inarray, unsigned int cells, int flags=0) =0;
1.151 -
1.152 - /**
1.153 - * @brief Pushes a string onto the current call.
1.154 - *
1.155 - * @param string String to push.
1.156 - * @return Error code, if any.
1.157 - */
1.158 - virtual int PushString(const char *string) =0;
1.159 -
1.160 - /**
1.161 - * @brief Pushes a string or string buffer.
1.162 - *
1.163 - * NOTE: On Execute, the pointer passed will be modified if copy-back is enabled.
1.164 - *
1.165 - * @param buffer Pointer to string buffer.
1.166 - * @param length Length of buffer.
1.167 - * @param sz_flags String flags. In copy mode, the string will be copied
1.168 - * according to the handling (ascii, utf-8, binary, etc).
1.169 - * @param cp_flags Copy-back flags.
1.170 - * @return Error code, if any.
1.171 - */
1.172 - virtual int PushStringEx(char *buffer, size_t length, int sz_flags, int cp_flags) =0;
1.173 -
1.174 - /**
1.175 - * @brief Cancels a function call that is being pushed but not yet executed.
1.176 - * This can be used be reset for CallFunction() use.
1.177 - */
1.178 - virtual void Cancel() =0;
1.179 - };
1.180 -
1.181 -
1.182 - /**
1.183 - * @brief Encapsulates a function call in a plugin.
1.184 - *
1.185 - * NOTE: Function calls must be atomic to one execution context.
1.186 - * NOTE: This object should not be deleted. It lives for the lifetime of the plugin.
1.187 - */
1.188 - class IPluginFunction : public ICallable
1.189 - {
1.190 - public:
1.191 - /**
1.192 - * @brief Executes the function, resets the pushed parameter list, and
1.193 - * performs any copybacks.
1.194 - *
1.195 - * @param result Pointer to store return value in.
1.196 - * @return Error code, if any.
1.197 - */
1.198 - virtual int Execute(cell_t *result) =0;
1.199 -
1.200 - /**
1.201 - * @brief Executes the function with the given parameter array.
1.202 - * Parameters are read in forward order (i.e. index 0 is parameter #1)
1.203 - * NOTE: You will get an error if you attempt to use CallFunction() with
1.204 - * previously pushed parameters.
1.205 - *
1.206 - * @param params Array of cell parameters.
1.207 - * @param num_params Number of parameters to push.
1.208 - * @param result Pointer to store result of function on return.
1.209 - * @return SourcePawn error code (if any).
1.210 - */
1.211 - virtual int CallFunction(const cell_t *params, unsigned int num_params, cell_t *result) =0;
1.212 -
1.213 - /**
1.214 - * @brief Deprecated, do not use.
1.215 - *
1.216 - * @return GetDefaultContext() of parent runtime.
1.217 - */
1.218 - virtual IPluginContext *GetParentContext() =0;
1.219 -
1.220 - /**
1.221 - * @brief Returns whether the parent plugin is paused.
1.222 - *
1.223 - * @return True if runnable, false otherwise.
1.224 - */
1.225 - virtual bool IsRunnable() =0;
1.226 -
1.227 - /**
1.228 - * @brief Returns the function ID of this function.
1.229 - *
1.230 - * Note: This was added in API version 4.
1.231 - *
1.232 - * @return Function id.
1.233 - */
1.234 - virtual funcid_t GetFunctionID() =0;
1.235 -
1.236 - /**
1.237 - * @brief Executes the forward, resets the pushed parameter list, and
1.238 - * performs any copybacks.
1.239 - *
1.240 - * Note: A function can only be executed given a runtime it was created in.
1.241 - *
1.242 - * @param ctx Context to execute the function in.
1.243 - * @param result Pointer to store return value in.
1.244 - * @return Error code, if any.
1.245 - */
1.246 - virtual int Execute2(IPluginContext *ctx, cell_t *result) =0;
1.247 -
1.248 - /**
1.249 - * @brief Executes the function with the given parameter array.
1.250 - * Parameters are read in forward order (i.e. index 0 is parameter #1)
1.251 - * NOTE: You will get an error if you attempt to use CallFunction() with
1.252 - * previously pushed parameters.
1.253 - *
1.254 - * Note: A function can only be executed given a runtime it was created in.
1.255 - *
1.256 - * @param ctx Context to execute the function in.
1.257 - * @param params Array of cell parameters.
1.258 - * @param num_params Number of parameters to push.
1.259 - * @param result Pointer to store result of function on return.
1.260 - * @return SourcePawn error code (if any).
1.261 - */
1.262 - virtual int CallFunction2(IPluginContext *ctx,
1.263 - const cell_t *params,
1.264 - unsigned int num_params,
1.265 - cell_t *result) =0;
1.266 - };
1.267 -
1.268 -
1.269 - /**
1.270 - * @brief Interface to managing a debug context at runtime.
1.271 - */
1.272 - class IPluginDebugInfo
1.273 - {
1.274 - public:
1.275 - /**
1.276 - * @brief Given a code pointer, finds the file it is associated with.
1.277 - *
1.278 - * @param addr Code address offset.
1.279 - * @param filename Pointer to store filename pointer in.
1.280 - */
1.281 - virtual int LookupFile(ucell_t addr, const char **filename) =0;
1.282 -
1.283 - /**
1.284 - * @brief Given a code pointer, finds the function it is associated with.
1.285 - *
1.286 - * @param addr Code address offset.
1.287 - * @param name Pointer to store function name pointer in.
1.288 - */
1.289 - virtual int LookupFunction(ucell_t addr, const char **name) =0;
1.290 -
1.291 - /**
1.292 - * @brief Given a code pointer, finds the line it is associated with.
1.293 - *
1.294 - * @param addr Code address offset.
1.295 - * @param line Pointer to store line number in.
1.296 - */
1.297 - virtual int LookupLine(ucell_t addr, uint32_t *line) =0;
1.298 - };
1.299 -
1.300 - /**
1.301 - * @brief Represents a JIT compilation or plugin loading options.
1.302 - */
1.303 - class ICompilation
1.304 - {
1.305 - public:
1.306 - /**
1.307 - * @brief Sets a compilation option.
1.308 - *
1.309 - * @param key Option name.
1.310 - * @param val Option value.
1.311 - * @return True on success, false on failure.
1.312 - */
1.313 - virtual bool SetOption(const char *key, const char *val) =0;
1.314 -
1.315 - /**
1.316 - * @brief Aborts the compilation and destroys this object.
1.317 - */
1.318 - virtual void Abort() =0;
1.319 - };
1.320 -
1.321 - /**
1.322 - * @brief Interface to managing a runtime plugin.
1.323 - */
1.324 - class IPluginRuntime
1.325 - {
1.326 - public:
1.327 - /**
1.328 - * @brief Virtual destructor (you may call delete).
1.329 - */
1.330 - virtual ~IPluginRuntime()
1.331 - {
1.332 - }
1.333 -
1.334 - /**
1.335 - * @brief Returns debug info.
1.336 - *
1.337 - * @return IPluginDebugInfo, or NULL if no debug info found.
1.338 - */
1.339 - virtual IPluginDebugInfo *GetDebugInfo() =0;
1.340 -
1.341 - /**
1.342 - * @brief Finds a native by name.
1.343 - *
1.344 - * @param name Name of native.
1.345 - * @param index Optionally filled with native index number.
1.346 - */
1.347 - virtual int FindNativeByName(const char *name, uint32_t *index) =0;
1.348 -
1.349 - /**
1.350 - * @brief Gets native info by index.
1.351 - *
1.352 - * @param index Index number of native.
1.353 - * @param native Optionally filled with pointer to native structure.
1.354 - */
1.355 - virtual int GetNativeByIndex(uint32_t index, sp_native_t **native) =0;
1.356 -
1.357 - /**
1.358 - * @brief Gets the number of natives.
1.359 - *
1.360 - * @return Filled with the number of natives.
1.361 - */
1.362 - virtual uint32_t GetNativesNum() =0;
1.363 -
1.364 - /**
1.365 - * @brief Finds a public function by name.
1.366 - *
1.367 - * @param name Name of public
1.368 - * @param index Optionally filled with public index number.
1.369 - */
1.370 - virtual int FindPublicByName(const char *name, uint32_t *index) =0;
1.371 -
1.372 - /**
1.373 - * @brief Gets public function info by index.
1.374 - *
1.375 - * @param index Public function index number.
1.376 - * @param publicptr Optionally filled with pointer to public structure.
1.377 - */
1.378 - virtual int GetPublicByIndex(uint32_t index, sp_public_t **publicptr) =0;
1.379 -
1.380 - /**
1.381 - * @brief Gets the number of public functions.
1.382 - *
1.383 - * @return Filled with the number of public functions.
1.384 - */
1.385 - virtual uint32_t GetPublicsNum() =0;
1.386 -
1.387 - /**
1.388 - * @brief Gets public variable info by index.
1.389 - *
1.390 - * @param index Public variable index number.
1.391 - * @param pubvar Optionally filled with pointer to pubvar structure.
1.392 - */
1.393 - virtual int GetPubvarByIndex(uint32_t index, sp_pubvar_t **pubvar) =0;
1.394 -
1.395 - /**
1.396 - * @brief Finds a public variable by name.
1.397 - *
1.398 - * @param name Name of pubvar
1.399 - * @param index Optionally filled with pubvar index number.
1.400 - */
1.401 - virtual int FindPubvarByName(const char *name, uint32_t *index) =0;
1.402 -
1.403 - /**
1.404 - * @brief Gets the addresses of a public variable.
1.405 - *
1.406 - * @param index Index of public variable.
1.407 - * @param local_addr Address to store local address in.
1.408 - * @param phys_addr Address to store physically relocated in.
1.409 - */
1.410 - virtual int GetPubvarAddrs(uint32_t index, cell_t *local_addr, cell_t **phys_addr) =0;
1.411 -
1.412 - /**
1.413 - * @brief Returns the number of public variables.
1.414 - *
1.415 - * @return Number of public variables.
1.416 - */
1.417 - virtual uint32_t GetPubVarsNum() =0;
1.418 -
1.419 - /**
1.420 - * @brief Returns a function by name.
1.421 - *
1.422 - * @param public_name Name of the function.
1.423 - * @return A new IPluginFunction pointer, NULL if not found.
1.424 - */
1.425 - virtual IPluginFunction *GetFunctionByName(const char *public_name) =0;
1.426 -
1.427 - /**
1.428 - * @brief Returns a function by its id.
1.429 - *
1.430 - * @param func_id Function ID.
1.431 - * @return A new IPluginFunction pointer, NULL if not found.
1.432 - */
1.433 - virtual IPluginFunction *GetFunctionById(funcid_t func_id) =0;
1.434 -
1.435 - /**
1.436 - * @brief Returns the default context. The default context
1.437 - * should not be destroyed.
1.438 - *
1.439 - * @return Default context pointer.
1.440 - */
1.441 - virtual IPluginContext *GetDefaultContext() =0;
1.442 -
1.443 - /**
1.444 - * @brief Returns true if the plugin is in debug mode.
1.445 - *
1.446 - * @return True if in debug mode, false otherwise.
1.447 - */
1.448 - virtual bool IsDebugging() =0;
1.449 -
1.450 - /**
1.451 - * @brief Applies new compilation/runtime settings to the runtime code.
1.452 - *
1.453 - * The compilation object is destroyed once this function completes.
1.454 - *
1.455 - * @return Error code (SP_ERROR_NONE on success).
1.456 - */
1.457 - virtual int ApplyCompilationOptions(ICompilation *co) =0;
1.458 -
1.459 - /**
1.460 - * @brief Sets whether or not the plugin is paused (cannot be run).
1.461 - *
1.462 - * @param pause Pause state.
1.463 - */
1.464 - virtual void SetPauseState(bool paused) =0;
1.465 -
1.466 - /**
1.467 - * @brief Returns whether or not the plugin is paused (runnable).
1.468 - *
1.469 - * @return Pause state (true = paused, false = not).
1.470 - */
1.471 - virtual bool IsPaused() =0;
1.472 -
1.473 - /**
1.474 - * @brief Returns the estimated memory usage of this plugin.
1.475 - *
1.476 - * @return Memory usage, in bytes.
1.477 - */
1.478 - virtual size_t GetMemUsage() =0;
1.479 - };
1.480 -
1.481 - /**
1.482 - * @brief Interface to managing a context at runtime.
1.483 - */
1.484 - class IPluginContext
1.485 - {
1.486 - public:
1.487 - /** Virtual destructor */
1.488 - virtual ~IPluginContext() { };
1.489 - public:
1.490 - /**
1.491 - * @brief Deprecated, does nothing.
1.492 - *
1.493 - * @return NULL.
1.494 - */
1.495 - virtual IVirtualMachine *GetVirtualMachine() =0;
1.496 -
1.497 - /**
1.498 - * @brief Deprecated, do not use.
1.499 - *
1.500 - * Returns the pointer of this object, casted to an opaque structure.
1.501 - *
1.502 - * @return Returns this.
1.503 - */
1.504 - virtual sp_context_t *GetContext() =0;
1.505 -
1.506 - /**
1.507 - * @brief Returns true if the plugin is in debug mode.
1.508 - *
1.509 - * @return True if in debug mode, false otherwise.
1.510 - */
1.511 - virtual bool IsDebugging() =0;
1.512 -
1.513 - /**
1.514 - * @brief Deprecated, does nothing.
1.515 - *
1.516 - * @param newpfn Unused.
1.517 - * @param oldpfn Unused.
1.518 - */
1.519 - virtual int SetDebugBreak(void *newpfn, void *oldpfn) =0;
1.520 -
1.521 - /**
1.522 - * @brief Deprecated, do not use.
1.523 - *
1.524 - * @return NULL.
1.525 - */
1.526 - virtual IPluginDebugInfo *GetDebugInfo() =0;
1.527 -
1.528 - /**
1.529 - * @brief Allocates memory on the secondary stack of a plugin.
1.530 - * Note that although called a heap, it is in fact a stack.
1.531 - *
1.532 - * @param cells Number of cells to allocate.
1.533 - * @param local_addr Will be filled with data offset to heap.
1.534 - * @param phys_addr Physical address to heap memory.
1.535 - */
1.536 - virtual int HeapAlloc(unsigned int cells, cell_t *local_addr, cell_t **phys_addr) =0;
1.537 -
1.538 - /**
1.539 - * @brief Pops a heap address off the heap stack. Use this to free memory allocated with
1.540 - * SP_HeapAlloc().
1.541 - * Note that in SourcePawn, the heap is in fact a bottom-up stack. Deallocations
1.542 - * with this native should be performed in precisely the REVERSE order.
1.543 - *
1.544 - * @param local_addr Local address to free.
1.545 - */
1.546 - virtual int HeapPop(cell_t local_addr) =0;
1.547 -
1.548 - /**
1.549 - * @brief Releases a heap address using a different method than SP_HeapPop().
1.550 - * This allows you to release in any order. However, if you allocate N
1.551 - * objects, release only some of them, then begin allocating again,
1.552 - * you cannot go back and starting freeing the originals.
1.553 - * In other words, for each chain of allocations, if you start deallocating,
1.554 - * then allocating more in a chain, you must only deallocate from the current
1.555 - * allocation chain. This is basically HeapPop() except on a larger scale.
1.556 - *
1.557 - * @param local_addr Local address to free.
1.558 - */
1.559 - virtual int HeapRelease(cell_t local_addr) =0;
1.560 -
1.561 - /**
1.562 - * @brief Deprecated, use IPluginRuntime instead.
1.563 - *
1.564 - * @param name Name of native.
1.565 - * @param index Optionally filled with native index number.
1.566 - */
1.567 - virtual int FindNativeByName(const char *name, uint32_t *index) =0;
1.568 -
1.569 - /**
1.570 - * @brief Deprecated, use IPluginRuntime instead.
1.571 - *
1.572 - * @param index Index number of native.
1.573 - * @param native Optionally filled with pointer to native structure.
1.574 - */
1.575 - virtual int GetNativeByIndex(uint32_t index, sp_native_t **native) =0;
1.576 -
1.577 - /**
1.578 - * @brief Deprecated, use IPluginRuntime instead.
1.579 - *
1.580 - * @return Filled with the number of natives.
1.581 - */
1.582 - virtual uint32_t GetNativesNum() =0;
1.583 -
1.584 - /**
1.585 - * @brief Deprecated, use IPluginRuntime instead.
1.586 - *
1.587 - * @param name Name of public
1.588 - * @param index Optionally filled with public index number.
1.589 - */
1.590 - virtual int FindPublicByName(const char *name, uint32_t *index) =0;
1.591 -
1.592 - /**
1.593 - * @brief Deprecated, use IPluginRuntime instead.
1.594 - *
1.595 - * @param index Public function index number.
1.596 - * @param publicptr Optionally filled with pointer to public structure.
1.597 - */
1.598 - virtual int GetPublicByIndex(uint32_t index, sp_public_t **publicptr) =0;
1.599 -
1.600 - /**
1.601 - * @brief Deprecated, use IPluginRuntime instead.
1.602 - *
1.603 - * @return Filled with the number of public functions.
1.604 - */
1.605 - virtual uint32_t GetPublicsNum() =0;
1.606 -
1.607 - /**
1.608 - * @brief Deprecated, use IPluginRuntime instead.
1.609 - *
1.610 - * @param index Public variable index number.
1.611 - * @param pubvar Optionally filled with pointer to pubvar structure.
1.612 - */
1.613 - virtual int GetPubvarByIndex(uint32_t index, sp_pubvar_t **pubvar) =0;
1.614 -
1.615 - /**
1.616 - * @brief Deprecated, use IPluginRuntime instead.
1.617 - *
1.618 - * @param name Name of pubvar
1.619 - * @param index Optionally filled with pubvar index number.
1.620 - */
1.621 - virtual int FindPubvarByName(const char *name, uint32_t *index) =0;
1.622 -
1.623 - /**
1.624 - * @brief Deprecated, use IPluginRuntime instead.
1.625 - *
1.626 - * @param index Index of public variable.
1.627 - * @param local_addr Address to store local address in.
1.628 - * @param phys_addr Address to store physically relocated in.
1.629 - */
1.630 - virtual int GetPubvarAddrs(uint32_t index, cell_t *local_addr, cell_t **phys_addr) =0;
1.631 -
1.632 - /**
1.633 - * @brief Deprecated, use IPluginRuntime instead.
1.634 - *
1.635 - * @return Number of public variables.
1.636 - */
1.637 - virtual uint32_t GetPubVarsNum() =0;
1.638 -
1.639 - /**
1.640 - * @brief Converts a plugin reference to a physical address
1.641 - *
1.642 - * @param local_addr Local address in plugin.
1.643 - * @param phys_addr Optionally filled with relocated physical address.
1.644 - */
1.645 - virtual int LocalToPhysAddr(cell_t local_addr, cell_t **phys_addr) =0;
1.646 -
1.647 - /**
1.648 - * @brief Converts a local address to a physical string.
1.649 - *
1.650 - * @param local_addr Local address in plugin.
1.651 - * @param addr Destination output pointer.
1.652 - */
1.653 - virtual int LocalToString(cell_t local_addr, char **addr) =0;
1.654 -
1.655 - /**
1.656 - * @brief Converts a physical string to a local address.
1.657 - *
1.658 - * @param local_addr Local address in plugin.
1.659 - * @param bytes Number of chars to write, including NULL terminator.
1.660 - * @param source Source string to copy.
1.661 - */
1.662 - virtual int StringToLocal(cell_t local_addr, size_t bytes, const char *source) =0;
1.663 -
1.664 - /**
1.665 - * @brief Converts a physical UTF-8 string to a local address.
1.666 - * This function is the same as the ANSI version, except it will copy the maximum number
1.667 - * of characters possible without accidentally chopping a multi-byte character.
1.668 - *
1.669 - * @param local_addr Local address in plugin.
1.670 - * @param maxbytes Number of bytes to write, including NULL terminator.
1.671 - * @param source Source string to copy.
1.672 - * @param wrtnbytes Optionally set to the number of actual bytes written.
1.673 - */
1.674 - virtual int StringToLocalUTF8(cell_t local_addr,
1.675 - size_t maxbytes,
1.676 - const char *source,
1.677 - size_t *wrtnbytes) =0;
1.678 -
1.679 - /**
1.680 - * @brief Deprecated, does nothing.
1.681 - *
1.682 - * @param value Unused.
1.683 - */
1.684 - virtual int PushCell(cell_t value) =0;
1.685 -
1.686 - /**
1.687 - * @brief Deprecated, does nothing.
1.688 - *
1.689 - * @param local_addr Unused.
1.690 - * @param phys_addr Unused.
1.691 - * @param array Unused.
1.692 - * @param numcells Unused.
1.693 - */
1.694 - virtual int PushCellArray(cell_t *local_addr, cell_t **phys_addr, cell_t array[], unsigned int numcells) =0;
1.695 -
1.696 - /**
1.697 - * @brief Deprecated, does nothing.
1.698 - *
1.699 - * @param local_addr Unused.
1.700 - * @param phys_addr Unused.
1.701 - * @param string Unused.
1.702 - */
1.703 - virtual int PushString(cell_t *local_addr, char **phys_addr, const char *string) =0;
1.704 -
1.705 - /**
1.706 - * @brief Deprecated, does nothing.
1.707 - *
1.708 - * @param array Unused.
1.709 - * @param numcells Unused.
1.710 - */
1.711 - virtual int PushCellsFromArray(cell_t array[], unsigned int numcells) =0;
1.712 -
1.713 - /**
1.714 - * @brief Deprecated, does nothing.
1.715 - *
1.716 - * @param natives Deprecated; do not use.
1.717 - * @param num Deprecated; do not use.
1.718 - * @param overwrite Deprecated; do not use.
1.719 - */
1.720 - virtual int BindNatives(const sp_nativeinfo_t *natives, unsigned int num, int overwrite) =0;
1.721 -
1.722 - /**
1.723 - * @brief Deprecated, does nothing.
1.724 - *
1.725 - * @param native Deprecated; do not use.
1.726 - */
1.727 - virtual int BindNative(const sp_nativeinfo_t *native) =0;
1.728 -
1.729 - /**
1.730 - * @brief Deprecated, does nothing.
1.731 - *
1.732 - * @param native Unused.
1.733 - */
1.734 - virtual int BindNativeToAny(SPVM_NATIVE_FUNC native) =0;
1.735 -
1.736 - /**
1.737 - * @brief Deprecated, does nothing.
1.738 - *
1.739 - * @param code_addr Unused.
1.740 - * @param result Unused.
1.741 - * @return SP_ERROR_ABORTED.
1.742 - */
1.743 - virtual int Execute(uint32_t code_addr, cell_t *result) =0;
1.744 -
1.745 - /**
1.746 - * @brief Throws a error and halts any current execution.
1.747 - *
1.748 - * @param error The error number to set.
1.749 - * @param msg Custom error message format. NULL to use default.
1.750 - * @param ... Message format arguments, if any.
1.751 - * @return 0 for convenience.
1.752 - */
1.753 - virtual cell_t ThrowNativeErrorEx(int error, const char *msg, ...) =0;
1.754 -
1.755 - /**
1.756 - * @brief Throws a generic native error and halts any current execution.
1.757 - *
1.758 - * @param msg Custom error message format. NULL to set no message.
1.759 - * @param ... Message format arguments, if any.
1.760 - * @return 0 for convenience.
1.761 - */
1.762 - virtual cell_t ThrowNativeError(const char *msg, ...) =0;
1.763 -
1.764 - /**
1.765 - * @brief Returns a function by name.
1.766 - *
1.767 - * @param public_name Name of the function.
1.768 - * @return A new IPluginFunction pointer, NULL if not found.
1.769 - */
1.770 - virtual IPluginFunction *GetFunctionByName(const char *public_name) =0;
1.771 -
1.772 - /**
1.773 - * @brief Returns a function by its id.
1.774 - *
1.775 - * @param func_id Function ID.
1.776 - * @return A new IPluginFunction pointer, NULL if not found.
1.777 - */
1.778 - virtual IPluginFunction *GetFunctionById(funcid_t func_id) =0;
1.779 -
1.780 - /**
1.781 - * @brief Returns the identity token for this context.
1.782 - *
1.783 - * Note: This is a compatibility shim and is the same as GetKey(1).
1.784 - *
1.785 - * @return Identity token.
1.786 - */
1.787 - virtual SourceMod::IdentityToken_t *GetIdentity() =0;
1.788 -
1.789 - /**
1.790 - * @brief Returns a NULL reference based on one of the available NULL
1.791 - * reference types.
1.792 - *
1.793 - * @param type NULL reference type.
1.794 - * @return cell_t address to compare to.
1.795 - */
1.796 - virtual cell_t *GetNullRef(SP_NULL_TYPE type) =0;
1.797 -
1.798 - /**
1.799 - * @brief Converts a local address to a physical string, and allows
1.800 - * for NULL_STRING to be set.
1.801 - *
1.802 - * @param local_addr Local address in plugin.
1.803 - * @param addr Destination output pointer.
1.804 - */
1.805 - virtual int LocalToStringNULL(cell_t local_addr, char **addr) =0;
1.806 -
1.807 - /**
1.808 - * @brief Deprecated; do not use.
1.809 - *
1.810 - * @param index Deprecated; do not use.
1.811 - * @param native Deprecated; do not use.
1.812 - */
1.813 - virtual int BindNativeToIndex(uint32_t index, SPVM_NATIVE_FUNC native) =0;
1.814 -
1.815 - /**
1.816 - * @brief Returns if there is currently an execution in progress.
1.817 - *
1.818 - * @return True if in exec, false otherwise.
1.819 - */
1.820 - virtual bool IsInExec() =0;
1.821 -
1.822 - /**
1.823 - * @brief Returns the parent runtime of a context.
1.824 - *
1.825 - * @return Parent runtime.
1.826 - */
1.827 - virtual IPluginRuntime *GetRuntime() =0;
1.828 -
1.829 - /**
1.830 - * @brief Executes a function in the context. The function must be
1.831 - * a member of the context's parent runtime.
1.832 - *
1.833 - * @param function Function.
1.834 - * @param params Parameters.
1.835 - * @param num_params Number of parameters in the parameter array.
1.836 - * @param result Optional pointer to store the result on success.
1.837 - * @return Error code.
1.838 - */
1.839 - virtual int Execute2(IPluginFunction *function,
1.840 - const cell_t *params,
1.841 - unsigned int num_params,
1.842 - cell_t *result) =0;
1.843 -
1.844 - /**
1.845 - * @brief Returns whether a context is in an error state.
1.846 - *
1.847 - * This should only be used inside natives to determine whether
1.848 - * a prior call failed.
1.849 - */
1.850 - virtual int GetLastNativeError() =0;
1.851 -
1.852 - /**
1.853 - * @brief Returns the local parameter stack, starting from the
1.854 - * cell that contains the number of parameters passed.
1.855 - *
1.856 - * Local parameters are the parameters passed to the function
1.857 - * from which a native was called (and thus this can only be
1.858 - * called inside a native).
1.859 - *
1.860 - * @return Parameter stack.
1.861 - */
1.862 - virtual cell_t *GetLocalParams() =0;
1.863 -
1.864 - /**
1.865 - * @brief Sets a local "key" that can be used for fast lookup.
1.866 - *
1.867 - * Only the "owner" of the context should be setting this.
1.868 - *
1.869 - * @param key Key number (values allowed: 1 through 4).
1.870 - * @param value Pointer value.
1.871 - */
1.872 - virtual void SetKey(int k, void *value) =0;
1.873 -
1.874 - /**
1.875 - * @brief Retrieves a previously set "key."
1.876 - *
1.877 - * @param key Key number (values allowed: 1 through 4).
1.878 - * @param value Pointer to store value.
1.879 - * @return True on success, false on failure.
1.880 - */
1.881 - virtual bool GetKey(int k, void **value) =0;
1.882 - };
1.883 -
1.884 -
1.885 - /**
1.886 - * @brief Information about a position in a call stack.
1.887 - */
1.888 - struct CallStackInfo
1.889 - {
1.890 - const char *filename; /**< NULL if not found */
1.891 - unsigned int line; /**< 0 if not found */
1.892 - const char *function; /**< NULL if not found */
1.893 - };
1.894 -
1.895 - /**
1.896 - * @brief Retrieves error information from a debug hook.
1.897 - */
1.898 - class IContextTrace
1.899 - {
1.900 - public:
1.901 - /**
1.902 - * @brief Returns the integer error code.
1.903 - *
1.904 - * @return Integer error code.
1.905 - */
1.906 - virtual int GetErrorCode() =0;
1.907 -
1.908 - /**
1.909 - * @brief Returns a string describing the error.
1.910 - *
1.911 - * @return Error string.
1.912 - */
1.913 - virtual const char *GetErrorString() =0;
1.914 -
1.915 - /**
1.916 - * @brief Returns whether debug info is available.
1.917 - *
1.918 - * @return True if debug info is available, false otherwise.
1.919 - */
1.920 - virtual bool DebugInfoAvailable() =0;
1.921 -
1.922 - /**
1.923 - * @brief Returns a custom error message.
1.924 - *
1.925 - * @return A pointer to a custom error message, or NULL otherwise.
1.926 - */
1.927 - virtual const char *GetCustomErrorString() =0;
1.928 -
1.929 - /**
1.930 - * @brief Returns trace info for a specific point in the backtrace, if any.
1.931 - * The next subsequent call to GetTraceInfo() will return the next item in the call stack.
1.932 - * Calls are retrieved in descending order (i.e. the first item is at the top of the stack/call sequence).
1.933 - *
1.934 - * @param trace An ErrorTraceInfo buffer to store information (NULL to ignore).
1.935 - * @return True if successful, false if there are no more traces.
1.936 - */
1.937 - virtual bool GetTraceInfo(CallStackInfo *trace) =0;
1.938 -
1.939 - /**
1.940 - * @brief Resets the trace to its original position (the call on the top of the stack).
1.941 - */
1.942 - virtual void ResetTrace() =0;
1.943 -
1.944 - /**
1.945 - * @brief Retrieves the name of the last native called.
1.946 - * Returns NULL if there was no native that caused the error.
1.947 - *
1.948 - * @param index Optional pointer to store index.
1.949 - * @return Native name, or NULL if none.
1.950 - */
1.951 - virtual const char *GetLastNative(uint32_t *index) =0;
1.952 - };
1.953 -
1.954 -
1.955 - /**
1.956 - * @brief Provides callbacks for debug information.
1.957 - */
1.958 - class IDebugListener
1.959 - {
1.960 - public:
1.961 - virtual void OnContextExecuteError(IPluginContext *ctx, IContextTrace *error) =0;
1.962 - };
1.963 -
1.964 - /**
1.965 - * @brief Represents a code profiler for plugins.
1.966 - */
1.967 - class IProfiler
1.968 - {
1.969 - public:
1.970 - /**
1.971 - * @brief Invoked by the JIT to notify that a native is being started.
1.972 - *
1.973 - * @param pContext Plugin context.
1.974 - * @param native Native information.
1.975 - */
1.976 - virtual void OnNativeBegin(IPluginContext *pContext, sp_native_t *native) =0;
1.977 -
1.978 - /**
1.979 - * @brief Invoked by the JIT to notify that the last native on the stack
1.980 - * is no longer being executed.
1.981 - */
1.982 - virtual void OnNativeEnd() =0;
1.983 -
1.984 - /**
1.985 - * @brief Invoked by the JIT to notify that a function call is starting.
1.986 - *
1.987 - * @param pContext Plugin context.
1.988 - * @param name Function name, or NULL if not known.
1.989 - * @param code_addr P-Code address.
1.990 - */
1.991 - virtual void OnFunctionBegin(IPluginContext *pContext, const char *name) =0;
1.992 -
1.993 - /**
1.994 - * @brief Invoked by the JIT to notify that the last function call has
1.995 - * concluded. In the case of an error inside a function, this will not
1.996 - * be called. Instead, the VM will call OnCallbackEnd() and the profiler
1.997 - * stack must be unwound.
1.998 - */
1.999 - virtual void OnFunctionEnd() =0;
1.1000 -
1.1001 - /**
1.1002 - * @brief Invoked by the VM to notify that a forward/callback is starting.
1.1003 - *
1.1004 - * @param pContext Plugin context.
1.1005 - * @param pubfunc Public function information.
1.1006 - * @return Unique number to pass to OnFunctionEnd().
1.1007 - */
1.1008 - virtual int OnCallbackBegin(IPluginContext *pContext, sp_public_t *pubfunc) =0;
1.1009 -
1.1010 - /**
1.1011 - * @brief Invoked by the JIT to notify that a callback has ended.
1.1012 - *
1.1013 - * As noted in OnFunctionEnd(), this my be called with a misaligned
1.1014 - * profiler stack. To correct this, the stack should be unwound
1.1015 - * (discarding data as appropriate) to a matching serial number.
1.1016 - *
1.1017 - * @param serial Unique number from OnCallbackBegin().
1.1018 - */
1.1019 - virtual void OnCallbackEnd(int serial) =0;
1.1020 - };
1.1021 -
1.1022 - struct sp_plugin_s;
1.1023 - typedef struct sp_plugin_s sp_plugin_t;
1.1024 -
1.1025 - /**
1.1026 - * @brief Contains helper functions used by VMs and the host app
1.1027 - */
1.1028 - class ISourcePawnEngine
1.1029 - {
1.1030 - public:
1.1031 - /**
1.1032 - * @brief Deprecated, do not use.
1.1033 - *
1.1034 - * @param fp Unused.
1.1035 - * @param err Unused.
1.1036 - * @return NULL.
1.1037 - */
1.1038 - virtual sp_plugin_t *LoadFromFilePointer(FILE *fp, int *err) =0;
1.1039 -
1.1040 - /**
1.1041 - * @brief Deprecated, do not use,
1.1042 - *
1.1043 - * @param base Unused.
1.1044 - * @param plugin Unused.
1.1045 - * @param err Unused.
1.1046 - * @return NULL.
1.1047 - */
1.1048 - virtual sp_plugin_t *LoadFromMemory(void *base, sp_plugin_t *plugin, int *err) =0;
1.1049 -
1.1050 - /**
1.1051 - * @brief Deprecated, do not use.
1.1052 - *
1.1053 - * @param plugin Unused.
1.1054 - * @return SP_ERROR_ABORTED.
1.1055 - */
1.1056 - virtual int FreeFromMemory(sp_plugin_t *plugin) =0;
1.1057 -
1.1058 - /**
1.1059 - * @brief Allocates large blocks of temporary memory.
1.1060 - *
1.1061 - * @param size Size of memory to allocate.
1.1062 - * @return Pointer to memory, NULL if allocation failed.
1.1063 - */
1.1064 - virtual void *BaseAlloc(size_t size) =0;
1.1065 -
1.1066 - /**
1.1067 - * @brief Frees memory allocated with BaseAlloc.
1.1068 - *
1.1069 - * @param memory Memory address to free.
1.1070 - */
1.1071 - virtual void BaseFree(void *memory) =0;
1.1072 -
1.1073 - /**
1.1074 - * @brief Allocates executable memory.
1.1075 - * @deprecated Use AllocPageMemory()
1.1076 - *
1.1077 - * @param size Size of memory to allocate.
1.1078 - * @return Pointer to memory, NULL if allocation failed.
1.1079 - */
1.1080 - virtual void *ExecAlloc(size_t size) =0;
1.1081 -
1.1082 - /**
1.1083 - * @brief Frees executable memory.
1.1084 - * @deprecated Use FreePageMemory()
1.1085 - *
1.1086 - * @param address Address to free.
1.1087 - */
1.1088 - virtual void ExecFree(void *address) =0;
1.1089 -
1.1090 - /**
1.1091 - * @brief Sets the debug listener. This should only be called once.
1.1092 - * If called successively (using manual chaining), only the last function should
1.1093 - * attempt to call back into the same plugin. Otherwise, globally cached states
1.1094 - * can be accidentally overwritten.
1.1095 - *
1.1096 - * @param listener Pointer to an IDebugListener.
1.1097 - * @return Old IDebugListener, or NULL if none.
1.1098 - */
1.1099 - virtual IDebugListener *SetDebugListener(IDebugListener *listener) =0;
1.1100 -
1.1101 - /**
1.1102 - * @brief Deprecated, do not use.
1.1103 - *
1.1104 - * @return 0.
1.1105 - */
1.1106 - virtual unsigned int GetContextCallCount() =0;
1.1107 -
1.1108 - /**
1.1109 - * @brief Returns the engine API version.
1.1110 - *
1.1111 - * @return Engine API version.
1.1112 - */
1.1113 - virtual unsigned int GetEngineAPIVersion() =0;
1.1114 -
1.1115 - /**
1.1116 - * @brief Allocates executable memory.
1.1117 - *
1.1118 - * @param size Size of memory to allocate.
1.1119 - * @return Pointer to memory, NULL if allocation failed.
1.1120 - */
1.1121 - virtual void *AllocatePageMemory(size_t size) =0;
1.1122 -
1.1123 - /**
1.1124 - * @brief Sets the input memory permissions to read+write.
1.1125 - *
1.1126 - * @param ptr Memory block.
1.1127 - */
1.1128 - virtual void SetReadWrite(void *ptr) =0;
1.1129 -
1.1130 - /**
1.1131 - * @brief Sets the input memory permissions to read+execute.
1.1132 - *
1.1133 - * @param ptr Memory block.
1.1134 - */
1.1135 - virtual void SetReadExecute(void *ptr) =0;
1.1136 -
1.1137 - /**
1.1138 - * @brief Frees executable memory.
1.1139 - *
1.1140 - * @param ptr Address to free.
1.1141 - */
1.1142 - virtual void FreePageMemory(void *ptr) =0;
1.1143 - };
1.1144 -
1.1145 - /**
1.1146 - * @brief Outlines the interface a Virtual Machine (JIT) must expose
1.1147 - */
1.1148 - class ISourcePawnEngine2
1.1149 - {
1.1150 - public:
1.1151 - /**
1.1152 - * @brief Returns the second engine API version.
1.1153 - *
1.1154 - * @return API version.
1.1155 - */
1.1156 - virtual unsigned int GetAPIVersion() =0;
1.1157 -
1.1158 - /**
1.1159 - * @brief Returns the string name of a VM implementation.
1.1160 - */
1.1161 - virtual const char *GetEngineName() =0;
1.1162 -
1.1163 - /**
1.1164 - * @brief Returns a version string.
1.1165 - *
1.1166 - * @return Versioning string.
1.1167 - */
1.1168 - virtual const char *GetVersionString() =0;
1.1169 -
1.1170 - /**
1.1171 - * @brief Creates a new compilation options object.
1.1172 - *
1.1173 - * @return Compilation options object.
1.1174 - */
1.1175 - virtual ICompilation *StartCompilation() =0;
1.1176 -
1.1177 - /**
1.1178 - * @brief Loads a plugin from disk.
1.1179 - *
1.1180 - * If a compilation object is supplied, it is destroyed upon
1.1181 - * the function's return.
1.1182 - *
1.1183 - * @param co Compilation options, or NULL for defaults.
1.1184 - * @param file Path to the file to compile.
1.1185 - * @param err Error code (filled on failure); required.
1.1186 - * @return New runtime pointer, or NULL on failure.
1.1187 - */
1.1188 - virtual IPluginRuntime *LoadPlugin(ICompilation *co, const char *file, int *err) =0;
1.1189 -
1.1190 - /**
1.1191 - * @brief Creates a fake native and binds it to a general callback function.
1.1192 - *
1.1193 - * @param callback Callback function to bind the native to.
1.1194 - * @param pData Private data to pass to the callback when the native is invoked.
1.1195 - * @return A new fake native function as a wrapper around the callback.
1.1196 - */
1.1197 - virtual SPVM_NATIVE_FUNC CreateFakeNative(SPVM_FAKENATIVE_FUNC callback, void *pData) =0;
1.1198 -
1.1199 - /**
1.1200 - * @brief Destroys a fake native function wrapper.
1.1201 - *
1.1202 - * @param func Pointer to the fake native created by CreateFakeNative.
1.1203 - */
1.1204 - virtual void DestroyFakeNative(SPVM_NATIVE_FUNC func) =0;
1.1205 -
1.1206 - /**
1.1207 - * @brief Sets the debug listener. This should only be called once.
1.1208 - * If called successively (using manual chaining), only the last function should
1.1209 - * attempt to call back into the same plugin. Otherwise, globally cached states
1.1210 - * can be accidentally overwritten.
1.1211 - *
1.1212 - * @param listener Pointer to an IDebugListener.
1.1213 - * @return Old IDebugListener, or NULL if none.
1.1214 - */
1.1215 - virtual IDebugListener *SetDebugListener(IDebugListener *listener) =0;
1.1216 -
1.1217 - /**
1.1218 - * @brief Sets the global profiler.
1.1219 - *
1.1220 - * @param profiler Profiler pointer.
1.1221 - */
1.1222 - virtual void SetProfiler(IProfiler *profiler) =0;
1.1223 -
1.1224 - /**
1.1225 - * @brief Returns the string representation of an error message.
1.1226 - *
1.1227 - * @param err Error code.
1.1228 - * @return Error string, or NULL if not found.
1.1229 - */
1.1230 - virtual const char *GetErrorString(int err) =0;
1.1231 - };
1.1232 -};
1.1233 -
1.1234 -#endif //_INCLUDE_SOURCEPAWN_VM_API_H_
