3 * ===============================================================
4 * SourceMod (C)2004-2007 AlliedModders LLC. All rights reserved.
5 * ===============================================================
7 * This file is part of the SourceMod/SourcePawn SDK. This file may only be used
8 * or modified under the Terms and Conditions of its License Agreement, which is found
9 * in LICENSE.txt. The Terms and Conditions for making SourceMod extensions/plugins
10 * may change at any time. To view the latest information, see:
11 * http://www.sourcemod.net/license.php
16 #define SP_PARAMFLAG_BYREF (1<<0) /**< Internal use only. */
19 * Describes the various ways to pass parameters to functions or forwards.
23 Param_Any = 0, /**< Any data type can be pushed */
24 Param_Cell = (1<<1), /**< Only basic cells can be pushed */
25 Param_Float = (2<<1), /**< Only floats can be pushed */
26 Param_String = (3<<1)|SP_PARAMFLAG_BYREF, /**< Only strings can be pushed */
27 Param_Array = (4<<1)|SP_PARAMFLAG_BYREF, /**< Only arrays can be pushed */
28 Param_VarArgs = (5<<1), /**< Same as "..." in plugins, anything can be pushed, but it will always be byref */
29 Param_CellByRef = (1<<1)|SP_PARAMFLAG_BYREF, /**< Only a cell by reference can be pushed */
30 Param_FloatByRef = (2<<1)|SP_PARAMFLAG_BYREF /**< Only a float by reference can be pushed */
34 * Defines how a forward iterates through plugin functions.
38 ET_Ignore = 0, /**< Ignore all return values, return 0 */
39 ET_Single = 1, /**< Only return the last exec, ignore all others */
40 ET_Event = 2, /**< Acts as an event with the Actions defined in core.inc, no mid-Stops allowed, returns highest */
41 ET_Hook = 3 /**< Acts as a hook with the Actions defined in core.inc, mid-Stops allowed, returns highest */
45 * @section Flags that are used with Call_PushArrayEx() and Call_PushStringEx()
47 #define SM_PARAM_COPYBACK (1<<0) /**< Copy an array/reference back after call */
48 #define SM_PARAM_STRING_UTF8 (1<<0) /**< String should be UTF-8 handled */
49 #define SM_PARAM_STRING_COPY (1<<1) /**< String should be copied into the plugin */
56 * @section Error codes
58 #define SP_ERROR_NONE 0 /**< No error occurred */
59 #define SP_ERROR_FILE_FORMAT 1 /**< File format unrecognized */
60 #define SP_ERROR_DECOMPRESSOR 2 /**< A decompressor was not found */
61 #define SP_ERROR_HEAPLOW 3 /**< Not enough space left on the heap */
62 #define SP_ERROR_PARAM 4 /**< Invalid parameter or parameter type */
63 #define SP_ERROR_INVALID_ADDRESS 5 /**< A memory address was not valid */
64 #define SP_ERROR_NOT_FOUND 6 /**< The object in question was not found */
65 #define SP_ERROR_INDEX 7 /**< Invalid index parameter */
66 #define SP_ERROR_STACKLOW 8 /**< Nnot enough space left on the stack */
67 #define SP_ERROR_NOTDEBUGGING 9 /**< Debug mode was not on or debug section not found */
68 #define SP_ERROR_INVALID_INSTRUCTION 10 /**< Invalid instruction was encountered */
69 #define SP_ERROR_MEMACCESS 11 /**< Invalid memory access */
70 #define SP_ERROR_STACKMIN 12 /**< Stack went beyond its minimum value */
71 #define SP_ERROR_HEAPMIN 13 /**< Heap went beyond its minimum value */
72 #define SP_ERROR_DIVIDE_BY_ZERO 14 /**< Division by zero */
73 #define SP_ERROR_ARRAY_BOUNDS 15 /**< Array index is out of bounds */
74 #define SP_ERROR_INSTRUCTION_PARAM 16 /**< Instruction had an invalid parameter */
75 #define SP_ERROR_STACKLEAK 17 /**< A native leaked an item on the stack */
76 #define SP_ERROR_HEAPLEAK 18 /**< A native leaked an item on the heap */
77 #define SP_ERROR_ARRAY_TOO_BIG 19 /**< A dynamic array is too big */
78 #define SP_ERROR_TRACKER_BOUNDS 20 /**< Tracker stack is out of bounds */
79 #define SP_ERROR_INVALID_NATIVE 21 /**< Native was pending or invalid */
80 #define SP_ERROR_PARAMS_MAX 22 /**< Maximum number of parameters reached */
81 #define SP_ERROR_NATIVE 23 /**< Error originates from a native */
82 #define SP_ERROR_NOT_RUNNABLE 24 /**< Function or plugin is not runnable */
83 #define SP_ERROR_ABORTED 25 /**< Function call was aborted */
90 * Gets a function id from a function name.
92 * @param plugin Handle of the plugin that contains the function.
93 Pass INVALID_HANDLE to search in the calling plugin.
94 * @param name Name of the function.
95 * @return Function id or INVALID_FUNCTION if not found.
96 * @error Invalid or corrupt plugin handle.
98 native Function:GetFunctionByName(Handle:plugin, const String:name[]);
101 * Creates a global forward.
103 * @note The name used to create the forward is used as its public function in all target plugins.
104 * @note This is ideal for global, static forwards that are never changed.
105 * @note Global forwards cannot be cloned.
106 * @note Use CloseHandle() to destroy these.
108 * @param name Name of public function to use in forward.
109 * @param type Execution type to be used.
110 * @param ... Variable number of parameter types (up to 32).
111 * @return Handle to new global forward.
112 * @error More than 32 paramater types passed.
114 native Handle:CreateGlobalForward(const String:name[], ExecType:type, ParamType:...);
117 * Creates a private forward.
119 * @note No functions are automatically added. Use AddToForward() to do this.
120 * @note Private forwards can be cloned.
121 * @note Use CloseHandle() to destroy these.
123 * @param type Execution type to be used.
124 * @param ... Variable number of parameter types (up to 32).
125 * @return Handle to new private forward.
126 * @error More than 32 paramater types passed.
128 native Handle:CreateForward(ExecType:type, ParamType:...);
131 * Returns the number of functions in a global or private forward's call list.
133 * @param fwd Handle to global or private forward.
134 * @return Number of functions in forward.
135 * @error Invalid or corrupt forward handle.
137 native GetForwardFunctionCount(Handle:fwd);
140 * Adds a function to a private forward's call list.
142 * @note Cannot be used during an incompleted call.
144 * @param fwd Handle to private forward.
145 * @param plugin Handle of the plugin that contains the function.
146 * Pass INVALID_HANDLE to specify the calling plugin.
147 * @param func Function to add to forward.
148 * @return True on success, false otherwise.
149 * @error Invalid or corrupt private forward handle, invalid or corrupt plugin handle, or invalid function.
151 native bool:AddToForward(Handle:fwd, Handle:plugin, Function:func);
154 * Removes a function from a private forward's call list.
156 * @note Only removes one instance.
157 * @note Functions will be removed automatically if their parent plugin is unloaded.
159 * @param fwd Handle to private forward.
160 * @param plugin Handle of the plugin that contains the function.
161 * Pass INVALID_HANDLE to specify the calling plugin.
162 * @param func Function to remove from forward.
163 * @return True on success, false otherwise.
164 * @error Invalid or corrupt private forward handle, invalid or corrupt plugin handle, or invalid function.
166 native bool:RemoveFromForward(Handle:fwd, Handle:plugin, Function:func);
169 * Removes all instances of a plugin from a private forward's call list.
171 * @note Functions will be removed automatically if their parent plugin is unloaded.
173 * @param fwd Handle to private forward.
174 * @param plugin Handle of the plugin to remove instances of.
175 * Pass INVALID_HANDLE to specify the calling plugin.
176 * @return Number of functions removed from forward.
177 * @error Invalid or corrupt private forward handle or invalid or corrupt plugin handle.
179 native RemoveAllFromForward(Handle:fwd, Handle:plugin);
182 * Starts a call to functions in a forward's call list.
184 * @note Cannot be used during an incompleted call.
186 * @param fwd Handle to global or private forward.
188 * @error Invalid or corrupt forward handle or called before another call has completed.
190 native Call_StartForward(Handle:fwd);
193 * Starts a call to a function.
195 * @note Cannot be used during an incompleted call.
197 * @param plugin Handle of the plugin that contains the function.
198 * Pass INVALID_HANDLE to specify the calling plugin.
199 * @param func Function to call.
201 * @error Invalid or corrupt plugin handle, invalid function, or called before another call has completed.
203 native Call_StartFunction(Handle:plugin, Function:func);
206 * Pushes a cell onto the current call.
208 * @note Cannot be used before a call has been started.
210 * @param value Cell value to push.
212 * @error Called before a call has been started.
214 native Call_PushCell({Handle,Function,_}:value);
217 * Pushes a cell by reference onto the current call.
219 * @note Cannot be used before a call has been started.
221 * @param value Cell reference to push.
223 * @error Called before a call has been started.
225 native Call_PushCellRef(&{Handle,Function,_}:value);
229 * Pushes a float onto the current call.
231 * @note Cannot be used before a call has been started.
233 * @param value Floating point value to push.
235 * @error Called before a call has been started.
237 native Call_PushFloat(Float:value);
240 * Pushes a float by reference onto the current call.
242 * @note Cannot be used before a call has been started.
244 * @param value Floating point reference to push.
246 * @error Called before a call has been started.
248 native Call_PushFloatRef(&Float:value);
251 * Pushes an array onto the current call.
253 * @note Changes to array are not copied back to caller. Use PushArrayEx() to do this.
254 * @note Cannot be used before a call has been started.
256 * @param value Array to push.
257 * @param size Size of array.
259 * @error Called before a call has been started.
261 native Call_PushArray(const {Handle,Float,Function,_}:value[], size);
264 * Pushes an array onto the current call.
266 * @note Cannot be used before a call has been started.
268 * @param value Array to push.
269 * @param size Size of array.
270 * @param cpflags Whether or not changes should be copied back to the input array.
271 * See SP_PARAM_* constants for details.
273 * @error Called before a call has been started.
275 native Call_PushArrayEx({Handle,Float,Function,_}:value[], size, cpflags);
278 * Pushes a string onto the current call.
280 * @note Changes to string are not copied back to caller. Use PushStringEx() to do this.
281 * @note Cannot be used before a call has been started.
283 * @param value String to push.
285 * @error Called before a call has been started.
287 native Call_PushString(const String:value[]);
290 * Pushes a string onto the current call.
292 * @note Cannot be used before a call has been started.
294 * @param value String to push.
295 * @param length Length of string buffer.
296 * @param szflags Flags determining how string should be handled.
297 * See SP_PARAM_STRING_* constants for details.
298 * @param cpflags Whether or not changes should be copied back to the input array.
299 * See SP_PARAM_* constants for details.
301 * @error Called before a call has been started.
303 native Call_PushStringEx(String:value[], length, szflags, cpflags);
306 * Completes a call to a function or forward's call list.
308 * @note Cannot be used before a call has been started.
310 * @param result Return value of function or forward's call list.
311 * @return SP_ERROR_NONE on success, any other integer on failure.
312 * @error Called before a call has been started.
314 native Call_Finish(&result);
317 * Cancels a call to a function or forward's call list.
319 * @note Cannot be used before a call has been started.
322 * @error Called before a call has been started.
324 native Call_Cancel();
327 * Defines a native function.
329 * It is not necessary to validate the parameter count
331 * @param plugin Handle of the calling plugin.
332 * @param numParams Number of parameters passed to the native.
333 * @return Value for the native call to return.
335 functag NativeCall public(Handle:plugin, numParams);
338 * Creates a dynamic native. This should only be called in AskPluginLoad(), or
339 * else you risk not having your native shared with other plugins.
341 * @param name Name of the dynamic native; must be unique amongst
342 * all other registered dynamic native.s
343 * @param func Function to use as the dynamic native.
346 native CreateNative(const String:name[], NativeCall:func);
349 * Throws an error in the calling plugin of a native, instead of your own plugin.
351 * @param error Error code to use.
352 * @param fmt Error message format.
353 * @param ... Format arguments.
355 native ThrowNativeError(error, const String:fmt[], any:...);
358 * Retrieves the string length from a native parameter string. This is useful
359 * fetching the entire string using dynamic arrays.
360 * @note If this function succeeds, Get/SetNativeString will also succeed.
362 * @param param Parameter number, starting from 1.
363 * @param length Stores the length of the string.
364 * @return SP_ERROR_NONE on success, any other integer on failure.
365 * @error Invalid parameter number or calling from a non-native function.
367 native GetNativeStringLength(param, &length);
370 * Retrieves a string from a native parameter.
371 * @note Output conditions are undefined on failure.
373 * @param param Parameter number, starting from 1.
374 * @param buffer Buffer to store the string in.
375 * @param maxlength Maximum length of the buffer.
376 * @param bytes Optionally store the number of bytes written.
377 * @return SP_ERROR_NONE on success, any other integer on failure.
378 * @error Invalid parameter number or calling from a non-native function.
380 native GetNativeString(param, String:buffer[], maxlength, &bytes=0);
383 * Sets a string in a native parameter.
384 * @note Output conditions are undefined on failure.
386 * @param param Parameter number, starting from 1.
387 * @param source Source string to use.
388 * @param maxlength Maximum number of bytes to write.
389 * @param utf8 If false, string will not be written
391 * @param bytes Optionally store the number of bytes written.
392 * @return SP_ERROR_NONE on success, any other integer on failure.
393 * @error Invalid parameter number or calling from a non-native function.
395 native SetNativeString(param, const String:source[], maxlength, bool:utf8=true, &bytes=0);
398 * Gets a cell from a native parameter.
400 * @param param Parameter number, starting from 1.
401 * @return Cell value at the parameter number.
402 * @error Invalid parameter number or calling from a non-native function.
404 native GetNativeCell(param);
407 * Gets a cell from a native parameter, by reference.
409 * @param param Parameter number, starting from 1.
410 * @return Cell value at the parameter number.
411 * @error Invalid parameter number or calling from a non-native function.
413 native GetNativeCellRef(param);
416 * Sets a cell from a native parameter, by reference.
418 * @param param Parameter number, starting from 1.
419 * @param value Cell value at the parameter number to set by reference.
421 * @error Invalid parameter number or calling from a non-native function.
423 native SetNativeCellRef(param, {Float,Function,Handle,_}:value);
426 * Gets an array from a native parameter (always by reference).
428 * @param param Parameter number, starting from 1.
429 * @param local Local array to copy into.
430 * @param size Maximum size of local array.
431 * @return SP_ERROR_NONE on success, anything else on failure.
432 * @error Invalid parameter number or calling from a non-native function.
434 native GetNativeArray(param, {Float,Function,Handle,_}:local[], size);
437 * Copies a local array into a native parameter array (always by reference).
439 * @param param Parameter number, starting from 1.
440 * @param local Local array to copy from.
441 * @param size Size of the local array to copy.
442 * @return SP_ERROR_NONE on success, anything else on failure.
443 * @error Invalid parameter number or calling from a non-native function.
445 native SetNativeArray(param, const {Float,Function,Handle,_}:local[], size);
448 * Formats a string using parameters from a native.
450 * @note All parameter indexes start at 1.
451 * @note If the input and output buffers overlap, the contents
452 * of the output buffer at the end is undefined.
454 * @param out_param Output parameter number to write to. If 0, out_string is used.
455 * @param fmt_param Format parameter number. If 0, fmt_string is used.
456 * @param vararg_param First variable parameter number.
457 * @param out_len Output string buffer maximum length (always required).
458 * @param written Optionally stores the number of bytes written.
459 * @param out_string Output string buffer to use if out_param is not used.
460 * @param fmt_string Format string to use if fmt_param is not used.
461 * @return SP_ERROR_NONE on success, anything else on failure.
463 native FormatNativeString(out_param,
468 String:out_string[]="",
469 const String:fmt_string[]="");
471 stock Float:GetNativeFloat(param, bool:byref)
475 return Float:GetNativeCell(param);
477 return Float:GetNativeCellRef(param);
480 stock Handle:GetNativeHandle(param, bool:byref)
484 return Handle:GetNativeCell(param);
486 return Handle:GetNativeCellRef(param);
