00001 /** 00002 * vim: set ts=4 : 00003 * ============================================================================= 00004 * SourcePawn 00005 * Copyright (C) 2004-2008 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 * Version: $Id: sp_vm_api.h 2459 2008-08-15 05:22:26Z dvander $ 00030 */ 00031 00032 #ifndef _INCLUDE_SOURCEPAWN_VM_API_H_ 00033 #define _INCLUDE_SOURCEPAWN_VM_API_H_ 00034 00035 /** 00036 * @file sp_vm_api.h 00037 * @brief Contains all of the object structures used in the SourcePawn API. 00038 */ 00039 00040 #include <stdio.h> 00041 #include "sp_vm_types.h" 00042 00043 /** SourcePawn Engine API Version */ 00044 #define SOURCEPAWN_ENGINE_API_VERSION 4 00045 #define SOURCEPAWN_ENGINE2_API_VERSION 2 00046 00047 #if !defined SOURCEMOD_BUILD 00048 #define SOURCEMOD_BUILD 00049 #endif 00050 00051 #if defined SOURCEMOD_BUILD 00052 namespace SourceMod 00053 { 00054 struct IdentityToken_t; 00055 }; 00056 #endif 00057 00058 struct sp_context_s; 00059 typedef struct sp_context_s sp_context_t; 00060 00061 namespace SourcePawn 00062 { 00063 class IVirtualMachine; 00064 00065 /* Parameter flags */ 00066 #define SM_PARAM_COPYBACK (1<<0) /**< Copy an array/reference back after call */ 00067 00068 /* String parameter flags (separate from parameter flags) */ 00069 #define SM_PARAM_STRING_UTF8 (1<<0) /**< String should be UTF-8 handled */ 00070 #define SM_PARAM_STRING_COPY (1<<1) /**< String should be copied into the plugin */ 00071 #define SM_PARAM_STRING_BINARY (1<<2) /**< String should be handled as binary data */ 00072 00073 #if defined SOURCEMOD_BUILD 00074 /** 00075 * @brief Pseudo-NULL reference types. 00076 */ 00077 enum SP_NULL_TYPE 00078 { 00079 SP_NULL_VECTOR = 0, /**< Float[3] reference */ 00080 SP_NULL_STRING = 1, /**< const String[1] reference */ 00081 }; 00082 #endif 00083 00084 /** 00085 * @brief Represents what a function needs to implement in order to be callable. 00086 */ 00087 class ICallable 00088 { 00089 public: 00090 /** 00091 * @brief Pushes a cell onto the current call. 00092 * 00093 * @param cell Parameter value to push. 00094 * @return Error code, if any. 00095 */ 00096 virtual int PushCell(cell_t cell) =0; 00097 00098 /** 00099 * @brief Pushes a cell by reference onto the current call. 00100 * NOTE: On Execute, the pointer passed will be modified if copyback is enabled. 00101 * NOTE: By reference parameters are cached and thus are not read until execution. 00102 * This means you cannot push a pointer, change it, and push it again and expect 00103 * two different values to come out. 00104 * 00105 * @param cell Address containing parameter value to push. 00106 * @param flags Copy-back flags. 00107 * @return Error code, if any. 00108 */ 00109 virtual int PushCellByRef(cell_t *cell, int flags=SM_PARAM_COPYBACK) =0; 00110 00111 /** 00112 * @brief Pushes a float onto the current call. 00113 * 00114 * @param number Parameter value to push. 00115 * @return Error code, if any. 00116 */ 00117 virtual int PushFloat(float number) =0; 00118 00119 /** 00120 * @brief Pushes a float onto the current call by reference. 00121 * NOTE: On Execute, the pointer passed will be modified if copyback is enabled. 00122 * NOTE: By reference parameters are cached and thus are not read until execution. 00123 * This means you cannot push a pointer, change it, and push it again and expect 00124 * two different values to come out. 00125 * 00126 * @param number Parameter value to push. 00127 & @param flags Copy-back flags. 00128 * @return Error code, if any. 00129 */ 00130 virtual int PushFloatByRef(float *number, int flags=SM_PARAM_COPYBACK) =0; 00131 00132 /** 00133 * @brief Pushes an array of cells onto the current call. 00134 * 00135 * On Execute, the pointer passed will be modified if non-NULL and copy-back 00136 * is enabled. 00137 * 00138 * By reference parameters are cached and thus are not read until execution. 00139 * This means you cannot push a pointer, change it, and push it again and expect 00140 * two different values to come out. 00141 * 00142 * @param inarray Array to copy, NULL if no initial array should be copied. 00143 * @param cells Number of cells to allocate and optionally read from the input array. 00144 * @param flags Whether or not changes should be copied back to the input array. 00145 * @return Error code, if any. 00146 */ 00147 virtual int PushArray(cell_t *inarray, unsigned int cells, int flags=0) =0; 00148 00149 /** 00150 * @brief Pushes a string onto the current call. 00151 * 00152 * @param string String to push. 00153 * @return Error code, if any. 00154 */ 00155 virtual int PushString(const char *string) =0; 00156 00157 /** 00158 * @brief Pushes a string or string buffer. 00159 * 00160 * NOTE: On Execute, the pointer passed will be modified if copy-back is enabled. 00161 * 00162 * @param buffer Pointer to string buffer. 00163 * @param length Length of buffer. 00164 * @param sz_flags String flags. In copy mode, the string will be copied 00165 * according to the handling (ascii, utf-8, binary, etc). 00166 * @param cp_flags Copy-back flags. 00167 * @return Error code, if any. 00168 */ 00169 virtual int PushStringEx(char *buffer, size_t length, int sz_flags, int cp_flags) =0; 00170 00171 /** 00172 * @brief Cancels a function call that is being pushed but not yet executed. 00173 * This can be used be reset for CallFunction() use. 00174 */ 00175 virtual void Cancel() =0; 00176 }; 00177 00178 00179 /** 00180 * @brief Encapsulates a function call in a plugin. 00181 * 00182 * NOTE: Function calls must be atomic to one execution context. 00183 * NOTE: This object should not be deleted. It lives for the lifetime of the plugin. 00184 */ 00185 class IPluginFunction : public ICallable 00186 { 00187 public: 00188 /** 00189 * @brief Executes the function, resets the pushed parameter list, and 00190 * performs any copybacks. 00191 * 00192 * @param result Pointer to store return value in. 00193 * @return Error code, if any. 00194 */ 00195 virtual int Execute(cell_t *result) =0; 00196 00197 /** 00198 * @brief Executes the function with the given parameter array. 00199 * Parameters are read in forward order (i.e. index 0 is parameter #1) 00200 * NOTE: You will get an error if you attempt to use CallFunction() with 00201 * previously pushed parameters. 00202 * 00203 * @param params Array of cell parameters. 00204 * @param num_params Number of parameters to push. 00205 * @param result Pointer to store result of function on return. 00206 * @return SourcePawn error code (if any). 00207 */ 00208 virtual int CallFunction(const cell_t *params, unsigned int num_params, cell_t *result) =0; 00209 00210 /** 00211 * @brief Deprecated, do not use. 00212 * 00213 * @return GetDefaultContext() of parent runtime. 00214 */ 00215 virtual IPluginContext *GetParentContext() =0; 00216 00217 /** 00218 * @brief Returns whether the parent plugin is paused. 00219 * 00220 * @return True if runnable, false otherwise. 00221 */ 00222 virtual bool IsRunnable() =0; 00223 00224 /** 00225 * @brief Returns the function ID of this function. 00226 * 00227 * Note: This was added in API version 4. 00228 * 00229 * @return Function id. 00230 */ 00231 virtual funcid_t GetFunctionID() =0; 00232 00233 /** 00234 * @brief Executes the forward, resets the pushed parameter list, and 00235 * performs any copybacks. 00236 * 00237 * Note: A function can only be executed given a runtime it was created in. 00238 * 00239 * @param ctx Context to execute the function in. 00240 * @param result Pointer to store return value in. 00241 * @return Error code, if any. 00242 */ 00243 virtual int Execute2(IPluginContext *ctx, cell_t *result) =0; 00244 00245 /** 00246 * @brief Executes the function with the given parameter array. 00247 * Parameters are read in forward order (i.e. index 0 is parameter #1) 00248 * NOTE: You will get an error if you attempt to use CallFunction() with 00249 * previously pushed parameters. 00250 * 00251 * Note: A function can only be executed given a runtime it was created in. 00252 * 00253 * @param ctx Context to execute the function in. 00254 * @param params Array of cell parameters. 00255 * @param num_params Number of parameters to push. 00256 * @param result Pointer to store result of function on return. 00257 * @return SourcePawn error code (if any). 00258 */ 00259 virtual int CallFunction2(IPluginContext *ctx, 00260 const cell_t *params, 00261 unsigned int num_params, 00262 cell_t *result) =0; 00263 }; 00264 00265 00266 /** 00267 * @brief Interface to managing a debug context at runtime. 00268 */ 00269 class IPluginDebugInfo 00270 { 00271 public: 00272 /** 00273 * @brief Given a code pointer, finds the file it is associated with. 00274 * 00275 * @param addr Code address offset. 00276 * @param filename Pointer to store filename pointer in. 00277 */ 00278 virtual int LookupFile(ucell_t addr, const char **filename) =0; 00279 00280 /** 00281 * @brief Given a code pointer, finds the function it is associated with. 00282 * 00283 * @param addr Code address offset. 00284 * @param name Pointer to store function name pointer in. 00285 */ 00286 virtual int LookupFunction(ucell_t addr, const char **name) =0; 00287 00288 /** 00289 * @brief Given a code pointer, finds the line it is associated with. 00290 * 00291 * @param addr Code address offset. 00292 * @param line Pointer to store line number in. 00293 */ 00294 virtual int LookupLine(ucell_t addr, uint32_t *line) =0; 00295 }; 00296 00297 /** 00298 * @brief Represents a JIT compilation or plugin loading options. 00299 */ 00300 class ICompilation 00301 { 00302 public: 00303 /** 00304 * @brief Sets a compilation option. 00305 * 00306 * @param key Option name. 00307 * @param val Option value. 00308 * @return True on success, false on failure. 00309 */ 00310 virtual bool SetOption(const char *key, const char *val) =0; 00311 00312 /** 00313 * @brief Aborts the compilation and destroys this object. 00314 */ 00315 virtual void Abort() =0; 00316 }; 00317 00318 /** 00319 * @brief Interface to managing a runtime plugin. 00320 */ 00321 class IPluginRuntime 00322 { 00323 public: 00324 /** 00325 * @brief Virtual destructor (you may call delete). 00326 */ 00327 virtual ~IPluginRuntime() 00328 { 00329 } 00330 00331 /** 00332 * @brief Returns debug info. 00333 * 00334 * @return IPluginDebugInfo, or NULL if no debug info found. 00335 */ 00336 virtual IPluginDebugInfo *GetDebugInfo() =0; 00337 00338 /** 00339 * @brief Finds a native by name. 00340 * 00341 * @param name Name of native. 00342 * @param index Optionally filled with native index number. 00343 */ 00344 virtual int FindNativeByName(const char *name, uint32_t *index) =0; 00345 00346 /** 00347 * @brief Gets native info by index. 00348 * 00349 * @param index Index number of native. 00350 * @param native Optionally filled with pointer to native structure. 00351 */ 00352 virtual int GetNativeByIndex(uint32_t index, sp_native_t **native) =0; 00353 00354 /** 00355 * @brief Gets the number of natives. 00356 * 00357 * @return Filled with the number of natives. 00358 */ 00359 virtual uint32_t GetNativesNum() =0; 00360 00361 /** 00362 * @brief Finds a public function by name. 00363 * 00364 * @param name Name of public 00365 * @param index Optionally filled with public index number. 00366 */ 00367 virtual int FindPublicByName(const char *name, uint32_t *index) =0; 00368 00369 /** 00370 * @brief Gets public function info by index. 00371 * 00372 * @param index Public function index number. 00373 * @param publicptr Optionally filled with pointer to public structure. 00374 */ 00375 virtual int GetPublicByIndex(uint32_t index, sp_public_t **publicptr) =0; 00376 00377 /** 00378 * @brief Gets the number of public functions. 00379 * 00380 * @return Filled with the number of public functions. 00381 */ 00382 virtual uint32_t GetPublicsNum() =0; 00383 00384 /** 00385 * @brief Gets public variable info by index. 00386 * 00387 * @param index Public variable index number. 00388 * @param pubvar Optionally filled with pointer to pubvar structure. 00389 */ 00390 virtual int GetPubvarByIndex(uint32_t index, sp_pubvar_t **pubvar) =0; 00391 00392 /** 00393 * @brief Finds a public variable by name. 00394 * 00395 * @param name Name of pubvar 00396 * @param index Optionally filled with pubvar index number. 00397 */ 00398 virtual int FindPubvarByName(const char *name, uint32_t *index) =0; 00399 00400 /** 00401 * @brief Gets the addresses of a public variable. 00402 * 00403 * @param index Index of public variable. 00404 * @param local_addr Address to store local address in. 00405 * @param phys_addr Address to store physically relocated in. 00406 */ 00407 virtual int GetPubvarAddrs(uint32_t index, cell_t *local_addr, cell_t **phys_addr) =0; 00408 00409 /** 00410 * @brief Returns the number of public variables. 00411 * 00412 * @return Number of public variables. 00413 */ 00414 virtual uint32_t GetPubVarsNum() =0; 00415 00416 /** 00417 * @brief Returns a function by name. 00418 * 00419 * @param public_name Name of the function. 00420 * @return A new IPluginFunction pointer, NULL if not found. 00421 */ 00422 virtual IPluginFunction *GetFunctionByName(const char *public_name) =0; 00423 00424 /** 00425 * @brief Returns a function by its id. 00426 * 00427 * @param func_id Function ID. 00428 * @return A new IPluginFunction pointer, NULL if not found. 00429 */ 00430 virtual IPluginFunction *GetFunctionById(funcid_t func_id) =0; 00431 00432 /** 00433 * @brief Returns the default context. The default context 00434 * should not be destroyed. 00435 * 00436 * @return Default context pointer. 00437 */ 00438 virtual IPluginContext *GetDefaultContext() =0; 00439 00440 /** 00441 * @brief Returns true if the plugin is in debug mode. 00442 * 00443 * @return True if in debug mode, false otherwise. 00444 */ 00445 virtual bool IsDebugging() =0; 00446 00447 /** 00448 * @brief Applies new compilation/runtime settings to the runtime code. 00449 * 00450 * The compilation object is destroyed once this function completes. 00451 * 00452 * @return Error code (SP_ERROR_NONE on success). 00453 */ 00454 virtual int ApplyCompilationOptions(ICompilation *co) =0; 00455 00456 /** 00457 * @brief Sets whether or not the plugin is paused (cannot be run). 00458 * 00459 * @param pause Pause state. 00460 */ 00461 virtual void SetPauseState(bool paused) =0; 00462 00463 /** 00464 * @brief Returns whether or not the plugin is paused (runnable). 00465 * 00466 * @return Pause state (true = paused, false = not). 00467 */ 00468 virtual bool IsPaused() =0; 00469 00470 /** 00471 * @brief Returns the estimated memory usage of this plugin. 00472 * 00473 * @return Memory usage, in bytes. 00474 */ 00475 virtual size_t GetMemUsage() =0; 00476 }; 00477 00478 /** 00479 * @brief Interface to managing a context at runtime. 00480 */ 00481 class IPluginContext 00482 { 00483 public: 00484 /** Virtual destructor */ 00485 virtual ~IPluginContext() { }; 00486 public: 00487 /** 00488 * @brief Deprecated, does nothing. 00489 * 00490 * @return NULL. 00491 */ 00492 virtual IVirtualMachine *GetVirtualMachine() =0; 00493 00494 /** 00495 * @brief Deprecated, do not use. 00496 * 00497 * Returns the pointer of this object, casted to an opaque structure. 00498 * 00499 * @return Returns this. 00500 */ 00501 virtual sp_context_t *GetContext() =0; 00502 00503 /** 00504 * @brief Returns true if the plugin is in debug mode. 00505 * 00506 * @return True if in debug mode, false otherwise. 00507 */ 00508 virtual bool IsDebugging() =0; 00509 00510 /** 00511 * @brief Deprecated, does nothing. 00512 * 00513 * @param newpfn Unused. 00514 * @param oldpfn Unused. 00515 */ 00516 virtual int SetDebugBreak(void *newpfn, void *oldpfn) =0; 00517 00518 /** 00519 * @brief Deprecated, do not use. 00520 * 00521 * @return NULL. 00522 */ 00523 virtual IPluginDebugInfo *GetDebugInfo() =0; 00524 00525 /** 00526 * @brief Allocates memory on the secondary stack of a plugin. 00527 * Note that although called a heap, it is in fact a stack. 00528 * 00529 * @param cells Number of cells to allocate. 00530 * @param local_addr Will be filled with data offset to heap. 00531 * @param phys_addr Physical address to heap memory. 00532 */ 00533 virtual int HeapAlloc(unsigned int cells, cell_t *local_addr, cell_t **phys_addr) =0; 00534 00535 /** 00536 * @brief Pops a heap address off the heap stack. Use this to free memory allocated with 00537 * SP_HeapAlloc(). 00538 * Note that in SourcePawn, the heap is in fact a bottom-up stack. Deallocations 00539 * with this native should be performed in precisely the REVERSE order. 00540 * 00541 * @param local_addr Local address to free. 00542 */ 00543 virtual int HeapPop(cell_t local_addr) =0; 00544 00545 /** 00546 * @brief Releases a heap address using a different method than SP_HeapPop(). 00547 * This allows you to release in any order. However, if you allocate N 00548 * objects, release only some of them, then begin allocating again, 00549 * you cannot go back and starting freeing the originals. 00550 * In other words, for each chain of allocations, if you start deallocating, 00551 * then allocating more in a chain, you must only deallocate from the current 00552 * allocation chain. This is basically HeapPop() except on a larger scale. 00553 * 00554 * @param local_addr Local address to free. 00555 */ 00556 virtual int HeapRelease(cell_t local_addr) =0; 00557 00558 /** 00559 * @brief Deprecated, use IPluginRuntime instead. 00560 * 00561 * @param name Name of native. 00562 * @param index Optionally filled with native index number. 00563 */ 00564 virtual int FindNativeByName(const char *name, uint32_t *index) =0; 00565 00566 /** 00567 * @brief Deprecated, use IPluginRuntime instead. 00568 * 00569 * @param index Index number of native. 00570 * @param native Optionally filled with pointer to native structure. 00571 */ 00572 virtual int GetNativeByIndex(uint32_t index, sp_native_t **native) =0; 00573 00574 /** 00575 * @brief Deprecated, use IPluginRuntime instead. 00576 * 00577 * @return Filled with the number of natives. 00578 */ 00579 virtual uint32_t GetNativesNum() =0; 00580 00581 /** 00582 * @brief Deprecated, use IPluginRuntime instead. 00583 * 00584 * @param name Name of public 00585 * @param index Optionally filled with public index number. 00586 */ 00587 virtual int FindPublicByName(const char *name, uint32_t *index) =0; 00588 00589 /** 00590 * @brief Deprecated, use IPluginRuntime instead. 00591 * 00592 * @param index Public function index number. 00593 * @param publicptr Optionally filled with pointer to public structure. 00594 */ 00595 virtual int GetPublicByIndex(uint32_t index, sp_public_t **publicptr) =0; 00596 00597 /** 00598 * @brief Deprecated, use IPluginRuntime instead. 00599 * 00600 * @return Filled with the number of public functions. 00601 */ 00602 virtual uint32_t GetPublicsNum() =0; 00603 00604 /** 00605 * @brief Deprecated, use IPluginRuntime instead. 00606 * 00607 * @param index Public variable index number. 00608 * @param pubvar Optionally filled with pointer to pubvar structure. 00609 */ 00610 virtual int GetPubvarByIndex(uint32_t index, sp_pubvar_t **pubvar) =0; 00611 00612 /** 00613 * @brief Deprecated, use IPluginRuntime instead. 00614 * 00615 * @param name Name of pubvar 00616 * @param index Optionally filled with pubvar index number. 00617 */ 00618 virtual int FindPubvarByName(const char *name, uint32_t *index) =0; 00619 00620 /** 00621 * @brief Deprecated, use IPluginRuntime instead. 00622 * 00623 * @param index Index of public variable. 00624 * @param local_addr Address to store local address in. 00625 * @param phys_addr Address to store physically relocated in. 00626 */ 00627 virtual int GetPubvarAddrs(uint32_t index, cell_t *local_addr, cell_t **phys_addr) =0; 00628 00629 /** 00630 * @brief Deprecated, use IPluginRuntime instead. 00631 * 00632 * @return Number of public variables. 00633 */ 00634 virtual uint32_t GetPubVarsNum() =0; 00635 00636 /** 00637 * @brief Converts a plugin reference to a physical address 00638 * 00639 * @param local_addr Local address in plugin. 00640 * @param phys_addr Optionally filled with relocated physical address. 00641 */ 00642 virtual int LocalToPhysAddr(cell_t local_addr, cell_t **phys_addr) =0; 00643 00644 /** 00645 * @brief Converts a local address to a physical string. 00646 * 00647 * @param local_addr Local address in plugin. 00648 * @param addr Destination output pointer. 00649 */ 00650 virtual int LocalToString(cell_t local_addr, char **addr) =0; 00651 00652 /** 00653 * @brief Converts a physical string to a local address. 00654 * 00655 * @param local_addr Local address in plugin. 00656 * @param bytes Number of chars to write, including NULL terminator. 00657 * @param source Source string to copy. 00658 */ 00659 virtual int StringToLocal(cell_t local_addr, size_t bytes, const char *source) =0; 00660 00661 /** 00662 * @brief Converts a physical UTF-8 string to a local address. 00663 * This function is the same as the ANSI version, except it will copy the maximum number 00664 * of characters possible without accidentally chopping a multi-byte character. 00665 * 00666 * @param local_addr Local address in plugin. 00667 * @param maxbytes Number of bytes to write, including NULL terminator. 00668 * @param source Source string to copy. 00669 * @param wrtnbytes Optionally set to the number of actual bytes written. 00670 */ 00671 virtual int StringToLocalUTF8(cell_t local_addr, 00672 size_t maxbytes, 00673 const char *source, 00674 size_t *wrtnbytes) =0; 00675 00676 /** 00677 * @brief Deprecated, does nothing. 00678 * 00679 * @param value Unused. 00680 */ 00681 virtual int PushCell(cell_t value) =0; 00682 00683 /** 00684 * @brief Deprecated, does nothing. 00685 * 00686 * @param local_addr Unused. 00687 * @param phys_addr Unused. 00688 * @param array Unused. 00689 * @param numcells Unused. 00690 */ 00691 virtual int PushCellArray(cell_t *local_addr, cell_t **phys_addr, cell_t array[], unsigned int numcells) =0; 00692 00693 /** 00694 * @brief Deprecated, does nothing. 00695 * 00696 * @param local_addr Unused. 00697 * @param phys_addr Unused. 00698 * @param string Unused. 00699 */ 00700 virtual int PushString(cell_t *local_addr, char **phys_addr, const char *string) =0; 00701 00702 /** 00703 * @brief Deprecated, does nothing. 00704 * 00705 * @param array Unused. 00706 * @param numcells Unused. 00707 */ 00708 virtual int PushCellsFromArray(cell_t array[], unsigned int numcells) =0; 00709 00710 /** 00711 * @brief Deprecated, does nothing. 00712 * 00713 * @param natives Deprecated; do not use. 00714 * @param num Deprecated; do not use. 00715 * @param overwrite Deprecated; do not use. 00716 */ 00717 virtual int BindNatives(const sp_nativeinfo_t *natives, unsigned int num, int overwrite) =0; 00718 00719 /** 00720 * @brief Deprecated, does nothing. 00721 * 00722 * @param native Deprecated; do not use. 00723 */ 00724 virtual int BindNative(const sp_nativeinfo_t *native) =0; 00725 00726 /** 00727 * @brief Deprecated, does nothing. 00728 * 00729 * @param native Unused. 00730 */ 00731 virtual int BindNativeToAny(SPVM_NATIVE_FUNC native) =0; 00732 00733 /** 00734 * @brief Deprecated, does nothing. 00735 * 00736 * @param code_addr Unused. 00737 * @param result Unused. 00738 * @return SP_ERROR_ABORTED. 00739 */ 00740 virtual int Execute(uint32_t code_addr, cell_t *result) =0; 00741 00742 /** 00743 * @brief Throws a error and halts any current execution. 00744 * 00745 * @param error The error number to set. 00746 * @param msg Custom error message format. NULL to use default. 00747 * @param ... Message format arguments, if any. 00748 * @return 0 for convenience. 00749 */ 00750 virtual cell_t ThrowNativeErrorEx(int error, const char *msg, ...) =0; 00751 00752 /** 00753 * @brief Throws a generic native error and halts any current execution. 00754 * 00755 * @param msg Custom error message format. NULL to set no message. 00756 * @param ... Message format arguments, if any. 00757 * @return 0 for convenience. 00758 */ 00759 virtual cell_t ThrowNativeError(const char *msg, ...) =0; 00760 00761 /** 00762 * @brief Returns a function by name. 00763 * 00764 * @param public_name Name of the function. 00765 * @return A new IPluginFunction pointer, NULL if not found. 00766 */ 00767 virtual IPluginFunction *GetFunctionByName(const char *public_name) =0; 00768 00769 /** 00770 * @brief Returns a function by its id. 00771 * 00772 * @param func_id Function ID. 00773 * @return A new IPluginFunction pointer, NULL if not found. 00774 */ 00775 virtual IPluginFunction *GetFunctionById(funcid_t func_id) =0; 00776 00777 /** 00778 * @brief Returns the identity token for this context. 00779 * 00780 * Note: This is a compatibility shim and is the same as GetKey(1). 00781 * 00782 * @return Identity token. 00783 */ 00784 virtual SourceMod::IdentityToken_t *GetIdentity() =0; 00785 00786 /** 00787 * @brief Returns a NULL reference based on one of the available NULL 00788 * reference types. 00789 * 00790 * @param type NULL reference type. 00791 * @return cell_t address to compare to. 00792 */ 00793 virtual cell_t *GetNullRef(SP_NULL_TYPE type) =0; 00794 00795 /** 00796 * @brief Converts a local address to a physical string, and allows 00797 * for NULL_STRING to be set. 00798 * 00799 * @param local_addr Local address in plugin. 00800 * @param addr Destination output pointer. 00801 */ 00802 virtual int LocalToStringNULL(cell_t local_addr, char **addr) =0; 00803 00804 /** 00805 * @brief Deprecated; do not use. 00806 * 00807 * @param index Deprecated; do not use. 00808 * @param native Deprecated; do not use. 00809 */ 00810 virtual int BindNativeToIndex(uint32_t index, SPVM_NATIVE_FUNC native) =0; 00811 00812 /** 00813 * @brief Returns if there is currently an execution in progress. 00814 * 00815 * @return True if in exec, false otherwise. 00816 */ 00817 virtual bool IsInExec() =0; 00818 00819 /** 00820 * @brief Returns the parent runtime of a context. 00821 * 00822 * @return Parent runtime. 00823 */ 00824 virtual IPluginRuntime *GetRuntime() =0; 00825 00826 /** 00827 * @brief Executes a function in the context. The function must be 00828 * a member of the context's parent runtime. 00829 * 00830 * @param function Function. 00831 * @param params Parameters. 00832 * @param num_params Number of parameters in the parameter array. 00833 * @param result Optional pointer to store the result on success. 00834 * @return Error code. 00835 */ 00836 virtual int Execute2(IPluginFunction *function, 00837 const cell_t *params, 00838 unsigned int num_params, 00839 cell_t *result) =0; 00840 00841 /** 00842 * @brief Returns whether a context is in an error state. 00843 * 00844 * This should only be used inside natives to determine whether 00845 * a prior call failed. 00846 */ 00847 virtual int GetLastNativeError() =0; 00848 00849 /** 00850 * @brief Returns the local parameter stack, starting from the 00851 * cell that contains the number of parameters passed. 00852 * 00853 * Local parameters are the parameters passed to the function 00854 * from which a native was called (and thus this can only be 00855 * called inside a native). 00856 * 00857 * @return Parameter stack. 00858 */ 00859 virtual cell_t *GetLocalParams() =0; 00860 00861 /** 00862 * @brief Sets a local "key" that can be used for fast lookup. 00863 * 00864 * Only the "owner" of the context should be setting this. 00865 * 00866 * @param key Key number (values allowed: 1 through 4). 00867 * @param value Pointer value. 00868 */ 00869 virtual void SetKey(int k, void *value) =0; 00870 00871 /** 00872 * @brief Retrieves a previously set "key." 00873 * 00874 * @param key Key number (values allowed: 1 through 4). 00875 * @param value Pointer to store value. 00876 * @return True on success, false on failure. 00877 */ 00878 virtual bool GetKey(int k, void **value) =0; 00879 }; 00880 00881 00882 /** 00883 * @brief Information about a position in a call stack. 00884 */ 00885 struct CallStackInfo 00886 { 00887 const char *filename; /**< NULL if not found */ 00888 unsigned int line; /**< 0 if not found */ 00889 const char *function; /**< NULL if not found */ 00890 }; 00891 00892 /** 00893 * @brief Retrieves error information from a debug hook. 00894 */ 00895 class IContextTrace 00896 { 00897 public: 00898 /** 00899 * @brief Returns the integer error code. 00900 * 00901 * @return Integer error code. 00902 */ 00903 virtual int GetErrorCode() =0; 00904 00905 /** 00906 * @brief Returns a string describing the error. 00907 * 00908 * @return Error string. 00909 */ 00910 virtual const char *GetErrorString() =0; 00911 00912 /** 00913 * @brief Returns whether debug info is available. 00914 * 00915 * @return True if debug info is available, false otherwise. 00916 */ 00917 virtual bool DebugInfoAvailable() =0; 00918 00919 /** 00920 * @brief Returns a custom error message. 00921 * 00922 * @return A pointer to a custom error message, or NULL otherwise. 00923 */ 00924 virtual const char *GetCustomErrorString() =0; 00925 00926 /** 00927 * @brief Returns trace info for a specific point in the backtrace, if any. 00928 * The next subsequent call to GetTraceInfo() will return the next item in the call stack. 00929 * Calls are retrieved in descending order (i.e. the first item is at the top of the stack/call sequence). 00930 * 00931 * @param trace An ErrorTraceInfo buffer to store information (NULL to ignore). 00932 * @return True if successful, false if there are no more traces. 00933 */ 00934 virtual bool GetTraceInfo(CallStackInfo *trace) =0; 00935 00936 /** 00937 * @brief Resets the trace to its original position (the call on the top of the stack). 00938 */ 00939 virtual void ResetTrace() =0; 00940 00941 /** 00942 * @brief Retrieves the name of the last native called. 00943 * Returns NULL if there was no native that caused the error. 00944 * 00945 * @param index Optional pointer to store index. 00946 * @return Native name, or NULL if none. 00947 */ 00948 virtual const char *GetLastNative(uint32_t *index) =0; 00949 }; 00950 00951 00952 /** 00953 * @brief Provides callbacks for debug information. 00954 */ 00955 class IDebugListener 00956 { 00957 public: 00958 /** 00959 * @brief Invoked on a context execution error. 00960 * 00961 * @param ctx Context. 00962 * @param error Object holding error information and a backtrace. 00963 */ 00964 virtual void OnContextExecuteError(IPluginContext *ctx, IContextTrace *error) =0; 00965 00966 /** 00967 * @brief Called on debug spew. 00968 * 00969 * @param msg Message text. 00970 * @param fmt Message formatting arguments (printf-style). 00971 */ 00972 virtual void OnDebugSpew(const char *msg, ...) =0; 00973 }; 00974 00975 /** 00976 * @brief Represents a code profiler for plugins. 00977 */ 00978 class IProfiler 00979 { 00980 public: 00981 /** 00982 * @brief Invoked by the JIT to notify that a native is being started. 00983 * 00984 * @param pContext Plugin context. 00985 * @param native Native information. 00986 */ 00987 virtual void OnNativeBegin(IPluginContext *pContext, sp_native_t *native) =0; 00988 00989 /** 00990 * @brief Invoked by the JIT to notify that the last native on the stack 00991 * is no longer being executed. 00992 */ 00993 virtual void OnNativeEnd() =0; 00994 00995 /** 00996 * @brief Invoked by the JIT to notify that a function call is starting. 00997 * <