ds@457: /**
ds@475:  * vim: set ts=4 :
ds@457:  * ===============================================================
ds@457:  * SourceMod (C)2004-2007 AlliedModders LLC.  All rights reserved.
ds@457:  * ===============================================================
ds@457:  *
ds@457:  *  This file is part of the SourceMod/SourcePawn SDK.  This file may only be used 
ds@457:  * or modified under the Terms and Conditions of its License Agreement, which is found 
ds@457:  * in LICENSE.txt.  The Terms and Conditions for making SourceMod extensions/plugins 
ds@457:  * may change at any time.  To view the latest information, see:
ds@457:  *   http://www.sourcemod.net/license.php
ds@457:  *
ds@457:  * Version: $Id$
ds@457:  */
ds@457:  
ds@457: #if defined _console_included
ds@457:  #endinput
ds@457: #endif
ds@457: #define _console_included
ds@457: 
ds@457: /**
ds@714:  * Console variable bound values used with Get/SetConVarBounds()
ds@714:  */
ds@714: enum ConVarBounds
ds@714: {
ds@714: 	ConVarBound_Upper = 0,
ds@714: 	ConVarBound_Lower
ds@714: };
ds@714: 
ds@714: /**
ds@697:  * Console variable query helper values.
ds@697:  */
ds@697: enum QueryCookie
ds@697: {
ds@697: 	QUERYCOOKIE_FAILED = 0,
dvander@815: };
ds@697: 
ds@697: /**
ds@696:  * Console variable query result values.
ds@696:  */
ds@696: enum ConVarQueryResult
ds@696: {
ds@696: 	ConVarQuery_Okay = 0,				/**< Retrieval of client convar value was successful. */
ds@696: 	ConVarQuery_NotFound,				/**< Client convar was not found. */
ds@696: 	ConVarQuery_NotValid,				/**< A console command with the same name was found, but there is no convar. */
ds@696: 	ConVarQuery_Protected				/**< Client convar was found, but it is protected. The server cannot retrieve its value. */
ds@696: };
ds@696: 
ds@696: /**
dvander@619:  * @section Flags for console commands and console variables.  The descriptions 
dvander@619:  * for each constant come directly from the Source SDK.
ds@457:  */
ds@475: #define FCVAR_NONE				0		/**< The default, no flags at all */
ds@475: #define FCVAR_UNREGISTERED		(1<<0)	/**< If this is set, don't add to linked list, etc. */
ds@475: #define FCVAR_LAUNCHER			(1<<1)	/**< Defined by launcher. */
ds@475: #define FCVAR_GAMEDLL			(1<<2)	/**< Defined by the game DLL. */
ds@475: #define FCVAR_CLIENTDLL			(1<<3)	/**< Defined by the client DLL. */
ds@475: #define FCVAR_MATERIAL_SYSTEM	(1<<4)	/**< Defined by the material system. */
ds@475: #define FCVAR_PROTECTED			(1<<5)	/**< It's a server cvar, but we don't send the data since it's a password, etc. Sends 1 if it's not bland/zero, 0 otherwise as value. */
ds@475: #define FCVAR_SPONLY			(1<<6)	/**< This cvar cannot be changed by clients connected to a multiplayer server. */
ds@475: #define	FCVAR_ARCHIVE			(1<<7)	/**< Set to cause it to be saved to vars.rc */
ds@475: #define	FCVAR_NOTIFY			(1<<8)	/**< Notifies players when changed. */
ds@475: #define	FCVAR_USERINFO			(1<<9)	/**< Changes the client's info string. */
ds@475: #define FCVAR_PRINTABLEONLY		(1<<10)	/**< This cvar's string cannot contain unprintable characters (e.g., used for player name, etc.) */
ds@475: #define FCVAR_UNLOGGED			(1<<11)	/**< If this is a FCVAR_SERVER, don't log changes to the log file / console if we are creating a log */
ds@475: #define FCVAR_NEVER_AS_STRING	(1<<12)	/**< Never try to print that cvar. */
ds@475: #define FCVAR_REPLICATED		(1<<13)	/**< Server setting enforced on clients. */
ds@475: #define FCVAR_CHEAT				(1<<14)	/**< Only useable in singleplayer / debug / multiplayer & sv_cheats */
ds@475: #define FCVAR_STUDIORENDER		(1<<15)	/**< Defined by the studiorender system. */
ds@475: #define FCVAR_DEMO				(1<<16)	/**< Record this cvar when starting a demo file. */
ds@475: #define FCVAR_DONTRECORD		(1<<17)	/**< Don't record these command in demo files. */
ds@475: #define FCVAR_PLUGIN			(1<<18)	/**< Defined by a 3rd party plugin. */
ds@475: #define FCVAR_DATACACHE			(1<<19)	/**< Defined by the datacache system. */
ds@475: #define FCVAR_TOOLSYSTEM		(1<<20)	/**< Defined by an IToolSystem library */
ds@475: #define FCVAR_FILESYSTEM		(1<<21)	/**< Defined by the file system. */
ds@475: #define FCVAR_NOT_CONNECTED		(1<<22)	/**< Cvar cannot be changed by a client that is connected to a server. */
ds@475: #define FCVAR_SOUNDSYSTEM		(1<<23)	/**< Defined by the soundsystem library. */
ds@475: #define FCVAR_ARCHIVE_XBOX		(1<<24)	/**< Cvar written to config.cfg on the Xbox. */
ds@475: #define FCVAR_INPUTSYSTEM		(1<<25)	/**< Defined by the inputsystem DLL. */
ds@475: #define FCVAR_NETWORKSYSTEM		(1<<26)	/**< Defined by the network system. */
ds@476: #define FCVAR_VPHYSICS			(1<<27)	/**< Defined by vphysics. */
ds@457: 
dvander@522: /**
dvander@619:  * @endsection
dvander@619:  */
dvander@619: 
dvander@619: /**
dvander@522:  * Executes a server command as if it were on the server console (or RCON)
dvander@522:  *
dvander@522:  * @param format		Formatting rules.
dvander@522:  * @param ...			Variable number of format parameters.
dvander@522:  * @noreturn
dvander@522:  */
ds@634: native ServerCommand(const String:format[], any:...);
dvander@522: 
dvander@522: /**
dvander@522:  * Inserts a server command at the beginning of the server command buffer.
dvander@522:  *
dvander@522:  * @param format		Formatting rules.
dvander@522:  * @param ...			Variable number of format parameters.
dvander@522:  * @noreturn
dvander@522:  */
ds@634: native InsertServerCommand(const String:format[], any:...);
dvander@522: 
dvander@522: /**
dvander@522:  * Executes every command in the server's command buffer, rather than once per frame.
dvander@522:  *
dvander@522:  * @noreturn
dvander@522:  */
dvander@522: native ServerExecute();
dvander@480: 
dvander@480: /**
dvander@532:  * Executes a client command.  Note that this will not work on clients unless
dvander@532:  * they have cl_restrict_server_commands set to 0.
dvander@532:  *
dvander@532:  * @param client		Index of the client.
dvander@532:  * @param fmt			Format of the client command.
dvander@532:  * @param ...			Format parameters/
dvander@532:  * @noreturn
dvander@532:  * @error				Invalid client index, or client not connected.
dvander@532:  */
ds@634: native ClientCommand(client, const String:fmt[], any:...);
dvander@532: 
dvander@532: /**
dvander@480:  * Sends a message to the server console.
dvander@480:  *
dvander@480:  * @param format		Formatting rules.
dvander@480:  * @param ...			Variable number of format parameters.
dvander@480:  * @noreturn
dvander@480:  */
ds@634: native PrintToServer(const String:format[], any:...);
dvander@480: 
dvander@480: /**
dvander@480:  * Sends a message to a client's console.
dvander@480:  *
dvander@893:  * @param client		Client index.
dvander@480:  * @param format		Formatting rules.
dvander@480:  * @param ...			Variable number of format parameters.
dvander@480:  * @noreturn
ds@873:  * @error				If the client is not connected an error will be thrown.
dvander@480:  */
ds@634: native PrintToConsole(client, const String:format[], any:...);
dvander@480: 
ds@457: /**
dvander@893:  * Reples to a message in a command.
dvander@893:  *
dvander@893:  * A client index of 0 will use PrintToServer().
dvander@893:  * If the command was from the console, PrintToConsole() is used.
dvander@893:  * If the command was from chat, PrintToChat() is used.
dvander@893:  *
dvander@893:  * @param client		Client index, or 0 for server.
dvander@893:  * @param format		Formatting rules.
dvander@893:  * @param ...			Variable number of format parameters.
dvander@893:  * @noreturn
dvander@893:  * @error				If the client is not connected or invalid.
dvander@893:  */
dvander@893: native ReplyToCommand(client, const String:fornmat[], any:...);
dvander@893: 
dvander@893: /**
dvander@498:  * Called when a server-only command is invoked.  
dvander@498:  *
dvander@520:  * @params args			Number of arguments that were in the argument string.
dvander@708:  * @return				An Action value.  Not handling the command
dvander@498:  *						means that Source will report it as "not found."
dvander@498:  */
dvander@520: functag SrvCmd Action:public(args);
dvander@498: 
dvander@498: /**
dvander@498:  * Creates a server-only console command, or hooks an already existing one.  
dvander@498:  *
dvander@498:  * @param cmd			Name of the command to hook or create.
dvander@498:  * @param callback		A function to use as a callback for when the command is invoked.
dvander@498:  * @param description	Optional description to use for command creation.
dvander@498:  * @param flags			Optional flags to use for command creation.
dvander@498:  * @noreturn
ds@579:  * @error				Command name is the same as an existing convar.
dvander@498:  */
dvander@498: native RegServerCmd(const String:cmd[], SrvCmd:callback, const String:description[]="", flags=0);
dvander@498: 
dvander@498: /**
dvander@498:  * Called when a generic console command is invoked.
dvander@498:  *
dvander@498:  * @param client		Index of the client, or 0 from the server.
dvander@520:  * @param args			Number of arguments that were in the argument string.
dvander@708:  * @return				An Action value.  Not handling the command
dvander@498:  *						means that Source will report it as "not found."
dvander@498:  */
dvander@520: functag ConCmd Action:public(client, args);
dvander@498: 
dvander@498: /**
dvander@498:  * Creates a console command, or hooks an already existing one.
dvander@498:  *
dvander@498:  * @param cmd			Name of the command to hook or create.
dvander@498:  * @param callback		A function to use as a callback for when the command is invoked.
dvander@498:  * @param description	Optional description to use for command creation.
dvander@498:  * @param flags			Optional flags to use for command creation.
dvander@498:  * @noreturn
ds@579:  * @error				Command name is the same as an existing convar.
dvander@498:  */
dvander@498: native RegConsoleCmd(const String:cmd[], ConCmd:callback, const String:description[]="", flags=0);
dvander@498: 
dvander@498: /**
dvander@498:  * Creates a console command as an administrative command.  If the command does not exist,
dvander@520:  * it is created.  When this command is invoked, the access rights of the player are 
dvander@520:  * automatically checked before allowing it to continue.
dvander@498:  *
dvander@498:  * @param cmd			String containing command to register.
dvander@498:  * @param callback		A function to use as a callback for when the command is invoked.
dvander@498:  * @param adminflags	Administrative flags (bitstring) to use for permissions.
dvander@498:  * @param group			String containing the command group to use.  If empty,
dvander@498:  * 						the plugin's filename will be used instead.
dvander@498:  * @param description	Optional description to use for help.
dvander@498:  * @param flags			Optional console flags.
dvander@498:  * @noreturn
ds@579:  * @error				Command name is the same as an existing convar.
dvander@498:  */
dvander@514: native RegAdminCmd(const String:cmd[],
dvander@514: 					ConCmd:callback,
dvander@514: 					adminflags,
dvander@514: 					const String:description[]="",
dvander@514: 					const String:group[]="",
dvander@514: 					flags=0);
dvander@517: 					
dvander@517: /**
dvander@517:  * Returns the number of arguments from the current console or server command.
dvander@517:  * @note Unlike the HL2 engine call, this does not include the command itself.
dvander@517:  *
dvander@517:  * @return				Number of arguments to the current command.
dvander@517:  */
dvander@517: native GetCmdArgs();
dvander@517: 
dvander@517: /**
dvander@517:  * Retrieves a command argument given its index, from the current console or 
dvander@517:  * server command.
dvander@517:  * @note Argument indexes start at 1; 0 retrieves the command name.
dvander@517:  *
dvander@517:  * @param argnum		Argument number to retrieve.
dvander@517:  * @param buffer		Buffer to use for storing the string.
dvander@517:  * @param maxlength		Maximum length of the buffer.
dvander@517:  * @noreturn
dvander@517:  */
dvander@517: native GetCmdArg(argnum, String:buffer[], maxlength);
dvander@517: 
dvander@517: /**
dvander@517:  * Retrieves the entire command argument string in one lump from the current 
dvander@517:  * console or server command.
dvander@517:  *
dvander@517:  * @param buffer		Buffer to use for storing the string.
dvander@517:  * @param maxlength		Maximum length of the buffer.
dvander@517:  * @noreturn
dvander@517:  */
dvander@517: native GetCmdArgString(String:buffer[], maxlength);
dvander@498: 
dvander@498: /**
ds@457:  * Creates a new console variable.
ds@457:  *
ds@475:  * @param name			Name of new convar.
ds@475:  * @param defaultValue	String containing the default value of new convar.
ds@582:  * @param description	Optional description of the convar.
ds@576:  * @param flags			Optional bitstring of flags determining how the convar should be handled. See FCVAR_* constants for more details.
ds@475:  * @param hasMin		Optional boolean that determines if the convar has a minimum value.
ds@475:  * @param min			Minimum floating point value that the convar can have if hasMin is true.
ds@475:  * @param hasMax		Optional boolean that determines if the convar has a maximum value.
ds@475:  * @param max			Maximum floating point value that the convar can have if hasMax is true.
ds@457:  * @return				A handle to the newly created convar. If the convar already exists, INVALID_HANDLE is returned.
ds@579:  * @error				Convar name is blank or is the same as an existing console command.
ds@457:  */
ds@582: native Handle: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);
ds@457: 
ds@457: /**
ds@457:  * Searches for a console variable.
ds@457:  *
ds@475:  * @param name			Name of convar to find.
ds@475:  * @return				A handle to the convar if it is found. INVALID_HANDLE otherwise.
ds@457:  */
ds@457: native Handle:FindConVar(const String:name[]);
ds@457: 
ds@457: /**
ds@465:  * Called when a console variable's value is changed.
ds@465:  *
ds@475:  * @param convar		Handle to the convar that was changed.
ds@475:  * @param oldValue		String containing the value of the convar before it was changed.
ds@475:  * @param newValue		String containing the new value of the convar.
ds@465:  * @noreturn
ds@465:  */
ds@582: functag ConVarChanged public(Handle:convar, const String:oldValue[], const String:newValue[]);
ds@465: 
ds@465: /**
ds@465:  * Creates a hook for when a console variable's value is changed.
ds@465:  *
ds@475:  * @param convar		Handle to the convar.
ds@475:  * @param callback		An OnConVarChanged function pointer.
ds@465:  * @noreturn
ds@475:  * @error				Invalid or corrupt Handle or invalid callback function.
ds@465:  */
ds@582: native HookConVarChange(Handle:convar, ConVarChanged:callback);
ds@465: 
ds@465: /**
ds@465:  * Removes a hook for when a console variable's value is changed.
ds@465:  *
ds@475:  * @param convar		Handle to the convar.
ds@475:  * @param callback		An OnConVarChanged function pointer.
ds@472:  * @noreturn
ds@475:  * @error				Invalid or corrupt Handle, invalid callback function, or no active hook on convar.
ds@465:  */
ds@582: native UnhookConVarChange(Handle:convar, ConVarChanged:callback);
ds@465: 
ds@465: /**
ds@457:  * Returns the boolean value of a console variable.
ds@457:  *
ds@475:  * @param convar		Handle to the convar.
ds@475:  * @return				The boolean value of the convar.
ds@475:  * @error				Invalid or corrupt Handle.
ds@457:  */
ds@457: native bool:GetConVarBool(Handle:convar);
ds@457: 
ds@457: /**
ds@457:  * Sets the boolean value of a console variable.
ds@457:  *
ds@475:  * @param convar		Handle to the convar.
ds@475:  * @param value			New boolean value.
ds@457:  * @noreturn
ds@475:  * @error				Invalid or corrupt Handle.
ds@457:  */
ds@457: native SetConVarBool(Handle:convar, bool:value);
ds@457: 
ds@457: /**
ds@457:  * Returns the integer value of a console variable.
ds@457:  *
ds@475:  * @param convar		Handle to the convar.
ds@475:  * @return				The integer value of the convar.
ds@475:  * @error				Invalid or corrupt Handle.
ds@457:  */
ds@457: native GetConVarInt(Handle:convar);
ds@457: 
ds@457: /**
ds@457:  * Sets the integer value of a console variable.
ds@457:  *
ds@475:  * @param convar		Handle to the convar.
ds@475:  * @param value			New integer value.
ds@457:  * @noreturn
ds@475:  * @error				Invalid or corrupt Handle.
ds@457:  */
ds@457: native SetConVarInt(Handle:convar, value);
ds@457: 
ds@457: /**
ds@457:  * Returns the floating point value of a console variable.
ds@457:  *
ds@475:  * @param convar		Handle to the convar.
ds@475:  * @return				The floating point value of the convar.
ds@475:  * @error				Invalid or corrupt Handle.
ds@457:  */
ds@457: native Float:GetConVarFloat(Handle:convar);
ds@457: 
ds@457: /**
ds@457:  * Sets the floating point value of a console variable.
ds@457:  *
ds@475:  * @param convar		Handle to the convar.
ds@475:  * @param value			New floating point value.
ds@457:  * @noreturn
ds@475:  * @error				Invalid or corrupt Handle.
ds@457:  */
ds@457: native SetConVarFloat(Handle:convar, Float:value);
ds@457: 
ds@457: /**
ds@457:  * Retrieves the string value of a console variable.
ds@457:  *
ds@475:  * @param convar		Handle to the convar.
ds@475:  * @param value			Buffer to store the value of the convar.
ds@475:  * @param maxlength		Maximum length of string buffer.
ds@457:  * @noreturn
ds@475:  * @error				Invalid or corrupt Handle.     
ds@457:  */
ds@465: native GetConVarString(Handle:convar, String:value[], maxlength);
ds@457: 
ds@457: /**
ds@457:  * Sets the string value of a console variable.
ds@457:  *
ds@475:  * @param convar		Handle to the convar.
ds@475:  * @param value			New string value.
ds@457:  * @noreturn
ds@475:  * @error				Invalid or corrupt Handle.
ds@457:  */
ds@457: native SetConVarString(Handle:convar, const String:value[]);
ds@457: 
ds@457: /**
ds@457:  * Returns the bitstring of flags on a console variable.
ds@457:  *
ds@475:  * @param convar		Handle to the convar.
ds@475:  * @return				A bitstring containing the FCVAR_* flags that are enabled.
ds@475:  * @error				Invalid or corrupt Handle.
ds@457:  */
ds@457: native GetConVarFlags(Handle:convar);
ds@457: 
ds@457: /**
ds@457:  * Sets the bitstring of flags on a console variable.
ds@457:  *
ds@475:  * @param convar		Handle to the convar.
ds@475:  * @param flags			A bitstring containing the FCVAR_* flags to enable.
ds@457:  * @noreturn
ds@475:  * @error				Invalid or corrupt Handle.
ds@457:  */
ds@457: native SetConVarFlags(Handle:convar, flags);
ds@457: 
ds@457: /**
ds@714:  * Retrieves the specified bound of a console variable.
ds@714:  *
ds@714:  * @param convar		Handle to the convar.
ds@714:  * @param type			Type of bound to retrieve, ConVarBound_Lower or ConVarBound_Upper.
ds@714:  * @param value			By-reference cell to store the specified floating point bound value.
ds@714:  * @return				True if the convar has the specified bound set, false otherwise.
ds@714:  * @error				Invalid or corrupt Handle.
ds@714:  */
ds@714: native bool:GetConVarBounds(Handle:convar, ConVarBounds:type, &Float:value);
ds@714: 
ds@714: /**
ds@714:  * Sets the specified bound of a console variable.
ds@714:  *
ds@714:  * @param convar		Handle to the convar.
ds@714:  * @param type			Type of bound to set, ConVarBound_Lower or ConVarBound_Upper
ds@714:  * @param set			If set to true, convar will use specified bound. If false, bound will be removed.
ds@714:  * @param value			Floating point value to use as the specified bound.
ds@714:  * @noreturn
ds@714:  * @error				Invalid or corrupt Handle.
ds@714:  */
ds@714: native SetConVarBounds(Handle:convar, ConVarBounds:type, bool:set, Float:value=0.0);
ds@714: 
ds@714: /**
ds@465:  * Retrieves the name of a console variable.
ds@465:  *
ds@475:  * @param convar		Handle to the convar.
ds@475:  * @param value			Buffer to store the name of the convar.
ds@475:  * @param maxlength		Maximum length of string buffer.
ds@465:  * @noreturn
ds@475:  * @error				Invalid or corrupt Handle.     
ds@465:  */
ds@465: native GetConVarName(Handle:convar, const String:name[], maxlength);
ds@465: 
ds@465: /**
ds@457:  * Resets the console variable to its default value.
ds@457:  *
ds@475:  * @param convar		Handle to the convar.
ds@457:  * @noreturn
ds@475:  * @error				Invalid or corrupt Handle.
ds@457:  */
ds@457: native ResetConVar(Handle:convar);
ds@696: 
ds@696: funcenum ConVarQueryFinished
ds@696: {	
ds@696: 	/**
ds@696: 	 * Called when a query to retrieve a client's console variable has finished.
ds@696: 	 *
ds@696: 	 * @param cookie		Unique identifier of query.
ds@696: 	 * @param client		Player index.
ds@696: 	 * @param result		Result of query that tells one whether or not query was successful.
ds@696: 	 *						See ConVarQueryResult enum for more details.
ds@696: 	 * @param convarName	Name of client convar that was queried.
ds@696: 	 * @param convarValue	Value of client convar that was queried if successful. This will be "" if it was not.
ds@696: 	 * @param value			Value that was passed when query was started.
ds@696: 	 * @noreturn
ds@696: 	 */
ds@696: 	public(QueryCookie:cookie, client, ConVarQueryResult:result, const String:cvarName[], const String:cvarValue[], any:value),
ds@696: 	
ds@696: 	/**
ds@696: 	 * Called when a query to retrieve a client's console variable has finished.
ds@696: 	 *
ds@696: 	 * @param cookie		Unique identifier of query.
ds@696: 	 * @param client		Player index.
ds@696: 	 * @param result		Result of query that tells one whether or not query was successful.
ds@696: 	 *						See ConVarQueryResult enum for more details.
ds@696: 	 * @param convarName	Name of client convar that was queried.
ds@696: 	 * @param convarValue	Value of client convar that was queried if successful. This will be "" if it was not.
ds@696: 	 * @noreturn
ds@696: 	 */
ds@696: 	public(QueryCookie:cookie, client, ConVarQueryResult:result, const String:cvarName[], const String:cvarValue[])
ds@696: };
ds@696: 
ds@696: /**
ds@696:  * Starts a query to retrieve the value of a client's console variable.
ds@696:  *
ds@696:  * @param client		Player index.
ds@696:  * @param name			Name of client convar to query.
ds@696:  * @param callback		A function to use as a callback when the query has finished.
ds@696:  * @param value			Optional value to pass to the callback function.
ds@697:  * @return				A cookie that uniquely identifies the query. 
ds@697:  *						Returns QUERYCOOKIE_FAILED on failure, such as when used on a bot.
ds@696:  */
ds@696: native QueryCookie:QueryClientConVar(client, const String:cvarName[], ConVarQueryFinished:callback, any:value=0);