sourcemod/plugins/include/functions.inc

/**
 * vim: set ts=4 :
 * ===============================================================
 * SourceMod (C)2004-2007 AlliedModders LLC.  All rights reserved.
 * ===============================================================
 *
 *  This file is part of the SourceMod/SourcePawn SDK.  This file may only be used 
 * or modified under the Terms and Conditions of its License Agreement, which is found 
 * in LICENSE.txt.  The Terms and Conditions for making SourceMod extensions/plugins 
 * may change at any time.  To view the latest information, see:
 *   http://www.sourcemod.net/license.php
 *
 * Version: $Id$
 */
 
#define SP_ERROR_NONE					0	/**< No error occurred */
#define SP_ERROR_FILE_FORMAT			1	/**< File format unrecognized */
#define SP_ERROR_DECOMPRESSOR			2	/**< A decompressor was not found */
#define SP_ERROR_HEAPLOW				3	/**< Not enough space left on the heap */
#define SP_ERROR_PARAM					4	/**< Invalid parameter or parameter type */
#define SP_ERROR_INVALID_ADDRESS		5	/**< A memory address was not valid */
#define SP_ERROR_NOT_FOUND				6	/**< The object in question was not found */
#define SP_ERROR_INDEX					7	/**< Invalid index parameter */
#define SP_ERROR_STACKLOW				8	/**< Nnot enough space left on the stack */
#define SP_ERROR_NOTDEBUGGING			9	/**< Debug mode was not on or debug section not found */
#define SP_ERROR_INVALID_INSTRUCTION	10	/**< Invalid instruction was encountered */
#define SP_ERROR_MEMACCESS				11	/**< Invalid memory access */
#define SP_ERROR_STACKMIN				12	/**< Stack went beyond its minimum value */
#define SP_ERROR_HEAPMIN				13  /**< Heap went beyond its minimum value */
#define SP_ERROR_DIVIDE_BY_ZERO			14	/**< Division by zero */
#define SP_ERROR_ARRAY_BOUNDS			15	/**< Array index is out of bounds */
#define SP_ERROR_INSTRUCTION_PARAM		16	/**< Instruction had an invalid parameter */
#define SP_ERROR_STACKLEAK				17  /**< A native leaked an item on the stack */
#define SP_ERROR_HEAPLEAK				18  /**< A native leaked an item on the heap */
#define SP_ERROR_ARRAY_TOO_BIG			19	/**< A dynamic array is too big */
#define SP_ERROR_TRACKER_BOUNDS			20	/**< Tracker stack is out of bounds */
#define SP_ERROR_INVALID_NATIVE			21	/**< Native was pending or invalid */
#define SP_ERROR_PARAMS_MAX				22	/**< Maximum number of parameters reached */
#define SP_ERROR_NATIVE					23	/**< Error originates from a native */
#define SP_ERROR_NOT_RUNNABLE			24	/**< Function or plugin is not runnable */
#define SP_ERROR_ABORTED				25	/**< Function call was aborted */

/**
 * Defines a native function.
 *
 * It is not necessary to validate the parameter count 
 *
 * @param plugin			Handle of the calling plugin.
 * @param numParams			Number of parameters passed to the native.
 * @return 					Value for the native call to return.
 */
functag NativeCall public(Handle:plugin, numParams);

/**
 * Creates a dynamic native.  This should only be called in AskPluginLoad(), or 
 * else you risk not having your native shared with other plugins.
 *
 * @param name				Name of the dynamic native; must be unique amongst
 *							all other registered dynamic native.s
 * @param func				Function to use as the dynamic native.
 * @noreturn
 */
native CreateNative(const String:name[], NativeCall:func);

/**
 * Throws an error in the calling plugin of a native, instead of your own plugin.
 *
 * @param error				Error code to use.
 * @param fmt				Error message format.
 * @param ...				Format arguments.
 */
native ThrowNativeError(error, const String:fmt[], {Handle,Float,String,_}:...);

/**
 * Retrieves the string length from a native parameter string.  This is useful 
 * fetching the entire string using dynamic arrays.
 * @note If this function succeeds, Get/SetNativeString will also succeed.
 *
 * @param param				Parameter number, starting from 1.
 * @param length			Stores the length of the string.
 * @return					SP_ERROR_NONE on sucecss, any other integer on failure.
 * @error					Invalid parameter number or calling from a non-native function.
 */
native GetNativeStringLength(param, &length);

/**
 * Retrieves a string from a native parameter.
 * @note Output conditions are undefined on failure.
 *
 * @param param				Parameter number, starting from 1.
 * @param buffer			Buffer to store the string in.
 * @param maxlength			Maximum length of the buffer.
 * @param bytes				Optionally store the number of bytes written.
 * @return					SP_ERROR_NONE on success, any other integer on failure.
 * @error					Invalid parameter number or calling from a non-native function.
 */
native GetNativeString(param, String:buffer[], maxlength, &bytes=0);

/**
 * Sets a string in a native parameter.
 * @note Output conditions are undefined on failure.
 *
 * @param param				Parameter number, starting from 1.
 * @param source			Source string to use.
 * @param maxlength			Maximum number of bytes to write.
 * @param utf8				If false, string will not be written
 *							with UTF8 safety.
 * @param bytes				Optionally store the number of bytes written.
 * @return					SP_ERROR_NONE on success, any other integer on failure.
 * @error					Invalid parameter number or calling from a non-native function.
 */
native SetNativeString(param, const String:source[], maxlength, bool:utf8=true, &bytes=0);

/**
 * Gets a cell from a native parameter.
 *
 * @param param				Parameter number, starting from 1.
 * @return					Cell value at the parameter number.
 * @error					Invalid parameter number or calling from a non-native function.
 */
native GetNativeCell(param);

/**
 * Gets a cell from a native parameter, by reference.
 *
 * @param param				Parameter number, starting from 1.
 * @return					Cell value at the parameter number.
 * @error					Invalid parameter number or calling from a non-native function.
 */
native GetNativeCellRef(param);

/**
 * Sets a cell from a native parameter, by reference.
 *
 * @param param				Parameter number, starting from 1.
 * @param value				Cell value at the parameter number to set by reference.
 * @noreturn
 * @error					Invalid parameter number or calling from a non-native function.
 */
native SetNativeCellRef(param, {Float,Handle,_}:value);

/**
 * Gets an array from a native parameter (always by reference).
 *
 * @param param				Parameter number, starting from 1.
 * @param local				Local array to copy into.
 * @param size				Maximum size of local array.
 * @return					SP_ERROR_NONE on success, anything else on failure.
 * @error					Invalid parameter number or calling from a non-native function.
 */
native GetNativeArray(param, {Float,Handle,_}:local[], size);

/**
 * Copies a local array into a native parameter array (always by reference).
 * 
 * @param param				Parameter number, starting from 1.
 * @param local				Local array to copy from.
 * @param size				Size of the local array to copy.
 * @return					SP_ERROR_NONE on success, anything else on failure.
 * @error					Invalid parameter number or calling from a non-native function.
 */
native SetNativeArray(param, const {Float,Handle,_}:local[], size);

/**
 * Formats a string using parameters from a native.
 *
 * @note All parameter indexes start at 1.
 * @note If the input and output buffers overlap, the contents
 *  of the output buffer at the end is undefined.
 *
 * @param out_param			Output parameter number to write to.  If 0, out_string is used.
 * @param fmt_param			Format parameter number.  If 0, fmt_string is used.
 * @param vararg_param		First variable parameter number.
 * @param out_len			Output string buffer maximum length (always required).
 * @param written			Optionally stores the number of bytes written.
 * @param out_string		Output string buffer to use if out_param is not used.
 * @param fmt_string		Format string to use if fmt_param is not used.
 * @return					SP_ERROR_NONE on success, anything else on failure.
 */
native FormatNativeString(out_param, 
						  fmt_param, 
						  vararg_param, 
						  out_len,
						  &written=0,
						  String:out_string[]="",
						  const String:fmt_string[]="");

stock Float:GetNativeFloat(param, bool:byref)
{
	if (!byref)
	{
		return Float:GetNativeCell(param);
	} else {
		return Float:GetNativeCellRef(param);
	}
}
stock Handle:GetNativeHandle(param, bool:byref)
{
	if (!byref)
	{
		return Handle:GetNativeCell(param);
	} else {
		return Handle:GetNativeCellRef(param);
	}
}