3 * =============================================================================
4 * SourceMod (C)2004-2007 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 #define SP_PARAMFLAG_BYREF (1<<0) /**< Internal use only. */
36 * Describes the various ways to pass parameters to functions or forwards.
40 Param_Any = 0, /**< Any data type can be pushed */
41 Param_Cell = (1<<1), /**< Only basic cells can be pushed */
42 Param_Float = (2<<1), /**< Only floats can be pushed */
43 Param_String = (3<<1)|SP_PARAMFLAG_BYREF, /**< Only strings can be pushed */
44 Param_Array = (4<<1)|SP_PARAMFLAG_BYREF, /**< Only arrays can be pushed */
45 Param_VarArgs = (5<<1), /**< Same as "..." in plugins, anything can be pushed, but it will always be byref */
46 Param_CellByRef = (1<<1)|SP_PARAMFLAG_BYREF, /**< Only a cell by reference can be pushed */
47 Param_FloatByRef = (2<<1)|SP_PARAMFLAG_BYREF /**< Only a float by reference can be pushed */
51 * Defines how a forward iterates through plugin functions.
55 ET_Ignore = 0, /**< Ignore all return values, return 0 */
56 ET_Single = 1, /**< Only return the last exec, ignore all others */
57 ET_Event = 2, /**< Acts as an event with the Actions defined in core.inc, no mid-Stops allowed, returns highest */
58 ET_Hook = 3 /**< Acts as a hook with the Actions defined in core.inc, mid-Stops allowed, returns highest */
62 * @section Flags that are used with Call_PushArrayEx() and Call_PushStringEx()
64 #define SM_PARAM_COPYBACK (1<<0) /**< Copy an array/reference back after call */
65 #define SM_PARAM_STRING_UTF8 (1<<0) /**< String should be UTF-8 handled */
66 #define SM_PARAM_STRING_COPY (1<<1) /**< String should be copied into the plugin */
73 * @section Error codes
75 #define SP_ERROR_NONE 0 /**< No error occurred */
76 #define SP_ERROR_FILE_FORMAT 1 /**< File format unrecognized */
77 #define SP_ERROR_DECOMPRESSOR 2 /**< A decompressor was not found */
78 #define SP_ERROR_HEAPLOW 3 /**< Not enough space left on the heap */
79 #define SP_ERROR_PARAM 4 /**< Invalid parameter or parameter type */
80 #define SP_ERROR_INVALID_ADDRESS 5 /**< A memory address was not valid */
81 #define SP_ERROR_NOT_FOUND 6 /**< The object in question was not found */
82 #define SP_ERROR_INDEX 7 /**< Invalid index parameter */
83 #define SP_ERROR_STACKLOW 8 /**< Nnot enough space left on the stack */
84 #define SP_ERROR_NOTDEBUGGING 9 /**< Debug mode was not on or debug section not found */
85 #define SP_ERROR_INVALID_INSTRUCTION 10 /**< Invalid instruction was encountered */
86 #define SP_ERROR_MEMACCESS 11 /**< Invalid memory access */
87 #define SP_ERROR_STACKMIN 12 /**< Stack went beyond its minimum value */
88 #define SP_ERROR_HEAPMIN 13 /**< Heap went beyond its minimum value */
89 #define SP_ERROR_DIVIDE_BY_ZERO 14 /**< Division by zero */
90 #define SP_ERROR_ARRAY_BOUNDS 15 /**< Array index is out of bounds */
91 #define SP_ERROR_INSTRUCTION_PARAM 16 /**< Instruction had an invalid parameter */
92 #define SP_ERROR_STACKLEAK 17 /**< A native leaked an item on the stack */
93 #define SP_ERROR_HEAPLEAK 18 /**< A native leaked an item on the heap */
94 #define SP_ERROR_ARRAY_TOO_BIG 19 /**< A dynamic array is too big */
95 #define SP_ERROR_TRACKER_BOUNDS 20 /**< Tracker stack is out of bounds */
96 #define SP_ERROR_INVALID_NATIVE 21 /**< Native was pending or invalid */
97 #define SP_ERROR_PARAMS_MAX 22 /**< Maximum number of parameters reached */
98 #define SP_ERROR_NATIVE 23 /**< Error originates from a native */
99 #define SP_ERROR_NOT_RUNNABLE 24 /**< Function or plugin is not runnable */
100 #define SP_ERROR_ABORTED 25 /**< Function call was aborted */
107 * Gets a function id from a function name.
109 * @param plugin Handle of the plugin that contains the function.
110 Pass INVALID_HANDLE to search in the calling plugin.
111 * @param name Name of the function.
112 * @return Function id or INVALID_FUNCTION if not found.
113 * @error Invalid or corrupt plugin handle.
115 native Function:GetFunctionByName(Handle:plugin, const String:name[]);
118 * Creates a global forward.
120 * @note The name used to create the forward is used as its public function in all target plugins.
121 * @note This is ideal for global, static forwards that are never changed.
122 * @note Global forwards cannot be cloned.
123 * @note Use CloseHandle() to destroy these.
125 * @param name Name of public function to use in forward.
126 * @param type Execution type to be used.
127 * @param ... Variable number of parameter types (up to 32).
128 * @return Handle to new global forward.
129 * @error More than 32 paramater types passed.
131 native Handle:CreateGlobalForward(const String:name[], ExecType:type, ParamType:...);
134 * Creates a private forward.
136 * @note No functions are automatically added. Use AddToForward() to do this.
137 * @note Private forwards can be cloned.
138 * @note Use CloseHandle() to destroy these.
140 * @param type Execution type to be used.
141 * @param ... Variable number of parameter types (up to 32).
142 * @return Handle to new private forward.
143 * @error More than 32 paramater types passed.
145 native Handle:CreateForward(ExecType:type, ParamType:...);
148 * Returns the number of functions in a global or private forward's call list.
150 * @param fwd Handle to global or private forward.
151 * @return Number of functions in forward.
152 * @error Invalid or corrupt forward handle.
154 native GetForwardFunctionCount(Handle:fwd);
157 * Adds a function to a private forward's call list.
159 * @note Cannot be used during an incompleted call.
161 * @param fwd Handle to private forward.
162 * @param plugin Handle of the plugin that contains the function.
163 * Pass INVALID_HANDLE to specify the calling plugin.
164 * @param func Function to add to forward.
165 * @return True on success, false otherwise.
166 * @error Invalid or corrupt private forward handle, invalid or corrupt plugin handle, or invalid function.
168 native bool:AddToForward(Handle:fwd, Handle:plugin, Function:func);
171 * Removes a function from a private forward's call list.
173 * @note Only removes one instance.
174 * @note Functions will be removed automatically if their parent plugin is unloaded.
176 * @param fwd Handle to private forward.
177 * @param plugin Handle of the plugin that contains the function.
178 * Pass INVALID_HANDLE to specify the calling plugin.
179 * @param func Function to remove from forward.
180 * @return True on success, false otherwise.
181 * @error Invalid or corrupt private forward handle, invalid or corrupt plugin handle, or invalid function.
183 native bool:RemoveFromForward(Handle:fwd, Handle:plugin, Function:func);
186 * Removes all instances of a plugin from a private forward's call list.
188 * @note Functions will be removed automatically if their parent plugin is unloaded.
190 * @param fwd Handle to private forward.
191 * @param plugin Handle of the plugin to remove instances of.
192 * Pass INVALID_HANDLE to specify the calling plugin.
193 * @return Number of functions removed from forward.
194 * @error Invalid or corrupt private forward handle or invalid or corrupt plugin handle.
196 native RemoveAllFromForward(Handle:fwd, Handle:plugin);
199 * Starts a call to functions in a forward's call list.
201 * @note Cannot be used during an incompleted call.
203 * @param fwd Handle to global or private forward.
205 * @error Invalid or corrupt forward handle or called before another call has completed.
207 native Call_StartForward(Handle:fwd);
210 * Starts a call to a function.
212 * @note Cannot be used during an incompleted call.
214 * @param plugin Handle of the plugin that contains the function.
215 * Pass INVALID_HANDLE to specify the calling plugin.
216 * @param func Function to call.
218 * @error Invalid or corrupt plugin handle, invalid function, or called before another call has completed.
220 native Call_StartFunction(Handle:plugin, Function:func);
223 * Pushes a cell onto the current call.
225 * @note Cannot be used before a call has been started.
227 * @param value Cell value to push.
229 * @error Called before a call has been started.
231 native Call_PushCell(any:value);
234 * Pushes a cell by reference onto the current call.
236 * @note Cannot be used before a call has been started.
238 * @param value Cell reference to push.
240 * @error Called before a call has been started.
242 native Call_PushCellRef(&any:value);
245 * Pushes a float onto the current call.
247 * @note Cannot be used before a call has been started.
249 * @param value Floating point value to push.
251 * @error Called before a call has been started.
253 native Call_PushFloat(Float:value);
256 * Pushes a float by reference onto the current call.
258 * @note Cannot be used before a call has been started.
260 * @param value Floating point reference to push.
262 * @error Called before a call has been started.
264 native Call_PushFloatRef(&Float:value);
267 * Pushes an array onto the current call.
269 * @note Changes to array are not copied back to caller. Use PushArrayEx() to do this.
270 * @note Cannot be used before a call has been started.
272 * @param value Array to push.
273 * @param size Size of array.
275 * @error Called before a call has been started.
277 native Call_PushArray(const any:value[], size);
280 * Pushes an array onto the current call.
282 * @note Cannot be used before a call has been started.
284 * @param value Array to push.
285 * @param size Size of array.
286 * @param cpflags Whether or not changes should be copied back to the input array.
287 * See SP_PARAM_* constants for details.
289 * @error Called before a call has been started.
291 native Call_PushArrayEx(any:value[], size, cpflags);
294 * Pushes a string onto the current call.
296 * @note Changes to string are not copied back to caller. Use PushStringEx() to do this.
297 * @note Cannot be used before a call has been started.
299 * @param value String to push.
301 * @error Called before a call has been started.
303 native Call_PushString(const String:value[]);
306 * Pushes a string onto the current call.
308 * @note Cannot be used before a call has been started.
310 * @param value String to push.
311 * @param length Length of string buffer.
312 * @param szflags Flags determining how string should be handled.
313 * See SP_PARAM_STRING_* constants for details.
314 * @param cpflags Whether or not changes should be copied back to the input array.
315 * See SP_PARAM_* constants for details.
317 * @error Called before a call has been started.
319 native Call_PushStringEx(String:value[], length, szflags, cpflags);
322 * Completes a call to a function or forward's call list.
324 * @note Cannot be used before a call has been started.
326 * @param result Return value of function or forward's call list.
327 * @return SP_ERROR_NONE on success, any other integer on failure.
328 * @error Called before a call has been started.
330 native Call_Finish(&any:result=0);
333 * Cancels a call to a function or forward's call list.
335 * @note Cannot be used before a call has been started.
338 * @error Called before a call has been started.
340 native Call_Cancel();
343 * Defines a native function.
345 * It is not necessary to validate the parameter count
347 * @param plugin Handle of the calling plugin.
348 * @param numParams Number of parameters passed to the native.
349 * @return Value for the native call to return.
351 functag NativeCall public(Handle:plugin, numParams);
354 * Creates a dynamic native. This should only be called in AskPluginLoad(), or
355 * else you risk not having your native shared with other plugins.
357 * @param name Name of the dynamic native; must be unique amongst
358 * all other registered dynamic natives.
359 * @param func Function to use as the dynamic native.
362 native CreateNative(const String:name[], NativeCall:func);
365 * Throws an error in the calling plugin of a native, instead of your own plugin.
367 * @param error Error code to use.
368 * @param fmt Error message format.
369 * @param ... Format arguments.
371 native ThrowNativeError(error, const String:fmt[], any:...);
374 * Retrieves the string length from a native parameter string. This is useful
375 * fetching the entire string using dynamic arrays.
376 * @note If this function succeeds, Get/SetNativeString will also succeed.
378 * @param param Parameter number, starting from 1.
379 * @param length Stores the length of the string.
380 * @return SP_ERROR_NONE on success, any other integer on failure.
381 * @error Invalid parameter number or calling from a non-native function.
383 native GetNativeStringLength(param, &length);
386 * Retrieves a string from a native parameter.
387 * @note Output conditions are undefined on failure.
389 * @param param Parameter number, starting from 1.
390 * @param buffer Buffer to store the string in.
391 * @param maxlength Maximum length of the buffer.
392 * @param bytes Optionally store the number of bytes written.
393 * @return SP_ERROR_NONE on success, any other integer on failure.
394 * @error Invalid parameter number or calling from a non-native function.
396 native GetNativeString(param, String:buffer[], maxlength, &bytes=0);
399 * Sets a string in a native parameter.
400 * @note Output conditions are undefined on failure.
402 * @param param Parameter number, starting from 1.
403 * @param source Source string to use.
404 * @param maxlength Maximum number of bytes to write.
405 * @param utf8 If false, string will not be written
407 * @param bytes Optionally store the number of bytes written.
408 * @return SP_ERROR_NONE on success, any other integer on failure.
409 * @error Invalid parameter number or calling from a non-native function.
411 native SetNativeString(param, const String:source[], maxlength, bool:utf8=true, &bytes=0);
414 * Gets a cell from a native parameter.
416 * @param param Parameter number, starting from 1.
417 * @return Cell value at the parameter number.
418 * @error Invalid parameter number or calling from a non-native function.
420 native any:GetNativeCell(param);
423 * Gets a cell from a native parameter, by reference.
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:GetNativeCellRef(param);
432 * Sets a cell from a native parameter, by reference.
434 * @param param Parameter number, starting from 1.
435 * @param value Cell value at the parameter number to set by reference.
437 * @error Invalid parameter number or calling from a non-native function.
439 native SetNativeCellRef(param, any:value);
442 * Gets an array from a native parameter (always by reference).
444 * @param param Parameter number, starting from 1.
445 * @param local Local array to copy into.
446 * @param size Maximum size of local array.
447 * @return SP_ERROR_NONE on success, anything else on failure.
448 * @error Invalid parameter number or calling from a non-native function.
450 native GetNativeArray(param, any:local[], size);
453 * Copies a local array into a native parameter array (always by reference).
455 * @param param Parameter number, starting from 1.
456 * @param local Local array to copy from.
457 * @param size Size of the local array to copy.
458 * @return SP_ERROR_NONE on success, anything else on failure.
459 * @error Invalid parameter number or calling from a non-native function.
461 native SetNativeArray(param, const any:local[], size);
464 * Formats a string using parameters from a native.
466 * @note All parameter indexes start at 1.
467 * @note If the input and output buffers overlap, the contents
468 * of the output buffer at the end is undefined.
470 * @param out_param Output parameter number to write to. If 0, out_string is used.
471 * @param fmt_param Format parameter number. If 0, fmt_string is used.
472 * @param vararg_param First variable parameter number.
473 * @param out_len Output string buffer maximum length (always required).
474 * @param written Optionally stores the number of bytes written.
475 * @param out_string Output string buffer to use if out_param is not used.
476 * @param fmt_string Format string to use if fmt_param is not used.
477 * @return SP_ERROR_NONE on success, anything else on failure.
479 native FormatNativeString(out_param,
484 String:out_string[]="",
485 const String:fmt_string[]="");
488 * Backwards compatibility stock - use GetNativeCell or GetNativeCellRef
492 #pragma deprecated Use GetNativeCell() or GetNativeCellRef() instead
493 stock Float:GetNativeFloat(param, bool:byref)
497 return Float:GetNativeCell(param);
499 return Float:GetNativeCellRef(param);
504 * Backwards compatibility stock - use GetNativeCell or GetNativeCellRef
508 #pragma deprecated Use GetNativeCell() or GetNativeCellRef() instead
509 stock Handle:GetNativeHandle(param, bool:byref)
513 return Handle:GetNativeCell(param);
515 return Handle:GetNativeCellRef(param);
