SourcePawn::IPluginContext

SourcePawn::IPluginContext Class Reference

Interface to managing a context at runtime. More...

#include <public/sourcepawn/sp_vm_api.h>

List of all members.

Public Member Functions

virtual ~IPluginContext ()
virtual IVirtualMachine * GetVirtualMachine ()=0
 Deprecated, does nothing.
virtual sp_context_t * GetContext ()=0
 Deprecated, do not use.
virtual bool IsDebugging ()=0
 Returns true if the plugin is in debug mode.
virtual int SetDebugBreak (void *newpfn, void *oldpfn)=0
 Deprecated, does nothing.
virtual IPluginDebugInfo * GetDebugInfo ()=0
 Deprecated, do not use.
virtual int HeapAlloc (unsigned int cells, cell_t *local_addr, cell_t **phys_addr)=0
 Allocates 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
 Deprecated, use IPluginRuntime instead.
virtual int GetNativeByIndex (uint32_t index, sp_native_t **native)=0
 Deprecated, use IPluginRuntime instead.
virtual uint32_t GetNativesNum ()=0
 Deprecated, use IPluginRuntime instead.
virtual int FindPublicByName (const char *name, uint32_t *index)=0
 Deprecated, use IPluginRuntime instead.
virtual int GetPublicByIndex (uint32_t index, sp_public_t **publicptr)=0
 Deprecated, use IPluginRuntime instead.
virtual uint32_t GetPublicsNum ()=0
 Deprecated, use IPluginRuntime instead.
virtual int GetPubvarByIndex (uint32_t index, sp_pubvar_t **pubvar)=0
 Deprecated, use IPluginRuntime instead.
virtual int FindPubvarByName (const char *name, uint32_t *index)=0
 Deprecated, use IPluginRuntime instead.
virtual int GetPubvarAddrs (uint32_t index, cell_t *local_addr, cell_t **phys_addr)=0
 Deprecated, use IPluginRuntime instead.
virtual uint32_t GetPubVarsNum ()=0
 Deprecated, use IPluginRuntime instead.
virtual int LocalToPhysAddr (cell_t local_addr, cell_t **phys_addr)=0
 Converts 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
 Deprecated, does nothing.
virtual int PushCellArray (cell_t *local_addr, cell_t **phys_addr, cell_t array[], unsigned int numcells)=0
 Deprecated, does nothing.
virtual int PushString (cell_t *local_addr, char **phys_addr, const char *string)=0
 Deprecated, does nothing.
virtual int PushCellsFromArray (cell_t array[], unsigned int numcells)=0
 Deprecated, does nothing.
virtual int BindNatives (const sp_nativeinfo_t *natives, unsigned int num, int overwrite)=0
 Deprecated, does nothing.
virtual int BindNative (const sp_nativeinfo_t *native)=0
 Deprecated, does nothing.
virtual int BindNativeToAny (SPVM_NATIVE_FUNC native)=0
 Deprecated, does nothing.
virtual int Execute (uint32_t code_addr, cell_t *result)=0
 Deprecated, does nothing.
virtual cell_t 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.
virtual IPluginFunction * GetFunctionByName (const char *public_name)=0
 Returns a function by name.
virtual IPluginFunction * GetFunctionById (funcid_t func_id)=0
 Returns a function by its id.
virtual SourceMod::IdentityToken_t * GetIdentity ()=0
 Returns the identity token for this context.
virtual cell_t * GetNullRef (SP_NULL_TYPE type)=0
 Returns a NULL reference based on one of the available NULL reference types.
virtual int LocalToStringNULL (cell_t local_addr, char **addr)=0
 Converts a local address to a physical string, and allows for NULL_STRING to be set.
virtual int BindNativeToIndex (uint32_t index, SPVM_NATIVE_FUNC native)=0
 Deprecated; do not use.
virtual bool IsInExec ()=0
 Returns if there is currently an execution in progress.
virtual IPluginRuntime * GetRuntime ()=0
 Returns the parent runtime of a context.
virtual int Execute2 (IPluginFunction *function, const cell_t *params, unsigned int num_params, cell_t *result)=0
 Executes a function in the context. The function must be a member of the context's parent runtime.
virtual int GetLastNativeError ()=0
 Returns whether a context is in an error state.
virtual cell_t * GetLocalParams ()=0
 Returns the local parameter stack, starting from the cell that contains the number of parameters passed.
virtual void SetKey (int k, void *value)=0
 Sets a local "key" that can be used for fast lookup.
virtual bool GetKey (int k, void **value)=0
 Retrieves a previously set "key.".

Detailed Description

Interface to managing a context at runtime.

Definition at line 481 of file sp_vm_api.h.

Constructor & Destructor Documentation

virtual SourcePawn::IPluginContext::~IPluginContext (  )  [inline, virtual]

Virtual destructor

Definition at line 485 of file sp_vm_api.h.

Member Function Documentation

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

Deprecated, does nothing.

Returns:
NULL.

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

Deprecated, do not use.

Returns the pointer of this object, casted to an opaque structure.

Returns:
Returns this.

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 ( void *  newpfn,
void *  oldpfn 
) [pure virtual]

Deprecated, does nothing.

Parameters:
newpfn Unused.
oldpfn Unused.

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

Deprecated, do not use.

Returns:
NULL.

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

Allocates 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]

Deprecated, use IPluginRuntime instead.

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]

Deprecated, use IPluginRuntime instead.

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

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

Deprecated, use IPluginRuntime instead.

Returns:
Filled with the number of natives.

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

Deprecated, use IPluginRuntime instead.

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]

Deprecated, use IPluginRuntime instead.

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

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

Deprecated, use IPluginRuntime instead.

Returns:
Filled with the number of public functions.

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

Deprecated, use IPluginRuntime instead.

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]

Deprecated, use IPluginRuntime instead.

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]

Deprecated, use IPluginRuntime instead.

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]

Deprecated, use IPluginRuntime instead.

Returns:
Number of public variables.

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

Converts 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]

Deprecated, does nothing.

Parameters:
value Unused.

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

Deprecated, does nothing.

Parameters:
local_addr Unused.
phys_addr Unused.
array Unused.
numcells Unused.

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

Deprecated, does nothing.

Parameters:
local_addr Unused.
phys_addr Unused.
string Unused.

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

Deprecated, does nothing.

Parameters:
array Unused.
numcells Unused.

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

Deprecated, does nothing.

Parameters:
natives Deprecated; do not use.
num Deprecated; do not use.
overwrite Deprecated; do not use.

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

Deprecated, does nothing.

Parameters:
native Deprecated; do not use.

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

Deprecated, does nothing.

Parameters:
native Unused.

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

Deprecated, does nothing.

Parameters:
code_addr Unused.
result Unused.
Returns:
SP_ERROR_ABORTED.

virtual cell_t 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.
Returns:
0 for convenience.

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.

virtual IPluginFunction* SourcePawn::IPluginContext::GetFunctionByName ( const char *  public_name  )  [pure virtual]

Returns a function by name.

Parameters:
public_name Name of the function.
Returns:
A new IPluginFunction pointer, NULL if not found.

virtual IPluginFunction* SourcePawn::IPluginContext::GetFunctionById ( funcid_t  func_id  )  [pure virtual]

Returns a function by its id.

Parameters:
func_id Function ID.
Returns:
A new IPluginFunction pointer, NULL if not found.

virtual SourceMod::IdentityToken_t* SourcePawn::IPluginContext::GetIdentity (  )  [pure virtual]

Returns the identity token for this context.

Note: This is a compatibility shim and is the same as GetKey(1).

Returns:
Identity token.

virtual cell_t* SourcePawn::IPluginContext::GetNullRef ( SP_NULL_TYPE  type  )  [pure virtual]

Returns a NULL reference based on one of the available NULL reference types.

Parameters:
type NULL reference type.
Returns:
cell_t address to compare to.

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

Converts a local address to a physical string, and allows for NULL_STRING to be set.

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

virtual int SourcePawn::IPluginContext::BindNativeToIndex ( uint32_t  index,
SPVM_NATIVE_FUNC  native 
) [pure virtual]

Deprecated; do not use.

Parameters:
index Deprecated; do not use.
native Deprecated; do not use.

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

Returns if there is currently an execution in progress.

Returns:
True if in exec, false otherwise.

virtual IPluginRuntime* SourcePawn::IPluginContext::GetRuntime (  )  [pure virtual]

Returns the parent runtime of a context.

Returns:
Parent runtime.

virtual int SourcePawn::IPluginContext::Execute2 ( IPluginFunction *  function,
const cell_t *  params,
unsigned int  num_params,
cell_t *  result 
) [pure virtual]

Executes a function in the context. The function must be a member of the context's parent runtime.

Parameters:
function Function.
params Parameters.
num_params Number of parameters in the parameter array.
result Optional pointer to store the result on success.
Returns:
Error code.

virtual int SourcePawn::IPluginContext::GetLastNativeError (  )  [pure virtual]

Returns whether a context is in an error state.

This should only be used inside natives to determine whether a prior call failed.

virtual cell_t* SourcePawn::IPluginContext::GetLocalParams (  )  [pure virtual]

Returns the local parameter stack, starting from the cell that contains the number of parameters passed.

Local parameters are the parameters passed to the function from which a native was called (and thus this can only be called inside a native).

Returns:
Parameter stack.

virtual void SourcePawn::IPluginContext::SetKey ( int  k,
void *  value 
) [pure virtual]

Sets a local "key" that can be used for fast lookup.

Only the "owner" of the context should be setting this.

Parameters:
key Key number (values allowed: 1 through 4).
value Pointer value.

virtual bool SourcePawn::IPluginContext::GetKey ( int  k,
void **  value 
) [pure virtual]

Retrieves a previously set "key.".

Parameters:
key Key number (values allowed: 1 through 4).
value Pointer to store value.
Returns:
True on success, false on failure.

The documentation for this class was generated from the following file:
Generated on Fri Nov 21 03:10:07 2008 for SourceMod SDK by  doxygen 1.5.1