3 * ================================================================
4 * SourcePawn, Copyright (C) 2004-2007 AlliedModders LLC.
6 * ================================================================
8 * This file is part of the SourceMod/SourcePawn SDK. This file may only be
9 * used or modified under the Terms and Conditions of its License Agreement,
10 * which is found in public/licenses/LICENSE.txt. As of this notice, derivative
11 * works must be licensed under the GNU General Public License (version 2 or
12 * greater). A copy of the GPL is included under public/licenses/GPL.txt.
14 * To view the latest information, see: http://www.sourcemod.net/license.php
19 #ifndef _INCLUDE_SOURCEPAWN_VM_API_H_
20 #define _INCLUDE_SOURCEPAWN_VM_API_H_
24 * @brief Contains all of the object structures used in the SourcePawn API.
28 #include "sp_vm_types.h"
30 /** SourcePawn VM API Version */
31 #define SOURCEPAWN_VM_API_VERSION 1
33 #if defined SOURCEMOD_BUILD
36 struct IdentityToken_t;
42 class IVirtualMachine;
44 #define SM_PARAM_COPYBACK (1<<0) /**< Copy an array/reference back after call */
45 #define SM_PARAM_STRING_UTF8 (1<<0) /**< String should be UTF-8 handled */
46 #define SM_PARAM_STRING_COPY (1<<1) /**< String should be copied into the plugin */
49 * @brief Represents what a function needs to implement in order to be callable.
55 * @brief Pushes a cell onto the current call.
57 * @param cell Parameter value to push.
58 * @return Error code, if any.
60 virtual int PushCell(cell_t cell) =0;
63 * @brief Pushes a cell by reference onto the current call.
64 * NOTE: On Execute, the pointer passed will be modified if copyback is enabled.
65 * NOTE: By reference parameters are cached and thus are not read until execution.
66 * This means you cannot push a pointer, change it, and push it again and expect
67 * two different values to come out.
69 * @param cell Address containing parameter value to push.
70 * @param flags Copy-back flags.
71 * @return Error code, if any.
73 virtual int PushCellByRef(cell_t *cell, int flags) =0;
76 * @brief Pushes a float onto the current call.
78 * @param number Parameter value to push.
79 * @return Error code, if any.
81 virtual int PushFloat(float number) =0;
84 * @brief Pushes a float onto the current call by reference.
85 * NOTE: On Execute, the pointer passed will be modified if copyback is enabled.
86 * NOTE: By reference parameters are cached and thus are not read until execution.
87 * This means you cannot push a pointer, change it, and push it again and expect
88 * two different values to come out.
90 * @param number Parameter value to push.
91 & @param flags Copy-back flags.
92 * @return Error code, if any.
94 virtual int PushFloatByRef(float *number, int flags) =0;
97 * @brief Pushes an array of cells onto the current call.
98 * NOTE: On Execute, the pointer passed will be modified if non-NULL and copy-back
100 * NOTE: By reference parameters are cached and thus are not read until execution.
101 * This means you cannot push a pointer, change it, and push it again and expect
102 * two different values to come out.
104 * @param inarray Array to copy, NULL if no initial array should be copied.
105 * @param cells Number of cells to allocate and optionally read from the input array.
106 * @param phys_addr Optional return address for physical array, if one was made.
107 * @param flags Whether or not changes should be copied back to the input array.
108 * @return Error code, if any.
110 virtual int PushArray(cell_t *inarray,
116 * @brief Pushes a string onto the current call.
118 * @param string String to push.
119 * @return Error code, if any.
121 virtual int PushString(const char *string) =0;
124 * @brief Pushes a string or string buffer.
125 * NOTE: On Execute, the pointer passed will be modified if copy-back is enabled.
127 * @param buffer Pointer to string buffer.
128 * @param length Length of buffer.
129 * @param sz_flags String flags.
130 * @param cp_flags Copy-back flags.
131 * @return Error code, if any.
133 virtual int PushStringEx(char *buffer, size_t length, int sz_flags, int cp_flags) =0;
136 * @brief Cancels a function call that is being pushed but not yet executed.
137 * This can be used be reset for CallFunction() use.
139 virtual void Cancel() =0;
144 * @brief Encapsulates a function call in a plugin.
146 * NOTE: Function calls must be atomic to one execution context.
147 * NOTE: This object should not be deleted. It lives for the lifetime of the plugin.
149 class IPluginFunction : public ICallable
153 * @brief Executes the forward, resets the pushed parameter list, and performs any copybacks.
155 * @param result Pointer to store return value in.
156 * @return Error code, if any.
158 virtual int Execute(cell_t *result) =0;
161 * @brief Executes the function with the given parameter array.
162 * Parameters are read in forward order (i.e. index 0 is parameter #1)
163 * NOTE: You will get an error if you attempt to use CallFunction() with
164 * previously pushed parameters.
166 * @param params Array of cell parameters.
167 * @param num_params Number of parameters to push.
168 * @param result Pointer to store result of function on return.
169 * @return SourcePawn error code (if any).
171 virtual int CallFunction(const cell_t *params, unsigned int num_params, cell_t *result) =0;
174 * @brief Returns which plugin this function belongs to.
176 * @return IPluginContext pointer to parent plugin.
178 virtual IPluginContext *GetParentContext() =0;
181 * @brief Returns the physical address of a by-reference parameter.
183 * @param param Parameter index to read (beginning at 0).
184 * @return Address, or NULL if invalid parameter specified.
186 virtual cell_t *GetAddressOfPushedParam(unsigned int param) =0;
191 * @brief Interface to managing a debug context at runtime.
193 class IPluginDebugInfo
197 * @brief Given a code pointer, finds the file it is associated with.
199 * @param addr Code address offset.
200 * @param filename Pointer to store filename pointer in.
202 virtual int LookupFile(ucell_t addr, const char **filename) =0;
205 * @brief Given a code pointer, finds the function it is associated with.
207 * @param addr Code address offset.
208 * @param name Pointer to store function name pointer in.
210 virtual int LookupFunction(ucell_t addr, const char **name) =0;
213 * @brief Given a code pointer, finds the line it is associated with.
215 * @param addr Code address offset.
216 * @param line Pointer to store line number in.
218 virtual int LookupLine(ucell_t addr, uint32_t *line) =0;
222 * @brief Interface to managing a context at runtime.
227 /** Virtual destructor */
228 virtual ~IPluginContext() { };
231 * @brief Returns the parent IVirtualMachine.
233 * @return Parent virtual machine pointer.
235 virtual IVirtualMachine *GetVirtualMachine() =0;
238 * @brief Returns the child sp_context_t structure.
240 * @return Child sp_context_t structure.
242 virtual sp_context_t *GetContext() =0;
245 * @brief Returns true if the plugin is in debug mode.
247 * @return True if in debug mode, false otherwise.
249 virtual bool IsDebugging() =0;
252 * @brief Installs a debug break and returns the old one, if any.
253 * This will fail if the plugin is not debugging.
255 * @param newpfn New function pointer.
256 * @param oldpfn Pointer to retrieve old function pointer.
258 virtual int SetDebugBreak(SPVM_DEBUGBREAK newpfn, SPVM_DEBUGBREAK *oldpfn) =0;
261 * @brief Returns debug info.
263 * @return IPluginDebugInfo, or NULL if no debug info found.
265 virtual IPluginDebugInfo *GetDebugInfo() =0;
268 * @brief Allocates memory on the secondary stack of a plugin.
269 * Note that although called a heap, it is in fact a stack.
271 * @param cells Number of cells to allocate.
272 * @param local_addr Will be filled with data offset to heap.
273 * @param phys_addr Physical address to heap memory.
275 virtual int HeapAlloc(unsigned int cells, cell_t *local_addr, cell_t **phys_addr) =0;
278 * @brief Pops a heap address off the heap stack. Use this to free memory allocated with
280 * Note that in SourcePawn, the heap is in fact a bottom-up stack. Deallocations
281 * with this native should be performed in precisely the REVERSE order.
283 * @param local_addr Local address to free.
285 virtual int HeapPop(cell_t local_addr) =0;
288 * @brief Releases a heap address using a different method than SP_HeapPop().
289 * This allows you to release in any order. However, if you allocate N
290 * objects, release only some of them, then begin allocating again,
291 * you cannot go back and starting freeing the originals.
292 * In other words, for each chain of allocations, if you start deallocating,
293 * then allocating more in a chain, you must only deallocate from the current
294 * allocation chain. This is basically HeapPop() except on a larger scale.
296 * @param local_addr Local address to free.
298 virtual int HeapRelease(cell_t local_addr) =0;
301 * @brief Finds a native by name.
303 * @param name Name of native.
304 * @param index Optionally filled with native index number.
306 virtual int FindNativeByName(const char *name, uint32_t *index) =0;
309 * @brief Gets native info by index.
311 * @param index Index number of native.
312 * @param native Optionally filled with pointer to native structure.
314 virtual int GetNativeByIndex(uint32_t index, sp_native_t **native) =0;
317 * @brief Gets the number of natives.
319 * @return Filled with the number of natives.
321 virtual uint32_t GetNativesNum() =0;
324 * @brief Finds a public function by name.
326 * @param name Name of public
327 * @param index Optionally filled with public index number.
329 virtual int FindPublicByName(const char *name, uint32_t *index) =0;
332 * @brief Gets public function info by index.
334 * @param index Public function index number.
335 * @param publicptr Optionally filled with pointer to public structure.
337 virtual int GetPublicByIndex(uint32_t index, sp_public_t **publicptr) =0;
340 * @brief Gets the number of public functions.
342 * @return Filled with the number of public functions.
344 virtual uint32_t GetPublicsNum() =0;
347 * @brief Gets public variable info by index.
349 * @param index Public variable index number.
350 * @param pubvar Optionally filled with pointer to pubvar structure.
352 virtual int GetPubvarByIndex(uint32_t index, sp_pubvar_t **pubvar) =0;
355 * @brief Finds a public variable by name.
357 * @param name Name of pubvar
358 * @param index Optionally filled with pubvar index number.
360 virtual int FindPubvarByName(const char *name, uint32_t *index) =0;
363 * @brief Gets the addresses of a public variable.
365 * @param index Index of public variable.
366 * @param local_addr Address to store local address in.
367 * @param phys_addr Address to store physically relocated in.
369 virtual int GetPubvarAddrs(uint32_t index, cell_t *local_addr, cell_t **phys_addr) =0;
372 * @brief Returns the number of public variables.
374 * @return Number of public variables.
376 virtual uint32_t GetPubVarsNum() =0;
379 * @brief Round-about method of converting a plugin reference to a physical address
381 * @param local_addr Local address in plugin.
382 * @param phys_addr Optionally filled with relocated physical address.
384 virtual int LocalToPhysAddr(cell_t local_addr, cell_t **phys_addr) =0;
387 * @brief Converts a local address to a physical string.
389 * @param local_addr Local address in plugin.
390 * @param addr Destination output pointer.
392 virtual int LocalToString(cell_t local_addr, char **addr) =0;
395 * @brief Converts a physical string to a local address.
397 * @param local_addr Local address in plugin.
398 * @param bytes Number of chars to write, including NULL terminator.
399 * @param source Source string to copy.
401 virtual int StringToLocal(cell_t local_addr, size_t bytes, const char *source) =0;
404 * @brief Converts a physical UTF-8 string to a local address.
405 * This function is the same as the ANSI version, except it will copy the maximum number of characters possible
406 * without accidentally chopping a multi-byte character.
408 * @param local_addr Local address in plugin.
409 * @param maxbytes Number of bytes to write, including NULL terminator.
410 * @param source Source string to copy.
411 * @param wrtnbytes Optionally set to the number of actual bytes written.
413 virtual int StringToLocalUTF8(cell_t local_addr,
416 size_t *wrtnbytes) =0;
419 * @brief Pushes a cell onto the stack. Increases the parameter count by one.
421 * @param value Cell value.
423 virtual int PushCell(cell_t value) =0;
426 * @brief Pushes an array of cells onto the stack. Increases the parameter count by one.
427 * If the function returns an error it will fail entirely, releasing anything allocated in the process.
428 * Note that this does not release the heap, so you should release it after
431 * @param local_addr Filled with local address to release.
432 * @param phys_addr Optionally filled with physical address of new array.
433 * @param array Cell array to copy.
434 * @param numcells Number of cells in the array to copy.
436 virtual int PushCellArray(cell_t *local_addr, cell_t **phys_addr, cell_t array[], unsigned int numcells) =0;
439 * @brief Pushes a string onto the stack (by reference) and increases the parameter count by one.
440 * Note that this does not release the heap, so you should release it after
443 * @param local_addr Filled with local address to release.
444 * @param phys_addr Optionally filled with physical address of new array.
445 * @param string Source string to push.
447 virtual int PushString(cell_t *local_addr, char **phys_addr, const char *string) =0;
450 * @brief Individually pushes each cell of an array of cells onto the stack. Increases the
451 * parameter count by the number of cells pushed.
452 * If the function returns an error it will fail entirely, releasing anything allocated in the process.
454 * @param array Array of cells to read from.
455 * @param numcells Number of cells to read.
457 virtual int PushCellsFromArray(cell_t array[], unsigned int numcells) =0;
460 * @brief Binds a list of native names and their function pointers to a context.
461 * If num is 0, the list is read until an entry with a NULL name is reached.
462 * If overwrite is non-zero, already registered natives will be overwritten.
464 * @param natives Array of natives.
465 * @param num Number of natives in array.
466 * @param overwrite Toggles overwrite.
468 virtual int BindNatives(const sp_nativeinfo_t *natives, unsigned int num, int overwrite) =0;
471 * @brief Binds a single native. Overwrites any existing bind.
472 * If the context does not contain the native that will be binded the function will return
473 * with a SP_ERROR_NOT_FOUND error.
475 * @param native Pointer to native.
477 virtual int BindNative(const sp_nativeinfo_t *native) =0;
480 * @brief Binds a single native to any non-registered native.
482 * @param native Native to bind.
484 virtual int BindNativeToAny(SPVM_NATIVE_FUNC native) =0;
487 * @brief Executes a function ID located in this context.
489 * @param code_addr Address to execute at.
490 * @param result Pointer to store the return value (required).
491 * @return Error code (if any) from the VM.
493 virtual int Execute(uint32_t code_addr, cell_t *result) =0;
496 * @brief Throws a error and halts any current execution.
498 * @param error The error number to set.
499 * @param msg Custom error message format. NULL to use default.
500 * @param ... Message format arguments, if any.
502 virtual void ThrowNativeErrorEx(int error, const char *msg, ...) =0;
505 * @brief Throws a generic native error and halts any current execution.
507 * @param msg Custom error message format. NULL to set no message.
508 * @param ... Message format arguments, if any.
509 * @return 0 for convenience.
511 virtual cell_t ThrowNativeError(const char *msg, ...) =0;
514 * @brief Returns a function by name.
516 * @param public_name Name of the function.
517 * @return A new IPluginFunction pointer, NULL if not found.
519 virtual IPluginFunction *GetFunctionByName(const char *public_name) =0;
522 * @brief Returns a function by its id.
524 * @param func_id Function ID.
525 * @return A new IPluginFunction pointer, NULL if not found.
527 virtual IPluginFunction *GetFunctionById(funcid_t func_id) =0;
529 #if defined SOURCEMOD_BUILD
531 * @brief Returns the identity token for this context.
532 * Note: This is a helper function for native calls and the Handle System.
534 * @return Identity token.
536 virtual SourceMod::IdentityToken_t *GetIdentity() =0;
539 * @brief Returns whether the identity is runnable.
541 * @return True if runnable, false otherwise.
543 virtual bool IsRunnable() =0;
549 * @brief Information about a position in a call stack.
553 const char *filename; /**< NULL if not found */
554 unsigned int line; /**< 0 if not found */
555 const char *function; /**< NULL if not found */
559 * @brief Retrieves error information from a debug hook.
565 * @brief Returns the integer error code.
567 * @return Integer error code.
569 virtual int GetErrorCode() =0;
572 * @brief Returns a string describing the error.
574 * @return Error string.
576 virtual const char *GetErrorString() =0;
579 * @brief Returns whether debug info is available.
581 * @return True if debug info is available, false otherwise.
583 virtual bool DebugInfoAvailable() =0;
586 * @brief Returns a custom error message.
588 * @return A pointer to a custom error message, or NULL otherwise.
590 virtual const char *GetCustomErrorString() =0;
593 * @brief Returns trace info for a specific point in the backtrace, if any.
594 * The next subsequent call to GetTraceInfo() will return the next item in the call stack.
595 * Calls are retrieved in descending order (i.e. the first item is at the top of the stack/call sequence).
597 * @param trace An ErrorTraceInfo buffer to store information (NULL to ignore).
598 * @return True if successful, false if there are no more traces.
600 virtual bool GetTraceInfo(CallStackInfo *trace) =0;
603 * @brief Resets the trace to its original position (the call on the top of the stack).
605 virtual void ResetTrace() =0;
608 * @brief Retrieves the name of the last native called.
609 * Returns NULL if there was no native that caused the error.
611 * @param index Optional pointer to store index.
612 * @return Native name, or NULL if none.
614 virtual const char *GetLastNative(uint32_t *index) =0;
619 * @brief Provides callbacks for debug information.
624 virtual void OnContextExecuteError(IPluginContext *ctx, IContextTrace *error) =0;
629 * @brief Contains helper functions used by VMs and the host app
631 class ISourcePawnEngine
635 * @brief Loads a named file from a file pointer.
636 * Note: Using this means the memory will be allocated by the VM.
638 * @param fp File pointer. May be at any offset. Not closed on return.
639 * @param err Optional error code pointer.
640 * @return A new plugin structure.
642 virtual sp_plugin_t *LoadFromFilePointer(FILE *fp, int *err) =0;
645 * @brief Loads a file from a base memory address.
647 * @param base Base address of the plugin's memory region.
648 * @param plugin If NULL, a new plugin pointer is returned.
649 * Otherwise, the passed pointer is used.
650 * @param err Optional error code pointer.
651 * @return The resulting plugin pointer.
653 virtual sp_plugin_t *LoadFromMemory(void *base, sp_plugin_t *plugin, int *err) =0;
656 * Frees all of the memory associated with a plugin file.
657 * If allocated using SP_LoadFromMemory, the base and plugin pointer
658 * itself are not freed (so this may end up doing nothing).
660 virtual int FreeFromMemory(sp_plugin_t *plugin) =0;
663 * @brief Allocates large blocks of temporary memory.
665 * @param size Size of memory to allocate.
666 * @return Pointer to memory, NULL if allocation failed.
668 virtual void *BaseAlloc(size_t size) =0;
671 * @brief Frees memory allocated with BaseAlloc.
673 * @param memory Memory address to free.
675 virtual void BaseFree(void *memory) =0;
678 * @brief Allocates executable memory.
680 * @param size Size of memory to allocate.
681 * @return Pointer to memory, NULL if allocation failed.
683 virtual void *ExecAlloc(size_t size) =0;
686 * @brief Frees executable memory.
688 * @param address Address to free.
690 virtual void ExecFree(void *address) =0;
693 * @brief Sets the debug listener. This should only be called once.
694 * If called successively (using manual chaining), only the last function should
695 * attempt to call back into the same plugin. Otherwise, globally cached states
696 * can be accidentally overwritten.
698 * @param listener Pointer to an IDebugListener.
699 * @return Old IDebugListener, or NULL if none.
701 virtual IDebugListener *SetDebugListener(IDebugListener *listener) =0;
704 * @brief Returns the number of plugins on the call stack.
706 * @return Number of contexts in the call stack.
708 virtual unsigned int GetContextCallCount() =0;
713 * @brief Dummy class for encapsulating private compilation data.
718 /** Virtual destructor */
719 virtual ~ICompilation() { };
724 * @brief Outlines the interface a Virtual Machine (JIT) must expose
726 class IVirtualMachine
730 * @brief Returns the current API version.
732 virtual unsigned int GetAPIVersion() =0;
735 * @brief Returns the string name of a VM implementation.
737 virtual const char *GetVMName() =0;
740 * @brief Begins a new compilation
742 * @param plugin Pointer to a plugin structure.
743 * @return New compilation pointer.
745 virtual ICompilation *StartCompilation(sp_plugin_t *plugin) =0;
748 * @brief Sets a compilation option.
750 * @param co Pointer to a compilation.
751 * @param key Option key name.
752 * @param val Option value string.
753 * @return True if option could be set, false otherwise.
755 virtual bool SetCompilationOption(ICompilation *co, const char *key, const char *val) =0;
758 * @brief Finalizes a compilation into a new sp_context_t.
759 * Note: This will free the ICompilation pointer.
761 * @param co Compilation pointer.
762 * @param err Filled with error code on exit.
763 * @return New plugin context.
765 virtual sp_context_t *CompileToContext(ICompilation *co, int *err) =0;
768 * @brief Aborts a compilation and frees the ICompilation pointer.
770 * @param co Compilation pointer.
772 virtual void AbortCompilation(ICompilation *co) =0;
775 * @brief Frees any internal variable usage on a context.
777 * @param ctx Context structure pointer.
779 virtual void FreeContext(sp_context_t *ctx) =0;
782 * @brief Calls the "execute" function on a context.
784 * @param ctx Executes a function in a context.
785 * @param code_addr Index into the code section.
786 * @param result Pointer to store result into.
787 * @return Error code (if any).
789 virtual int ContextExecute(sp_context_t *ctx, uint32_t code_addr, cell_t *result) =0;
792 * @brief Given a context and a code address, returns the index of the function.
794 * @param ctx Context to search.
795 * @param code_addr Index into the code section.
796 * @param result Pointer to store result into.
797 * @return True if code index is valid, false otherwise.
799 virtual bool FunctionLookup(const sp_context_t *ctx, uint32_t code_addr, unsigned int *result) =0;
802 * @brief Returns the number of functions defined in the context.
804 * @param ctx Context to search.
805 * @return Number of functions.
807 virtual unsigned int FunctionCount(const sp_context_t *ctx) =0;
810 * @brief Returns a version string.
812 * @return Versioning string.
814 virtual const char *GetVersionString() =0;
817 * @brief Returns a string describing optimizations.
819 * @return String describing CPU specific optimizations.
821 virtual const char *GetCPUOptimizations() =0;
824 * @brief Given a context and a p-code address, returns the index of the function.
826 * @param ctx Context to search.
827 * @param code_addr Index into the p-code section.
828 * @param result Pointer to store result into.
829 * @return True if code index is valid, false otherwise.
831 virtual bool FunctionPLookup(const sp_context_t *ctx, uint32_t code_addr, unsigned int *result) =0;
835 #endif //_INCLUDE_SOURCEPAWN_VM_API_H_
