1 #ifndef _INCLUDE_SOURCEMOD_PLUGINFUNCTION_INTERFACE_H_
2 #define _INCLUDE_SOURCEMOD_PLUGINFUNCTION_INTERFACE_H_
4 #include <IPluginSys.h>
8 #define SMFUNC_COPYBACK_NONE (0) /* Never copy an array back */
9 #define SMFUNC_COPYBACK_ONCE (1<<0) /* Copy an array back after call */
10 #define SMFUNC_COPYBACK_ALWAYS (1<<1) /* Copy an array back after subsequent calls (forwards) */
13 * @brief Represents what a function needs to implement in order to be callable.
19 * @brief Pushes a cell onto the current call.
21 * @param cell Parameter value to push.
22 * @return Error code, if any.
24 virtual int PushCell(cell_t cell) =0;
27 * @brief Pushes a cell by reference onto the current call.
28 * NOTE: On Execute, the pointer passed will be modified if copyback is enabled.
30 * @param cell Address containing parameter value to push.
31 * @param flags Copy-back flags.
32 * @return Error code, if any.
34 virtual int PushCellByRef(cell_t *cell, int flags) =0;
37 * @brief Pushes a float onto the current call.
39 * @param float Parameter value to push.
40 * @return Error code, if any.
42 virtual int PushFloat(float number) =0;
45 * @brief Pushes a float onto the current call by reference.
46 * NOTE: On Execute, the pointer passed will be modified if copyback is enabled.
48 * @param float Parameter value to push.
49 & @param flags Copy-back flags.
50 * @return Error code, if any.
52 virtual int PushFloatByRef(float *number, int flags) =0;
55 * @brief Pushes an array of cells onto the current call, each cell individually.
56 * NOTE: This is essentially a crippled version of PushArray().
58 * @param array Array of cells.
59 * @param numcells Number of cells in array.
60 * @param each Whether or not to push as an array or individual cells.
61 * @return Error code, if any.
63 virtual int PushCells(cell_t array[], unsigned int numcells, bool each) =0;
66 * @brief Pushes an array of cells onto the current call.
67 * NOTE: On Execute, the pointer passed will be modified if non-NULL and copy-back
70 * @param array Array to copy, NULL if no initial array should be copied.
71 * @param cells Number of cells to allocate and optionally read from the input array.
72 * @param phys_addr Optional return address for physical array, if one was made.
73 * @param flags Whether or not changes should be copied back to the input array.
74 * @return Error code, if any.
76 virtual int PushArray(cell_t *inarray,
79 int flags=SMFUNC_COPYBACK_NONE) =0;
82 * @brief Pushes a string onto the current call.
84 * @param string String to push.
85 * @return Error code, if any.
87 virtual int PushString(const char *string) =0;
90 * @brief Pushes a string onto the current call.
91 * NOTE: On Execute, the pointer passed will be modified if copy-back is enabled.
93 * @param string String to push.
94 * @param flags Copy-back flags.
95 * @return Error code, if any.
97 virtual int PushStringByRef(char *string, int flags) =0;
100 * @brief Cancels a function call that is being pushed but not yet executed.
101 * This can be used be reset for CallFunction() use.
103 virtual void Cancel() =0;
108 * @brief Used for copy-back notification
110 class IFunctionCopybackReader
114 * @brief Called before an array is copied back.
116 * @param param Parameter index.
117 * @param cells Number of cells in the array.
118 * @param source_addr Source address in the plugin that will be copied.
119 * @param orig_addr Destination addres in plugin that will be overwritten.
120 * @param flags Copy flags.
121 * @return True to copy back, false otherwise.
123 virtual bool OnCopybackArray(unsigned int param,
131 * @brief Encapsulates a function call in a plugin.
132 * NOTE: Function calls must be atomic to one execution context.
133 * NOTE: This object should not be deleted. It lives for the lifetime of the plugin.
135 class IPluginFunction : public ICallable
139 * @brief Executes the forward, resets the pushed parameter list, and performs any copybacks.
141 * @param result Pointer to store return value in.
142 * @param reader Copy-back listener. NULL to specify
143 * @return Error code, if any.
145 virtual int Execute(cell_t *result, IFunctionCopybackReader *reader) =0;
148 * @brief Executes the function with the given parameter array.
149 * Parameters are read in forward order (i.e. index 0 is parameter #1)
150 * NOTE: You will get an error if you attempt to use CallFunction() with
151 * previously pushed parameters.
153 * @param param Array of cell parameters.
154 * @param num_params Number of parameters to push.
155 * @param result Pointer to store result of function on return.
156 * @return SourcePawn error code (if any).
158 virtual int CallFunction(const cell_t *params, unsigned int num_params, cell_t *result) =0;
161 * @brief Returns which plugin this function belongs to.
163 * @return IPlugin pointer to parent plugin.
165 virtual IPlugin *GetParentPlugin() =0;
168 * @brief Returns the physical address of a by-reference parameter.
170 * @param Parameter index to read (beginning at 0).
171 * @return Address, or NULL if invalid parameter specified.
173 virtual cell_t *GetAddressOfPushedParam(unsigned int param) =0;
177 * @brief Clones the function object. This can be used to maintain a private copy.
178 * The copy retains no push states and must be freeed with ReleaseCopy().
180 virtual IPluginFunction *Copy() =0;
183 * @brief If this object is a clone, this function must be called to destroy it.
185 virtual void ReleaseCopy() =0;
188 * @brief Returns original function pointer, if any.
189 * Note: IsCopyOf() will return the original non-copy, even if used
192 * @return The original object that this was sourced from.
194 virtual IPluginFunction *IsCopyOf() =0;
199 #endif //_INCLUDE_SOURCEMOD_PLUGINFUNCTION_INTERFACE_H_
