1.1 --- a/plugins/include/functions.inc Fri Mar 28 06:21:34 2008 +0000
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,517 +0,0 @@
1.4 -/**
1.5 - * vim: set ts=4 :
1.6 - * =============================================================================
1.7 - * SourceMod (C)2004-2007 AlliedModders LLC. All rights reserved.
1.8 - * =============================================================================
1.9 - *
1.10 - * This file is part of the SourceMod/SourcePawn SDK.
1.11 - *
1.12 - * This program is free software; you can redistribute it and/or modify it under
1.13 - * the terms of the GNU General Public License, version 3.0, as published by the
1.14 - * Free Software Foundation.
1.15 - *
1.16 - * This program is distributed in the hope that it will be useful, but WITHOUT
1.17 - * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
1.18 - * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
1.19 - * details.
1.20 - *
1.21 - * You should have received a copy of the GNU General Public License along with
1.22 - * this program. If not, see <http://www.gnu.org/licenses/>.
1.23 - *
1.24 - * As a special exception, AlliedModders LLC gives you permission to link the
1.25 - * code of this program (as well as its derivative works) to "Half-Life 2," the
1.26 - * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software
1.27 - * by the Valve Corporation. You must obey the GNU General Public License in
1.28 - * all respects for all other code used. Additionally, AlliedModders LLC grants
1.29 - * this exception to all derivative works. AlliedModders LLC defines further
1.30 - * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),
1.31 - * or <http://www.sourcemod.net/license.php>.
1.32 - *
1.33 - * Version: $Id$
1.34 - */
1.35 -
1.36 -#define SP_PARAMFLAG_BYREF (1<<0) /**< Internal use only. */
1.37 -
1.38 -/**
1.39 - * Describes the various ways to pass parameters to functions or forwards.
1.40 - */
1.41 -enum ParamType
1.42 -{
1.43 - Param_Any = 0, /**< Any data type can be pushed */
1.44 - Param_Cell = (1<<1), /**< Only basic cells can be pushed */
1.45 - Param_Float = (2<<1), /**< Only floats can be pushed */
1.46 - Param_String = (3<<1)|SP_PARAMFLAG_BYREF, /**< Only strings can be pushed */
1.47 - Param_Array = (4<<1)|SP_PARAMFLAG_BYREF, /**< Only arrays can be pushed */
1.48 - Param_VarArgs = (5<<1), /**< Same as "..." in plugins, anything can be pushed, but it will always be byref */
1.49 - Param_CellByRef = (1<<1)|SP_PARAMFLAG_BYREF, /**< Only a cell by reference can be pushed */
1.50 - Param_FloatByRef = (2<<1)|SP_PARAMFLAG_BYREF /**< Only a float by reference can be pushed */
1.51 -};
1.52 -
1.53 -/**
1.54 - * Defines how a forward iterates through plugin functions.
1.55 - */
1.56 -enum ExecType
1.57 -{
1.58 - ET_Ignore = 0, /**< Ignore all return values, return 0 */
1.59 - ET_Single = 1, /**< Only return the last exec, ignore all others */
1.60 - ET_Event = 2, /**< Acts as an event with the Actions defined in core.inc, no mid-Stops allowed, returns highest */
1.61 - ET_Hook = 3 /**< Acts as a hook with the Actions defined in core.inc, mid-Stops allowed, returns highest */
1.62 -};
1.63 -
1.64 -/**
1.65 - * @section Flags that are used with Call_PushArrayEx() and Call_PushStringEx()
1.66 - */
1.67 -#define SM_PARAM_COPYBACK (1<<0) /**< Copy an array/reference back after call */
1.68 -#define SM_PARAM_STRING_UTF8 (1<<0) /**< String should be UTF-8 handled */
1.69 -#define SM_PARAM_STRING_COPY (1<<1) /**< String should be copied into the plugin */
1.70 -
1.71 -/**
1.72 - * @endsection
1.73 - */
1.74 -
1.75 -/**
1.76 - * @section Error codes
1.77 - */
1.78 -#define SP_ERROR_NONE 0 /**< No error occurred */
1.79 -#define SP_ERROR_FILE_FORMAT 1 /**< File format unrecognized */
1.80 -#define SP_ERROR_DECOMPRESSOR 2 /**< A decompressor was not found */
1.81 -#define SP_ERROR_HEAPLOW 3 /**< Not enough space left on the heap */
1.82 -#define SP_ERROR_PARAM 4 /**< Invalid parameter or parameter type */
1.83 -#define SP_ERROR_INVALID_ADDRESS 5 /**< A memory address was not valid */
1.84 -#define SP_ERROR_NOT_FOUND 6 /**< The object in question was not found */
1.85 -#define SP_ERROR_INDEX 7 /**< Invalid index parameter */
1.86 -#define SP_ERROR_STACKLOW 8 /**< Nnot enough space left on the stack */
1.87 -#define SP_ERROR_NOTDEBUGGING 9 /**< Debug mode was not on or debug section not found */
1.88 -#define SP_ERROR_INVALID_INSTRUCTION 10 /**< Invalid instruction was encountered */
1.89 -#define SP_ERROR_MEMACCESS 11 /**< Invalid memory access */
1.90 -#define SP_ERROR_STACKMIN 12 /**< Stack went beyond its minimum value */
1.91 -#define SP_ERROR_HEAPMIN 13 /**< Heap went beyond its minimum value */
1.92 -#define SP_ERROR_DIVIDE_BY_ZERO 14 /**< Division by zero */
1.93 -#define SP_ERROR_ARRAY_BOUNDS 15 /**< Array index is out of bounds */
1.94 -#define SP_ERROR_INSTRUCTION_PARAM 16 /**< Instruction had an invalid parameter */
1.95 -#define SP_ERROR_STACKLEAK 17 /**< A native leaked an item on the stack */
1.96 -#define SP_ERROR_HEAPLEAK 18 /**< A native leaked an item on the heap */
1.97 -#define SP_ERROR_ARRAY_TOO_BIG 19 /**< A dynamic array is too big */
1.98 -#define SP_ERROR_TRACKER_BOUNDS 20 /**< Tracker stack is out of bounds */
1.99 -#define SP_ERROR_INVALID_NATIVE 21 /**< Native was pending or invalid */
1.100 -#define SP_ERROR_PARAMS_MAX 22 /**< Maximum number of parameters reached */
1.101 -#define SP_ERROR_NATIVE 23 /**< Error originates from a native */
1.102 -#define SP_ERROR_NOT_RUNNABLE 24 /**< Function or plugin is not runnable */
1.103 -#define SP_ERROR_ABORTED 25 /**< Function call was aborted */
1.104 -
1.105 -/**
1.106 - * @endsection
1.107 - */
1.108 -
1.109 -/**
1.110 - * Gets a function id from a function name.
1.111 - *
1.112 - * @param plugin Handle of the plugin that contains the function.
1.113 - Pass INVALID_HANDLE to search in the calling plugin.
1.114 - * @param name Name of the function.
1.115 - * @return Function id or INVALID_FUNCTION if not found.
1.116 - * @error Invalid or corrupt plugin handle.
1.117 - */
1.118 -native Function:GetFunctionByName(Handle:plugin, const String:name[]);
1.119 -
1.120 -/**
1.121 - * Creates a global forward.
1.122 - *
1.123 - * @note The name used to create the forward is used as its public function in all target plugins.
1.124 - * @note This is ideal for global, static forwards that are never changed.
1.125 - * @note Global forwards cannot be cloned.
1.126 - * @note Use CloseHandle() to destroy these.
1.127 - *
1.128 - * @param name Name of public function to use in forward.
1.129 - * @param type Execution type to be used.
1.130 - * @param ... Variable number of parameter types (up to 32).
1.131 - * @return Handle to new global forward.
1.132 - * @error More than 32 paramater types passed.
1.133 - */
1.134 -native Handle:CreateGlobalForward(const String:name[], ExecType:type, ParamType:...);
1.135 -
1.136 -/**
1.137 - * Creates a private forward.
1.138 - *
1.139 - * @note No functions are automatically added. Use AddToForward() to do this.
1.140 - * @note Private forwards can be cloned.
1.141 - * @note Use CloseHandle() to destroy these.
1.142 - *
1.143 - * @param type Execution type to be used.
1.144 - * @param ... Variable number of parameter types (up to 32).
1.145 - * @return Handle to new private forward.
1.146 - * @error More than 32 paramater types passed.
1.147 - */
1.148 -native Handle:CreateForward(ExecType:type, ParamType:...);
1.149 -
1.150 -/**
1.151 - * Returns the number of functions in a global or private forward's call list.
1.152 - *
1.153 - * @param fwd Handle to global or private forward.
1.154 - * @return Number of functions in forward.
1.155 - * @error Invalid or corrupt forward handle.
1.156 - */
1.157 -native GetForwardFunctionCount(Handle:fwd);
1.158 -
1.159 -/**
1.160 - * Adds a function to a private forward's call list.
1.161 - *
1.162 - * @note Cannot be used during an incompleted call.
1.163 - *
1.164 - * @param fwd Handle to private forward.
1.165 - * @param plugin Handle of the plugin that contains the function.
1.166 - * Pass INVALID_HANDLE to specify the calling plugin.
1.167 - * @param func Function to add to forward.
1.168 - * @return True on success, false otherwise.
1.169 - * @error Invalid or corrupt private forward handle, invalid or corrupt plugin handle, or invalid function.
1.170 - */
1.171 -native bool:AddToForward(Handle:fwd, Handle:plugin, Function:func);
1.172 -
1.173 -/**
1.174 - * Removes a function from a private forward's call list.
1.175 - *
1.176 - * @note Only removes one instance.
1.177 - * @note Functions will be removed automatically if their parent plugin is unloaded.
1.178 - *
1.179 - * @param fwd Handle to private forward.
1.180 - * @param plugin Handle of the plugin that contains the function.
1.181 - * Pass INVALID_HANDLE to specify the calling plugin.
1.182 - * @param func Function to remove from forward.
1.183 - * @return True on success, false otherwise.
1.184 - * @error Invalid or corrupt private forward handle, invalid or corrupt plugin handle, or invalid function.
1.185 - */
1.186 -native bool:RemoveFromForward(Handle:fwd, Handle:plugin, Function:func);
1.187 -
1.188 -/**
1.189 - * Removes all instances of a plugin from a private forward's call list.
1.190 - *
1.191 - * @note Functions will be removed automatically if their parent plugin is unloaded.
1.192 - *
1.193 - * @param fwd Handle to private forward.
1.194 - * @param plugin Handle of the plugin to remove instances of.
1.195 - * Pass INVALID_HANDLE to specify the calling plugin.
1.196 - * @return Number of functions removed from forward.
1.197 - * @error Invalid or corrupt private forward handle or invalid or corrupt plugin handle.
1.198 - */
1.199 -native RemoveAllFromForward(Handle:fwd, Handle:plugin);
1.200 -
1.201 -/**
1.202 - * Starts a call to functions in a forward's call list.
1.203 - *
1.204 - * @note Cannot be used during an incompleted call.
1.205 - *
1.206 - * @param fwd Handle to global or private forward.
1.207 - * @noreturn
1.208 - * @error Invalid or corrupt forward handle or called before another call has completed.
1.209 - */
1.210 -native Call_StartForward(Handle:fwd);
1.211 -
1.212 -/**
1.213 - * Starts a call to a function.
1.214 - *
1.215 - * @note Cannot be used during an incompleted call.
1.216 - *
1.217 - * @param plugin Handle of the plugin that contains the function.
1.218 - * Pass INVALID_HANDLE to specify the calling plugin.
1.219 - * @param func Function to call.
1.220 - * @noreturn
1.221 - * @error Invalid or corrupt plugin handle, invalid function, or called before another call has completed.
1.222 - */
1.223 -native Call_StartFunction(Handle:plugin, Function:func);
1.224 -
1.225 -/**
1.226 - * Pushes a cell onto the current call.
1.227 - *
1.228 - * @note Cannot be used before a call has been started.
1.229 - *
1.230 - * @param value Cell value to push.
1.231 - * @noreturn
1.232 - * @error Called before a call has been started.
1.233 - */
1.234 -native Call_PushCell(any:value);
1.235 -
1.236 -/**
1.237 - * Pushes a cell by reference onto the current call.
1.238 - *
1.239 - * @note Cannot be used before a call has been started.
1.240 - *
1.241 - * @param value Cell reference to push.
1.242 - * @noreturn
1.243 - * @error Called before a call has been started.
1.244 - */
1.245 -native Call_PushCellRef(&any:value);
1.246 -
1.247 -/**
1.248 - * Pushes a float onto the current call.
1.249 - *
1.250 - * @note Cannot be used before a call has been started.
1.251 - *
1.252 - * @param value Floating point value to push.
1.253 - * @noreturn
1.254 - * @error Called before a call has been started.
1.255 - */
1.256 -native Call_PushFloat(Float:value);
1.257 -
1.258 -/**
1.259 - * Pushes a float by reference onto the current call.
1.260 - *
1.261 - * @note Cannot be used before a call has been started.
1.262 - *
1.263 - * @param value Floating point reference to push.
1.264 - * @noreturn
1.265 - * @error Called before a call has been started.
1.266 - */
1.267 -native Call_PushFloatRef(&Float:value);
1.268 -
1.269 -/**
1.270 - * Pushes an array onto the current call.
1.271 - *
1.272 - * @note Changes to array are not copied back to caller. Use PushArrayEx() to do this.
1.273 - * @note Cannot be used before a call has been started.
1.274 - *
1.275 - * @param value Array to push.
1.276 - * @param size Size of array.
1.277 - * @noreturn
1.278 - * @error Called before a call has been started.
1.279 - */
1.280 -native Call_PushArray(const any:value[], size);
1.281 -
1.282 -/**
1.283 - * Pushes an array onto the current call.
1.284 - *
1.285 - * @note Cannot be used before a call has been started.
1.286 - *
1.287 - * @param value Array to push.
1.288 - * @param size Size of array.
1.289 - * @param cpflags Whether or not changes should be copied back to the input array.
1.290 - * See SP_PARAM_* constants for details.
1.291 - * @noreturn
1.292 - * @error Called before a call has been started.
1.293 - */
1.294 -native Call_PushArrayEx(any:value[], size, cpflags);
1.295 -
1.296 -/**
1.297 - * Pushes a string onto the current call.
1.298 - *
1.299 - * @note Changes to string are not copied back to caller. Use PushStringEx() to do this.
1.300 - * @note Cannot be used before a call has been started.
1.301 - *
1.302 - * @param value String to push.
1.303 - * @noreturn
1.304 - * @error Called before a call has been started.
1.305 - */
1.306 -native Call_PushString(const String:value[]);
1.307 -
1.308 -/**
1.309 - * Pushes a string onto the current call.
1.310 - *
1.311 - * @note Cannot be used before a call has been started.
1.312 - *
1.313 - * @param value String to push.
1.314 - * @param length Length of string buffer.
1.315 - * @param szflags Flags determining how string should be handled.
1.316 - * See SP_PARAM_STRING_* constants for details.
1.317 - * @param cpflags Whether or not changes should be copied back to the input array.
1.318 - * See SP_PARAM_* constants for details.
1.319 - * @noreturn
1.320 - * @error Called before a call has been started.
1.321 - */
1.322 -native Call_PushStringEx(String:value[], length, szflags, cpflags);
1.323 -
1.324 -/**
1.325 - * Completes a call to a function or forward's call list.
1.326 - *
1.327 - * @note Cannot be used before a call has been started.
1.328 - *
1.329 - * @param result Return value of function or forward's call list.
1.330 - * @return SP_ERROR_NONE on success, any other integer on failure.
1.331 - * @error Called before a call has been started.
1.332 - */
1.333 -native Call_Finish(&any:result=0);
1.334 -
1.335 -/**
1.336 - * Cancels a call to a function or forward's call list.
1.337 - *
1.338 - * @note Cannot be used before a call has been started.
1.339 - *
1.340 - * @noreturn
1.341 - * @error Called before a call has been started.
1.342 - */
1.343 -native Call_Cancel();
1.344 -
1.345 -/**
1.346 - * Defines a native function.
1.347 - *
1.348 - * It is not necessary to validate the parameter count
1.349 - *
1.350 - * @param plugin Handle of the calling plugin.
1.351 - * @param numParams Number of parameters passed to the native.
1.352 - * @return Value for the native call to return.
1.353 - */
1.354 -functag NativeCall public(Handle:plugin, numParams);
1.355 -
1.356 -/**
1.357 - * Creates a dynamic native. This should only be called in AskPluginLoad(), or
1.358 - * else you risk not having your native shared with other plugins.
1.359 - *
1.360 - * @param name Name of the dynamic native; must be unique amongst
1.361 - * all other registered dynamic natives.
1.362 - * @param func Function to use as the dynamic native.
1.363 - * @noreturn
1.364 - */
1.365 -native CreateNative(const String:name[], NativeCall:func);
1.366 -
1.367 -/**
1.368 - * Throws an error in the calling plugin of a native, instead of your own plugin.
1.369 - *
1.370 - * @param error Error code to use.
1.371 - * @param fmt Error message format.
1.372 - * @param ... Format arguments.
1.373 - */
1.374 -native ThrowNativeError(error, const String:fmt[], any:...);
1.375 -
1.376 -/**
1.377 - * Retrieves the string length from a native parameter string. This is useful
1.378 - * fetching the entire string using dynamic arrays.
1.379 - * @note If this function succeeds, Get/SetNativeString will also succeed.
1.380 - *
1.381 - * @param param Parameter number, starting from 1.
1.382 - * @param length Stores the length of the string.
1.383 - * @return SP_ERROR_NONE on success, any other integer on failure.
1.384 - * @error Invalid parameter number or calling from a non-native function.
1.385 - */
1.386 -native GetNativeStringLength(param, &length);
1.387 -
1.388 -/**
1.389 - * Retrieves a string from a native parameter.
1.390 - * @note Output conditions are undefined on failure.
1.391 - *
1.392 - * @param param Parameter number, starting from 1.
1.393 - * @param buffer Buffer to store the string in.
1.394 - * @param maxlength Maximum length of the buffer.
1.395 - * @param bytes Optionally store the number of bytes written.
1.396 - * @return SP_ERROR_NONE on success, any other integer on failure.
1.397 - * @error Invalid parameter number or calling from a non-native function.
1.398 - */
1.399 -native GetNativeString(param, String:buffer[], maxlength, &bytes=0);
1.400 -
1.401 -/**
1.402 - * Sets a string in a native parameter.
1.403 - * @note Output conditions are undefined on failure.
1.404 - *
1.405 - * @param param Parameter number, starting from 1.
1.406 - * @param source Source string to use.
1.407 - * @param maxlength Maximum number of bytes to write.
1.408 - * @param utf8 If false, string will not be written
1.409 - * with UTF8 safety.
1.410 - * @param bytes Optionally store the number of bytes written.
1.411 - * @return SP_ERROR_NONE on success, any other integer on failure.
1.412 - * @error Invalid parameter number or calling from a non-native function.
1.413 - */
1.414 -native SetNativeString(param, const String:source[], maxlength, bool:utf8=true, &bytes=0);
1.415 -
1.416 -/**
1.417 - * Gets a cell from a native parameter.
1.418 - *
1.419 - * @param param Parameter number, starting from 1.
1.420 - * @return Cell value at the parameter number.
1.421 - * @error Invalid parameter number or calling from a non-native function.
1.422 - */
1.423 -native any:GetNativeCell(param);
1.424 -
1.425 -/**
1.426 - * Gets a cell from a native parameter, by reference.
1.427 - *
1.428 - * @param param Parameter number, starting from 1.
1.429 - * @return Cell value at the parameter number.
1.430 - * @error Invalid parameter number or calling from a non-native function.
1.431 - */
1.432 -native any:GetNativeCellRef(param);
1.433 -
1.434 -/**
1.435 - * Sets a cell from a native parameter, by reference.
1.436 - *
1.437 - * @param param Parameter number, starting from 1.
1.438 - * @param value Cell value at the parameter number to set by reference.
1.439 - * @noreturn
1.440 - * @error Invalid parameter number or calling from a non-native function.
1.441 - */
1.442 -native SetNativeCellRef(param, any:value);
1.443 -
1.444 -/**
1.445 - * Gets an array from a native parameter (always by reference).
1.446 - *
1.447 - * @param param Parameter number, starting from 1.
1.448 - * @param local Local array to copy into.
1.449 - * @param size Maximum size of local array.
1.450 - * @return SP_ERROR_NONE on success, anything else on failure.
1.451 - * @error Invalid parameter number or calling from a non-native function.
1.452 - */
1.453 -native GetNativeArray(param, any:local[], size);
1.454 -
1.455 -/**
1.456 - * Copies a local array into a native parameter array (always by reference).
1.457 - *
1.458 - * @param param Parameter number, starting from 1.
1.459 - * @param local Local array to copy from.
1.460 - * @param size Size of the local array to copy.
1.461 - * @return SP_ERROR_NONE on success, anything else on failure.
1.462 - * @error Invalid parameter number or calling from a non-native function.
1.463 - */
1.464 -native SetNativeArray(param, const any:local[], size);
1.465 -
1.466 -/**
1.467 - * Formats a string using parameters from a native.
1.468 - *
1.469 - * @note All parameter indexes start at 1.
1.470 - * @note If the input and output buffers overlap, the contents
1.471 - * of the output buffer at the end is undefined.
1.472 - *
1.473 - * @param out_param Output parameter number to write to. If 0, out_string is used.
1.474 - * @param fmt_param Format parameter number. If 0, fmt_string is used.
1.475 - * @param vararg_param First variable parameter number.
1.476 - * @param out_len Output string buffer maximum length (always required).
1.477 - * @param written Optionally stores the number of bytes written.
1.478 - * @param out_string Output string buffer to use if out_param is not used.
1.479 - * @param fmt_string Format string to use if fmt_param is not used.
1.480 - * @return SP_ERROR_NONE on success, anything else on failure.
1.481 - */
1.482 -native FormatNativeString(out_param,
1.483 - fmt_param,
1.484 - vararg_param,
1.485 - out_len,
1.486 - &written=0,
1.487 - String:out_string[]="",
1.488 - const String:fmt_string[]="");
1.489 -
1.490 -/**
1.491 - * Backwards compatibility stock - use GetNativeCell or GetNativeCellRef
1.492 - *
1.493 - * @deprecated
1.494 - */
1.495 -#pragma deprecated Use GetNativeCell() or GetNativeCellRef() instead
1.496 -stock Float:GetNativeFloat(param, bool:byref)
1.497 -{
1.498 - if (!byref)
1.499 - {
1.500 - return Float:GetNativeCell(param);
1.501 - } else {
1.502 - return Float:GetNativeCellRef(param);
1.503 - }
1.504 -}
1.505 -
1.506 -/**
1.507 - * Backwards compatibility stock - use GetNativeCell or GetNativeCellRef
1.508 - *
1.509 - * @deprecated
1.510 - */
1.511 -#pragma deprecated Use GetNativeCell() or GetNativeCellRef() instead
1.512 -stock Handle:GetNativeHandle(param, bool:byref)
1.513 -{
1.514 - if (!byref)
1.515 - {
1.516 - return Handle:GetNativeCell(param);
1.517 - } else {
1.518 - return Handle:GetNativeCellRef(param);
1.519 - }
1.520 -}
