1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/core/interfaces/IPluginFunction.h Sat Nov 11 11:10:24 2006 +0000
1.3 @@ -0,0 +1,177 @@
1.4 +#ifndef _INCLUDE_SOURCEMOD_PLUGINFUNCTION_INTERFACE_H_
1.5 +#define _INCLUDE_SOURCEMOD_PLUGINFUNCTION_INTERFACE_H_
1.6 +
1.7 +#include <IPluginSys.h>
1.8 +
1.9 +namespace SourceMod
1.10 +{
1.11 + #define SMFUNC_COPYBACK_NONE (0) /* Never copy an array back */
1.12 + #define SMFUNC_COPYBACK_ONCE (1<<0) /* Copy an array back after call */
1.13 + #define SMFUNC_COPYBACK_ALWAYS (1<<1) /* Copy an array back after subsequent calls (forwards) */
1.14 +
1.15 + /**
1.16 + * @brief Represents what a function needs to implement in order to be callable.
1.17 + */
1.18 + class ICallable
1.19 + {
1.20 + public:
1.21 + /**
1.22 + * @brief Pushes a cell onto the current call.
1.23 + *
1.24 + * @param cell Parameter value to push.
1.25 + * @return Error code, if any.
1.26 + */
1.27 + virtual int PushCell(cell_t cell) =0;
1.28 +
1.29 + /**
1.30 + * @brief Pushes a cell by reference onto the current call.
1.31 + * NOTE: On Execute, the pointer passed will be modified if copyback is enabled.
1.32 + *
1.33 + * @param cell Address containing parameter value to push.
1.34 + * @param flags Copy-back flags.
1.35 + * @return Error code, if any.
1.36 + */
1.37 + virtual int PushCellByRef(cell_t *cell, int flags) =0;
1.38 +
1.39 + /**
1.40 + * @brief Pushes a float onto the current call.
1.41 + *
1.42 + * @param float Parameter value to push.
1.43 + * @return Error code, if any.
1.44 + */
1.45 + virtual int PushFloat(float number) =0;
1.46 +
1.47 + /**
1.48 + * @brief Pushes a float onto the current call by reference.
1.49 + * NOTE: On Execute, the pointer passed will be modified if copyback is enabled.
1.50 + *
1.51 + * @param float Parameter value to push.
1.52 + & @param flags Copy-back flags.
1.53 + * @return Error code, if any.
1.54 + */
1.55 + virtual int PushFloatByRef(float *number, int flags) =0;
1.56 +
1.57 + /**
1.58 + * @brief Pushes an array of cells onto the current call, each cell individually.
1.59 + * NOTE: This is essentially a crippled version of PushArray().
1.60 + *
1.61 + * @param array Array of cells.
1.62 + * @param numcells Number of cells in array.
1.63 + * @param each Whether or not to push as an array or individual cells.
1.64 + * @return Error code, if any.
1.65 + */
1.66 + virtual int PushCells(cell_t array[], unsigned int numcells, bool each) =0;
1.67 +
1.68 + /**
1.69 + * @brief Pushes an array of cells onto the current call.
1.70 + * NOTE: On Execute, the pointer passed will be modified if non-NULL and copy-back
1.71 + * is enabled.
1.72 + *
1.73 + * @param array Array to copy, NULL if no initial array should be copied.
1.74 + * @param cells Number of cells to allocate and optionally read from the input array.
1.75 + * @param phys_addr Optional return address for physical array (if array was non-NULL, will be array).
1.76 + * @param flags Whether or not changes should be copied back to the input array.
1.77 + * @return Error code, if any.
1.78 + */
1.79 + virtual int PushArray(cell_t *inarray,
1.80 + unsigned int cells,
1.81 + cell_t **phys_addr,
1.82 + int flags=SMFUNC_COPYBACK_NONE) =0;
1.83 +
1.84 + /**
1.85 + * @brief Pushes a string onto the current call.
1.86 + *
1.87 + * @param string String to push.
1.88 + * @return Error code, if any.
1.89 + */
1.90 + virtual int PushString(const char *string) =0;
1.91 +
1.92 + /**
1.93 + * @brief Pushes a string onto the current call.
1.94 + * NOTE: On Execute, the pointer passed will be modified if copy-back is enabled.
1.95 + *
1.96 + * @param string String to push.
1.97 + * @param flags Copy-back flags.
1.98 + * @return Error code, if any.
1.99 + */
1.100 + virtual int PushStringByRef(char *string, int flags) =0;
1.101 +
1.102 + /**
1.103 + * @brief Cancels a function call that is being pushed but not yet executed.
1.104 + * This can be used be reset for CallFunction() use.
1.105 + */
1.106 + virtual void Cancel() =0;
1.107 + };
1.108 +
1.109 +
1.110 + /**
1.111 + * @brief Used for copy-back notification
1.112 + */
1.113 + class IFunctionCopybackReader
1.114 + {
1.115 + public:
1.116 + /**
1.117 + * @brief Called before an array is copied back.
1.118 + *
1.119 + * @param param Parameter index.
1.120 + * @param cells Number of cells in the array.
1.121 + * @param source_addr Source address in the plugin that will be copied.
1.122 + * @param orig_addr Destination addres in plugin that will be overwritten.
1.123 + * @param flags Copy flags.
1.124 + * @return True to copy back, false otherwise.
1.125 + */
1.126 + virtual bool OnCopybackArray(unsigned int param,
1.127 + unsigned int cells,
1.128 + cell_t *source_addr,
1.129 + cell_t *orig_addr,
1.130 + int flags) =0;
1.131 + };
1.132 +
1.133 + /**
1.134 + * @brief Encapsulates a function call in a plugin.
1.135 + * NOTE: Function calls must be atomic to one execution context.
1.136 + * NOTE: This object should not be deleted. It lives for the lifetime of the plugin.
1.137 + */
1.138 + class IPluginFunction : public ICallable
1.139 + {
1.140 + public:
1.141 + /**
1.142 + * @brief Executes the forward, resets the pushed parameter list, and performs any copybacks.
1.143 + *
1.144 + * @param result Pointer to store return value in.
1.145 + * @param reader Copy-back listener. NULL to specify
1.146 + * @return Error code, if any.
1.147 + */
1.148 + virtual int Execute(cell_t *result, IFunctionCopybackReader *reader) =0;
1.149 +
1.150 + /**
1.151 + * @brief Executes the function with the given parameter array.
1.152 + * Parameters are read in forward order (i.e. index 0 is parameter #1)
1.153 + * NOTE: You will get an error if you attempt to use CallFunction() with
1.154 + * previously pushed parameters.
1.155 + *
1.156 + * @param param Array of cell parameters.
1.157 + * @param num_params Number of parameters to push.
1.158 + * @param result Pointer to store result of function on return.
1.159 + * @return SourcePawn error code (if any).
1.160 + */
1.161 + virtual int CallFunction(const cell_t *params, unsigned int num_params, cell_t *result) =0;
1.162 +
1.163 + /**
1.164 + * @brief Returns which plugin this function belongs to.
1.165 + *
1.166 + * @return IPlugin pointer to parent plugin.
1.167 + */
1.168 + virtual IPlugin *GetParentPlugin() =0;
1.169 +
1.170 + /**
1.171 + * @brief Returns the physical address of a by-reference parameter.
1.172 + *
1.173 + * @param Parameter index to read (beginning at 0).
1.174 + * @return Address, or NULL if invalid parameter specified.
1.175 + */
1.176 + virtual cell_t *GetAddressOfPushedParam(unsigned int param) =0;
1.177 + };
1.178 +};
1.179 +
1.180 +#endif //_INCLUDE_SOURCEMOD_PLUGINFUNCTION_INTERFACE_H_
