3 * =============================================================================
4 * SourceMod (C)2004-2008 AlliedModders LLC. All rights reserved.
5 * =============================================================================
7 * This file is part of the SourceMod/SourcePawn SDK.
9 * This program is free software; you can redistribute it and/or modify it under
10 * the terms of the GNU General Public License, version 3.0, as published by the
11 * Free Software Foundation.
13 * This program is distributed in the hope that it will be useful, but WITHOUT
14 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
15 * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
18 * You should have received a copy of the GNU General Public License along with
19 * this program. If not, see <http://www.gnu.org/licenses/>.
21 * As a special exception, AlliedModders LLC gives you permission to link the
22 * code of this program (as well as its derivative works) to "Half-Life 2," the
23 * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software
24 * by the Valve Corporation. You must obey the GNU General Public License in
25 * all respects for all other code used. Additionally, AlliedModders LLC grants
26 * this exception to all derivative works. AlliedModders LLC defines further
27 * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),
28 * or <http://www.sourcemod.net/license.php>.
33 #if defined _functions_included
36 #define _functions_included
38 #define SP_PARAMFLAG_BYREF (1<<0) /**< Internal use only. */
41 * Describes the various ways to pass parameters to functions or forwards.
45 Param_Any = 0, /**< Any data type can be pushed */
46 Param_Cell = (1<<1), /**< Only basic cells can be pushed */
47 Param_Float = (2<<1), /**< Only floats can be pushed */
48 Param_String = (3<<1)|SP_PARAMFLAG_BYREF, /**< Only strings can be pushed */
49 Param_Array = (4<<1)|SP_PARAMFLAG_BYREF, /**< Only arrays can be pushed */
50 Param_VarArgs = (5<<1), /**< Same as "..." in plugins, anything can be pushed, but it will always be byref */
51 Param_CellByRef = (1<<1)|SP_PARAMFLAG_BYREF, /**< Only a cell by reference can be pushed */
52 Param_FloatByRef = (2<<1)|SP_PARAMFLAG_BYREF /**< Only a float by reference can be pushed */
56 * Defines how a forward iterates through plugin functions.
60 ET_Ignore = 0, /**< Ignore all return values, return 0 */
61 ET_Single = 1, /**< Only return the last exec, ignore all others */
62 ET_Event = 2, /**< Acts as an event with the Actions defined in core.inc, no mid-Stops allowed, returns highest */
63 ET_Hook = 3 /**< Acts as a hook with the Actions defined in core.inc, mid-Stops allowed, returns highest */
67 * @section Flags that are used with Call_PushArrayEx() and Call_PushStringEx()
70 #define SM_PARAM_COPYBACK (1<<0) /**< Copy an array/reference back after call */
72 #define SM_PARAM_STRING_UTF8 (1<<0) /**< String should be UTF-8 handled */
73 #define SM_PARAM_STRING_COPY (1<<1) /**< String should be copied into the plugin */
74 #define SM_PARAM_STRING_BINARY (1<<2) /**< Treat the string as a binary string */
81 * @section Error codes
83 #define SP_ERROR_NONE 0 /**< No error occurred */
84 #define SP_ERROR_FILE_FORMAT 1 /**< File format unrecognized */
85 #define SP_ERROR_DECOMPRESSOR 2 /**< A decompressor was not found */
86 #define SP_ERROR_HEAPLOW 3 /**< Not enough space left on the heap */
87 #define SP_ERROR_PARAM 4 /**< Invalid parameter or parameter type */
88 #define SP_ERROR_INVALID_ADDRESS 5 /**< A memory address was not valid */
89 #define SP_ERROR_NOT_FOUND 6 /**< The object in question was not found */
90 #define SP_ERROR_INDEX 7 /**< Invalid index parameter */
91 #define SP_ERROR_STACKLOW 8 /**< Nnot enough space left on the stack */
92 #define SP_ERROR_NOTDEBUGGING 9 /**< Debug mode was not on or debug section not found */
93 #define SP_ERROR_INVALID_INSTRUCTION 10 /**< Invalid instruction was encountered */
94 #define SP_ERROR_MEMACCESS 11 /**< Invalid memory access */
95 #define SP_ERROR_STACKMIN 12 /**< Stack went beyond its minimum value */
96 #define SP_ERROR_HEAPMIN 13 /**< Heap went beyond its minimum value */
97 #define SP_ERROR_DIVIDE_BY_ZERO 14 /**< Division by zero */
98 #define SP_ERROR_ARRAY_BOUNDS 15 /**< Array index is out of bounds */
99 #define SP_ERROR_INSTRUCTION_PARAM 16 /**< Instruction had an invalid parameter */
100 #define SP_ERROR_STACKLEAK 17 /**< A native leaked an item on the stack */
101 #define SP_ERROR_HEAPLEAK 18 /**< A native leaked an item on the heap */
102 #define SP_ERROR_ARRAY_TOO_BIG 19 /**< A dynamic array is too big */
103 #define SP_ERROR_TRACKER_BOUNDS 20 /**< Tracker stack is out of bounds */
104 #define SP_ERROR_INVALID_NATIVE 21 /**< Native was pending or invalid */
105 #define SP_ERROR_PARAMS_MAX 22 /**< Maximum number of parameters reached */
106 #define SP_ERROR_NATIVE 23 /**< Error originates from a native */
107 #define SP_ERROR_NOT_RUNNABLE 24 /**< Function or plugin is not runnable */
108 #define SP_ERROR_ABORTED 25 /**< Function call was aborted */
115 * Gets a function id from a function name.
117 * @param plugin Handle of the plugin that contains the function.
118 Pass INVALID_HANDLE to search in the calling plugin.
119 * @param name Name of the function.
120 * @return Function id or INVALID_FUNCTION if not found.
121 * @error Invalid or corrupt plugin handle.
123 native Function:GetFunctionByName(Handle:plugin, const String:name[]);
126 * Creates a global forward.
128 * @note The name used to create the forward is used as its public function in all target plugins.
129 * @note This is ideal for global, static forwards that are never changed.
130 * @note Global forwards cannot be cloned.
131 * @note Use CloseHandle() to destroy these.
133 * @param name Name of public function to use in forward.
134 * @param type Execution type to be used.
135 * @param ... Variable number of parameter types (up to 32).
136 * @return Handle to new global forward.
137 * @error More than 32 paramater types passed.
139 native Handle:CreateGlobalForward(const String:name[], ExecType:type, ParamType:...);
142 * Creates a private forward.
144 * @note No functions are automatically added. Use AddToForward() to do this.
145 * @note Private forwards can be cloned.
146 * @note Use CloseHandle() to destroy these.
148 * @param type Execution type to be used.
149 * @param ... Variable number of parameter types (up to 32).
150 * @return Handle to new private forward.
151 * @error More than 32 paramater types passed.
153 native Handle:CreateForward(ExecType:type, ParamType:...);
156 * Returns the number of functions in a global or private forward's call list.
158 * @param fwd Handle to global or private forward.
159 * @return Number of functions in forward.
160 * @error Invalid or corrupt forward handle.
162 native GetForwardFunctionCount(Handle:fwd);
165 * Adds a function to a private forward's call list.
167 * @note Cannot be used during an incompleted call.
169 * @param fwd Handle to private forward.
170 * @param plugin Handle of the plugin that contains the function.
171 * Pass INVALID_HANDLE to specify the calling plugin.
172 * @param func Function to add to forward.
173 * @return True on success, false otherwise.
174 * @error Invalid or corrupt private forward handle, invalid or corrupt plugin handle, or invalid function.
176 native bool:AddToForward(Handle:fwd, Handle:plugin, Function:func);
179 * Removes a function from a private forward's call list.
181 * @note Only removes one instance.
182 * @note Functions will be removed automatically if their parent plugin is unloaded.
184 * @param fwd Handle to private forward.
185 * @param plugin Handle of the plugin that contains the function.
186 * Pass INVALID_HANDLE to specify the calling plugin.
187 * @param func Function to remove from forward.
188 * @return True on success, false otherwise.
189 * @error Invalid or corrupt private forward handle, invalid or corrupt plugin handle, or invalid function.
191 native bool:RemoveFromForward(Handle:fwd, Handle:plugin, Function:func);
194 * Removes all instances of a plugin from a private forward's call list.
196 * @note Functions will be removed automatically if their parent plugin is unloaded.
198 * @param fwd Handle to private forward.
199 * @param plugin Handle of the plugin to remove instances of.
200 * Pass INVALID_HANDLE to specify the calling plugin.
201 * @return Number of functions removed from forward.
202 * @error Invalid or corrupt private forward handle or invalid or corrupt plugin handle.
204 native RemoveAllFromForward(Handle:fwd, Handle:plugin);
207 * Starts a call to functions in a forward's call list.
209 * @note Cannot be used during an incompleted call.
211 * @param fwd Handle to global or private forward.
213 * @error Invalid or corrupt forward handle or called before another call has completed.
215 native Call_StartForward(Handle:fwd);
218 * Starts a call to a function.
220 * @note Cannot be used during an incompleted call.
222 * @param plugin Handle of the plugin that contains the function.
223 * Pass INVALID_HANDLE to specify the calling plugin.
224 * @param func Function to call.
226 * @error Invalid or corrupt plugin handle, invalid function, or called before another call has completed.
228 native Call_StartFunction(Handle:plugin, Function:func);
231 * Pushes a cell onto the current call.
233 * @note Cannot be used before a call has been started.
235 * @param value Cell value to push.
237 * @error Called before a call has been started.
239 native Call_PushCell(any:value);
242 * Pushes a cell by reference onto the current call.
244 * @note Cannot be used before a call has been started.
246 * @param value Cell reference to push.
248 * @error Called before a call has been started.
250 native Call_PushCellRef(&any:value);
253 * Pushes a float onto the current call.
255 * @note Cannot be used before a call has been started.
257 * @param value Floating point value to push.
259 * @error Called before a call has been started.
261 native Call_PushFloat(Float:value);
264 * Pushes a float by reference onto the current call.
266 * @note Cannot be used before a call has been started.
268 * @param value Floating point reference to push.
270 * @error Called before a call has been started.
272 native Call_PushFloatRef(&Float:value);
275 * Pushes an array onto the current call.
277 * @note Changes to array are not copied back to caller. Use PushArrayEx() to do this.
278 * @note Cannot be used before a call has been started.
280 * @param value Array to push.
281 * @param size Size of array.
283 * @error Called before a call has been started.
285 native Call_PushArray(const any:value[], size);
288 * Pushes an array onto the current call.
290 * @note Cannot be used before a call has been started.
292 * @param value Array to push.
293 * @param size Size of array.
294 * @param cpflags Whether or not changes should be copied back to the input array.
295 * See SP_PARAM_* constants for details.
297 * @error Called before a call has been started.
299 native Call_PushArrayEx(any:value[], size, cpflags);
302 * Pushes a string onto the current call.
304 * @note Changes to string are not copied back to caller. Use PushStringEx() to do this.
305 * @note Cannot be used before a call has been started.
307 * @param value String to push.
309 * @error Called before a call has been started.
311 native Call_PushString(const String:value[]);
314 * Pushes a string onto the current call.
316 * @note Cannot be used before a call has been started.
318 * @param value String to push.
319 * @param length Length of string buffer.
320 * @param szflags Flags determining how string should be handled.
321 * See SP_PARAM_STRING_* constants for details.
322 * The default (0) is to push ASCII.
323 * @param cpflags Whether or not changes should be copied back to the input array.
324 * See SP_PARAM_* constants for details.
326 * @error Called before a call has been started.
328 native Call_PushStringEx(String:value[], length, szflags, cpflags);
331 * Completes a call to a function or forward's call list.
333 * @note Cannot be used before a call has been started.
335 * @param result Return value of function or forward's call list.
336 * @return SP_ERROR_NONE on success, any other integer on failure.
337 * @error Called before a call has been started.
339 native Call_Finish(&any:result=0);
342 * Cancels a call to a function or forward's call list.
344 * @note Cannot be used before a call has been started.
347 * @error Called before a call has been started.
349 native Call_Cancel();
352 * Defines a native function.
354 * It is not necessary to validate the parameter count
356 * @param plugin Handle of the calling plugin.
357 * @param numParams Number of parameters passed to the native.
358 * @return Value for the native call to return.
360 functag public NativeCall(Handle:plugin, numParams);
363 * Creates a dynamic native. This should only be called in AskPluginLoad(), or
364 * else you risk not having your native shared with other plugins.
366 * @param name Name of the dynamic native; must be unique amongst
367 * all other registered dynamic natives.
368 * @param func Function to use as the dynamic native.
371 native CreateNative(const String:name[], NativeCall:func);
374 * Throws an error in the calling plugin of a native, instead of your own plugin.
376 * @param error Error code to use.
377 * @param fmt Error message format.
378 * @param ... Format arguments.
380 native ThrowNativeError(error, const String:fmt[], any:...);
383 * Retrieves the string length from a native parameter string. This is useful
384 * fetching the entire string using dynamic arrays.
385 * @note If this function succeeds, Get/SetNativeString will also succeed.
387 * @param param Parameter number, starting from 1.
388 * @param length Stores the length of the string.
389 * @return SP_ERROR_NONE on success, any other integer on failure.
390 * @error Invalid parameter number or calling from a non-native function.
392 native GetNativeStringLength(param, &length);
395 * Retrieves a string from a native parameter.
396 * @note Output conditions are undefined on failure.
398 * @param param Parameter number, starting from 1.
399 * @param buffer Buffer to store the string in.
400 * @param maxlength Maximum length of the buffer.
401 * @param bytes Optionally store the number of bytes written.
402 * @return SP_ERROR_NONE on success, any other integer on failure.
403 * @error Invalid parameter number or calling from a non-native function.
405 native GetNativeString(param, String:buffer[], maxlength, &bytes=0);
408 * Sets a string in a native parameter.
409 * @note Output conditions are undefined on failure.
411 * @param param Parameter number, starting from 1.
412 * @param source Source string to use.
413 * @param maxlength Maximum number of bytes to write.
414 * @param utf8 If false, string will not be written
416 * @param bytes Optionally store the number of bytes written.
417 * @return SP_ERROR_NONE on success, any other integer on failure.
418 * @error Invalid parameter number or calling from a non-native function.
420 native SetNativeString(param, const String:source[], maxlength, bool:utf8=true, &bytes=0);
423 * Gets a cell from a native parameter.
425 * @param param Parameter number, starting from 1.
426 * @return Cell value at the parameter number.
427 * @error Invalid parameter number or calling from a non-native function.
429 native any:GetNativeCell(param);
432 * Gets a cell from a native parameter, by reference.
434 * @param param Parameter number, starting from 1.
435 * @return Cell value at the parameter number.
436 * @error Invalid parameter number or calling from a non-native function.
438 native any:GetNativeCellRef(param);
441 * Sets a cell from a native parameter, by reference.
443 * @param param Parameter number, starting from 1.
444 * @param value Cell value at the parameter number to set by reference.
446 * @error Invalid parameter number or calling from a non-native function.
448 native SetNativeCellRef(param, any:value);
451 * Gets an array from a native parameter (always by reference).
453 * @param param Parameter number, starting from 1.
454 * @param local Local array to copy into.
455 * @param size Maximum size of local array.
456 * @return SP_ERROR_NONE on success, anything else on failure.
457 * @error Invalid parameter number or calling from a non-native function.
459 native GetNativeArray(param, any:local[], size);
462 * Copies a local array into a native parameter array (always by reference).
464 * @param param Parameter number, starting from 1.
465 * @param local Local array to copy from.
466 * @param size Size of the local array to copy.
467 * @return SP_ERROR_NONE on success, anything else on failure.
468 * @error Invalid parameter number or calling from a non-native function.
470 native SetNativeArray(param, const any:local[], size);
473 * Formats a string using parameters from a native.
475 * @note All parameter indexes start at 1.
476 * @note If the input and output buffers overlap, the contents
477 * of the output buffer at the end is undefined.
479 * @param out_param Output parameter number to write to. If 0, out_string is used.
480 * @param fmt_param Format parameter number. If 0, fmt_string is used.
481 * @param vararg_param First variable parameter number.
482 * @param out_len Output string buffer maximum length (always required).
483 * @param written Optionally stores the number of bytes written.
484 * @param out_string Output string buffer to use if out_param is not used.
485 * @param fmt_string Format string to use if fmt_param is not used.
486 * @return SP_ERROR_NONE on success, anything else on failure.
488 native FormatNativeString(out_param,
493 String:out_string[]="",
494 const String:fmt_string[]="");
