ds@1331: /**
dvander@601: * vim: set ts=4 :
ds@1330: * =============================================================================
dvander@601: * SourceMod (C)2004-2007 AlliedModders LLC. All rights reserved.
ds@1330: * =============================================================================
ds@1330: *
ds@1330: * This file is part of the SourceMod/SourcePawn SDK.
dvander@601: *
ds@1330: * This program is free software; you can redistribute it and/or modify it under
ds@1330: * the terms of the GNU General Public License, version 3.0, as published by the
ds@1330: * Free Software Foundation.
ds@1330: *
ds@1330: * This program is distributed in the hope that it will be useful, but WITHOUT
ds@1330: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
ds@1330: * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
ds@1330: * details.
ds@1330: *
ds@1330: * You should have received a copy of the GNU General Public License along with
ds@1330: * this program. If not, see .
ds@1330: *
ds@1330: * As a special exception, AlliedModders LLC gives you permission to link the
ds@1330: * code of this program (as well as its derivative works) to "Half-Life 2," the
ds@1330: * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software
ds@1330: * by the Valve Corporation. You must obey the GNU General Public License in
ds@1330: * all respects for all other code used. Additionally, AlliedModders LLC grants
ds@1330: * this exception to all derivative works. AlliedModders LLC defines further
ds@1330: * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),
ds@1330: * or .
dvander@601: *
dvander@601: * Version: $Id$
dvander@601: */
dvander@601:
ds@621: #define SP_PARAMFLAG_BYREF (1<<0) /**< Internal use only. */
ds@621:
ds@621: /**
ds@621: * Describes the various ways to pass parameters to functions or forwards.
ds@621: */
ds@621: enum ParamType
ds@621: {
ds@621: Param_Any = 0, /**< Any data type can be pushed */
ds@621: Param_Cell = (1<<1), /**< Only basic cells can be pushed */
ds@621: Param_Float = (2<<1), /**< Only floats can be pushed */
ds@621: Param_String = (3<<1)|SP_PARAMFLAG_BYREF, /**< Only strings can be pushed */
ds@621: Param_Array = (4<<1)|SP_PARAMFLAG_BYREF, /**< Only arrays can be pushed */
ds@621: Param_VarArgs = (5<<1), /**< Same as "..." in plugins, anything can be pushed, but it will always be byref */
ds@621: Param_CellByRef = (1<<1)|SP_PARAMFLAG_BYREF, /**< Only a cell by reference can be pushed */
ds@621: Param_FloatByRef = (2<<1)|SP_PARAMFLAG_BYREF /**< Only a float by reference can be pushed */
ds@621: };
ds@621:
ds@621: /**
ds@621: * Defines how a forward iterates through plugin functions.
ds@621: */
ds@621: enum ExecType
ds@621: {
ds@621: ET_Ignore = 0, /**< Ignore all return values, return 0 */
ds@621: ET_Single = 1, /**< Only return the last exec, ignore all others */
ds@621: ET_Event = 2, /**< Acts as an event with the Actions defined in core.inc, no mid-Stops allowed, returns highest */
ds@621: ET_Hook = 3 /**< Acts as a hook with the Actions defined in core.inc, mid-Stops allowed, returns highest */
ds@621: };
ds@621:
ds@621: /**
ds@621: * @section Flags that are used with Call_PushArrayEx() and Call_PushStringEx()
ds@621: */
ds@621: #define SM_PARAM_COPYBACK (1<<0) /**< Copy an array/reference back after call */
ds@621: #define SM_PARAM_STRING_UTF8 (1<<0) /**< String should be UTF-8 handled */
ds@621: #define SM_PARAM_STRING_COPY (1<<1) /**< String should be copied into the plugin */
ds@621:
ds@621: /**
ds@621: * @endsection
ds@621: */
ds@621:
ds@621: /**
ds@621: * @section Error codes
ds@621: */
dvander@601: #define SP_ERROR_NONE 0 /**< No error occurred */
dvander@601: #define SP_ERROR_FILE_FORMAT 1 /**< File format unrecognized */
dvander@601: #define SP_ERROR_DECOMPRESSOR 2 /**< A decompressor was not found */
dvander@601: #define SP_ERROR_HEAPLOW 3 /**< Not enough space left on the heap */
dvander@601: #define SP_ERROR_PARAM 4 /**< Invalid parameter or parameter type */
dvander@601: #define SP_ERROR_INVALID_ADDRESS 5 /**< A memory address was not valid */
dvander@601: #define SP_ERROR_NOT_FOUND 6 /**< The object in question was not found */
dvander@601: #define SP_ERROR_INDEX 7 /**< Invalid index parameter */
dvander@601: #define SP_ERROR_STACKLOW 8 /**< Nnot enough space left on the stack */
dvander@601: #define SP_ERROR_NOTDEBUGGING 9 /**< Debug mode was not on or debug section not found */
dvander@601: #define SP_ERROR_INVALID_INSTRUCTION 10 /**< Invalid instruction was encountered */
dvander@601: #define SP_ERROR_MEMACCESS 11 /**< Invalid memory access */
dvander@601: #define SP_ERROR_STACKMIN 12 /**< Stack went beyond its minimum value */
dvander@601: #define SP_ERROR_HEAPMIN 13 /**< Heap went beyond its minimum value */
dvander@601: #define SP_ERROR_DIVIDE_BY_ZERO 14 /**< Division by zero */
dvander@601: #define SP_ERROR_ARRAY_BOUNDS 15 /**< Array index is out of bounds */
dvander@601: #define SP_ERROR_INSTRUCTION_PARAM 16 /**< Instruction had an invalid parameter */
dvander@601: #define SP_ERROR_STACKLEAK 17 /**< A native leaked an item on the stack */
dvander@601: #define SP_ERROR_HEAPLEAK 18 /**< A native leaked an item on the heap */
dvander@601: #define SP_ERROR_ARRAY_TOO_BIG 19 /**< A dynamic array is too big */
dvander@601: #define SP_ERROR_TRACKER_BOUNDS 20 /**< Tracker stack is out of bounds */
dvander@601: #define SP_ERROR_INVALID_NATIVE 21 /**< Native was pending or invalid */
dvander@601: #define SP_ERROR_PARAMS_MAX 22 /**< Maximum number of parameters reached */
dvander@601: #define SP_ERROR_NATIVE 23 /**< Error originates from a native */
dvander@601: #define SP_ERROR_NOT_RUNNABLE 24 /**< Function or plugin is not runnable */
dvander@601: #define SP_ERROR_ABORTED 25 /**< Function call was aborted */
dvander@601:
dvander@601: /**
ds@621: * @endsection
ds@621: */
ds@621:
ds@621: /**
ds@621: * Gets a function id from a function name.
ds@621: *
ds@621: * @param plugin Handle of the plugin that contains the function.
ds@621: Pass INVALID_HANDLE to search in the calling plugin.
ds@621: * @param name Name of the function.
ds@621: * @return Function id or INVALID_FUNCTION if not found.
ds@621: * @error Invalid or corrupt plugin handle.
ds@621: */
ds@621: native Function:GetFunctionByName(Handle:plugin, const String:name[]);
ds@621:
ds@621: /**
ds@621: * Creates a global forward.
ds@621: *
ds@621: * @note The name used to create the forward is used as its public function in all target plugins.
ds@621: * @note This is ideal for global, static forwards that are never changed.
ds@635: * @note Global forwards cannot be cloned.
ds@635: * @note Use CloseHandle() to destroy these.
ds@621: *
ds@621: * @param name Name of public function to use in forward.
ds@621: * @param type Execution type to be used.
ds@621: * @param ... Variable number of parameter types (up to 32).
ds@621: * @return Handle to new global forward.
ds@621: * @error More than 32 paramater types passed.
ds@621: */
ds@634: native Handle:CreateGlobalForward(const String:name[], ExecType:type, ParamType:...);
ds@621:
ds@621: /**
ds@621: * Creates a private forward.
ds@621: *
ds@621: * @note No functions are automatically added. Use AddToForward() to do this.
ds@635: * @note Private forwards can be cloned.
ds@635: * @note Use CloseHandle() to destroy these.
ds@621: *
ds@621: * @param type Execution type to be used.
ds@621: * @param ... Variable number of parameter types (up to 32).
ds@621: * @return Handle to new private forward.
ds@621: * @error More than 32 paramater types passed.
ds@621: */
ds@634: native Handle:CreateForward(ExecType:type, ParamType:...);
ds@621:
ds@621: /**
ds@621: * Returns the number of functions in a global or private forward's call list.
ds@621: *
ds@621: * @param fwd Handle to global or private forward.
ds@621: * @return Number of functions in forward.
ds@621: * @error Invalid or corrupt forward handle.
ds@621: */
ds@621: native GetForwardFunctionCount(Handle:fwd);
ds@621:
ds@621: /**
ds@621: * Adds a function to a private forward's call list.
ds@621: *
ds@621: * @note Cannot be used during an incompleted call.
ds@621: *
ds@621: * @param fwd Handle to private forward.
ds@621: * @param plugin Handle of the plugin that contains the function.
ds@621: * Pass INVALID_HANDLE to specify the calling plugin.
ds@621: * @param func Function to add to forward.
ds@621: * @return True on success, false otherwise.
ds@621: * @error Invalid or corrupt private forward handle, invalid or corrupt plugin handle, or invalid function.
ds@621: */
ds@621: native bool:AddToForward(Handle:fwd, Handle:plugin, Function:func);
ds@621:
ds@621: /**
ds@621: * Removes a function from a private forward's call list.
ds@621: *
ds@621: * @note Only removes one instance.
ds@621: * @note Functions will be removed automatically if their parent plugin is unloaded.
ds@621: *
ds@621: * @param fwd Handle to private forward.
ds@621: * @param plugin Handle of the plugin that contains the function.
ds@621: * Pass INVALID_HANDLE to specify the calling plugin.
ds@621: * @param func Function to remove from forward.
ds@621: * @return True on success, false otherwise.
ds@621: * @error Invalid or corrupt private forward handle, invalid or corrupt plugin handle, or invalid function.
ds@621: */
ds@621: native bool:RemoveFromForward(Handle:fwd, Handle:plugin, Function:func);
ds@621:
ds@621: /**
ds@621: * Removes all instances of a plugin from a private forward's call list.
ds@621: *
ds@621: * @note Functions will be removed automatically if their parent plugin is unloaded.
ds@621: *
ds@621: * @param fwd Handle to private forward.
ds@621: * @param plugin Handle of the plugin to remove instances of.
ds@621: * Pass INVALID_HANDLE to specify the calling plugin.
ds@621: * @return Number of functions removed from forward.
ds@621: * @error Invalid or corrupt private forward handle or invalid or corrupt plugin handle.
ds@621: */
ds@621: native RemoveAllFromForward(Handle:fwd, Handle:plugin);
ds@621:
ds@621: /**
ds@621: * Starts a call to functions in a forward's call list.
ds@621: *
ds@621: * @note Cannot be used during an incompleted call.
ds@621: *
ds@621: * @param fwd Handle to global or private forward.
ds@621: * @noreturn
ds@621: * @error Invalid or corrupt forward handle or called before another call has completed.
ds@621: */
ds@621: native Call_StartForward(Handle:fwd);
ds@621:
ds@621: /**
ds@621: * Starts a call to a function.
ds@621: *
ds@621: * @note Cannot be used during an incompleted call.
ds@621: *
ds@621: * @param plugin Handle of the plugin that contains the function.
ds@621: * Pass INVALID_HANDLE to specify the calling plugin.
ds@621: * @param func Function to call.
ds@621: * @noreturn
ds@621: * @error Invalid or corrupt plugin handle, invalid function, or called before another call has completed.
ds@621: */
ds@621: native Call_StartFunction(Handle:plugin, Function:func);
ds@621:
ds@621: /**
ds@621: * Pushes a cell onto the current call.
ds@621: *
ds@621: * @note Cannot be used before a call has been started.
ds@621: *
ds@621: * @param value Cell value to push.
ds@621: * @noreturn
ds@621: * @error Called before a call has been started.
ds@621: */
dvander@815: native Call_PushCell(any:value);
ds@621:
ds@621: /**
ds@621: * Pushes a cell by reference onto the current call.
ds@621: *
ds@621: * @note Cannot be used before a call has been started.
ds@621: *
ds@621: * @param value Cell reference to push.
ds@621: * @noreturn
ds@621: * @error Called before a call has been started.
ds@621: */
dvander@815: native Call_PushCellRef(&any:value);
ds@621:
ds@621: /**
ds@621: * Pushes a float onto the current call.
ds@621: *
ds@621: * @note Cannot be used before a call has been started.
ds@621: *
ds@621: * @param value Floating point value to push.
ds@621: * @noreturn
ds@621: * @error Called before a call has been started.
ds@621: */
ds@621: native Call_PushFloat(Float:value);
ds@621:
ds@621: /**
ds@621: * Pushes a float by reference onto the current call.
ds@621: *
ds@621: * @note Cannot be used before a call has been started.
ds@621: *
ds@621: * @param value Floating point reference to push.
ds@621: * @noreturn
ds@621: * @error Called before a call has been started.
ds@621: */
ds@621: native Call_PushFloatRef(&Float:value);
ds@621:
ds@621: /**
ds@621: * Pushes an array onto the current call.
ds@621: *
ds@621: * @note Changes to array are not copied back to caller. Use PushArrayEx() to do this.
ds@621: * @note Cannot be used before a call has been started.
ds@621: *
ds@621: * @param value Array to push.
ds@621: * @param size Size of array.
ds@621: * @noreturn
ds@621: * @error Called before a call has been started.
ds@621: */
dvander@815: native Call_PushArray(const any:value[], size);
ds@621:
ds@621: /**
ds@621: * Pushes an array onto the current call.
ds@621: *
ds@621: * @note Cannot be used before a call has been started.
ds@621: *
ds@621: * @param value Array to push.
ds@621: * @param size Size of array.
ds@621: * @param cpflags Whether or not changes should be copied back to the input array.
ds@621: * See SP_PARAM_* constants for details.
ds@621: * @noreturn
ds@621: * @error Called before a call has been started.
ds@621: */
dvander@815: native Call_PushArrayEx(any:value[], size, cpflags);
ds@621:
ds@621: /**
ds@621: * Pushes a string onto the current call.
ds@621: *
ds@621: * @note Changes to string are not copied back to caller. Use PushStringEx() to do this.
ds@621: * @note Cannot be used before a call has been started.
ds@621: *
ds@621: * @param value String to push.
ds@621: * @noreturn
ds@621: * @error Called before a call has been started.
ds@621: */
ds@621: native Call_PushString(const String:value[]);
ds@621:
ds@621: /**
ds@621: * Pushes a string onto the current call.
ds@621: *
ds@621: * @note Cannot be used before a call has been started.
ds@621: *
ds@621: * @param value String to push.
ds@621: * @param length Length of string buffer.
ds@621: * @param szflags Flags determining how string should be handled.
ds@621: * See SP_PARAM_STRING_* constants for details.
ds@621: * @param cpflags Whether or not changes should be copied back to the input array.
ds@621: * See SP_PARAM_* constants for details.
ds@621: * @noreturn
ds@621: * @error Called before a call has been started.
ds@621: */
ds@621: native Call_PushStringEx(String:value[], length, szflags, cpflags);
ds@621:
ds@621: /**
ds@621: * Completes a call to a function or forward's call list.
ds@621: *
ds@621: * @note Cannot be used before a call has been started.
ds@621: *
ds@621: * @param result Return value of function or forward's call list.
ds@621: * @return SP_ERROR_NONE on success, any other integer on failure.
ds@621: * @error Called before a call has been started.
ds@621: */
dvander@982: native Call_Finish(&any:result=0);
ds@621:
ds@621: /**
ds@621: * Cancels a call to a function or forward's call list.
ds@621: *
ds@621: * @note Cannot be used before a call has been started.
ds@621: *
ds@621: * @noreturn
ds@621: * @error Called before a call has been started.
ds@621: */
ds@621: native Call_Cancel();
ds@621:
ds@621: /**
dvander@601: * Defines a native function.
dvander@601: *
dvander@601: * It is not necessary to validate the parameter count
dvander@601: *
dvander@601: * @param plugin Handle of the calling plugin.
dvander@601: * @param numParams Number of parameters passed to the native.
dvander@601: * @return Value for the native call to return.
dvander@601: */
dvander@601: functag NativeCall public(Handle:plugin, numParams);
dvander@601:
dvander@601: /**
dvander@601: * Creates a dynamic native. This should only be called in AskPluginLoad(), or
dvander@601: * else you risk not having your native shared with other plugins.
dvander@601: *
dvander@601: * @param name Name of the dynamic native; must be unique amongst
dvander@764: * all other registered dynamic natives.
dvander@601: * @param func Function to use as the dynamic native.
dvander@601: * @noreturn
dvander@601: */
dvander@601: native CreateNative(const String:name[], NativeCall:func);
dvander@601:
dvander@601: /**
dvander@601: * Throws an error in the calling plugin of a native, instead of your own plugin.
dvander@601: *
dvander@601: * @param error Error code to use.
dvander@601: * @param fmt Error message format.
dvander@601: * @param ... Format arguments.
dvander@601: */
ds@634: native ThrowNativeError(error, const String:fmt[], any:...);
dvander@601:
dvander@601: /**
dvander@601: * Retrieves the string length from a native parameter string. This is useful
dvander@601: * fetching the entire string using dynamic arrays.
dvander@601: * @note If this function succeeds, Get/SetNativeString will also succeed.
dvander@601: *
dvander@601: * @param param Parameter number, starting from 1.
dvander@601: * @param length Stores the length of the string.
ds@621: * @return SP_ERROR_NONE on success, any other integer on failure.
dvander@601: * @error Invalid parameter number or calling from a non-native function.
dvander@601: */
dvander@601: native GetNativeStringLength(param, &length);
dvander@601:
dvander@601: /**
dvander@601: * Retrieves a string from a native parameter.
dvander@601: * @note Output conditions are undefined on failure.
dvander@601: *
dvander@601: * @param param Parameter number, starting from 1.
dvander@601: * @param buffer Buffer to store the string in.
dvander@601: * @param maxlength Maximum length of the buffer.
dvander@601: * @param bytes Optionally store the number of bytes written.
dvander@601: * @return SP_ERROR_NONE on success, any other integer on failure.
dvander@601: * @error Invalid parameter number or calling from a non-native function.
dvander@601: */
dvander@601: native GetNativeString(param, String:buffer[], maxlength, &bytes=0);
dvander@601:
dvander@601: /**
dvander@601: * Sets a string in a native parameter.
dvander@601: * @note Output conditions are undefined on failure.
dvander@601: *
dvander@601: * @param param Parameter number, starting from 1.
dvander@601: * @param source Source string to use.
dvander@601: * @param maxlength Maximum number of bytes to write.
dvander@601: * @param utf8 If false, string will not be written
dvander@601: * with UTF8 safety.
dvander@601: * @param bytes Optionally store the number of bytes written.
dvander@601: * @return SP_ERROR_NONE on success, any other integer on failure.
dvander@601: * @error Invalid parameter number or calling from a non-native function.
dvander@601: */
dvander@601: native SetNativeString(param, const String:source[], maxlength, bool:utf8=true, &bytes=0);
dvander@601:
dvander@601: /**
dvander@601: * Gets a cell from a native parameter.
dvander@601: *
dvander@601: * @param param Parameter number, starting from 1.
dvander@601: * @return Cell value at the parameter number.
dvander@601: * @error Invalid parameter number or calling from a non-native function.
dvander@601: */
ds@872: native any:GetNativeCell(param);
dvander@601:
dvander@601: /**
dvander@601: * Gets a cell from a native parameter, by reference.
dvander@601: *
dvander@601: * @param param Parameter number, starting from 1.
dvander@601: * @return Cell value at the parameter number.
dvander@601: * @error Invalid parameter number or calling from a non-native function.
dvander@601: */
ds@872: native any:GetNativeCellRef(param);
dvander@601:
dvander@601: /**
dvander@601: * Sets a cell from a native parameter, by reference.
dvander@601: *
dvander@601: * @param param Parameter number, starting from 1.
dvander@601: * @param value Cell value at the parameter number to set by reference.
dvander@601: * @noreturn
dvander@601: * @error Invalid parameter number or calling from a non-native function.
dvander@601: */
dvander@815: native SetNativeCellRef(param, any:value);
dvander@601:
dvander@601: /**
dvander@601: * Gets an array from a native parameter (always by reference).
dvander@601: *
dvander@601: * @param param Parameter number, starting from 1.
dvander@601: * @param local Local array to copy into.
dvander@601: * @param size Maximum size of local array.
dvander@601: * @return SP_ERROR_NONE on success, anything else on failure.
dvander@601: * @error Invalid parameter number or calling from a non-native function.
dvander@601: */
dvander@815: native GetNativeArray(param, any:local[], size);
dvander@601:
dvander@601: /**
dvander@601: * Copies a local array into a native parameter array (always by reference).
dvander@601: *
dvander@601: * @param param Parameter number, starting from 1.
dvander@601: * @param local Local array to copy from.
dvander@601: * @param size Size of the local array to copy.
dvander@601: * @return SP_ERROR_NONE on success, anything else on failure.
dvander@601: * @error Invalid parameter number or calling from a non-native function.
dvander@601: */
dvander@815: native SetNativeArray(param, const any:local[], size);
dvander@601:
dvander@601: /**
dvander@601: * Formats a string using parameters from a native.
dvander@601: *
dvander@601: * @note All parameter indexes start at 1.
dvander@601: * @note If the input and output buffers overlap, the contents
dvander@601: * of the output buffer at the end is undefined.
dvander@601: *
dvander@601: * @param out_param Output parameter number to write to. If 0, out_string is used.
dvander@601: * @param fmt_param Format parameter number. If 0, fmt_string is used.
dvander@601: * @param vararg_param First variable parameter number.
dvander@601: * @param out_len Output string buffer maximum length (always required).
dvander@601: * @param written Optionally stores the number of bytes written.
dvander@601: * @param out_string Output string buffer to use if out_param is not used.
dvander@601: * @param fmt_string Format string to use if fmt_param is not used.
dvander@601: * @return SP_ERROR_NONE on success, anything else on failure.
dvander@601: */
dvander@601: native FormatNativeString(out_param,
dvander@601: fmt_param,
dvander@601: vararg_param,
dvander@601: out_len,
dvander@601: &written=0,
dvander@601: String:out_string[]="",
dvander@601: const String:fmt_string[]="");
dvander@601:
ds@872: /**
ds@872: * Backwards compatibility stock - use GetNativeCell or GetNativeCellRef
ds@872: *
ds@872: * @deprecated
ds@872: */
ds@1268: #pragma deprecated Use GetNativeCell() or GetNativeCellRef() instead
dvander@601: stock Float:GetNativeFloat(param, bool:byref)
dvander@601: {
dvander@601: if (!byref)
dvander@601: {
dvander@601: return Float:GetNativeCell(param);
dvander@601: } else {
dvander@601: return Float:GetNativeCellRef(param);
dvander@601: }
dvander@601: }
ds@872:
ds@872: /**
ds@872: * Backwards compatibility stock - use GetNativeCell or GetNativeCellRef
ds@872: *
ds@872: * @deprecated
ds@872: */
ds@1268: #pragma deprecated Use GetNativeCell() or GetNativeCellRef() instead
dvander@601: stock Handle:GetNativeHandle(param, bool:byref)
dvander@601: {
dvander@601: if (!byref)
dvander@601: {
dvander@601: return Handle:GetNativeCell(param);
dvander@601: } else {
dvander@601: return Handle:GetNativeCellRef(param);
dvander@601: }
dvander@601: }