1.1 --- a/core/interfaces/IForwardSys.h Sun Nov 12 00:40:58 2006 +0000
1.2 +++ b/core/interfaces/IForwardSys.h Sun Nov 12 01:06:17 2006 +0000
1.3 @@ -3,6 +3,7 @@
1.4
1.5 #include <IForwardSys.h>
1.6 #include <IPluginSys.h>
1.7 +#include <IPluginFunction.h>
1.8
1.9 #define SMINTERFACE_FORWARDMANAGER_NAME "IForwardManager"
1.10 #define SMINTERFACE_FORWARDMANAGER_VERSION 1
1.11 @@ -24,18 +25,76 @@
1.12 enum ExecType
1.13 {
1.14 ET_Ignore = 0, /* Ignore all return values, return 0 */
1.15 - ET_Single = 1, /* Only return the first exec, ignore all others */
1.16 + ET_Single = 1, /* Only return the last exec, ignore all others */
1.17 ET_Event = 2, /* Acts as an event with the ResultTypes above, no mid-Stops allowed, returns highest */
1.18 ET_Hook = 3, /* Acts as a hook with the ResultTypes above, mid-Stops allowed, returns highest */
1.19 + ET_Custom = 4, /* Ignored or handled by an IForwardFilter */
1.20 + };
1.21 +
1.22 + class IForward;
1.23 +
1.24 + class IForwardFilter
1.25 + {
1.26 + public:
1.27 + /**
1.28 + * @brief Called when an error occurs executing a plugin.
1.29 + *
1.30 + * @param fwd IForward pointer.
1.31 + * @param func IPluginFunction pointer to the failed function.
1.32 + * @param err Error code.
1.33 + * @return True to handle, false to pass to global error reporter.
1.34 + */
1.35 + virtual bool OnErrorReport(IForward *fwd,
1.36 + IPluginFunction *func,
1.37 + int err)
1.38 + {
1.39 + return false;
1.40 + }
1.41 +
1.42 + /**
1.43 + * @brief Called after each function return during execution.
1.44 + * NOTE: Only used for ET_Custom.
1.45 + *
1.46 + * @param fwd IForward pointer.
1.47 + * @param func IPluginFunction pointer to the executed function.
1.48 + * @param retval Pointer to current return value (can be modified).
1.49 + * @return ResultType denoting the next action to take.
1.50 + */
1.51 + virtual ResultType OnFunctionReturn(IForward *fwd,
1.52 + IPluginFunction *func,
1.53 + cell_t *retval)
1.54 + {
1.55 + return Pl_Continue;
1.56 + }
1.57 +
1.58 + /**
1.59 + * @brief Called when execution begins.
1.60 + */
1.61 + virtual void OnExecuteBegin()
1.62 + {
1.63 + };
1.64 +
1.65 + /**
1.66 + * @brief Called when execution ends.
1.67 + *
1.68 + * @param final_ret Final return value (modifiable).
1.69 + * @param success Number of successful execs.
1.70 + * @param failed Number of failed execs.
1.71 + */
1.72 + virtual void OnExecuteEnd(cell_t *final_ret, unsigned int success, unsigned int failed)
1.73 + {
1.74 + }
1.75 };
1.76
1.77 /**
1.78 - * :TODO: finish this spec
1.79 * @brief Abstracts multiple function calling.
1.80 + *
1.81 * NOTE: Parameters should be pushed in forward order, unlike
1.82 - * the virtual machine/IPluginContext order.
1.83 - * NOTE: Some functions are repeated in here because their documentation differs
1.84 - * from their IPluginFunction equivalents.
1.85 + * the virtual machine/IPluginContext order.
1.86 + * NOTE: Some functions are repeated in here because their
1.87 + * documentation differs from their IPluginFunction equivalents.
1.88 + * Missing are the Push functions, whose only doc change is that
1.89 + * they throw SP_ERROR_PARAM on type mismatches.
1.90 */
1.91 class IForward : public ICallable
1.92 {
1.93 @@ -65,10 +124,25 @@
1.94 * @brief Executes the forward.
1.95 *
1.96 * @param result Pointer to store result in.
1.97 - * @param num_functions Optionally filled with the number of function sucessfully executed.
1.98 + * @param filter Optional pointer to an IForwardFilter.
1.99 * @return Error code, if any.
1.100 */
1.101 - virtual int Execute(cell_t *result, unsigned int *num_functions) =0;
1.102 + virtual int Execute(cell_t *result, IForwardFilter *filter=NULL) =0;
1.103 +
1.104 + /**
1.105 + * @brief Pushes an array of cells onto the current call. Different rules than ICallable.
1.106 + * NOTE: On Execute, the pointer passed will be modified according to the copyback rule.
1.107 + *
1.108 + * @param array Array to copy. Cannot be NULL, unlike ICallable's version.
1.109 + * @param cells Number of cells to allocate and optionally read from the input array.
1.110 + * @param phys_addr Unused. If a value is passed, it will be filled with NULL.
1.111 + * @param flags Whether or not changes should be copied back to the input array.
1.112 + * @return Error code, if any.
1.113 + */
1.114 + virtual int PushArray(cell_t *inarray,
1.115 + unsigned int cells,
1.116 + cell_t **phys_addr,
1.117 + int flags=SMFUNC_COPYBACK_NONE) =0;
1.118 };
1.119
1.120
1.121 @@ -77,10 +151,12 @@
1.122 public:
1.123 /**
1.124 * @brief Removes a function from the call list.
1.125 + * NOTE: Only removes one instance.
1.126 *
1.127 * @param func Function to remove.
1.128 + * @return Whether or not the function was removed.
1.129 */
1.130 - virtual void RemoveFunction(IPluginFunction *func) =0;
1.131 + virtual bool RemoveFunction(IPluginFunction *func) =0;
1.132
1.133 /**
1.134 * @brief Removes all instances of a plugin from the call list.
1.135 @@ -92,7 +168,9 @@
1.136
1.137 /**
1.138 * @brief Adds a function to the call list.
1.139 - * NOTE: Cannot be used during a call.
1.140 + * NOTE: Cannot be used during an incompleted call.
1.141 + * NOTE: If used during a call, function is temporarily queued until calls are over.
1.142 + * NOTE: Adding mulitple copies of the same function is illegal.
1.143 *
1.144 * @param func Function to add.
1.145 * @return True on success, otherwise false.
1.146 @@ -101,7 +179,8 @@
1.147
1.148 /**
1.149 * @brief Adds a function to the call list.
1.150 - * NOTE: Cannot be used during a call.
1.151 + * NOTE: Cannot be used during an incompleted call.
1.152 + * NOTE: If used during a call, function is temporarily queued until calls are over.
1.153 *
1.154 * @param ctx Context to use as a look-up.
1.155 * @param funcid Function id to add.
1.156 @@ -110,15 +189,24 @@
1.157 virtual bool AddFunction(sp_context_t *ctx, funcid_t index) =0;
1.158 };
1.159
1.160 + #define SP_PARAMTYPE_ANY 0
1.161 + #define SP_PARAMFLAG_BYREF (1<<0)
1.162 + #define SP_PARAMTYPE_CELL (1<<1)
1.163 + #define SP_PARAMTYPE_FLOAT (2<<1)
1.164 + #define SP_PARAMTYPE_STRING (3<<1)|SP_PARAMFLAG_BYREF
1.165 + #define SP_PARAMTYPE_ARRAY (4<<1)|SP_PARAMFLAG_BYREF
1.166 + #define SP_PARAMTYPE_VARARG (5<<1)
1.167 +
1.168 enum ParamType
1.169 {
1.170 - Param_Any = 0, //Any type will be accepted
1.171 - Param_Cell = 1, //Only a cell will be accepted
1.172 - Param_Float = 2, //Only a float value will be accepted
1.173 - Param_String = 3, //Only a string will be accepted
1.174 - Param_Array = 4, //Only a 1D array will be accepted
1.175 - Param_VarArgs = 5, //Anything will be accepted
1.176 - ParamTypes_Total = 6,
1.177 + Param_Any = SP_PARAMTYPE_ANY,
1.178 + Param_Cell = SP_PARAMTYPE_CELL,
1.179 + Param_Float = SP_PARAMTYPE_FLOAT,
1.180 + Param_String = SP_PARAMTYPE_STRING,
1.181 + Param_Array = SP_PARAMTYPE_ARRAY,
1.182 + Param_VarArgs = SP_PARAMTYPE_VARARG,
1.183 + Param_CellByRef = SP_PARAMTYPE_CELL|SP_PARAMFLAG_BYREF,
1.184 + Param_FloatByRef = SP_PARAMTYPE_FLOAT|SP_PARAMFLAG_BYREF,
1.185 };
1.186
1.187 class IForwardManager : public SMInterface
