SourcePawn::IPluginContext

SourcePawn::IPluginContext Class Reference

#include <sp_vm_api.h>

List of all members.

Detailed Description

Interface to managing a context at runtime.

Definition at line 54 of file sp_vm_api.h.

Public Member Functions

virtual ~IPluginContext ()
virtual IVirtualMachine * GetVirtualMachine ()=0
 Returns the parent IVirtualMachine.
virtual sp_context_t * GetContext ()=0
 Returns the child sp_context_t structure.
virtual bool IsDebugging ()=0
 Returns true if the plugin is in debug mode.
virtual int SetDebugBreak (SPVM_DEBUGBREAK newpfn, SPVM_DEBUGBREAK *oldpfn)=0
 Installs a debug break and returns the old one, if any. This will fail if the plugin is not debugging.
virtual IPluginDebugInfo * GetDebugInfo ()=0
 Returns debug info.
virtual int HeapAlloc (unsigned int cells, cell_t *local_addr, cell_t **phys_addr)=0
 Allocs memory on the secondary stack of a plugin. Note that although called a heap, it is in fact a stack.
virtual int HeapPop (cell_t local_addr)=0
 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.
virtual int HeapRelease (cell_t local_addr)=0
 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 HeapPop() except on a larger scale.
virtual int FindNativeByName (const char *name, uint32_t *index)=0
 Finds a native by name.
virtual int GetNativeByIndex (uint32_t index, sp_native_t **native)=0
 Gets native info by index.
virtual uint32_t GetNativesNum ()=0
 Gets the number of natives.
virtual int FindPublicByName (const char *name, uint32_t *index)=0
 Finds a public function by name.
virtual int GetPublicByIndex (uint32_t index, sp_public_t **publicptr)=0
 Gets public function info by index.
virtual uint32_t GetPublicsNum ()=0
 Gets the number of public functions.
virtual int GetPubvarByIndex (uint32_t index, sp_pubvar_t **pubvar)=0
 Gets public variable info by index.
virtual int FindPubvarByName (const char *name, uint32_t *index)=0
 Finds a public variable by name.
virtual int GetPubvarAddrs (uint32_t index, cell_t *local_addr, cell_t **phys_addr)=0
 Gets the addresses of a public variable.
virtual uint32_t GetPubVarsNum ()=0
 Returns the number of public variables.
virtual int LocalToPhysAddr (cell_t local_addr, cell_t **phys_addr)=0
 Round-about method of converting a plugin reference to a physical address.
virtual int LocalToString (cell_t local_addr, char **addr)=0
 Converts a local address to a physical string.
virtual int StringToLocal (cell_t local_addr, size_t bytes, const char *source)=0
 Converts a physical string to a local address.
virtual int StringToLocalUTF8 (cell_t local_addr, size_t maxbytes, const char *source, size_t *wrtnbytes)=0
 Converts a physical UTF-8 string to a local address. This function is the same as the ANSI version, except it will copy the maximum number of characters possible without accidentally chopping a multi-byte character.
virtual int PushCell (cell_t value)=0
 Pushes a cell onto the stack. Increases the parameter count by one.
virtual int PushCellArray (cell_t *local_addr, cell_t **phys_addr, cell_t array[], unsigned int numcells)=0
 Pushes an array of cells onto the stack. Increases the parameter count by one. If the function returns an error it will fail entirely, releasing anything allocated in the process. Note that this does not release the heap, so you should release it after calling Execute().
virtual int PushString (cell_t *local_addr, char **phys_addr, const char *string)=0
 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 Execute().
virtual int PushCellsFromArray (cell_t array[], unsigned int numcells)=0
 Individually pushes each cell of an array of cells onto the stack. Increases the parameter count by the number of cells pushed. If the function returns an error it will fail entirely, releasing anything allocated in the process.
virtual int BindNatives (sp_nativeinfo_t *natives, unsigned int num, int overwrite)=0
 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. If overwrite is non-zero, already registered natives will be overwritten.
virtual int BindNative (sp_nativeinfo_t *native)=0
 Binds a single native. Overwrites any existing bind. If the context does not contain the native that will be binded the function will return with a SP_ERROR_NOT_FOUND error.
virtual int BindNativeToAny (SPVM_NATIVE_FUNC native)=0
 Binds a single native to any non-registered native.
virtual int Execute (uint32_t funcid, cell_t *result)=0
 Executes a function ID located in this context.
virtual void ThrowNativeErrorEx (int error, const char *msg,...)=0
 Throws a error and halts any current execution.
virtual cell_t ThrowNativeError (const char *msg,...)=0
 Throws a generic native error and halts any current execution.

Member Function Documentation

virtual IVirtualMachine* SourcePawn::IPluginContext::GetVirtualMachine (  )  [pure virtual]

Returns the parent IVirtualMachine.

Returns:
Parent virtual machine pointer.

virtual sp_context_t* SourcePawn::IPluginContext::GetContext (  )  [pure virtual]

Returns the child sp_context_t structure.

Returns:
Child sp_context_t structure.

virtual bool SourcePawn::IPluginContext::IsDebugging (  )  [pure virtual]

Returns true if the plugin is in debug mode.

Returns:
True if in debug mode, false otherwise.

virtual int SourcePawn::IPluginContext::SetDebugBreak ( SPVM_DEBUGBREAK  newpfn,
SPVM_DEBUGBREAK *  oldpfn 
) [pure virtual]

Installs a debug break and returns the old one, if any. This will fail if the plugin is not debugging.

Parameters:
newpfn New function pointer.
oldpfn Pointer to retrieve old function pointer.

virtual IPluginDebugInfo* SourcePawn::IPluginContext::GetDebugInfo (  )  [pure virtual]

Returns debug info.

Returns:
IPluginDebugInfo, or NULL if no debug info found.

virtual int SourcePawn::IPluginContext::HeapAlloc ( unsigned int  cells,
cell_t *  local_addr,
cell_t **  phys_addr 
) [pure virtual]

Allocs memory on the secondary stack of a plugin. Note that although called a heap, it is in fact a stack.

Parameters:
cells Number of cells to allocate.
local_addr Will be filled with data offset to heap.
phys_addr Physical address to heap memory.

virtual int SourcePawn::IPluginContext::HeapPop ( cell_t  local_addr  )  [pure virtual]

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.

Parameters:
local_addr Local address to free.

virtual int SourcePawn::IPluginContext::HeapRelease ( cell_t  local_addr  )  [pure virtual]

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 HeapPop() except on a larger scale.

Parameters:
local_addr Local address to free.

virtual int SourcePawn::IPluginContext::FindNativeByName ( const char *  name,
uint32_t *  index 
) [pure virtual]

Finds a native by name.

Parameters:
name Name of native.
index Optionally filled with native index number.

virtual int SourcePawn::IPluginContext::GetNativeByIndex ( uint32_t  index,
sp_native_t **  native 
) [pure virtual]

Gets native info by index.

Parameters:
index Index number of native.
native Optionally filled with pointer to native structure.

virtual uint32_t SourcePawn::IPluginContext::GetNativesNum (  )  [pure virtual]

Gets the number of natives.

Returns:
Filled with the number of natives.

virtual int SourcePawn::IPluginContext::FindPublicByName ( const char *  name,
uint32_t *  index 
) [pure virtual]

Finds a public function by name.

Parameters:
name Name of public
index Optionally filled with public index number.

virtual int SourcePawn::IPluginContext::GetPublicByIndex ( uint32_t  index,
sp_public_t **  publicptr 
) [pure virtual]

Gets public function info by index.

Parameters:
index Public function index number.
publicptr Optionally filled with pointer to public structure.

virtual uint32_t SourcePawn::IPluginContext::GetPublicsNum (  )  [pure virtual]

Gets the number of public functions.

Returns:
Filled with the number of public functions.

virtual int SourcePawn::IPluginContext::GetPubvarByIndex ( uint32_t  index,
sp_pubvar_t **  pubvar 
) [pure virtual]

Gets public variable info by index.

Parameters:
index Public variable index number.
pubvar Optionally filled with pointer to pubvar structure.

virtual int SourcePawn::IPluginContext::FindPubvarByName ( const char *  name,
uint32_t *  index 
) [pure virtual]

Finds a public variable by name.

Parameters:
name Name of pubvar
index Optionally filled with pubvar index number.

virtual int SourcePawn::IPluginContext::GetPubvarAddrs ( uint32_t  index,
cell_t *  local_addr,
cell_t **  phys_addr 
) [pure virtual]

Gets the addresses of a public variable.

Parameters:
index Index of public variable.
local_addr Address to store local address in.
phys_addr Address to store physically relocated in.

virtual uint32_t SourcePawn::IPluginContext::GetPubVarsNum (  )  [pure virtual]

Returns the number of public variables.

Returns:
Number of public variables.

virtual int SourcePawn::IPluginContext::LocalToPhysAddr ( cell_t  local_addr,
cell_t **  phys_addr 
) [pure virtual]

Round-about method of converting a plugin reference to a physical address.

Parameters:
local_addr Local address in plugin.
phys_addr Optionally filled with relocated physical address.

virtual int SourcePawn::IPluginContext::LocalToString ( cell_t  local_addr,
char **  addr 
) [pure virtual]

Converts a local address to a physical string.

Parameters:
local_addr Local address in plugin.
addr Destination output pointer.

virtual int SourcePawn::IPluginContext::StringToLocal ( cell_t  local_addr,
size_t  bytes,
const char *  source 
) [pure virtual]

Converts a physical string to a local address.

Parameters:
local_addr Local address in plugin.
bytes Number of chars to write, including NULL terminator.
source Source string to copy.

virtual int SourcePawn::IPluginContext::StringToLocalUTF8 ( cell_t  local_addr,
size_t  maxbytes,
const char *  source,
size_t *  wrtnbytes 
) [pure virtual]

Converts a physical UTF-8 string to a local address. This function is the same as the ANSI version, except it will copy the maximum number of characters possible without accidentally chopping a multi-byte character.

Parameters:
local_addr Local address in plugin.
maxbytes Number of bytes to write, including NULL terminator.
source Source string to copy.
wrtnbytes Optionally set to the number of actual bytes written.

virtual int SourcePawn::IPluginContext::PushCell ( cell_t  value  )  [pure virtual]

Pushes a cell onto the stack. Increases the parameter count by one.

Parameters:
value Cell value.

virtual int SourcePawn::IPluginContext::PushCellArray ( cell_t *  local_addr,
cell_t **  phys_addr,
cell_t  array[],
unsigned int  numcells 
) [pure virtual]

Pushes an array of cells onto the stack. Increases the parameter count by one. If the function returns an error it will fail entirely, releasing anything allocated in the process. Note that this does not release the heap, so you should release it after calling Execute().

Parameters:
local_addr Filled with local address to release.
phys_addr Optionally filled with physical address of new array.
array Cell array to copy.
numcells Number of cells in the array to copy.

virtual int SourcePawn::IPluginContext::PushString ( cell_t *  local_addr,
char **  phys_addr,
const char *  string 
) [pure virtual]

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 Execute().

Parameters:
local_addr Filled with local address to release.
phys_addr Optionally filled with physical address of new array.
string Source string to push.

virtual int SourcePawn::IPluginContext::PushCellsFromArray ( cell_t  array[],
unsigned int  numcells 
) [pure virtual]

Individually pushes each cell of an array of cells onto the stack. Increases the parameter count by the number of cells pushed. If the function returns an error it will fail entirely, releasing anything allocated in the process.

Parameters:
array Array of cells to read from.
numcells Number of cells to read.

virtual int SourcePawn::IPluginContext::BindNatives ( sp_nativeinfo_t *  natives,
unsigned int  num,
int  overwrite 
) [pure virtual]

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. If overwrite is non-zero, already registered natives will be overwritten.

Parameters:
natives Array of natives.
num Number of natives in array.
overwrite Toggles overwrite.

virtual int SourcePawn::IPluginContext::BindNative ( sp_nativeinfo_t *  native  )  [pure virtual]

Binds a single native. Overwrites any existing bind. If the context does not contain the native that will be binded the function will return with a SP_ERROR_NOT_FOUND error.

Parameters:
native Pointer to native.

virtual int SourcePawn::IPluginContext::BindNativeToAny ( SPVM_NATIVE_FUNC  native  )  [pure virtual]

Binds a single native to any non-registered native.

Parameters:
native Native to bind.

virtual int SourcePawn::IPluginContext::Execute ( uint32_t  funcid,
cell_t *  result 
) [pure virtual]

Executes a function ID located in this context.

Parameters:
funcid Function id to execute.
result Pointer to store the return value (required).
Returns:
Error code (if any) from the VM.

virtual void SourcePawn::IPluginContext::ThrowNativeErrorEx ( int  error,
const char *  msg,
  ... 
) [pure virtual]

Throws a error and halts any current execution.

Parameters:
error The error number to set.
msg Custom error message format. NULL to use default.
... Message format arguments, if any.

virtual cell_t SourcePawn::IPluginContext::ThrowNativeError ( const char *  msg,
  ... 
) [pure virtual]

Throws a generic native error and halts any current execution.

Parameters:
msg Custom error message format. NULL to set no message.
... Message format arguments, if any.
Returns:
0 for convenience.

The documentation for this class was generated from the following file:
Generated on Thu Jan 4 13:34:37 2007 for SourcePawn JIT by  doxygen 1.5.1-p1