1.1 --- a/plugins/include/functions.inc Thu Mar 15 22:32:45 2007 +0000
1.2 +++ b/plugins/include/functions.inc Fri Mar 16 06:54:24 2007 +0000
1.3 @@ -13,6 +13,48 @@
1.4 * Version: $Id$
1.5 */
1.6
1.7 +#define SP_PARAMFLAG_BYREF (1<<0) /**< Internal use only. */
1.8 +
1.9 +/**
1.10 + * Describes the various ways to pass parameters to functions or forwards.
1.11 + */
1.12 +enum ParamType
1.13 +{
1.14 + Param_Any = 0, /**< Any data type can be pushed */
1.15 + Param_Cell = (1<<1), /**< Only basic cells can be pushed */
1.16 + Param_Float = (2<<1), /**< Only floats can be pushed */
1.17 + Param_String = (3<<1)|SP_PARAMFLAG_BYREF, /**< Only strings can be pushed */
1.18 + Param_Array = (4<<1)|SP_PARAMFLAG_BYREF, /**< Only arrays can be pushed */
1.19 + Param_VarArgs = (5<<1), /**< Same as "..." in plugins, anything can be pushed, but it will always be byref */
1.20 + Param_CellByRef = (1<<1)|SP_PARAMFLAG_BYREF, /**< Only a cell by reference can be pushed */
1.21 + Param_FloatByRef = (2<<1)|SP_PARAMFLAG_BYREF /**< Only a float by reference can be pushed */
1.22 +};
1.23 +
1.24 +/**
1.25 + * Defines how a forward iterates through plugin functions.
1.26 + */
1.27 +enum ExecType
1.28 +{
1.29 + ET_Ignore = 0, /**< Ignore all return values, return 0 */
1.30 + ET_Single = 1, /**< Only return the last exec, ignore all others */
1.31 + ET_Event = 2, /**< Acts as an event with the Actions defined in core.inc, no mid-Stops allowed, returns highest */
1.32 + ET_Hook = 3 /**< Acts as a hook with the Actions defined in core.inc, mid-Stops allowed, returns highest */
1.33 +};
1.34 +
1.35 +/**
1.36 + * @section Flags that are used with Call_PushArrayEx() and Call_PushStringEx()
1.37 + */
1.38 +#define SM_PARAM_COPYBACK (1<<0) /**< Copy an array/reference back after call */
1.39 +#define SM_PARAM_STRING_UTF8 (1<<0) /**< String should be UTF-8 handled */
1.40 +#define SM_PARAM_STRING_COPY (1<<1) /**< String should be copied into the plugin */
1.41 +
1.42 +/**
1.43 + * @endsection
1.44 + */
1.45 +
1.46 +/**
1.47 + * @section Error codes
1.48 + */
1.49 #define SP_ERROR_NONE 0 /**< No error occurred */
1.50 #define SP_ERROR_FILE_FORMAT 1 /**< File format unrecognized */
1.51 #define SP_ERROR_DECOMPRESSOR 2 /**< A decompressor was not found */
1.52 @@ -41,6 +83,243 @@
1.53 #define SP_ERROR_ABORTED 25 /**< Function call was aborted */
1.54
1.55 /**
1.56 + * @endsection
1.57 + */
1.58 +
1.59 +/**
1.60 + * Gets a function id from a function name.
1.61 + *
1.62 + * @param plugin Handle of the plugin that contains the function.
1.63 + Pass INVALID_HANDLE to search in the calling plugin.
1.64 + * @param name Name of the function.
1.65 + * @return Function id or INVALID_FUNCTION if not found.
1.66 + * @error Invalid or corrupt plugin handle.
1.67 + */
1.68 +native Function:GetFunctionByName(Handle:plugin, const String:name[]);
1.69 +
1.70 +/**
1.71 + * Creates a global forward.
1.72 + *
1.73 + * @note The name used to create the forward is used as its public function in all target plugins.
1.74 + * @note This is ideal for global, static forwards that are never changed.
1.75 + *
1.76 + * @param name Name of public function to use in forward.
1.77 + * @param type Execution type to be used.
1.78 + * @param ... Variable number of parameter types (up to 32).
1.79 + * @return Handle to new global forward.
1.80 + * @error More than 32 paramater types passed.
1.81 + */
1.82 +native Handle:CreateGlobalForward(const String:name[], ExecType:type, {ParamType}:...);
1.83 +
1.84 +/**
1.85 + * Creates a private forward.
1.86 + *
1.87 + * @note No functions are automatically added. Use AddToForward() to do this.
1.88 + *
1.89 + * @param type Execution type to be used.
1.90 + * @param ... Variable number of parameter types (up to 32).
1.91 + * @return Handle to new private forward.
1.92 + * @error More than 32 paramater types passed.
1.93 + */
1.94 +native Handle:CreateForward(ExecType:type, {ParamType}:...);
1.95 +
1.96 +/**
1.97 + * Returns the number of functions in a global or private forward's call list.
1.98 + *
1.99 + * @param fwd Handle to global or private forward.
1.100 + * @return Number of functions in forward.
1.101 + * @error Invalid or corrupt forward handle.
1.102 + */
1.103 +native GetForwardFunctionCount(Handle:fwd);
1.104 +
1.105 +/**
1.106 + * Adds a function to a private forward's call list.
1.107 + *
1.108 + * @note Cannot be used during an incompleted call.
1.109 + *
1.110 + * @param fwd Handle to private forward.
1.111 + * @param plugin Handle of the plugin that contains the function.
1.112 + * Pass INVALID_HANDLE to specify the calling plugin.
1.113 + * @param func Function to add to forward.
1.114 + * @return True on success, false otherwise.
1.115 + * @error Invalid or corrupt private forward handle, invalid or corrupt plugin handle, or invalid function.
1.116 + */
1.117 +native bool:AddToForward(Handle:fwd, Handle:plugin, Function:func);
1.118 +
1.119 +/**
1.120 + * Removes a function from a private forward's call list.
1.121 + *
1.122 + * @note Only removes one instance.
1.123 + * @note Functions will be removed automatically if their parent plugin is unloaded.
1.124 + *
1.125 + * @param fwd Handle to private forward.
1.126 + * @param plugin Handle of the plugin that contains the function.
1.127 + * Pass INVALID_HANDLE to specify the calling plugin.
1.128 + * @param func Function to remove from forward.
1.129 + * @return True on success, false otherwise.
1.130 + * @error Invalid or corrupt private forward handle, invalid or corrupt plugin handle, or invalid function.
1.131 + */
1.132 +native bool:RemoveFromForward(Handle:fwd, Handle:plugin, Function:func);
1.133 +
1.134 +/**
1.135 + * Removes all instances of a plugin from a private forward's call list.
1.136 + *
1.137 + * @note Functions will be removed automatically if their parent plugin is unloaded.
1.138 + *
1.139 + * @param fwd Handle to private forward.
1.140 + * @param plugin Handle of the plugin to remove instances of.
1.141 + * Pass INVALID_HANDLE to specify the calling plugin.
1.142 + * @return Number of functions removed from forward.
1.143 + * @error Invalid or corrupt private forward handle or invalid or corrupt plugin handle.
1.144 + */
1.145 +native RemoveAllFromForward(Handle:fwd, Handle:plugin);
1.146 +
1.147 +/**
1.148 + * Starts a call to functions in a forward's call list.
1.149 + *
1.150 + * @note Cannot be used during an incompleted call.
1.151 + *
1.152 + * @param fwd Handle to global or private forward.
1.153 + * @noreturn
1.154 + * @error Invalid or corrupt forward handle or called before another call has completed.
1.155 + */
1.156 +native Call_StartForward(Handle:fwd);
1.157 +
1.158 +/**
1.159 + * Starts a call to a function.
1.160 + *
1.161 + * @note Cannot be used during an incompleted call.
1.162 + *
1.163 + * @param plugin Handle of the plugin that contains the function.
1.164 + * Pass INVALID_HANDLE to specify the calling plugin.
1.165 + * @param func Function to call.
1.166 + * @noreturn
1.167 + * @error Invalid or corrupt plugin handle, invalid function, or called before another call has completed.
1.168 + */
1.169 +native Call_StartFunction(Handle:plugin, Function:func);
1.170 +
1.171 +/**
1.172 + * Pushes a cell onto the current call.
1.173 + *
1.174 + * @note Cannot be used before a call has been started.
1.175 + *
1.176 + * @param value Cell value to push.
1.177 + * @noreturn
1.178 + * @error Called before a call has been started.
1.179 + */
1.180 +native Call_PushCell({Handle,Function,_}:value);
1.181 +
1.182 +/**
1.183 + * Pushes a cell by reference onto the current call.
1.184 + *
1.185 + * @note Cannot be used before a call has been started.
1.186 + *
1.187 + * @param value Cell reference to push.
1.188 + * @noreturn
1.189 + * @error Called before a call has been started.
1.190 + */
1.191 +native Call_PushCellRef(&{Handle,Function,_}:value);
1.192 +
1.193 +
1.194 +/**
1.195 + * Pushes a float onto the current call.
1.196 + *
1.197 + * @note Cannot be used before a call has been started.
1.198 + *
1.199 + * @param value Floating point value to push.
1.200 + * @noreturn
1.201 + * @error Called before a call has been started.
1.202 + */
1.203 +native Call_PushFloat(Float:value);
1.204 +
1.205 +/**
1.206 + * Pushes a float by reference onto the current call.
1.207 + *
1.208 + * @note Cannot be used before a call has been started.
1.209 + *
1.210 + * @param value Floating point reference to push.
1.211 + * @noreturn
1.212 + * @error Called before a call has been started.
1.213 + */
1.214 +native Call_PushFloatRef(&Float:value);
1.215 +
1.216 +/**
1.217 + * Pushes an array onto the current call.
1.218 + *
1.219 + * @note Changes to array are not copied back to caller. Use PushArrayEx() to do this.
1.220 + * @note Cannot be used before a call has been started.
1.221 + *
1.222 + * @param value Array to push.
1.223 + * @param size Size of array.
1.224 + * @noreturn
1.225 + * @error Called before a call has been started.
1.226 + */
1.227 +native Call_PushArray(const {Handle,Float,Function,_}:value[], size);
1.228 +
1.229 +/**
1.230 + * Pushes an array onto the current call.
1.231 + *
1.232 + * @note Cannot be used before a call has been started.
1.233 + *
1.234 + * @param value Array to push.
1.235 + * @param size Size of array.
1.236 + * @param cpflags Whether or not changes should be copied back to the input array.
1.237 + * See SP_PARAM_* constants for details.
1.238 + * @noreturn
1.239 + * @error Called before a call has been started.
1.240 + */
1.241 +native Call_PushArrayEx({Handle,Float,Function,_}:value[], size, cpflags);
1.242 +
1.243 +/**
1.244 + * Pushes a string onto the current call.
1.245 + *
1.246 + * @note Changes to string are not copied back to caller. Use PushStringEx() to do this.
1.247 + * @note Cannot be used before a call has been started.
1.248 + *
1.249 + * @param value String to push.
1.250 + * @noreturn
1.251 + * @error Called before a call has been started.
1.252 + */
1.253 +native Call_PushString(const String:value[]);
1.254 +
1.255 +/**
1.256 + * Pushes a string onto the current call.
1.257 + *
1.258 + * @note Cannot be used before a call has been started.
1.259 + *
1.260 + * @param value String to push.
1.261 + * @param length Length of string buffer.
1.262 + * @param szflags Flags determining how string should be handled.
1.263 + * See SP_PARAM_STRING_* constants for details.
1.264 + * @param cpflags Whether or not changes should be copied back to the input array.
1.265 + * See SP_PARAM_* constants for details.
1.266 + * @noreturn
1.267 + * @error Called before a call has been started.
1.268 + */
1.269 +native Call_PushStringEx(String:value[], length, szflags, cpflags);
1.270 +
1.271 +/**
1.272 + * Completes a call to a function or forward's call list.
1.273 + *
1.274 + * @note Cannot be used before a call has been started.
1.275 + *
1.276 + * @param result Return value of function or forward's call list.
1.277 + * @return SP_ERROR_NONE on success, any other integer on failure.
1.278 + * @error Called before a call has been started.
1.279 + */
1.280 +native Call_Finish(&result);
1.281 +
1.282 +/**
1.283 + * Cancels a call to a function or forward's call list.
1.284 + *
1.285 + * @note Cannot be used before a call has been started.
1.286 + *
1.287 + * @noreturn
1.288 + * @error Called before a call has been started.
1.289 + */
1.290 +native Call_Cancel();
1.291 +
1.292 +/**
1.293 * Defines a native function.
1.294 *
1.295 * It is not necessary to validate the parameter count
1.296 @@ -69,7 +348,7 @@
1.297 * @param fmt Error message format.
1.298 * @param ... Format arguments.
1.299 */
1.300 -native ThrowNativeError(error, const String:fmt[], {Handle,Float,String,_}:...);
1.301 +native ThrowNativeError(error, const String:fmt[], {Handle,Float,String,Function,_}:...);
1.302
1.303 /**
1.304 * Retrieves the string length from a native parameter string. This is useful
1.305 @@ -78,7 +357,7 @@
1.306 *
1.307 * @param param Parameter number, starting from 1.
1.308 * @param length Stores the length of the string.
1.309 - * @return SP_ERROR_NONE on sucecss, any other integer on failure.
1.310 + * @return SP_ERROR_NONE on success, any other integer on failure.
1.311 * @error Invalid parameter number or calling from a non-native function.
1.312 */
1.313 native GetNativeStringLength(param, &length);
1.314 @@ -137,7 +416,7 @@
1.315 * @noreturn
1.316 * @error Invalid parameter number or calling from a non-native function.
1.317 */
1.318 -native SetNativeCellRef(param, {Float,Handle,_}:value);
1.319 +native SetNativeCellRef(param, {Float,Function,Handle,_}:value);
1.320
1.321 /**
1.322 * Gets an array from a native parameter (always by reference).
1.323 @@ -148,7 +427,7 @@
1.324 * @return SP_ERROR_NONE on success, anything else on failure.
1.325 * @error Invalid parameter number or calling from a non-native function.
1.326 */
1.327 -native GetNativeArray(param, {Float,Handle,_}:local[], size);
1.328 +native GetNativeArray(param, {Float,Function,Handle,_}:local[], size);
1.329
1.330 /**
1.331 * Copies a local array into a native parameter array (always by reference).
1.332 @@ -159,7 +438,7 @@
1.333 * @return SP_ERROR_NONE on success, anything else on failure.
1.334 * @error Invalid parameter number or calling from a non-native function.
1.335 */
1.336 -native SetNativeArray(param, const {Float,Handle,_}:local[], size);
1.337 +native SetNativeArray(param, const {Float,Function,Handle,_}:local[], size);
1.338
1.339 /**
1.340 * Formats a string using parameters from a native.
