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(any: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(&any:value);
228 * Pushes a float onto the current call.
230 * @note Cannot be used before a call has been started.
232 * @param value Floating point value to push.
234 * @error Called before a call has been started.
236 native Call_PushFloat(Float:value);
239 * Pushes a float by reference onto the current call.
241 * @note Cannot be used before a call has been started.
243 * @param value Floating point reference to push.
245 * @error Called before a call has been started.
247 native Call_PushFloatRef(&Float:value);
250 * Pushes an array onto the current call.
252 * @note Changes to array are not copied back to caller. Use PushArrayEx() to do this.
253 * @note Cannot be used before a call has been started.
255 * @param value Array to push.
256 * @param size Size of array.
258 * @error Called before a call has been started.
260 native Call_PushArray(const any:value[], size);
263 * Pushes an array onto the current call.
265 * @note Cannot be used before a call has been started.
267 * @param value Array to push.
268 * @param size Size of array.
269 * @param cpflags Whether or not changes should be copied back to the input array.
270 * See SP_PARAM_* constants for details.
272 * @error Called before a call has been started.
274 native Call_PushArrayEx(any:value[], size, cpflags);
277 * Pushes a string onto the current call.
279 * @note Changes to string are not copied back to caller. Use PushStringEx() to do this.
280 * @note Cannot be used before a call has been started.
282 * @param value String to push.
284 * @error Called before a call has been started.
286 native Call_PushString(const String:value[]);
289 * Pushes a string onto the current call.
291 * @note Cannot be used before a call has been started.
293 * @param value String to push.
294 * @param length Length of string buffer.
295 * @param szflags Flags determining how string should be handled.
296 * See SP_PARAM_STRING_* constants for details.
297 * @param cpflags Whether or not changes should be copied back to the input array.
298 * See SP_PARAM_* constants for details.
300 * @error Called before a call has been started.
302 native Call_PushStringEx(String:value[], length, szflags, cpflags);
305 * Completes a call to a function or forward's call list.
307 * @note Cannot be used before a call has been started.
309 * @param result Return value of function or forward's call list.
310 * @return SP_ERROR_NONE on success, any other integer on failure.
311 * @error Called before a call has been started.
313 native Call_Finish(&any:result=0);
316 * Cancels a call to a function or forward's call list.
318 * @note Cannot be used before a call has been started.
321 * @error Called before a call has been started.
323 native Call_Cancel();
326 * Defines a native function.
328 * It is not necessary to validate the parameter count
330 * @param plugin Handle of the calling plugin.
331 * @param numParams Number of parameters passed to the native.
332 * @return Value for the native call to return.
334 functag NativeCall public(Handle:plugin, numParams);
337 * Creates a dynamic native. This should only be called in AskPluginLoad(), or
338 * else you risk not having your native shared with other plugins.
340 * @param name Name of the dynamic native; must be unique amongst
341 * all other registered dynamic natives.
342 * @param func Function to use as the dynamic native.
345 native CreateNative(const String:name[], NativeCall:func);
348 * Throws an error in the calling plugin of a native, instead of your own plugin.
350 * @param error Error code to use.
351 * @param fmt Error message format.
352 * @param ... Format arguments.
354 native ThrowNativeError(error, const String:fmt[], any:...);
357 * Retrieves the string length from a native parameter string. This is useful
358 * fetching the entire string using dynamic arrays.
359 * @note If this function succeeds, Get/SetNativeString will also succeed.
361 * @param param Parameter number, starting from 1.
362 * @param length Stores the length of the string.
363 * @return SP_ERROR_NONE on success, any other integer on failure.
364 * @error Invalid parameter number or calling from a non-native function.
366 native GetNativeStringLength(param, &length);
369 * Retrieves a string from a native parameter.
370 * @note Output conditions are undefined on failure.
372 * @param param Parameter number, starting from 1.
373 * @param buffer Buffer to store the string in.
374 * @param maxlength Maximum length of the buffer.
375 * @param bytes Optionally store the number of bytes written.
376 * @return SP_ERROR_NONE on success, any other integer on failure.
377 * @error Invalid parameter number or calling from a non-native function.
379 native GetNativeString(param, String:buffer[], maxlength, &bytes=0);
382 * Sets a string in a native parameter.
383 * @note Output conditions are undefined on failure.
385 * @param param Parameter number, starting from 1.
386 * @param source Source string to use.
387 * @param maxlength Maximum number of bytes to write.
388 * @param utf8 If false, string will not be written
390 * @param bytes Optionally store the number of bytes written.
391 * @return SP_ERROR_NONE on success, any other integer on failure.
392 * @error Invalid parameter number or calling from a non-native function.
394 native SetNativeString(param, const String:source[], maxlength, bool:utf8=true, &bytes=0);
397 * Gets a cell from a native parameter.
399 * @param param Parameter number, starting from 1.
400 * @return Cell value at the parameter number.
401 * @error Invalid parameter number or calling from a non-native function.
403 native any:GetNativeCell(param);
406 * Gets a cell from a native parameter, by reference.
408 * @param param Parameter number, starting from 1.
409 * @return Cell value at the parameter number.
410 * @error Invalid parameter number or calling from a non-native function.
412 native any:GetNativeCellRef(param);
415 * Sets a cell from a native parameter, by reference.
417 * @param param Parameter number, starting from 1.
418 * @param value Cell value at the parameter number to set by reference.
420 * @error Invalid parameter number or calling from a non-native function.
422 native SetNativeCellRef(param, any:value);
425 * Gets an array from a native parameter (always by reference).
427 * @param param Parameter number, starting from 1.
428 * @param local Local array to copy into.
429 * @param size Maximum size of local array.
430 * @return SP_ERROR_NONE on success, anything else on failure.
431 * @error Invalid parameter number or calling from a non-native function.
433 native GetNativeArray(param, any:local[], size);
436 * Copies a local array into a native parameter array (always by reference).
438 * @param param Parameter number, starting from 1.
439 * @param local Local array to copy from.
440 * @param size Size of the local array to copy.
441 * @return SP_ERROR_NONE on success, anything else on failure.
442 * @error Invalid parameter number or calling from a non-native function.
444 native SetNativeArray(param, const any:local[], size);
447 * Formats a string using parameters from a native.
449 * @note All parameter indexes start at 1.
450 * @note If the input and output buffers overlap, the contents
451 * of the output buffer at the end is undefined.
453 * @param out_param Output parameter number to write to. If 0, out_string is used.
454 * @param fmt_param Format parameter number. If 0, fmt_string is used.
455 * @param vararg_param First variable parameter number.
456 * @param out_len Output string buffer maximum length (always required).
457 * @param written Optionally stores the number of bytes written.
458 * @param out_string Output string buffer to use if out_param is not used.
459 * @param fmt_string Format string to use if fmt_param is not used.
460 * @return SP_ERROR_NONE on success, anything else on failure.
462 native FormatNativeString(out_param,
467 String:out_string[]="",
468 const String:fmt_string[]="");
471 * Backwards compatibility stock - use GetNativeCell or GetNativeCellRef
475 #pragma deprecated Use GetNativeCell() or GetNativeCellRef() instead
476 stock Float:GetNativeFloat(param, bool:byref)
480 return Float:GetNativeCell(param);
482 return Float:GetNativeCellRef(param);
487 * Backwards compatibility stock - use GetNativeCell or GetNativeCellRef
491 #pragma deprecated Use GetNativeCell() or GetNativeCellRef() instead
492 stock Handle:GetNativeHandle(param, bool:byref)
496 return Handle:GetNativeCell(param);
498 return Handle:GetNativeCellRef(param);
