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 #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()
65 #define SM_PARAM_COPYBACK (1<<0) /**< Copy an array/reference back after call */
67 #define SM_PARAM_STRING_UTF8 (1<<0) /**< String should be UTF-8 handled */
68 #define SM_PARAM_STRING_COPY (1<<1) /**< String should be copied into the plugin */
69 #define SM_PARAM_STRING_BINARY (1<<2) /**< Treat the string as a binary string */
76 * @section Error codes
78 #define SP_ERROR_NONE 0 /**< No error occurred */
79 #define SP_ERROR_FILE_FORMAT 1 /**< File format unrecognized */
80 #define SP_ERROR_DECOMPRESSOR 2 /**< A decompressor was not found */
81 #define SP_ERROR_HEAPLOW 3 /**< Not enough space left on the heap */
82 #define SP_ERROR_PARAM 4 /**< Invalid parameter or parameter type */
83 #define SP_ERROR_INVALID_ADDRESS 5 /**< A memory address was not valid */
84 #define SP_ERROR_NOT_FOUND 6 /**< The object in question was not found */
85 #define SP_ERROR_INDEX 7 /**< Invalid index parameter */
86 #define SP_ERROR_STACKLOW 8 /**< Nnot enough space left on the stack */
87 #define SP_ERROR_NOTDEBUGGING 9 /**< Debug mode was not on or debug section not found */
88 #define SP_ERROR_INVALID_INSTRUCTION 10 /**< Invalid instruction was encountered */
89 #define SP_ERROR_MEMACCESS 11 /**< Invalid memory access */
90 #define SP_ERROR_STACKMIN 12 /**< Stack went beyond its minimum value */
91 #define SP_ERROR_HEAPMIN 13 /**< Heap went beyond its minimum value */
92 #define SP_ERROR_DIVIDE_BY_ZERO 14 /**< Division by zero */
93 #define SP_ERROR_ARRAY_BOUNDS 15 /**< Array index is out of bounds */
94 #define SP_ERROR_INSTRUCTION_PARAM 16 /**< Instruction had an invalid parameter */
95 #define SP_ERROR_STACKLEAK 17 /**< A native leaked an item on the stack */
96 #define SP_ERROR_HEAPLEAK 18 /**< A native leaked an item on the heap */
97 #define SP_ERROR_ARRAY_TOO_BIG 19 /**< A dynamic array is too big */
98 #define SP_ERROR_TRACKER_BOUNDS 20 /**< Tracker stack is out of bounds */
99 #define SP_ERROR_INVALID_NATIVE 21 /**< Native was pending or invalid */
100 #define SP_ERROR_PARAMS_MAX 22 /**< Maximum number of parameters reached */
101 #define SP_ERROR_NATIVE 23 /**< Error originates from a native */
102 #define SP_ERROR_NOT_RUNNABLE 24 /**< Function or plugin is not runnable */
103 #define SP_ERROR_ABORTED 25 /**< Function call was aborted */
110 * Gets a function id from a function name.
112 * @param plugin Handle of the plugin that contains the function.
113 Pass INVALID_HANDLE to search in the calling plugin.
114 * @param name Name of the function.
115 * @return Function id or INVALID_FUNCTION if not found.
116 * @error Invalid or corrupt plugin handle.
118 native Function:GetFunctionByName(Handle:plugin, const String:name[]);
121 * Creates a global forward.
123 * @note The name used to create the forward is used as its public function in all target plugins.
124 * @note This is ideal for global, static forwards that are never changed.
125 * @note Global forwards cannot be cloned.
126 * @note Use CloseHandle() to destroy these.
128 * @param name Name of public function to use in forward.
129 * @param type Execution type to be used.
130 * @param ... Variable number of parameter types (up to 32).
131 * @return Handle to new global forward.
132 * @error More than 32 paramater types passed.
134 native Handle:CreateGlobalForward(const String:name[], ExecType:type, ParamType:...);
137 * Creates a private forward.
139 * @note No functions are automatically added. Use AddToForward() to do this.
140 * @note Private forwards can be cloned.
141 * @note Use CloseHandle() to destroy these.
143 * @param type Execution type to be used.
144 * @param ... Variable number of parameter types (up to 32).
145 * @return Handle to new private forward.
146 * @error More than 32 paramater types passed.
148 native Handle:CreateForward(ExecType:type, ParamType:...);
151 * Returns the number of functions in a global or private forward's call list.
153 * @param fwd Handle to global or private forward.
154 * @return Number of functions in forward.
155 * @error Invalid or corrupt forward handle.
157 native GetForwardFunctionCount(Handle:fwd);
160 * Adds a function to a private forward's call list.
162 * @note Cannot be used during an incompleted call.
164 * @param fwd Handle to private forward.
165 * @param plugin Handle of the plugin that contains the function.
166 * Pass INVALID_HANDLE to specify the calling plugin.
167 * @param func Function to add to forward.
168 * @return True on success, false otherwise.
169 * @error Invalid or corrupt private forward handle, invalid or corrupt plugin handle, or invalid function.
171 native bool:AddToForward(Handle:fwd, Handle:plugin, Function:func);
174 * Removes a function from a private forward's call list.
176 * @note Only removes one instance.
177 * @note Functions will be removed automatically if their parent plugin is unloaded.
179 * @param fwd Handle to private forward.
180 * @param plugin Handle of the plugin that contains the function.
181 * Pass INVALID_HANDLE to specify the calling plugin.
182 * @param func Function to remove from forward.
183 * @return True on success, false otherwise.
184 * @error Invalid or corrupt private forward handle, invalid or corrupt plugin handle, or invalid function.
186 native bool:RemoveFromForward(Handle:fwd, Handle:plugin, Function:func);
189 * Removes all instances of a plugin from a private forward's call list.
191 * @note Functions will be removed automatically if their parent plugin is unloaded.
193 * @param fwd Handle to private forward.
194 * @param plugin Handle of the plugin to remove instances of.
195 * Pass INVALID_HANDLE to specify the calling plugin.
196 * @return Number of functions removed from forward.
197 * @error Invalid or corrupt private forward handle or invalid or corrupt plugin handle.
199 native RemoveAllFromForward(Handle:fwd, Handle:plugin);
202 * Starts a call to functions in a forward's call list.
204 * @note Cannot be used during an incompleted call.
206 * @param fwd Handle to global or private forward.
208 * @error Invalid or corrupt forward handle or called before another call has completed.
210 native Call_StartForward(Handle:fwd);
213 * Starts a call to a function.
215 * @note Cannot be used during an incompleted call.
217 * @param plugin Handle of the plugin that contains the function.
218 * Pass INVALID_HANDLE to specify the calling plugin.
219 * @param func Function to call.
221 * @error Invalid or corrupt plugin handle, invalid function, or called before another call has completed.
223 native Call_StartFunction(Handle:plugin, Function:func);
226 * Pushes a cell onto the current call.
228 * @note Cannot be used before a call has been started.
230 * @param value Cell value to push.
232 * @error Called before a call has been started.
234 native Call_PushCell(any:value);
237 * Pushes a cell by reference onto the current call.
239 * @note Cannot be used before a call has been started.
241 * @param value Cell reference to push.
243 * @error Called before a call has been started.
245 native Call_PushCellRef(&any:value);
248 * Pushes a float onto the current call.
250 * @note Cannot be used before a call has been started.
252 * @param value Floating point value to push.
254 * @error Called before a call has been started.
256 native Call_PushFloat(Float:value);
259 * Pushes a float by reference onto the current call.
261 * @note Cannot be used before a call has been started.
263 * @param value Floating point reference to push.
265 * @error Called before a call has been started.
267 native Call_PushFloatRef(&Float:value);
270 * Pushes an array onto the current call.
272 * @note Changes to array are not copied back to caller. Use PushArrayEx() to do this.
273 * @note Cannot be used before a call has been started.
275 * @param value Array to push.
276 * @param size Size of array.
278 * @error Called before a call has been started.
280 native Call_PushArray(const any:value[], size);
283 * Pushes an array onto the current call.
285 * @note Cannot be used before a call has been started.
287 * @param value Array to push.
288 * @param size Size of array.
289 * @param cpflags Whether or not changes should be copied back to the input array.
290 * See SP_PARAM_* constants for details.
292 * @error Called before a call has been started.
294 native Call_PushArrayEx(any:value[], size, cpflags);
297 * Pushes a string onto the current call.
299 * @note Changes to string are not copied back to caller. Use PushStringEx() to do this.
300 * @note Cannot be used before a call has been started.
302 * @param value String to push.
304 * @error Called before a call has been started.
306 native Call_PushString(const String:value[]);
309 * Pushes a string onto the current call.
311 * @note Cannot be used before a call has been started.
313 * @param value String to push.
314 * @param length Length of string buffer.
315 * @param szflags Flags determining how string should be handled.
316 * See SP_PARAM_STRING_* constants for details.
317 * The default (0) is to push ASCII.
318 * @param cpflags Whether or not changes should be copied back to the input array.
319 * See SP_PARAM_* constants for details.
321 * @error Called before a call has been started.
323 native Call_PushStringEx(String:value[], length, szflags, cpflags);
326 * Completes a call to a function or forward's call list.
328 * @note Cannot be used before a call has been started.
330 * @param result Return value of function or forward's call list.
331 * @return SP_ERROR_NONE on success, any other integer on failure.
332 * @error Called before a call has been started.
334 native Call_Finish(&any:result=0);
337 * Cancels a call to a function or forward's call list.
339 * @note Cannot be used before a call has been started.
342 * @error Called before a call has been started.
344 native Call_Cancel();
347 * Defines a native function.
349 * It is not necessary to validate the parameter count
351 * @param plugin Handle of the calling plugin.
352 * @param numParams Number of parameters passed to the native.
353 * @return Value for the native call to return.
355 functag NativeCall public(Handle:plugin, numParams);
358 * Creates a dynamic native. This should only be called in AskPluginLoad(), or
359 * else you risk not having your native shared with other plugins.
361 * @param name Name of the dynamic native; must be unique amongst
362 * all other registered dynamic natives.
363 * @param func Function to use as the dynamic native.
366 native CreateNative(const String:name[], NativeCall:func);
369 * Throws an error in the calling plugin of a native, instead of your own plugin.
371 * @param error Error code to use.
372 * @param fmt Error message format.
373 * @param ... Format arguments.
375 native ThrowNativeError(error, const String:fmt[], any:...);
378 * Retrieves the string length from a native parameter string. This is useful
379 * fetching the entire string using dynamic arrays.
380 * @note If this function succeeds, Get/SetNativeString will also succeed.
382 * @param param Parameter number, starting from 1.
383 * @param length Stores the length of the string.
384 * @return SP_ERROR_NONE on success, any other integer on failure.
385 * @error Invalid parameter number or calling from a non-native function.
387 native GetNativeStringLength(param, &length);
390 * Retrieves a string from a native parameter.
391 * @note Output conditions are undefined on failure.
393 * @param param Parameter number, starting from 1.
394 * @param buffer Buffer to store the string in.
395 * @param maxlength Maximum length of the buffer.
396 * @param bytes Optionally store the number of bytes written.
397 * @return SP_ERROR_NONE on success, any other integer on failure.
398 * @error Invalid parameter number or calling from a non-native function.
400 native GetNativeString(param, String:buffer[], maxlength, &bytes=0);
403 * Sets a string in a native parameter.
404 * @note Output conditions are undefined on failure.
406 * @param param Parameter number, starting from 1.
407 * @param source Source string to use.
408 * @param maxlength Maximum number of bytes to write.
409 * @param utf8 If false, string will not be written
411 * @param bytes Optionally store the number of bytes written.
412 * @return SP_ERROR_NONE on success, any other integer on failure.
413 * @error Invalid parameter number or calling from a non-native function.
415 native SetNativeString(param, const String:source[], maxlength, bool:utf8=true, &bytes=0);
418 * Gets a cell from a native parameter.
420 * @param param Parameter number, starting from 1.
421 * @return Cell value at the parameter number.
422 * @error Invalid parameter number or calling from a non-native function.
424 native any:GetNativeCell(param);
427 * Gets a cell from a native parameter, by reference.
429 * @param param Parameter number, starting from 1.
430 * @return Cell value at the parameter number.
431 * @error Invalid parameter number or calling from a non-native function.
433 native any:GetNativeCellRef(param);
436 * Sets a cell from a native parameter, by reference.
438 * @param param Parameter number, starting from 1.
439 * @param value Cell value at the parameter number to set by reference.
441 * @error Invalid parameter number or calling from a non-native function.
443 native SetNativeCellRef(param, any:value);
446 * Gets an array from a native parameter (always by reference).
448 * @param param Parameter number, starting from 1.
449 * @param local Local array to copy into.
450 * @param size Maximum size of local array.
451 * @return SP_ERROR_NONE on success, anything else on failure.
452 * @error Invalid parameter number or calling from a non-native function.
454 native GetNativeArray(param, any:local[], size);
457 * Copies a local array into a native parameter array (always by reference).
459 * @param param Parameter number, starting from 1.
460 * @param local Local array to copy from.
461 * @param size Size of the local array to copy.
462 * @return SP_ERROR_NONE on success, anything else on failure.
463 * @error Invalid parameter number or calling from a non-native function.
465 native SetNativeArray(param, const any:local[], size);
468 * Formats a string using parameters from a native.
470 * @note All parameter indexes start at 1.
471 * @note If the input and output buffers overlap, the contents
472 * of the output buffer at the end is undefined.
474 * @param out_param Output parameter number to write to. If 0, out_string is used.
475 * @param fmt_param Format parameter number. If 0, fmt_string is used.
476 * @param vararg_param First variable parameter number.
477 * @param out_len Output string buffer maximum length (always required).
478 * @param written Optionally stores the number of bytes written.
479 * @param out_string Output string buffer to use if out_param is not used.
480 * @param fmt_string Format string to use if fmt_param is not used.
481 * @return SP_ERROR_NONE on success, anything else on failure.
483 native FormatNativeString(out_param,
488 String:out_string[]="",
489 const String:fmt_string[]="");
