1 #ifndef _INCLUDE_SOURCEMOD_PLUGINFUNCTION_INTERFACE_H_
2 #define _INCLUDE_SOURCEMOD_PLUGINFUNCTION_INTERFACE_H_
4 #include <IPluginSys.h>
8 #define SM_PARAM_COPYBACK (1<<0) /* Copy an array/reference back after call */
10 #define SM_PARAM_STRING_UTF8 (1<<0) /* String should be UTF-8 handled */
11 #define SM_PARAM_STRING_COPY (1<<1) /* String should be copied into the plugin */
14 * @brief Represents what a function needs to implement in order to be callable.
20 * @brief Pushes a cell onto the current call.
22 * @param cell Parameter value to push.
23 * @return Error code, if any.
25 virtual int PushCell(cell_t cell) =0;
28 * @brief Pushes a cell by reference onto the current call.
29 * NOTE: On Execute, the pointer passed will be modified if copyback is enabled.
30 * NOTE: By reference parameters are cached and thus are not read until execution.
31 * This means you cannot push a pointer, change it, and push it again and expect
32 * two different values to come out.
34 * @param cell Address containing parameter value to push.
35 * @param flags Copy-back flags.
36 * @return Error code, if any.
38 virtual int PushCellByRef(cell_t *cell, int flags) =0;
41 * @brief Pushes a float onto the current call.
43 * @param float Parameter value to push.
44 * @return Error code, if any.
46 virtual int PushFloat(float number) =0;
49 * @brief Pushes a float onto the current call by reference.
50 * NOTE: On Execute, the pointer passed will be modified if copyback is enabled.
51 * NOTE: By reference parameters are cached and thus are not read until execution.
52 * This means you cannot push a pointer, change it, and push it again and expect
53 * two different values to come out.
55 * @param float Parameter value to push.
56 & @param flags Copy-back flags.
57 * @return Error code, if any.
59 virtual int PushFloatByRef(float *number, int flags) =0;
62 * @brief Pushes an array of cells onto the current call.
63 * NOTE: On Execute, the pointer passed will be modified if non-NULL and copy-back
65 * NOTE: By reference parameters are cached and thus are not read until execution.
66 * This means you cannot push a pointer, change it, and push it again and expect
67 * two different values to come out.
69 * @param inarray Array to copy, NULL if no initial array should be copied.
70 * @param cells Number of cells to allocate and optionally read from the input array.
71 * @param phys_addr Optional return address for physical array, if one was made.
72 * @param flags Whether or not changes should be copied back to the input array.
73 * @return Error code, if any.
75 virtual int PushArray(cell_t *inarray,
81 * @brief Pushes a string onto the current call.
83 * @param string String to push.
84 * @return Error code, if any.
86 virtual int PushString(const char *string) =0;
89 * @brief Pushes a string or string buffer.
90 * NOTE: On Execute, the pointer passed will be modified if copy-back is enabled.
92 * @param buffer Pointer to string buffer.
93 * @param length Length of buffer.
94 * @param sz_flags String flags.
95 * @param cp_flags Copy-back flags.
96 * @return Error code, if any.
98 virtual int PushStringEx(char *buffer, size_t length, int sz_flags, int cp_flags) =0;
101 * @brief Cancels a function call that is being pushed but not yet executed.
102 * This can be used be reset for CallFunction() use.
104 virtual void Cancel() =0;
108 * @brief Encapsulates a function call in a plugin.
109 * NOTE: Function calls must be atomic to one execution context.
110 * NOTE: This object should not be deleted. It lives for the lifetime of the plugin.
112 class IPluginFunction : public ICallable
116 * @brief Executes the forward, resets the pushed parameter list, and performs any copybacks.
118 * @param result Pointer to store return value in.
119 * @return Error code, if any.
121 virtual int Execute(cell_t *result) =0;
124 * @brief Executes the function with the given parameter array.
125 * Parameters are read in forward order (i.e. index 0 is parameter #1)
126 * NOTE: You will get an error if you attempt to use CallFunction() with
127 * previously pushed parameters.
129 * @param param Array of cell parameters.
130 * @param num_params Number of parameters to push.
131 * @param result Pointer to store result of function on return.
132 * @return SourcePawn error code (if any).
134 virtual int CallFunction(const cell_t *params, unsigned int num_params, cell_t *result) =0;
137 * @brief Returns which plugin this function belongs to.
139 * @return IPlugin pointer to parent plugin.
141 virtual IPlugin *GetParentPlugin() =0;
144 * @brief Returns the physical address of a by-reference parameter.
146 * @param Parameter index to read (beginning at 0).
147 * @return Address, or NULL if invalid parameter specified.
149 virtual cell_t *GetAddressOfPushedParam(unsigned int param) =0;
153 #endif //_INCLUDE_SOURCEMOD_PLUGINFUNCTION_INTERFACE_H_
