00001 /** 00002 * vim: set ts=4 sw=4 tw=99 noet : 00003 * ============================================================================= 00004 * SourcePawn 00005 * Copyright (C) 2004-2009 AlliedModders LLC. All rights reserved. 00006 * ============================================================================= 00007 * 00008 * This program is free software; you can redistribute it and/or modify it under 00009 * the terms of the GNU General Public License, version 3.0, as published by the 00010 * Free Software Foundation. 00011 * 00012 * This program is distributed in the hope that it will be useful, but WITHOUT 00013 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 00014 * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more 00015 * details. 00016 * 00017 * You should have received a copy of the GNU General Public License along with 00018 * this program. If not, see <http://www.gnu.org/licenses/>. 00019 * 00020 * As a special exception, AlliedModders LLC gives you permission to link the 00021 * code of this program (as well as its derivative works) to "Half-Life 2," the 00022 * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software 00023 * by the Valve Corporation. You must obey the GNU General Public License in 00024 * all respects for all other code used. Additionally, AlliedModders LLC grants 00025 * this exception to all derivative works. AlliedModders LLC defines further 00026 * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007), 00027 * or <http://www.sourcemod.net/license.php>. 00028 */ 00029 00030 #ifndef _INCLUDE_SOURCEPAWN_VM_API_H_ 00031 #define _INCLUDE_SOURCEPAWN_VM_API_H_ 00032 00033 /** 00034 * @file sp_vm_api.h 00035 * @brief Contains all of the object structures used in the SourcePawn API. 00036 */ 00037 00038 #include <stdio.h> 00039 #include "sp_vm_types.h" 00040 00041 /** SourcePawn Engine API Version */ 00042 #define SOURCEPAWN_ENGINE_API_VERSION 4 00043 #define SOURCEPAWN_ENGINE2_API_VERSION 3 00044 00045 #if !defined SOURCEMOD_BUILD 00046 #define SOURCEMOD_BUILD 00047 #endif 00048 00049 #if defined SOURCEMOD_BUILD 00050 namespace SourceMod 00051 { 00052 struct IdentityToken_t; 00053 }; 00054 #endif 00055 00056 struct sp_context_s; 00057 typedef struct sp_context_s sp_context_t; 00058 00059 namespace SourcePawn 00060 { 00061 class IVirtualMachine; 00062 class IPluginRuntime; 00063 00064 /* Parameter flags */ 00065 #define SM_PARAM_COPYBACK (1<<0) /**< Copy an array/reference back after call */ 00066 00067 /* String parameter flags (separate from parameter flags) */ 00068 #define SM_PARAM_STRING_UTF8 (1<<0) /**< String should be UTF-8 handled */ 00069 #define SM_PARAM_STRING_COPY (1<<1) /**< String should be copied into the plugin */ 00070 #define SM_PARAM_STRING_BINARY (1<<2) /**< String should be handled as binary data */ 00071 00072 #if defined SOURCEMOD_BUILD 00073 /** 00074 * @brief Pseudo-NULL reference types. 00075 */ 00076 enum SP_NULL_TYPE 00077 { 00078 SP_NULL_VECTOR = 0, /**< Float[3] reference */ 00079 SP_NULL_STRING = 1, /**< const String[1] reference */ 00080 }; 00081 #endif 00082 00083 /** 00084 * @brief Represents what a function needs to implement in order to be callable. 00085 */ 00086 class ICallable 00087 { 00088 public: 00089 /** 00090 * @brief Pushes a cell onto the current call. 00091 * 00092 * @param cell Parameter value to push. 00093 * @return Error code, if any. 00094 */ 00095 virtual int PushCell(cell_t cell) =0; 00096 00097 /** 00098 * @brief Pushes a cell by reference onto the current call. 00099 * NOTE: On Execute, the pointer passed will be modified if copyback is enabled. 00100 * NOTE: By reference parameters are cached and thus are not read until execution. 00101 * This means you cannot push a pointer, change it, and push it again and expect 00102 * two different values to come out. 00103 * 00104 * @param cell Address containing parameter value to push. 00105 * @param flags Copy-back flags. 00106 * @return Error code, if any. 00107 */ 00108 virtual int PushCellByRef(cell_t *cell, int flags=SM_PARAM_COPYBACK) =0; 00109 00110 /** 00111 * @brief Pushes a float onto the current call. 00112 * 00113 * @param number Parameter value to push. 00114 * @return Error code, if any. 00115 */ 00116 virtual int PushFloat(float number) =0; 00117 00118 /** 00119 * @brief Pushes a float onto the current call by reference. 00120 * NOTE: On Execute, the pointer passed will be modified if copyback is enabled. 00121 * NOTE: By reference parameters are cached and thus are not read until execution. 00122 * This means you cannot push a pointer, change it, and push it again and expect 00123 * two different values to come out. 00124 * 00125 * @param number Parameter value to push. 00126 & @param flags Copy-back flags. 00127 * @return Error code, if any. 00128 */ 00129 virtual int PushFloatByRef(float *number, int flags=SM_PARAM_COPYBACK) =0; 00130 00131 /** 00132 * @brief Pushes an array of cells onto the current call. 00133 * 00134 * On Execute, the pointer passed will be modified if non-NULL and copy-back 00135 * is enabled. 00136 * 00137 * By reference parameters are cached and thus are not read until execution. 00138 * This means you cannot push a pointer, change it, and push it again and expect 00139 * two different values to come out. 00140 * 00141 * @param inarray Array to copy, NULL if no initial array should be copied. 00142 * @param cells Number of cells to allocate and optionally read from the input array. 00143 * @param flags Whether or not changes should be copied back to the input array. 00144 * @return Error code, if any. 00145 */ 00146 virtual int PushArray(cell_t *inarray, unsigned int cells, int flags=0) =0; 00147 00148 /** 00149 * @brief Pushes a string onto the current call. 00150 * 00151 * @param string String to push. 00152 * @return Error code, if any. 00153 */ 00154 virtual int PushString(const char *string) =0; 00155 00156 /** 00157 * @brief Pushes a string or string buffer. 00158 * 00159 * NOTE: On Execute, the pointer passed will be modified if copy-back is enabled. 00160 * 00161 * @param buffer Pointer to string buffer. 00162 * @param length Length of buffer. 00163 * @param sz_flags String flags. In copy mode, the string will be copied 00164 * according to the handling (ascii, utf-8, binary, etc). 00165 * @param cp_flags Copy-back flags. 00166 * @return Error code, if any. 00167 */ 00168 virtual int PushStringEx(char *buffer, size_t length, int sz_flags, int cp_flags) =0; 00169 00170 /** 00171 * @brief Cancels a function call that is being pushed but not yet executed. 00172 * This can be used be reset for CallFunction() use. 00173 */ 00174 virtual void Cancel() =0; 00175 }; 00176 00177 00178 /** 00179 * @brief Encapsulates a function call in a plugin. 00180 * 00181 * NOTE: Function calls must be atomic to one execution context. 00182 * NOTE: This object should not be deleted. It lives for the lifetime of the plugin. 00183 */ 00184 class IPluginFunction : public ICallable 00185 { 00186 public: 00187 /** 00188 * @brief Executes the function, resets the pushed parameter list, and 00189 * performs any copybacks. 00190 * 00191 * @param result Pointer to store return value in. 00192 * @return Error code, if any. 00193 */ 00194 virtual int Execute(cell_t *result) =0; 00195 00196 /** 00197 * @brief Executes the function with the given parameter array. 00198 * Parameters are read in forward order (i.e. index 0 is parameter #1) 00199 * NOTE: You will get an error if you attempt to use CallFunction() with 00200 * previously pushed parameters. 00201 * 00202 * @param params Array of cell parameters. 00203 * @param num_params Number of parameters to push. 00204 * @param result Pointer to store result of function on return. 00205 * @return SourcePawn error code (if any). 00206 */ 00207 virtual int CallFunction(const cell_t *params, unsigned int num_params, cell_t *result) =0; 00208 00209 /** 00210 * @brief Deprecated, do not use. 00211 * 00212 * @return GetDefaultContext() of parent runtime. 00213 */ 00214 virtual IPluginContext *GetParentContext() =0; 00215 00216 /** 00217 * @brief Returns whether the parent plugin is paused. 00218 * 00219 * @return True if runnable, false otherwise. 00220 */ 00221 virtual bool IsRunnable() =0; 00222 00223 /** 00224 * @brief Returns the function ID of this function. 00225 * 00226 * Note: This was added in API version 4. 00227 * 00228 * @return Function id. 00229 */ 00230 virtual funcid_t GetFunctionID() =0; 00231 00232 /** 00233 * @brief Executes the forward, resets the pushed parameter list, and 00234 * performs any copybacks. 00235 * 00236 * Note: A function can only be executed given a runtime it was created in. 00237 * 00238 * @param ctx Context to execute the function in. 00239 * @param result Pointer to store return value in. 00240 * @return Error code, if any. 00241 */ 00242 virtual int Execute2(IPluginContext *ctx, cell_t *result) =0; 00243 00244 /** 00245 * @brief Executes the function with the given parameter array. 00246 * Parameters are read in forward order (i.e. index 0 is parameter #1) 00247 * NOTE: You will get an error if you attempt to use CallFunction() with 00248 * previously pushed parameters. 00249 * 00250 * Note: A function can only be executed given a runtime it was created in. 00251 * 00252 * @param ctx Context to execute the function in. 00253 * @param params Array of cell parameters. 00254 * @param num_params Number of parameters to push. 00255 * @param result Pointer to store result of function on return. 00256 * @return SourcePawn error code (if any). 00257 */ 00258 virtual int CallFunction2(IPluginContext *ctx, 00259 const cell_t *params, 00260 unsigned int num_params, 00261 cell_t *result) =0; 00262 00263 /** 00264 * @brief Returns parent plugin's runtime 00265 * 00266 * @return IPluginRuntime pointer. 00267 */ 00268 virtual IPluginRuntime *GetParentRuntime() =0; 00269 }; 00270 00271 00272 /** 00273 * @brief Interface to managing a debug context at runtime. 00274 */ 00275 class IPluginDebugInfo 00276 { 00277 public: 00278 /** 00279 * @brief Given a code pointer, finds the file it is associated with. 00280 * 00281 * @param addr Code address offset. 00282 * @param filename Pointer to store filename pointer in. 00283 */ 00284 virtual int LookupFile(ucell_t addr, const char **filename) =0; 00285 00286 /** 00287 * @brief Given a code pointer, finds the function it is associated with. 00288 * 00289 * @param addr Code address offset. 00290 * @param name Pointer to store function name pointer in. 00291 */ 00292 virtual int LookupFunction(ucell_t addr, const char **name) =0; 00293 00294 /** 00295 * @brief Given a code pointer, finds the line it is associated with. 00296 * 00297 * @param addr Code address offset. 00298 * @param line Pointer to store line number in. 00299 */ 00300 virtual int LookupLine(ucell_t addr, uint32_t *line) =0; 00301 }; 00302 00303 /** 00304 * @brief Represents a JIT compilation or plugin loading options. 00305 */ 00306 class ICompilation 00307 { 00308 public: 00309 /** 00310 * @brief Sets a compilation option. 00311 * 00312 * @param key Option name. 00313 * @param val Option value. 00314 * @return True on success, false on failure. 00315 */ 00316 virtual bool SetOption(const char *key, const char *val) =0; 00317 00318 /** 00319 * @brief Aborts the compilation and destroys this object. 00320 */ 00321 virtual void Abort() =0; 00322 }; 00323 00324 /** 00325 * @brief Interface to managing a runtime plugin. 00326 */ 00327 class IPluginRuntime 00328 { 00329 public: 00330 /** 00331 * @brief Virtual destructor (you may call delete). 00332 */ 00333 virtual ~IPluginRuntime() 00334 { 00335 } 00336 00337 /** 00338 * @brief Returns debug info. 00339 * 00340 * @return IPluginDebugInfo, or NULL if no debug info found. 00341 */ 00342 virtual IPluginDebugInfo *GetDebugInfo() =0; 00343 00344 /** 00345 * @brief Finds a native by name. 00346 * 00347 * @param name Name of native. 00348 * @param index Optionally filled with native index number. 00349 */ 00350 virtual int FindNativeByName(const char *name, uint32_t *index) =0; 00351 00352 /** 00353 * @brief Gets native info by index. 00354 * 00355 * @param index Index number of native. 00356 * @param native Optionally filled with pointer to native structure. 00357 */ 00358 virtual int GetNativeByIndex(uint32_t index, sp_native_t **native) =0; 00359 00360 /** 00361 * @brief Gets the number of natives. 00362 * 00363 * @return Filled with the number of natives. 00364 */ 00365 virtual uint32_t GetNativesNum() =0; 00366 00367 /** 00368 * @brief Finds a public function by name. 00369 * 00370 * @param name Name of public 00371 * @param index Optionally filled with public index number. 00372 */ 00373 virtual int FindPublicByName(const char *name, uint32_t *index) =0; 00374 00375 /** 00376 * @brief Gets public function info by index. 00377 * 00378 * @param index Public function index number. 00379 * @param publicptr Optionally filled with pointer to public structure. 00380 */ 00381 virtual int GetPublicByIndex(uint32_t index, sp_public_t **publicptr) =0; 00382 00383 /** 00384 * @brief Gets the number of public functions. 00385 * 00386 * @return Filled with the number of public functions. 00387 */ 00388 virtual uint32_t GetPublicsNum() =0; 00389 00390 /** 00391 * @brief Gets public variable info by index. 00392 * 00393 * @param index Public variable index number. 00394 * @param pubvar Optionally filled with pointer to pubvar structure. 00395 */ 00396 virtual int GetPubvarByIndex(uint32_t index, sp_pubvar_t **pubvar) =0; 00397 00398 /** 00399 * @brief Finds a public variable by name. 00400 * 00401 * @param name Name of pubvar 00402 * @param index Optionally filled with pubvar index number. 00403 */ 00404 virtual int FindPubvarByName(const char *name, uint32_t *index) =0; 00405 00406 /** 00407 * @brief Gets the addresses of a public variable. 00408 * 00409 * @param index Index of public variable. 00410 * @param local_addr Address to store local address in. 00411 * @param phys_addr Address to store physically relocated in. 00412 */ 00413 virtual int GetPubvarAddrs(uint32_t index, cell_t *local_addr, cell_t **phys_addr) =0; 00414 00415 /** 00416 * @brief Returns the number of public variables. 00417 * 00418 * @return Number of public variables. 00419 */ 00420 virtual uint32_t GetPubVarsNum() =0; 00421 00422 /** 00423 * @brief Returns a function by name. 00424 * 00425 * @param public_name Name of the function. 00426 * @return A new IPluginFunction pointer, NULL if not found. 00427 */ 00428 virtual IPluginFunction *GetFunctionByName(const char *public_name) =0; 00429 00430 /** 00431 * @brief Returns a function by its id. 00432 * 00433 * @param func_id Function ID. 00434 * @return A new IPluginFunction pointer, NULL if not found. 00435 */ 00436 virtual IPluginFunction *GetFunctionById(funcid_t func_id) =0; 00437 00438 /** 00439 * @brief Returns the default context. The default context 00440 * should not be destroyed. 00441 * 00442 * @return Default context pointer. 00443 */ 00444 virtual IPluginContext *GetDefaultContext() =0; 00445 00446 /** 00447 * @brief Returns true if the plugin is in debug mode. 00448 * 00449 * @return True if in debug mode, false otherwise. 00450 */ 00451 virtual bool IsDebugging() =0; 00452 00453 /** 00454 * @brief Applies new compilation/runtime settings to the runtime code. 00455 * 00456 * The compilation object is destroyed once this function completes. 00457 * 00458 * @return Error code (SP_ERROR_NONE on success). 00459 */ 00460 virtual int ApplyCompilationOptions(ICompilation *co) =0; 00461 00462 /** 00463 * @brief Sets whether or not the plugin is paused (cannot be run). 00464 * 00465 * @param pause Pause state. 00466 */ 00467 virtual void SetPauseState(bool paused) =0; 00468 00469 /** 00470 * @brief Returns whether or not the plugin is paused (runnable). 00471 * 00472 * @return Pause state (true = paused, false = not). 00473 */ 00474 virtual bool IsPaused() =0; 00475 00476 /** 00477 * @brief Returns the estimated memory usage of this plugin. 00478 * 00479 * @return Memory usage, in bytes. 00480 */ 00481 virtual size_t GetMemUsage() =0; 00482 }; 00483 00484 /** 00485 * @brief Interface to managing a context at runtime. 00486 */ 00487 class IPluginContext 00488 { 00489 public: 00490 /** Virtual destructor */ 00491 virtual ~IPluginContext() { }; 00492 public: 00493 /** 00494 * @brief Deprecated, does nothing. 00495 * 00496 * @return NULL. 00497 */ 00498 virtual IVirtualMachine *GetVirtualMachine() =0; 00499 00500 /** 00501 * @brief Deprecated, do not use. 00502 * 00503 * Returns the pointer of this object, casted to an opaque structure. 00504 * 00505 * @return Returns this. 00506 */ 00507 virtual sp_context_t *GetContext() =0; 00508 00509 /** 00510 * @brief Returns true if the plugin is in debug mode. 00511 * 00512 * @return True if in debug mode, false otherwise. 00513 */ 00514 virtual bool IsDebugging() =0; 00515 00516 /** 00517 * @brief Deprecated, does nothing. 00518 * 00519 * @param newpfn Unused. 00520 * @param oldpfn Unused. 00521 */ 00522 virtual int SetDebugBreak(void *newpfn, void *oldpfn) =0; 00523 00524 /** 00525 * @brief Deprecated, do not use. 00526 * 00527 * @return NULL. 00528 */ 00529 virtual IPluginDebugInfo *GetDebugInfo() =0; 00530 00531 /** 00532 * @brief Allocates memory on the secondary stack of a plugin. 00533 * Note that although called a heap, it is in fact a stack. 00534 * 00535 * @param cells Number of cells to allocate. 00536 * @param local_addr Will be filled with data offset to heap. 00537 * @param phys_addr Physical address to heap memory. 00538 */ 00539 virtual int HeapAlloc(unsigned int cells, cell_t *local_addr, cell_t **phys_addr) =0; 00540 00541 /** 00542 * @brief Pops a heap address off the heap stack. Use this to free memory allocated with 00543 * SP_HeapAlloc(). 00544 * Note that in SourcePawn, the heap is in fact a bottom-up stack. Deallocations 00545 * with this native should be performed in precisely the REVERSE order. 00546 * 00547 * @param local_addr Local address to free. 00548 */ 00549 virtual int HeapPop(cell_t local_addr) =0; 00550 00551 /** 00552 * @brief Releases a heap address using a different method than SP_HeapPop(). 00553 * This allows you to release in any order. However, if you allocate N 00554 * objects, release only some of them, then begin allocating again, 00555 * you cannot go back and starting freeing the originals. 00556 * In other words, for each chain of allocations, if you start deallocating, 00557 * then allocating more in a chain, you must only deallocate from the current 00558 * allocation chain. This is basically HeapPop() except on a larger scale. 00559 * 00560 * @param local_addr Local address to free. 00561 */ 00562 virtual int HeapRelease(cell_t local_addr) =0; 00563 00564 /** 00565 * @brief Deprecated, use IPluginRuntime instead. 00566 * 00567 * @param name Name of native. 00568 * @param index Optionally filled with native index number. 00569 */ 00570 virtual int FindNativeByName(const char *name, uint32_t *index) =0; 00571 00572 /** 00573 * @brief Deprecated, use IPluginRuntime instead. 00574 * 00575 * @param index Index number of native. 00576 * @param native Optionally filled with pointer to native structure. 00577 */ 00578 virtual int GetNativeByIndex(uint32_t index, sp_native_t **native) =0; 00579 00580 /** 00581 * @brief Deprecated, use IPluginRuntime instead. 00582 * 00583 * @return Filled with the number of natives. 00584 */ 00585 virtual uint32_t GetNativesNum() =0; 00586 00587 /** 00588 * @brief Deprecated, use IPluginRuntime instead. 00589 * 00590 * @param name Name of public 00591 * @param index Optionally filled with public index number. 00592 */ 00593 virtual int FindPublicByName(const char *name, uint32_t *index) =0; 00594 00595 /** 00596 * @brief Deprecated, use IPluginRuntime instead. 00597 * 00598 * @param index Public function index number. 00599 * @param publicptr Optionally filled with pointer to public structure. 00600 */ 00601 virtual int GetPublicByIndex(uint32_t index, sp_public_t **publicptr) =0; 00602 00603 /** 00604 * @brief Deprecated, use IPluginRuntime instead. 00605 * 00606 * @return Filled with the number of public functions. 00607 */ 00608 virtual uint32_t GetPublicsNum() =0; 00609 00610 /** 00611 * @brief Deprecated, use IPluginRuntime instead. 00612 * 00613 * @param index Public variable index number. 00614 * @param pubvar Optionally filled with pointer to pubvar structure. 00615 */ 00616 virtual int GetPubvarByIndex(uint32_t index, sp_pubvar_t **pubvar) =0; 00617 00618 /** 00619 * @brief Deprecated, use IPluginRuntime instead. 00620 * 00621 * @param name Name of pubvar 00622 * @param index Optionally filled with pubvar index number. 00623 */ 00624 virtual int FindPubvarByName(const char *name, uint32_t *index) =0; 00625 00626 /** 00627 * @brief Deprecated, use IPluginRuntime instead. 00628 * 00629 * @param index Index of public variable. 00630 * @param local_addr Address to store local address in. 00631 * @param phys_addr Address to store physically relocated in. 00632 */ 00633 virtual int GetPubvarAddrs(uint32_t index, cell_t *local_addr, cell_t **phys_addr) =0; 00634 00635 /** 00636 * @brief Deprecated, use IPluginRuntime instead. 00637 * 00638 * @return Number of public variables. 00639 */ 00640 virtual uint32_t GetPubVarsNum() =0; 00641 00642 /** 00643 * @brief Converts a plugin reference to a physical address 00644 * 00645 * @param local_addr Local address in plugin. 00646 * @param phys_addr Optionally filled with relocated physical address. 00647 */ 00648 virtual int LocalToPhysAddr(cell_t local_addr, cell_t **phys_addr) =0; 00649 00650 /** 00651 * @brief Converts a local address to a physical string. 00652 * 00653 * @param local_addr Local address in plugin. 00654 * @param addr Destination output pointer. 00655 */ 00656 virtual int LocalToString(cell_t local_addr, char **addr) =0; 00657 00658 /** 00659 * @brief Converts a physical string to a local address. 00660 * 00661 * @param local_addr Local address in plugin. 00662 * @param bytes Number of chars to write, including NULL terminator. 00663 * @param source Source string to copy. 00664 */ 00665 virtual int StringToLocal(cell_t local_addr, size_t bytes, const char *source) =0; 00666 00667 /** 00668 * @brief Converts a physical UTF-8 string to a local address. 00669 * This function is the same as the ANSI version, except it will copy the maximum number 00670 * of characters possible without accidentally chopping a multi-byte character. 00671 * 00672 * @param local_addr Local address in plugin. 00673 * @param maxbytes Number of bytes to write, including NULL terminator. 00674 * @param source Source string to copy. 00675 * @param wrtnbytes Optionally set to the number of actual bytes written. 00676 */ 00677 virtual int StringToLocalUTF8(cell_t local_addr, 00678 size_t maxbytes, 00679 const char *source, 00680 size_t *wrtnbytes) =0; 00681 00682 /** 00683 * @brief Deprecated, does nothing. 00684 * 00685 * @param value Unused. 00686 */ 00687 virtual int PushCell(cell_t value) =0; 00688 00689 /** 00690 * @brief Deprecated, does nothing. 00691 * 00692 * @param local_addr Unused. 00693 * @param phys_addr Unused. 00694 * @param array Unused. 00695 * @param numcells Unused. 00696 */ 00697 virtual int PushCellArray(cell_t *local_addr, cell_t **phys_addr, cell_t array[], unsigned int numcells) =0; 00698 00699 /** 00700 * @brief Deprecated, does nothing. 00701 * 00702 * @param local_addr Unused. 00703 * @param phys_addr Unused. 00704 * @param string Unused. 00705 */ 00706 virtual int PushString(cell_t *local_addr, char **phys_addr, const char *string) =0; 00707 00708 /** 00709 * @brief Deprecated, does nothing. 00710 * 00711 * @param array Unused. 00712 * @param numcells Unused. 00713 */ 00714 virtual int PushCellsFromArray(cell_t array[], unsigned int numcells) =0; 00715 00716 /** 00717 * @brief Deprecated, does nothing. 00718 * 00719 * @param natives Deprecated; do not use. 00720 * @param num Deprecated; do not use. 00721 * @param overwrite Deprecated; do not use. 00722 */ 00723 virtual int BindNatives(const sp_nativeinfo_t *natives, unsigned int num, int overwrite) =0; 00724 00725 /** 00726 * @brief Deprecated, does nothing. 00727 * 00728 * @param native Deprecated; do not use. 00729 */ 00730 virtual int BindNative(const sp_nativeinfo_t *native) =0; 00731 00732 /** 00733 * @brief Deprecated, does nothing. 00734 * 00735 * @param native Unused. 00736 */ 00737 virtual int BindNativeToAny(SPVM_NATIVE_FUNC native) =0; 00738 00739 /** 00740 * @brief Deprecated, does nothing. 00741 * 00742 * @param code_addr Unused. 00743 * @param result Unused. 00744 * @return SP_ERROR_ABORTED. 00745 */ 00746 virtual int Execute(uint32_t code_addr, cell_t *result) =0; 00747 00748 /** 00749 * @brief Throws a error and halts any current execution. 00750 * 00751 * @param error The error number to set. 00752 * @param msg Custom error message format. NULL to use default. 00753 * @param ... Message format arguments, if any. 00754 * @return 0 for convenience. 00755 */ 00756 virtual cell_t ThrowNativeErrorEx(int error, const char *msg, ...) =0; 00757 00758 /** 00759 * @brief Throws a generic native error and halts any current execution. 00760 * 00761 * @param msg Custom error message format. NULL to set no message. 00762 * @param ... Message format arguments, if any. 00763 * @return 0 for convenience. 00764 */ 00765 virtual cell_t ThrowNativeError(const char *msg, ...) =0; 00766 00767 /** 00768 * @brief Returns a function by name. 00769 * 00770 * @param public_name Name of the function. 00771 * @return A new IPluginFunction pointer, NULL if not found. 00772 */ 00773 virtual IPluginFunction *GetFunctionByName(const char *public_name) =0; 00774 00775 /** 00776 * @brief Returns a function by its id. 00777 * 00778 * @param func_id Function ID. 00779 * @return A new IPluginFunction pointer, NULL if not found. 00780 */ 00781 virtual IPluginFunction *GetFunctionById(funcid_t func_id) =0; 00782 00783 /** 00784 * @brief Returns the identity token for this context. 00785 * 00786 * Note: This is a compatibility shim and is the same as GetKey(1). 00787 * 00788 * @return Identity token. 00789 */ 00790 virtual SourceMod::IdentityToken_t *GetIdentity() =0; 00791 00792 /** 00793 * @brief Returns a NULL reference based on one of the available NULL 00794 * reference types. 00795 * 00796 * @param type NULL reference type. 00797 * @return cell_t address to compare to. 00798 */ 00799 virtual cell_t *GetNullRef(SP_NULL_TYPE type) =0; 00800 00801 /** 00802 * @brief Converts a local address to a physical string, and allows 00803 * for NULL_STRING to be set. 00804 * 00805 * @param local_addr Local address in plugin. 00806 * @param addr Destination output pointer. 00807 */ 00808 virtual int LocalToStringNULL(cell_t local_addr, char **addr) =0; 00809 00810 /** 00811 * @brief Deprecated; do not use. 00812 * 00813 * @param index Deprecated; do not use. 00814 * @param native Deprecated; do not use. 00815 */ 00816 virtual int BindNativeToIndex(uint32_t index, SPVM_NATIVE_FUNC native) =0; 00817 00818 /** 00819 * @brief Returns if there is currently an execution in progress. 00820 * 00821 * @return True if in exec, false otherwise. 00822 */ 00823 virtual bool IsInExec() =0; 00824 00825 /** 00826 * @brief Returns the parent runtime of a context. 00827 * 00828 * @return Parent runtime. 00829 */ 00830 virtual IPluginRuntime *GetRuntime() =0; 00831 00832 /** 00833 * @brief Executes a function in the context. The function must be 00834 * a member of the context's parent runtime. 00835 * 00836 * @param function Function. 00837 * @param params Parameters. 00838 * @param num_params Number of parameters in the parameter array. 00839 * @param result Optional pointer to store the result on success. 00840 * @return Error code. 00841 */ 00842 virtual int Execute2(IPluginFunction *function, 00843 const cell_t *params, 00844 unsigned int num_params, 00845 cell_t *result) =0; 00846 00847 /** 00848 * @brief Returns whether a context is in an error state. 00849 * 00850 * This should only be used inside natives to determine whether 00851 * a prior call failed. 00852 */ 00853 virtual int GetLastNativeError() =0; 00854 00855 /** 00856 * @brief Returns the local parameter stack, starting from the 00857 * cell that contains the number of parameters passed. 00858 * 00859 * Local parameters are the parameters passed to the function 00860 * from which a native was called (and thus this can only be 00861 * called inside a native). 00862 * 00863 * @return Parameter stack. 00864 */ 00865 virtual cell_t *GetLocalParams() =0; 00866 00867 /** 00868 * @brief Sets a local "key" that can be used for fast lookup. 00869 * 00870 * Only the "owner" of the context should be setting this. 00871 * 00872 * @param key Key number (values allowed: 1 through 4). 00873 * @param value Pointer value. 00874 */ 00875 virtual void SetKey(int k, void *value) =0; 00876 00877 /** 00878 * @brief Retrieves a previously set "key." 00879 * 00880 * @param key Key number (values allowed: 1 through 4). 00881 * @param value Pointer to store value. 00882 * @return True on success, false on failure. 00883 */ 00884 virtual bool GetKey(int k, void **value) =0; 00885 00886 /** 00887 * @brief Clears the last native error. 00888 */ 00889 virtual void ClearLastNativeError() =0; 00890 }; 00891 00892 00893 /** 00894 * @brief Information about a position in a call stack. 00895 */ 00896 struct CallStackInfo 00897 { 00898 const char *filename; /**< NULL if not found */ 00899 unsigned int line; /**< 0 if not found */ 00900 const char *function; /**< NULL if not found */ 00901 }; 00902 00903 /** 00904 * @brief Retrieves error information from a debug hook. 00905 */ 00906 class IContextTrace 00907 { 00908 public: 00909 /** 00910 * @brief Returns the integer error code. 00911 * 00912 * @return Integer error code. 00913 */ 00914 virtual int GetErrorCode() =0; 00915 00916 /** 00917 * @brief Returns a string describing the error. 00918 * 00919 * @return Error string. 00920 */ 00921 virtual const char *GetErrorString() =0; 00922 00923 /** 00924 * @brief Returns whether debug info is available. 00925 * 00926 * @return True if debug info is available, false otherwise. 00927 */ 00928 virtual bool DebugInfoAvailable() =0; 00929 00930 /** 00931 * @brief Returns a custom error message. 00932 * 00933 * @return A pointer to a custom error message, or NULL otherwise. 00934 */ 00935 virtual const char *GetCustomErrorString() =0; 00936 00937 /** 00938 * @brief Returns trace info for a specific point in the backtrace, if any. 00939 * The next subsequent call to GetTraceInfo() will return the next item in the call stack. 00940 * Calls are retrieved in descending order (i.e. the first item is at the top of the stack/call sequence). 00941 * 00942 * @param trace An ErrorTraceInfo buffer to store information (NULL to ignore). 00943 * @return True if successful, false if there are no more traces. 00944 */ 00945 virtual bool GetTraceInfo(CallStackInfo *trace) =0; 00946 00947 /** 00948 * @brief Resets the trace to its original position (the call on the top of the stack). 00949 */ 00950 virtual void ResetTrace() =0; 00951 00952 /** 00953 * @brief Retrieves the name of the last native called. 00954 * Returns NULL if there was no native that caused the error. 00955 * 00956 * @param index Optional pointer to store index. 00957 * @return Native name, or NULL if none. 00958 */ 00959 virtual const char *GetLastNative(uint32_t *index) =0; 00960 }; 00961 00962 00963 /** 00964 * @brief Provides callbacks for debug information. 00965 */ 00966 class IDebugListener 00967 { 00968 public: 00969 /** 00970 * @brief Invoked on a context execution error. 00971 * 00972 * @param ctx Context. 00973 * @param error Object holding error information and a backtrace. 00974 */ 00975 virtual void OnContextExecuteError(IPluginContext *ctx, IContextTrace *error) =0; 00976 00977 /** 00978 * @brief Called on debug spew. 00979 * 00980 * @param msg Message text. 00981 * @param fmt Message formatting arguments (printf-style). 00982 */ 00983 virtual void OnDebugSpew(const char *msg, ...) =0; 00984 }; 00985 00986 /** 00987 * @brief Represents a code profiler for plugins. 00988 */ 00989 class IProfiler 00990 { 00991 public: 00992 /** 00993 * @brief Invoked by the JIT to notify that a native is being started. 00994 * 00995 * @param pContext Plugin context. 00996 * @param native Native information. 00997 */ 00998 virtual void OnNativeBegin(IPluginContext *pContext, sp_native_t *native) =0; 00999 01000 /** 01001 * @brief Invoked by the JIT to notify that the last native on the stack 01002 * is no longer being executed. 01003 */ 01004 virtual void OnNativeEnd() =0; 01005 01006 /** 01007 * @brief Invoked by the JIT to notify that a function call is starting. 01008 * 01009 * @param pContext Plugin context. 01010 * @param name Function name, or NULL if not known. 01011 * @param code_addr P-Code address. 01012 */ 01013 virtual void OnFunctionBegin(IPluginContext *pContext, const char *name) =0; 01014 01015 /** 01016 * @brief Invoked by the JIT to notify that the last function call has 01017 * concluded. In the case of an error inside a function, this will not 01018 * be called. Instead, the VM will call OnCallbackEnd() and the profiler 01019 * stack must be unwound. 01020 */ 01021 virtual void OnFunctionEnd() =0; 01022 01023 /** 01024 * @brief Invoked by the VM to notify that a forward/callback is starting. 01025 * 01026 * @param pContext Plugin context. 01027 * @param pubfunc Public function information. 01028 * @return Unique number to pass to OnFunctionEnd(). 01029 */ 01030 virtual int OnCallbackBegin(IPluginContext *pContext, sp_public_t *pubfunc) =0; 01031 01032 /** 01033 * @brief Invoked by the JIT to notify that a callback has ended. 01034 * 01035 * As noted in OnFunctionEnd(), this my be called with a misaligned 01036 * profiler stack. To correct this, the stack should be unwound 01037 * (discarding data as appropriate) to a matching serial number. 01038 * 01039 * @param serial Unique number from OnCallbackBegin(). 01040 */ 01041 virtual void OnCallbackEnd(int serial) =0; 01042 }; 01043 01044 struct sp_plugin_s; 01045 typedef struct sp_plugin_s sp_plugin_t; 01046 01047 /** 01048 * @brief Contains helper functions used by VMs and the host app 01049 */ 01050 class ISourcePawnEngine 01051 { 01052 public: 01053 /** 01054 * @brief Deprecated, do not use. 01055 * 01056 * @param fp Unused. 01057 * @param err Unused. 01058 * @return NULL. 01059 */ 01060 virtual sp_plugin_t *LoadFromFilePointer(FILE *fp, int *err) =0; 01061 01062 /** 01063 * @brief Deprecated, do not use, 01064 * 01065 * @param base Unused. 01066 * @param plugin Unused. 01067 * @param err Unused. 01068 * @return NULL. 01069 */ 01070 virtual sp_plugin_t *LoadFromMemory(void *base, sp_plugin_t *plugin, int *err) =0; 01071 01072 /** 01073 * @brief Deprecated, do not use. 01074 * 01075 * @param plugin Unused. 01076 * @return SP_ERROR_ABORTED. 01077 */ 01078 virtual int FreeFromMemory(sp_plugin_t *plugin) =0; 01079 01080 /** 01081 * @brief Allocates large blocks of temporary memory. 01082 * 01083 * @param size Size of memory to allocate. 01084 * @return Pointer to memory, NULL if allocation failed. 01085 */ 01086 virtual void *BaseAlloc(size_t size) =0; 01087 01088 /** 01089 * @brief Frees memory allocated with BaseAlloc. 01090 * 01091 * @param memory Memory address to free. 01092 */ 01093 virtual void BaseFree(void *memory) =0; 01094 01095 /** 01096 * @brief Allocates executable memory. 01097 * @deprecated Use AllocPageMemory() 01098 * 01099 * @param size Size of memory to allocate. 01100 * @return Pointer to memory, NULL if allocation failed. 01101 */ 01102 virtual void *ExecAlloc(size_t size) =0; 01103 01104 /** 01105 * @brief Frees executable memory. 01106 * @deprecated Use FreePageMemory() 01107 * 01108 * @param address Address to free. 01109 */ 01110 virtual void ExecFree(void *address) =0; 01111 01112 /** 01113 * @brief Sets the debug listener. This should only be called once. 01114 * If called successively (using manual chaining), only the last function should 01115 * attempt to call back into the same plugin. Otherwise, globally cached states 01116 * can be accidentally overwritten. 01117 * 01118 * @param listener Pointer to an IDebugListener. 01119 * @return Old IDebugListener, or NULL if none. 01120 */ 01121 virtual IDebugListener *SetDebugListener(IDebugListener *listener) =0; 01122 01123 /** 01124 * @brief Deprecated, do not use. 01125 * 01126 * @return 0. 01127 */ 01128 virtual unsigned int GetContextCallCount() =0; 01129 01130 /** 01131 * @brief Returns the engine API version. 01132 * 01133 * @return Engine API version. 01134 */ 01135 virtual unsigned int GetEngineAPIVersion() =0; 01136 01137 /** 01138 * @brief Allocates executable memory. 01139 * 01140 * @param size Size of memory to allocate. 01141 * @return Pointer to memory, NULL if allocation failed. 01142 */ 01143 virtual void *AllocatePageMemory(size_t size) =0; 01144 01145 /** 01146 * @brief Sets the input memory permissions to read+write. 01147 * 01148 * @param ptr Memory block. 01149 */ 01150 virtual void SetReadWrite(void *ptr) =0; 01151 01152 /** 01153 * @brief Sets the input memory permissions to read+execute. 01154 * 01155 * @param ptr Memory block. 01156 */ 01157 virtual void SetReadExecute(void *ptr) =0; 01158 01159 /** 01160 * @brief Frees executable memory. 01161 * 01162 * @param ptr Address to free. 01163 */ 01164 virtual void FreePageMemory(void *ptr) =0; 01165 }; 01166 01167 /** 01168 * @brief Outlines the interface a Virtual Machine (JIT) must expose 01169 */ 01170 class ISourcePawnEngine2 01171 { 01172 public: 01173 /** 01174 * @brief Returns the second engine API version. 01175 * 01176 * @return API version. 01177 */ 01178 virtual unsigned int GetAPIVersion() =0; 01179 01180 /** 01181 * @brief Returns the string name of a VM implementation. 01182 */ 01183 virtual const char *GetEngineName() =0; 01184 01185 /** 01186 * @brief Returns a version string. 01187 * 01188 * @return Versioning string. 01189 */ 01190 virtual const char *GetVersionString() =0; 01191 01192 /** 01193 * @brief Creates a new compilation options object. 01194 * 01195 * @return Compilation options object. 01196 */ 01197 virtual ICompilation *StartCompilation() =0; 01198 01199 /** 01200 * @brief Loads a plugin from disk. 01201 * 01202 * If a compilation object is supplied, it is destroyed upon 01203 * the function's return. 01204 * 01205 * @param co Compilation options, or NULL for defaults. 01206 * @param file Path to the file to compile. 01207 * @param err Error code (filled on failure); required. 01208 * @return New runtime pointer, or NULL on failure. 01209 */ 01210 virtual IPluginRuntime *LoadPlugin(ICompilation *co, const char *file, int *err) =0; 01211 01212 /** 01213 * @brief Creates a fake native and binds it to a general callback function. 01214 * 01215 * @param callback Callback function to bind the native to. 01216 * @param pData Private data to pass to the callback when the native is invoked. 01217 * @return A new fake native function as a wrapper around the callback. 01218 */ 01219 virtual SPVM_NATIVE_FUNC CreateFakeNative(SPVM_FAKENATIVE_FUNC callback, void *pData) =0; 01220 01221 /** 01222 * @brief Destroys a fake native function wrapper. 01223 * 01224 * @param func Pointer to the fake native created by CreateFakeNative. 01225 */ 01226 virtual void DestroyFakeNative(SPVM_NATIVE_FUNC func) =0; 01227 01228 /** 01229 * @brief Sets the debug listener. This should only be called once. 01230 * If called successively (using manual chaining), only the last function should 01231 * attempt to call back into the same plugin. Otherwise, globally cached states 01232 * can be accidentally overwritten. 01233 * 01234 * @param listener Pointer to an IDebugListener. 01235 * @return Old IDebugListener, or NULL if none. 01236 */ 01237 virtual IDebugListener *SetDebugListener(IDebugListener *listener) =0; 01238 01239 /** 01240 * @brief Sets the global profiler. 01241 * 01242 * @param profiler Profiler pointer. 01243 */ 01244 virtual void SetProfiler(IProfiler *profiler) =0; 01245 01246 /** 01247 * @brief Returns the string representation of an error message. 01248 * 01249 * @param err Error code. 01250 * @return Error string, or NULL if not found. 01251 */ 01252 virtual const char *GetErrorString(int err) =0; 01253 01254 /** 01255 * @brief Initializes the SourcePawn engine. 01256 * 01257 * @return True on success, false if failed. 01258 */ 01259 virtual bool Initialize() =0; 01260 01261 /** 01262 * @brief Shuts down the SourcePawn engine. Only needs to be called if 01263 * Initialize() succeeded. 01264 */ 01265 virtual void Shutdown() =0; 01266 01267 /** 01268 * @brief Creates an empty plugin with a blob of memory. 01269 * 01270 * @param name Name, for debugging (NULL for anonymous). 01271 * @param bytes Number of bytes of memory (hea+stk). 01272 * @return New runtime, or NULL if not enough memory. 01273 */ 01274 virtual IPluginRuntime *CreateEmptyRuntime(const char *name, uint32_t memory) =0; 01275 }; 01276 }; 01277 01278 #endif //_INCLUDE_SOURCEPAWN_VM_API_H_
1.7.1