rewrote forward API to use cached parameter pushing instead of immediate pushing
removed copy back cruft since it's no longer needed
removed PushCells() from API requirements, not needed
adjusted documentation and added TODO list to ForwardSys.cpp
various internal improvements
1 #ifndef _INCLUDE_SOURCEMOD_PLUGINFUNCTION_INTERFACE_H_
2 #define _INCLUDE_SOURCEMOD_PLUGINFUNCTION_INTERFACE_H_
4 #include <IPluginSys.h>
8 #define SM_FUNCFLAG_COPYBACK (1<<0) /* Copy an array/reference back after call */
11 * @brief Represents what a function needs to implement in order to be callable.
17 * @brief Pushes a cell onto the current call.
19 * @param cell Parameter value to push.
20 * @return Error code, if any.
22 virtual int PushCell(cell_t cell) =0;
25 * @brief Pushes a cell by reference onto the current call.
26 * NOTE: On Execute, the pointer passed will be modified if copyback is enabled.
27 * NOTE: By reference parameters are cached and thus are not read until execution.
28 * This means you cannot push a pointer, change it, and push it again and expect
29 * two different values to come out.
31 * @param cell Address containing parameter value to push.
32 * @param flags Copy-back flags.
33 * @return Error code, if any.
35 virtual int PushCellByRef(cell_t *cell, int flags) =0;
38 * @brief Pushes a float onto the current call.
40 * @param float Parameter value to push.
41 * @return Error code, if any.
43 virtual int PushFloat(float number) =0;
46 * @brief Pushes a float onto the current call by reference.
47 * NOTE: On Execute, the pointer passed will be modified if copyback is enabled.
48 * NOTE: By reference parameters are cached and thus are not read until execution.
49 * This means you cannot push a pointer, change it, and push it again and expect
50 * two different values to come out.
52 * @param float Parameter value to push.
53 & @param flags Copy-back flags.
54 * @return Error code, if any.
56 virtual int PushFloatByRef(float *number, int flags) =0;
59 * @brief Pushes an array of cells onto the current call.
60 * NOTE: On Execute, the pointer passed will be modified if non-NULL and copy-back
62 * NOTE: By reference parameters are cached and thus are not read until execution.
63 * This means you cannot push a pointer, change it, and push it again and expect
64 * two different values to come out.
66 * @param array Array to copy, NULL if no initial array should be copied.
67 * @param cells Number of cells to allocate and optionally read from the input array.
68 * @param phys_addr Optional return address for physical array, if one was made.
69 * @param flags Whether or not changes should be copied back to the input array.
70 * @return Error code, if any.
72 virtual int PushArray(cell_t *inarray,
78 * @brief Pushes a string onto the current call.
80 * @param string String to push.
81 * @return Error code, if any.
83 virtual int PushString(const char *string) =0;
86 * @brief Pushes a string onto the current call.
87 * NOTE: On Execute, the pointer passed will be modified if copy-back is enabled.
89 * @param string String to push.
90 * @param flags Copy-back flags.
91 * @return Error code, if any.
93 virtual int PushStringEx(char *string, int flags) =0;
96 * @brief Cancels a function call that is being pushed but not yet executed.
97 * This can be used be reset for CallFunction() use.
99 virtual void Cancel() =0;
103 * @brief Encapsulates a function call in a plugin.
104 * NOTE: Function calls must be atomic to one execution context.
105 * NOTE: This object should not be deleted. It lives for the lifetime of the plugin.
107 class IPluginFunction : public ICallable
111 * @brief Executes the forward, resets the pushed parameter list, and performs any copybacks.
113 * @param result Pointer to store return value in.
114 * @param reader Copy-back listener. NULL to specify
115 * @return Error code, if any.
117 virtual int Execute(cell_t *result) =0;
120 * @brief Executes the function with the given parameter array.
121 * Parameters are read in forward order (i.e. index 0 is parameter #1)
122 * NOTE: You will get an error if you attempt to use CallFunction() with
123 * previously pushed parameters.
125 * @param param Array of cell parameters.
126 * @param num_params Number of parameters to push.
127 * @param result Pointer to store result of function on return.
128 * @return SourcePawn error code (if any).
130 virtual int CallFunction(const cell_t *params, unsigned int num_params, cell_t *result) =0;
133 * @brief Returns which plugin this function belongs to.
135 * @return IPlugin pointer to parent plugin.
137 virtual IPlugin *GetParentPlugin() =0;
140 * @brief Returns the physical address of a by-reference parameter.
142 * @param Parameter index to read (beginning at 0).
143 * @return Address, or NULL if invalid parameter specified.
145 virtual cell_t *GetAddressOfPushedParam(unsigned int param) =0;
149 #endif //_INCLUDE_SOURCEMOD_PLUGINFUNCTION_INTERFACE_H_
