1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/public/IPluginFunction.h Fri Jan 19 05:33:04 2007 +0000
1.3 @@ -0,0 +1,153 @@
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 SM_PARAM_COPYBACK (1<<0) /* Copy an array/reference back after call */
1.12 +
1.13 + #define SM_PARAM_STRING_UTF8 (1<<0) /* String should be UTF-8 handled */
1.14 + #define SM_PARAM_STRING_COPY (1<<1) /* String should be copied into the plugin */
1.15 +
1.16 + /**
1.17 + * @brief Represents what a function needs to implement in order to be callable.
1.18 + */
1.19 + class ICallable
1.20 + {
1.21 + public:
1.22 + /**
1.23 + * @brief Pushes a cell onto the current call.
1.24 + *
1.25 + * @param cell Parameter value to push.
1.26 + * @return Error code, if any.
1.27 + */
1.28 + virtual int PushCell(cell_t cell) =0;
1.29 +
1.30 + /**
1.31 + * @brief Pushes a cell by reference onto the current call.
1.32 + * NOTE: On Execute, the pointer passed will be modified if copyback is enabled.
1.33 + * NOTE: By reference parameters are cached and thus are not read until execution.
1.34 + * This means you cannot push a pointer, change it, and push it again and expect
1.35 + * two different values to come out.
1.36 + *
1.37 + * @param cell Address containing parameter value to push.
1.38 + * @param flags Copy-back flags.
1.39 + * @return Error code, if any.
1.40 + */
1.41 + virtual int PushCellByRef(cell_t *cell, int flags) =0;
1.42 +
1.43 + /**
1.44 + * @brief Pushes a float onto the current call.
1.45 + *
1.46 + * @param float Parameter value to push.
1.47 + * @return Error code, if any.
1.48 + */
1.49 + virtual int PushFloat(float number) =0;
1.50 +
1.51 + /**
1.52 + * @brief Pushes a float onto the current call by reference.
1.53 + * NOTE: On Execute, the pointer passed will be modified if copyback is enabled.
1.54 + * NOTE: By reference parameters are cached and thus are not read until execution.
1.55 + * This means you cannot push a pointer, change it, and push it again and expect
1.56 + * two different values to come out.
1.57 + *
1.58 + * @param float Parameter value to push.
1.59 + & @param flags Copy-back flags.
1.60 + * @return Error code, if any.
1.61 + */
1.62 + virtual int PushFloatByRef(float *number, int flags) =0;
1.63 +
1.64 + /**
1.65 + * @brief Pushes an array of cells onto the current call.
1.66 + * NOTE: On Execute, the pointer passed will be modified if non-NULL and copy-back
1.67 + * is enabled.
1.68 + * NOTE: By reference parameters are cached and thus are not read until execution.
1.69 + * This means you cannot push a pointer, change it, and push it again and expect
1.70 + * two different values to come out.
1.71 + *
1.72 + * @param inarray Array to copy, NULL if no initial array should be copied.
1.73 + * @param cells Number of cells to allocate and optionally read from the input array.
1.74 + * @param phys_addr Optional return address for physical array, if one was made.
1.75 + * @param flags Whether or not changes should be copied back to the input array.
1.76 + * @return Error code, if any.
1.77 + */
1.78 + virtual int PushArray(cell_t *inarray,
1.79 + unsigned int cells,
1.80 + cell_t **phys_addr,
1.81 + int flags=0) =0;
1.82 +
1.83 + /**
1.84 + * @brief Pushes a string onto the current call.
1.85 + *
1.86 + * @param string String to push.
1.87 + * @return Error code, if any.
1.88 + */
1.89 + virtual int PushString(const char *string) =0;
1.90 +
1.91 + /**
1.92 + * @brief Pushes a string or string buffer.
1.93 + * NOTE: On Execute, the pointer passed will be modified if copy-back is enabled.
1.94 + *
1.95 + * @param buffer Pointer to string buffer.
1.96 + * @param length Length of buffer.
1.97 + * @param sz_flags String flags.
1.98 + * @param cp_flags Copy-back flags.
1.99 + * @return Error code, if any.
1.100 + */
1.101 + virtual int PushStringEx(char *buffer, size_t length, int sz_flags, int cp_flags) =0;
1.102 +
1.103 + /**
1.104 + * @brief Cancels a function call that is being pushed but not yet executed.
1.105 + * This can be used be reset for CallFunction() use.
1.106 + */
1.107 + virtual void Cancel() =0;
1.108 + };
1.109 +
1.110 + /**
1.111 + * @brief Encapsulates a function call in a plugin.
1.112 + * NOTE: Function calls must be atomic to one execution context.
1.113 + * NOTE: This object should not be deleted. It lives for the lifetime of the plugin.
1.114 + */
1.115 + class IPluginFunction : public ICallable
1.116 + {
1.117 + public:
1.118 + /**
1.119 + * @brief Executes the forward, resets the pushed parameter list, and performs any copybacks.
1.120 + *
1.121 + * @param result Pointer to store return value in.
1.122 + * @return Error code, if any.
1.123 + */
1.124 + virtual int Execute(cell_t *result) =0;
1.125 +
1.126 + /**
1.127 + * @brief Executes the function with the given parameter array.
1.128 + * Parameters are read in forward order (i.e. index 0 is parameter #1)
1.129 + * NOTE: You will get an error if you attempt to use CallFunction() with
1.130 + * previously pushed parameters.
1.131 + *
1.132 + * @param param Array of cell parameters.
1.133 + * @param num_params Number of parameters to push.
1.134 + * @param result Pointer to store result of function on return.
1.135 + * @return SourcePawn error code (if any).
1.136 + */
1.137 + virtual int CallFunction(const cell_t *params, unsigned int num_params, cell_t *result) =0;
1.138 +
1.139 + /**
1.140 + * @brief Returns which plugin this function belongs to.
1.141 + *
1.142 + * @return IPlugin pointer to parent plugin.
1.143 + */
1.144 + virtual IPlugin *GetParentPlugin() =0;
1.145 +
1.146 + /**
1.147 + * @brief Returns the physical address of a by-reference parameter.
1.148 + *
1.149 + * @param Parameter index to read (beginning at 0).
1.150 + * @return Address, or NULL if invalid parameter specified.
1.151 + */
1.152 + virtual cell_t *GetAddressOfPushedParam(unsigned int param) =0;
1.153 + };
1.154 +};
1.155 +
1.156 +#endif //_INCLUDE_SOURCEMOD_PLUGINFUNCTION_INTERFACE_H_
