275 lines
9.2 KiB
C
275 lines
9.2 KiB
C
#ifndef _INCLUDE_SOURCEPAWN_VM_H_
|
|
#define _INCLUDE_SOURCEPAWN_VM_H_
|
|
|
|
#include <stdio.h>
|
|
#include "sp_vm_types.h"
|
|
|
|
/*****************
|
|
** Note that all functions return a non-zero error code on failure
|
|
* unless otherwise noted.
|
|
* All input pointers must be valid unless otherwise noted as optional.
|
|
* All local address are guaranteed to be positive. However, they are stored
|
|
* as signed integers, because they must logically fit inside a cell.
|
|
*/
|
|
|
|
typedef struct sp_nativeinfo_s
|
|
{
|
|
const char *name;
|
|
SPVM_NATIVE_FUNC func;
|
|
} sp_nativeinfo_t;
|
|
|
|
/**
|
|
* Loads a named file from a file pointer.
|
|
* Using this means base memory will be allocated by the VM.
|
|
*
|
|
* @param fp File pointer. May be at any offset. Not closed on return.
|
|
* @param err Optional error code pointer.
|
|
* @return A new plugin structure.
|
|
*/
|
|
sp_plugin_t *SP_LoadFromFilePointer(FILE *fp, int *err);
|
|
|
|
/**
|
|
* Loads a file from a base memory address.
|
|
*
|
|
* @param base Base address of the plugin's memory region.
|
|
* @param plugin If NULL, a new plugin pointer is returned.
|
|
* Otherwise, the passed pointer is used.
|
|
* @param err Optional error code pointer.
|
|
* @return The resulting plugin pointer.
|
|
*/
|
|
sp_plugin_t *SP_LoadFromMemory(void *base, sp_plugin_t *plugin, int *err);
|
|
|
|
/**
|
|
* Frees all of the memory associated with a plugin file.
|
|
* If allocated using SP_LoadFromMemory, the base and plugin pointer
|
|
* itself are not freed (so this may end up doing nothing).
|
|
*/
|
|
int SP_FreeFromMemory(sp_plugin_t *plugin);
|
|
|
|
/**
|
|
* Allocs memory on the secondary stack of a plugin.
|
|
* Note that although called a heap, it is in fact a stack.
|
|
*
|
|
* @param ctx Context pointer.
|
|
* @param cells Number of cells to allocate.
|
|
* @param local_adddr Will be filled with data offset to heap.
|
|
* @param phys_addr Physical address to heap memory.
|
|
*/
|
|
int SP_HeapAlloc(sp_context_t *ctx, unsigned int cells, cell_t *local_addr, cell_t **phys_addr);
|
|
|
|
/**
|
|
* Pops a heap address off the heap stack. Use this to free memory allocated with
|
|
* SP_HeapAlloc().
|
|
* Note that in SourcePawn, the heap is in fact a bottom-up stack. Deallocations
|
|
* with this native should be performed in precisely the REVERSE order.
|
|
*/
|
|
int SP_HeapPop(sp_context_t *ctx, cell_t local_addr);
|
|
|
|
/**
|
|
* Releases a heap address using a different method than SP_HeapPop().
|
|
* This allows you to release in any order. However, if you allocate N
|
|
* objects, release only some of them, then begin allocating again,
|
|
* you cannot go back and starting freeing the originals.
|
|
* In other words, for each chain of allocations, if you start deallocating,
|
|
* then allocating more in a chain, you must only deallocate from the current
|
|
* allocation chain. This is basically SP_HeapPop() except on a larger scale.
|
|
*/
|
|
int SP_HeapRelease(sp_context_t *ctx, cell_t local_addr);
|
|
|
|
/**
|
|
* Finds a native by name.
|
|
*
|
|
* @param ctx Context pointer.
|
|
* @param name Name of native.
|
|
* @param index Optionally filled with native index number.
|
|
*/
|
|
int SP_FindNativeByName(sp_context_t *ctx, const char *name, uint32_t *index);
|
|
|
|
/**
|
|
* Gets native info by index.
|
|
*
|
|
* @param ctx Context pointer.
|
|
* @param index Index number of native.
|
|
* @param native Optionally filled with pointer to native structure.
|
|
*/
|
|
int SP_GetNativeByIndex(sp_context_t *ctx, uint32_t index, sp_native_t **native);
|
|
|
|
/**
|
|
* Gets the number of natives.
|
|
*
|
|
* @param ctx Context pointer.
|
|
* @param num Filled with the number of natives.
|
|
*/
|
|
int SP_GetNativesNum(sp_context_t *ctx, uint32_t *num);
|
|
|
|
/**
|
|
* Finds a public function by name.
|
|
*
|
|
* @param ctx Context pointer.
|
|
* @param name Name of public
|
|
* @param index Optionally filled with public index number.
|
|
*/
|
|
int SP_FindPublicByName(sp_context_t *ctx, const char *name, uint32_t *index);
|
|
|
|
|
|
/**
|
|
* Gets public function info by index.
|
|
*
|
|
* @param ctx Context pointer.
|
|
* @param index Public function index number.
|
|
* @param pblic Optionally filled with pointer to public structure.
|
|
*/
|
|
int SP_GetPublicByIndex(sp_context_t *ctx, uint32_t index, sp_public_t **pblic);
|
|
|
|
/**
|
|
* Gets the number of public functions.
|
|
*
|
|
* @param ctx Context pointer.
|
|
* @param num Filled with the number of public functions.
|
|
*/
|
|
int SP_GetPublicsNum(sp_context_t *ctx, uint32_t *num);
|
|
|
|
/**
|
|
* Gets public variable info by index.
|
|
* @param ctx Context pointer.
|
|
* @param index Public variable index number.
|
|
* @param pubvar Optionally filled with pointer to pubvar structure.
|
|
*/
|
|
int SP_GetPubvarByIndex(sp_context_t *ctx, uint32_t index, sp_pubvar_t **pubvar);
|
|
|
|
/**
|
|
* Finds a public variable by name.
|
|
*
|
|
* @param ctx Context pointer.
|
|
* @param name Name of pubvar
|
|
* @param index Optionally filled with pubvar index number.
|
|
* @param local_addr Optionally filled with local address offset.
|
|
* @param phys_addr Optionally filled with relocated physical address.
|
|
*/
|
|
int SP_FindPubvarByName(sp_context_t *ctx,
|
|
const char *name,
|
|
uint32_t *index,
|
|
cell_t *local_addr,
|
|
cell_t **phys_addr);
|
|
|
|
/**
|
|
* Round-about method of converting a plugin reference to a physical address
|
|
*
|
|
* @param ctx Context pointer.
|
|
* @param local_addr Local address in plugin.
|
|
* @param phys_addr Optionally filled with relocated physical address.
|
|
*/
|
|
int SP_LocalToPhysAddr(sp_context_t *ctx, cell_t local_addr, cell_t **phys_addr);
|
|
|
|
/**
|
|
* Convers a local address to a physical string.
|
|
* Note that SourcePawn does not support packed strings, as such this function is
|
|
* 'cell to char' only.
|
|
*
|
|
* @param ctx Context pointer.
|
|
* @param local_addr Local address in plugin.
|
|
* @param chars Optionally filled with the number of characters written.
|
|
* @param buffer Destination output buffer.
|
|
* @param maxlength Maximum length of output buffer, including null terminator.
|
|
*/
|
|
int SP_LocalToString(sp_context_t *ctx,
|
|
cell_t local_addr,
|
|
int *chars,
|
|
char *buffer,
|
|
size_t maxlength);
|
|
|
|
/**
|
|
* Pushes a cell onto the stack. Increases the parameter count by one.
|
|
*
|
|
* @param ctx Context pointer.
|
|
* @param value Cell value.
|
|
*/
|
|
int SP_PushCell(sp_context_t *ctx, cell_t value);
|
|
|
|
/**
|
|
* Pushes an array of cells onto the stack. Increases the parameter count by one.
|
|
* Note that this does not release the heap, so you should release it after
|
|
* calling SP_Execute().
|
|
*
|
|
* @param ctx Context pointer.
|
|
* @param local_addr Filled with local address to release.
|
|
* @param phys_addr Optionally filled with physical address of new array.
|
|
* @param array Cell array to copy.
|
|
* @param numcells Number of cells in the array to copy.
|
|
*/
|
|
int SP_PushCellArray(sp_context_t *ctx,
|
|
cell_t *local_addr,
|
|
cell_t **phys_addr,
|
|
cell_t array[],
|
|
unsigned int numcells);
|
|
|
|
/**
|
|
* Pushes a string onto the stack (by reference) and increases the parameter count by one.
|
|
* Note that this does not release the heap, so you should release it after
|
|
* calling SP_Execute().
|
|
*
|
|
* @param ctx Context pointer.
|
|
* @param local_addr Filled with local address to release.
|
|
* @param phys_addr Optionally filled with physical address of new array.
|
|
* @param array Cell array to copy.
|
|
* @param numcells Number of cells in the array to copy.
|
|
*/
|
|
int SP_PushString(sp_context_t *ctx,
|
|
cell_t *local_addr,
|
|
cell_t **phys_addr,
|
|
const char *string);
|
|
|
|
/**
|
|
* Individually pushes each cell of an array of cells onto the stack. Increases the
|
|
* parameter count by the number of cells pushed.
|
|
*
|
|
* @param ctx Context pointer.
|
|
* @param array Array of cells to read from.
|
|
* @param numcells Number of cells to read.
|
|
*/
|
|
int SP_PushCellsFromArray(sp_context_t *ctx, cell_t array[], unsigned int numcells);
|
|
|
|
/**
|
|
* Binds a list of native names and their function pointers to a context.
|
|
* If num is 0, the list is read until an entry with a NULL name is reached.
|
|
* All natives are assigned a status of SP_NATIVE_OKAY by default.
|
|
* If overwrite is non-zero, already registered arrays will be overwritten.
|
|
*
|
|
* @param ctx Context pointer.
|
|
* @param natives Array of natives.
|
|
* @param num Number of natives in array.
|
|
*/
|
|
int SP_BindNatives(sp_context_t *ctx, sp_nativeinfo_t *natives, unsigned int num, int overwrite);
|
|
|
|
/**
|
|
* Binds a single native. Overwrites any existing bind.
|
|
*
|
|
* @param ctx Context pointer.
|
|
* @param native Pointer to native.
|
|
* @param status Status value to set (should be SP_NATIVE_OKAY).
|
|
*/
|
|
int SP_BindNative(sp_context_t *ctx, sp_nativeinfo_t *native, uint32_t status);
|
|
|
|
/**
|
|
* Binds a single native to any non-registered native.
|
|
* Status is automatically set to pending.
|
|
*
|
|
* @param ctx Context pointer.
|
|
*/
|
|
int SP_BindNativeToAny(sp_context_t *ctx, sp_nativeinfo_t *native);
|
|
|
|
/**
|
|
* Executes a public function in a context.
|
|
* The parameter count is set to zero during execution.
|
|
* All context-specific variables that are modified are saved before execution,
|
|
* thus allowing nested calls to SP_Execute().
|
|
*
|
|
* @param ctx Context pointer.
|
|
* @param idx Public function index number.
|
|
* @param result Optional pointer to store return value.
|
|
*/
|
|
int SP_Execute(sp_context_t *ctx, uint32_t idx, cell_t *result);
|
|
|
|
|
|
#endif //_INCLUDE_SOURCEPAWN_VM_H_
|