/**
 * vim: set ts=4 sw=4 tw=99 noet :
 * =============================================================================
 * SourceMod (C)2004-2014 AlliedModders LLC.  All rights reserved.
 * =============================================================================
 *
 * This file is part of the SourceMod/SourcePawn SDK.
 *
 * This program is free software; you can redistribute it and/or modify it under
 * the terms of the GNU General Public License, version 3.0, as published by the
 * Free Software Foundation.
 * 
 * This program is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 * FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
 * details.
 *
 * You should have received a copy of the GNU General Public License along with
 * this program.  If not, see <http://www.gnu.org/licenses/>.
 *
 * As a special exception, AlliedModders LLC gives you permission to link the
 * code of this program (as well as its derivative works) to "Half-Life 2," the
 * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software
 * by the Valve Corporation.  You must obey the GNU General Public License in
 * all respects for all other code used.  Additionally, AlliedModders LLC grants
 * this exception to all derivative works.  AlliedModders LLC defines further
 * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),
 * or <http://www.sourcemod.net/license.php>.
 *
 * Version: $Id$
 */

/**
 * Console variable bound values used with Get/SetConVarBounds()
 */
enum ConVarBounds
{
	ConVarBound_Upper = 0,
	ConVarBound_Lower
};

/**
 * Console variable query result values.
 */
enum ConVarQueryResult
{
	ConVarQuery_Okay = 0,				/**< Retrieval of client convar value was successful. */
	ConVarQuery_NotFound,				/**< Client convar was not found. */
	ConVarQuery_NotValid,				/**< A console command with the same name was found, but there is no convar. */
	ConVarQuery_Protected				/**< Client convar was found, but it is protected. The server cannot retrieve its value. */
};

/**
 * Creates a new console variable.
 *
 * @param name			Name of new convar.
 * @param defaultValue	String containing the default value of new convar.
 * @param description	Optional description of the convar.
 * @param flags			Optional bitstring of flags determining how the convar should be handled. See FCVAR_* constants for more details.
 * @param hasMin		Optional boolean that determines if the convar has a minimum value.
 * @param min			Minimum floating point value that the convar can have if hasMin is true.
 * @param hasMax		Optional boolean that determines if the convar has a maximum value.
 * @param max			Maximum floating point value that the convar can have if hasMax is true.
 * @return				A handle to the newly created convar. If the convar already exists, a handle to it will still be returned.
 * @error				Convar name is blank or is the same as an existing console command.
 */
native ConVar:CreateConVar(const String:name[], const String:defaultValue[], const String:description[]="", flags=0, bool:hasMin=false, Float:min=0.0, bool:hasMax=false, Float:max=0.0);

// Most of these aren't properties because they're more complex
methodmap ConVar < Handle
{
}

/**
 * Searches for a console variable.
 *
 * @param name			Name of convar to find.
 * @return				A handle to the convar if it is found. INVALID_HANDLE otherwise.
 */
native ConVar:FindConVar(const String:name[]);

/**
 * Called when a console variable's value is changed.
 *
 * @param convar		Handle to the convar that was changed.
 * @param oldValue		String containing the value of the convar before it was changed.
 * @param newValue		String containing the new value of the convar.
 * @noreturn
 */
typedef ConVarChanged = function void (ConVar convar, const char[] oldValue, const char[] newValue);

/**
 * Creates a hook for when a console variable's value is changed.
 *
 * @param convar		Handle to the convar.
 * @param callback		An OnConVarChanged function pointer.
 * @noreturn
 * @error				Invalid or corrupt Handle or invalid callback function.
 */
native HookConVarChange(Handle:convar, ConVarChanged:callback);

/**
 * Removes a hook for when a console variable's value is changed.
 *
 * @param convar		Handle to the convar.
 * @param callback		An OnConVarChanged function pointer.
 * @noreturn
 * @error				Invalid or corrupt Handle, invalid callback function, or no active hook on convar.
 */
native UnhookConVarChange(Handle:convar, ConVarChanged:callback);

/**
 * Returns the boolean value of a console variable.
 *
 * @param convar		Handle to the convar.
 * @return				The boolean value of the convar.
 * @error				Invalid or corrupt Handle.
 */
native bool:GetConVarBool(Handle:convar);

/**
 * Sets the boolean value of a console variable.
 *
 * Note: The replicate and notify params are only relevant for the original, Dark Messiah, and
 * Episode 1 engines. Newer engines automatically do these things when the convar value is changed.
 *
 * @param convar		Handle to the convar.
 * @param value			New boolean value.
 * @param replicate		If set to true, the new convar value will be set on all clients.
 *						This will only work if the convar has the FCVAR_REPLICATED flag
 *						and actually exists on clients.
 * @param notify		If set to true, clients will be notified that the convar has changed.
 *						This will only work if the convar has the FCVAR_NOTIFY flag.
 * @noreturn
 * @error				Invalid or corrupt Handle.
 */
native SetConVarBool(Handle:convar, bool:value, bool:replicate=false, bool:notify=false);

/**
 * Returns the integer value of a console variable.
 *
 * @param convar		Handle to the convar.
 * @return				The integer value of the convar.
 * @error				Invalid or corrupt Handle.
 */
native GetConVarInt(Handle:convar);

/**
 * Sets the integer value of a console variable.
 *
 * Note: The replicate and notify params are only relevant for the original, Dark Messiah, and
 * Episode 1 engines. Newer engines automatically do these things when the convar value is changed.
 *
 * @param convar		Handle to the convar.
 * @param value			New integer value.
 * @param replicate		If set to true, the new convar value will be set on all clients.
 *						This will only work if the convar has the FCVAR_REPLICATED flag
 *						and actually exists on clients.
 * @param notify		If set to true, clients will be notified that the convar has changed.
 *						This will only work if the convar has the FCVAR_NOTIFY flag.
 * @noreturn
 * @error				Invalid or corrupt Handle.
 */
native SetConVarInt(Handle:convar, value, bool:replicate=false, bool:notify=false);

/**
 * Returns the floating point value of a console variable.
 *
 * @param convar		Handle to the convar.
 * @return				The floating point value of the convar.
 * @error				Invalid or corrupt Handle.
 */
native Float:GetConVarFloat(Handle:convar);

/**
 * Sets the floating point value of a console variable.
 *
 * Note: The replicate and notify params are only relevant for the original, Dark Messiah, and
 * Episode 1 engines. Newer engines automatically do these things when the convar value is changed.
 *
 * @param convar		Handle to the convar.
 * @param value			New floating point value.
 * @param replicate		If set to true, the new convar value will be set on all clients.
 *						This will only work if the convar has the FCVAR_REPLICATED flag
 *						and actually exists on clients.
 * @param notify		If set to true, clients will be notified that the convar has changed.
 *						This will only work if the convar has the FCVAR_NOTIFY flag.
 * @noreturn
 * @error				Invalid or corrupt Handle.
 */
native SetConVarFloat(Handle:convar, Float:value, bool:replicate=false, bool:notify=false);

/**
 * Retrieves the string value of a console variable.
 *
 * @param convar		Handle to the convar.
 * @param value			Buffer to store the value of the convar.
 * @param maxlength		Maximum length of string buffer.
 * @noreturn
 * @error				Invalid or corrupt Handle.     
 */
native GetConVarString(Handle:convar, String:value[], maxlength);

/**
 * Sets the string value of a console variable.
 *
 * Note: The replicate and notify params are only relevant for the original, Dark Messiah, and
 * Episode 1 engines. Newer engines automatically do these things when the convar value is changed.
 *
 * @param convar		Handle to the convar.
 * @param value			New string value.
 * @param replicate		If set to true, the new convar value will be set on all clients.
 *						This will only work if the convar has the FCVAR_REPLICATED flag
 *						and actually exists on clients.
 * @param notify		If set to true, clients will be notified that the convar has changed.
 *						This will only work if the convar has the FCVAR_NOTIFY flag.
 * @noreturn
 * @error				Invalid or corrupt Handle.
 */
native SetConVarString(Handle:convar, const String:value[], bool:replicate=false, bool:notify=false);

/**
 * Resets the console variable to its default value.
 *
 * Note: The replicate and notify params are only relevant for the original, Dark Messiah, and
 * Episode 1 engines. Newer engines automatically do these things when the convar value is changed.
 *
 * @param convar		Handle to the convar.
 * @param replicate		If set to true, the new convar value will be set on all clients.
 *						This will only work if the convar has the FCVAR_REPLICATED flag
 *						and actually exists on clients.
 * @param notify		If set to true, clients will be notified that the convar has changed.
 *						This will only work if the convar has the FCVAR_NOTIFY flag.
 * @noreturn
 * @error				Invalid or corrupt Handle.
 */
native ResetConVar(Handle:convar, bool:replicate=false, bool:notify=false);

/**
 * Retrieves the default string value of a console variable.
 *
 * @param convar		Handle to the convar.
 * @param value			Buffer to store the default value of the convar.
 * @param maxlength		Maximum length of string buffer.
 * @return				Number of bytes written to the buffer (UTF-8 safe).
 * @error				Invalid or corrupt Handle.
 */
native GetConVarDefault(Handle:convar, String:value[], maxlength);

/**
 * Returns the bitstring of flags on a console variable.
 *
 * @param convar		Handle to the convar.
 * @return				A bitstring containing the FCVAR_* flags that are enabled.
 * @error				Invalid or corrupt Handle.
 */
native GetConVarFlags(Handle:convar);

/**
 * Sets the bitstring of flags on a console variable.
 *
 * @param convar		Handle to the convar.
 * @param flags			A bitstring containing the FCVAR_* flags to enable.
 * @noreturn
 * @error				Invalid or corrupt Handle.
 */
native SetConVarFlags(Handle:convar, flags);

/**
 * Retrieves the specified bound of a console variable.
 *
 * @param convar		Handle to the convar.
 * @param type			Type of bound to retrieve, ConVarBound_Lower or ConVarBound_Upper.
 * @param value			By-reference cell to store the specified floating point bound value.
 * @return				True if the convar has the specified bound set, false otherwise.
 * @error				Invalid or corrupt Handle.
 */
native bool:GetConVarBounds(Handle:convar, ConVarBounds:type, &Float:value);

/**
 * Sets the specified bound of a console variable.
 *
 * @param convar		Handle to the convar.
 * @param type			Type of bound to set, ConVarBound_Lower or ConVarBound_Upper
 * @param set			If set to true, convar will use specified bound. If false, bound will be removed.
 * @param value			Floating point value to use as the specified bound.
 * @noreturn
 * @error				Invalid or corrupt Handle.
 */
native SetConVarBounds(Handle:convar, ConVarBounds:type, bool:set, Float:value=0.0);

/**
 * Retrieves the name of a console variable.
 *
 * @param convar		Handle to the convar.
 * @param name			Buffer to store the name of the convar.
 * @param maxlength		Maximum length of string buffer.
 * @noreturn
 * @error				Invalid or corrupt Handle.     
 */
native GetConVarName(Handle:convar, String:name[], maxlength);

union ConVarQueryFinished
{	
	/**
	 * Called when a query to retrieve a client's console variable has finished.
	 *
	 * @param cookie		Unique identifier of query.
	 * @param client		Player index.
	 * @param result		Result of query that tells one whether or not query was successful.
	 *						See ConVarQueryResult enum for more details.
	 * @param convarName	Name of client convar that was queried.
	 * @param convarValue	Value of client convar that was queried if successful. This will be "" if it was not.
	 * @param value			Value that was passed when query was started.
	 * @noreturn
	 */
	function void (QueryCookie cookie, int client, ConVarQueryResult result, const char[] cvarName, const char[] cvarValue, any value);
	
	/**
	 * Called when a query to retrieve a client's console variable has finished.
	 *
	 * @param cookie		Unique identifier of query.
	 * @param client		Player index.
	 * @param result		Result of query that tells one whether or not query was successful.
	 *						See ConVarQueryResult enum for more details.
	 * @param convarName	Name of client convar that was queried.
	 * @param convarValue	Value of client convar that was queried if successful. This will be "" if it was not.
	 * @noreturn
	 */
	function void (QueryCookie cookie, int client, ConVarQueryResult result, const char[] cvarName, const char[] cvarValue);
};

/**
 * Starts a query to retrieve the value of a client's console variable.
 *
 * @param client		Player index.
 * @param cvarName			Name of client convar to query.
 * @param callback		A function to use as a callback when the query has finished.
 * @param value			Optional value to pass to the callback function.
 * @return				A cookie that uniquely identifies the query. 
 *						Returns QUERYCOOKIE_FAILED on failure, such as when used on a bot.
 */
native QueryCookie:QueryClientConVar(client, const String:cvarName[], ConVarQueryFinished:callback, any:value=0);

/**
 * Returns true if the supplied character is valid in a ConVar name.
 *
 * @param c			Character to validate.
 * @return			True is valid for ConVars, false otherwise
 */
stock bool:IsValidConVarChar(c)
{
	return (c == '_' || IsCharAlpha(c) || IsCharNumeric(c));
}

/**
 * Replicates a convar value to a specific client. This does not change the actual convar value.
 *
 * @param client		Client index
 * @param convar		ConVar handle
 * @param value			String value to send
 * @return				True on success, false on failure
 * @error 				Invalid client index, client not in game, or client is fake
 */
native bool:SendConVarValue(client, Handle:convar, const String:value[]);