dvander@545: /**
dvander@545:  * vim: set ts=4 :
dvander@545:  * ===============================================================
dvander@545:  * SourceMod (C)2004-2007 AlliedModders LLC.  All rights reserved.
dvander@545:  * ===============================================================
dvander@545:  *
dvander@545:  *  This file is part of the SourceMod/SourcePawn SDK.  This file may only be used 
dvander@545:  * or modified under the Terms and Conditions of its License Agreement, which is found 
dvander@545:  * in LICENSE.txt.  The Terms and Conditions for making SourceMod extensions/plugins 
dvander@545:  * may change at any time.  To view the latest information, see:
dvander@545:  *   http://www.sourcemod.net/license.php
dvander@545:  *
dvander@545:  * Version: $Id$
dvander@545:  */
dvander@545: 
dvander@545: #if defined _clients_included
dvander@545:  #endinput
dvander@545: #endif
dvander@545: #define _clients_included
dvander@545: 
faluco@682: enum NetFlow
faluco@682: {
ds@873: 	NetFlow_Outgoing = 0,	/**< Outgoing traffic */
faluco@682: 	NetFlow_Incoming,		/**< Incoming traffic */
faluco@682: 	NetFlow_Both			/**< Incoming and outgoing traffic */
faluco@682: };
faluco@682: 
ds@901: #define MAXPLAYERS		64	/**< Maximum number of players that can be in server */
ds@901: 
dvander@545: /**
dvander@545:  * Called on client connection.
dvander@545:  *
dvander@545:  * @param client		Player index.
dvander@545:  * @param rejectmsg		Buffer to store the rejection message when the connection is refused.
dvander@545:  * @param maxlen		Maximum number of characters for rejection buffer.
dvander@545:  * @return				True to validate client's connection, false to refuse it.
dvander@545:  */
dvander@545: forward bool:OnClientConnect(client, String:rejectmsg[], maxlen);
dvander@545: 
dvander@545: /**
dvander@545:  * Called when a client is entering to the game.
dvander@545:  *
dvander@545:  * @param client		Player index.
dvander@545:  * @noreturn
dvander@545:  */
dvander@545: forward OnClientPutInServer(client);
dvander@545: 
dvander@545: /**
dvander@545:  * Called when a client is disconnecting from the server.
dvander@545:  *
dvander@545:  * @param client		Player index.
dvander@545:  * @noreturn
dvander@545:  */
dvander@545: forward OnClientDisconnect(client);
dvander@545: 
dvander@545: /**
dvander@545:  * Called when a client is disconnected from the server.
dvander@545:  *
dvander@545:  * @param client		Player index.
dvander@545:  * @noreturn
dvander@545:  */
dvander@545: forward OnClientDisconnect_Post(client);
dvander@545: 
dvander@545: /**
dvander@545:  * Called when a client is sending a command.
dvander@545:  *
dvander@545:  * @param client		Player index.
dvander@545:  * @param args			Number of arguments.
dvander@545:  * @noreturn
dvander@545:  */
dvander@545: forward Action:OnClientCommand(client, args);
dvander@545: 
dvander@545: /**
dvander@545:  * Called whenever the client's settings are changed.
dvander@545:  *
dvander@545:  * @param client		Player index.
dvander@545:  * @noreturn
dvander@545:  */
dvander@545: forward OnClientSettingsChanged(client);
dvander@545: 
dvander@545: /**
dvander@545:  * Called when a client receives a Steam ID.
dvander@545:  * @note This is called by bots, but the ID will be "BOT"
dvander@545:  *
dvander@545:  * @param client		Player index.
dvander@545:  * @param auth			Player auth string.
dvander@545:  */
dvander@545: forward OnClientAuthorized(client, const String:auth[]);
dvander@545: 
dvander@545: /**
dvander@545:  * Returns the maximum number of clients allowed on the server.
dvander@545:  *
dvander@545:  * @return				Maximum number of clients allowed.
dvander@545:  */
dvander@545: native GetMaxClients();
dvander@545: 
dvander@545: /**
dvander@545:  * Returns the client count put in the server.
dvander@545:  *
dvander@545:  * @param inGameOnly	If false connecting players are also counted.
dvander@545:  * @return				Client count in the server.
dvander@545:  */
dvander@545: native GetClientCount(bool:inGameOnly=true);
dvander@545: 
dvander@545: /**
dvander@545:  * Returns the client's name.
dvander@545:  *
dvander@545:  * @param client		Player index.
dvander@545:  * @param name			Buffer to store the client's name.
dvander@545:  * @param maxlen		Maximum length of string buffer (includes NULL terminator).
dvander@545:  * @return				True on success, false otherwise.
dvander@545:  * @error				If the client is not connected an error will be thrown.
dvander@545:  */
dvander@545: native bool:GetClientName(client, String:name[], maxlen);
dvander@545: 
dvander@545: /**
dvander@545:  * Retrieves a client's IP address.
dvander@545:  *
dvander@545:  * @param client		Player index.
dvander@545:  * @param name			Buffer to store the client's ip address.
dvander@545:  * @param maxlen		Maximum length of string buffer (includes NULL terminator).
dvander@545:  * @param remport		Remove client's port from the ip string (true by default).
dvander@545:  * @return				True on success, false otherwise.
dvander@545:  * @error				If the client is not connected or the index is invalid.
dvander@545:  */
dvander@545: native bool:GetClientIP(client, String:ip[], maxlen, bool:remport=true);
dvander@545: 
dvander@545: /**
dvander@545:  * Retrieves a client's authentication string (SteamID).
dvander@545:  *
dvander@545:  * @param client		Player index.
dvander@545:  * @param auth			Buffer to store the client's auth string.
dvander@545:  * @param maxlen		Maximum length of string buffer (includes NULL terminator).
dvander@545:  * @return				True on success, false otherwise.
dvander@545:  * @error				If the client is not connected or the index is invalid.
dvander@545:  */
dvander@545: native bool:GetClientAuthString(client, String:auth[], maxlen);
dvander@545: 
dvander@545: /**
dvander@545:  * Retrieves a client's user id, which is an index incremented for every client
dvander@545:  * that joins the server.
dvander@545:  *
dvander@545:  * @param client		Player index.
dvander@545:  * @return				User id of the client.
dvander@545:  * @error 				If the client is not connected or the index is invalid.
dvander@545:  */
dvander@545: native GetClientUserId(client);
dvander@545: 
dvander@545: /**
dvander@545:  * Returns if a certain player is connected.
dvander@545:  *
dvander@545:  * @param client		Player index.
dvander@545:  * @return				True if player is connected to the server, false otherwise.
dvander@545:  */
dvander@545: native bool:IsClientConnected(client);
dvander@545: 
dvander@545: /**
dvander@545:  * Returns if a certain player has entered the game.
dvander@545:  *
dvander@545:  * @param client		Player index.
dvander@545:  * @return				True if player has entered the game, false otherwise.
dvander@545:  */
ds@784: native bool:IsClientInGame(client);
ds@784: 
ds@784: /**
ds@784:  * Backwards compatibility stock - use IsClientInGame
ds@784:  * @deprecated			Renamed to IsClientInGame
ds@784:  */
ds@784: stock bool:IsPlayerInGame(client)
ds@784: {
ds@784: 	return IsClientInGame(client);
ds@784: }
dvander@545: 
dvander@545: /**
dvander@545:  * Returns if a certain player has been authenticated.
dvander@545:  *
dvander@545:  * @param client		Player index.
dvander@545:  * @return				True if player has been authenticated, false otherwise.
dvander@545:  */
dvander@545: native bool:IsClientAuthorized(client);
dvander@545: 
dvander@545: /**
dvander@545:  * Returns if a certain player is a fake client.
dvander@545:  *
dvander@545:  * @param client		Player index.
dvander@545:  * @return				True if player is a fake client, false otherwise.
dvander@545:  */
dvander@545: native bool:IsFakeClient(client);
dvander@545: 
dvander@545: /**
ds@1001:  * Returns if a certain player is an observer/spectator.
ds@1001:  *
ds@1001:  * @param client		Player index.
ds@1001:  * @return				True if player is an obverser, false otherwise.
ds@1001:  */
ds@1001: native bool:IsClientObserver(client);
ds@1001: 
ds@1001: /**
dvander@545:  * Retrieves values from client replicated keys.
dvander@545:  *
dvander@545:  * @param client		Player's index.
dvander@545:  * @param key			Key string.
dvander@545:  * @param value			Buffer to store value.
dvander@545:  * @param maxlen		Maximum length of valve (UTF-8 safe).
dvander@545:  * @return 				True on success, false otherwise.
dvander@545:  * @error				Invalid client index, or client not connected.
dvander@545:  */
dvander@545: native bool:GetClientInfo(client, const String:key[], String:value[], maxlen);
dvander@545: 
dvander@545: /**
dvander@644:  * Retrieves a client's team index.
dvander@644:  *
dvander@644:  * @param client		Player's index.
dvander@644:  * @return				Team index the client is on (mod specific).
dvander@644:  * @error				Invalid client index, client not in game, or no mod support.
dvander@644:  */
dvander@644: native GetClientTeam(client);
dvander@644:  
dvander@644: /**
dvander@545:  * Sets a client's AdminId.  
dvander@545:  *
dvander@545:  * @param client		Player's index.
dvander@545:  * @param id			AdminId to set.  INVALID_ADMIN_ID removes admin permissions.
dvander@545:  * @param temp			True if the id should be freed on disconnect.
dvander@545:  * @noreturn
dvander@545:  * @error				Invalid client index, client not connected, or bogus AdminId.
dvander@545:  */
dvander@545: native SetUserAdmin(client, AdminId:id, bool:temp=false);
dvander@545: 
dvander@545: /**
dvander@545:  * Retrieves a client's AdminId.
dvander@545:  *
dvander@545:  * @param client		Player's index.
dvander@545:  * @return				AdminId of the client, or INVALID_ADMIN_ID if none.
dvander@545:  * @error				Invalid client index, or client not connected.
dvander@545:  */
dvander@545: native AdminId:GetUserAdmin(client);
dvander@545: 
dvander@545: /**
dvander@545:  * Sets access flags on a client.  If the client is not an admin,
dvander@545:  * a temporary, anonymous AdminId is given.
dvander@545:  *
dvander@545:  * @param client		Player's index.
dvander@545:  * @param ...			Flags to set on the client.
dvander@545:  * @noreturn
dvander@545:  * @error				Invalid client index, or client not connected.
dvander@545:  */
ds@634: native AddUserFlags(client, AdminFlag:...);
dvander@545: 
dvander@545: /**
dvander@545:  * Removes flags from a client.  If the client is not an admin,
dvander@545:  * this has no effect.
dvander@545:  *
dvander@545:  * @param client		Player's index.
dvander@545:  * @param ...			Flags to remove from the client.
dvander@545:  * @noreturn
dvander@545:  * @error				Invalid client index, or client not connected.
dvander@545:  */
ds@634: native RemoveUserFlags(client, AdminFlag:...);
dvander@545: 
dvander@545: /** 
dvander@545:  * Sets access flags on a client using bits instead of flags.  If the
dvander@545:  * client is not an admin, and flags not 0, a temporary, anonymous AdminId is given.
dvander@545:  *
dvander@545:  * @param client		Player's index.
dvander@545:  * @param flags			Bitstring of flags to set on client.
dvander@545:  * @noreturn
dvander@545:  */
dvander@545: native SetUserFlagBits(client, flags);
dvander@545: 
dvander@545: /**
dvander@545:  * Returns client access flags.  If the client is not an admin,
dvander@545:  * the result is always 0.
dvander@545:  * 
dvander@545:  * @param client		Player's index.
dvander@545:  * @return				Flags
dvander@545:  * @error				Invalid client index, or client not connected.
dvander@545:  */
dvander@545: native GetUserFlagBits(client);
dvander@545: 
dvander@545: /**
dvander@545:  * Returns whether a user can target another user.
dvander@545:  * This is a helper function for CanAdminTarget.
dvander@545:  *
dvander@545:  * @param client		Player's index.
dvander@545:  * @param target		Target player's index.
dvander@545:  * @return				True if target is targettable by the player, false otherwise.
dvander@545:  * @error				Invalid or unconnected player indexers.
dvander@545:  */
dvander@545: native bool:CanUserTarget(client, target);
dvander@545: 
dvander@545: /** 
dvander@545:  * Creates a fake client.
dvander@545:  *
dvander@545:  * @param name			Name to use.
dvander@545:  * @return				Client index on success, 0 otherwise.
dvander@545:  */
dvander@545: native CreateFakeClient(const String:name[]);
dvander@545: 
dvander@545: /**
dvander@545:  * Sets a convar value on a fake client.
dvander@545:  *
dvander@545:  * @param client		Client index.
dvander@545:  * @param cvar			ConVar name.
dvander@545:  * @param value			ConVar value.
dvander@545:  * @noreturn
dvander@545:  * @error				Invalid client index, client not connected,
dvander@545:  *						or client not a fake client.
dvander@545:  */
ds@621: native SetFakeClientConVar(client, const String:cvar[], const String:value[]);
faluco@658: 
faluco@658: /**
faluco@658:  * Returns the client's health.
faluco@658:  *
faluco@658:  * @param client		Player's index.
faluco@658:  * @return				Health value.
faluco@658:  * @error				Invalid client index, client not in game, or no mod support.
faluco@658:  */
faluco@658: native GetClientHealth(client);
faluco@658: 
faluco@658: /**
faluco@658:  * Returns the client's model name.
faluco@658:  *
faluco@658:  * @param client		Player's index.
faluco@658:  * @param model			Buffer to store the client's model name.
faluco@658:  * @param maxlen		Maximum length of string buffer (includes NULL terminator).
faluco@658:  * @noreturn
faluco@658:  * @error				Invalid client index, client not in game, or no mod support.
faluco@658:  */
faluco@658: native GetClientModel(client, String:model[], maxlen);
faluco@658: 
faluco@658: /**
faluco@658:  * Returns the client's weapon name.
faluco@658:  *
faluco@658:  * @param client		Player's index.
faluco@658:  * @param weapon		Buffer to store the client's weapon name.
faluco@658:  * @param maxlen		Maximum length of string buffer (includes NULL terminator).
faluco@658:  * @noreturn
faluco@658:  * @error				Invalid client index, client not in game, or no mod support.
faluco@658:  */
faluco@658: native GetClientWeapon(client, String:weapon[], maxlen);
faluco@658: 
faluco@658: /**
faluco@658:  * Returns the client's max size vector.
faluco@658:  *
faluco@658:  * @param client		Player's index.
faluco@658:  * @param vec			Destination vector to store the client's max size.
faluco@658:  * @noreturn
faluco@658:  * @error				Invalid client index, client not in game, or no mod support.
faluco@658:  */
faluco@658: native GetClientMaxs(client, Float:vec[3]);
faluco@658: 
faluco@658: /**
faluco@658:  * Returns the client's min size vector.
faluco@658:  *
faluco@658:  * @param client		Player's index.
faluco@658:  * @param vec			Destination vector to store the client's min size.
faluco@658:  * @noreturn
faluco@658:  * @error				Invalid client index, client not in game, or no mod support.
faluco@658:  */
faluco@658: native GetClientMins(client, Float:vec[3]);
faluco@658: 
faluco@658: /**
faluco@658:  * Returns the client's position angle.
faluco@658:  *
faluco@658:  * @param client		Player's index.
faluco@658:  * @param ang			Destination vector to store the client's position angle.
faluco@658:  * @noreturn
faluco@658:  * @error				Invalid client index, client not in game, or no mod support.
faluco@658:  */
faluco@658: native GetClientAbsAngles(client, Float:ang[3]);
faluco@658: 
faluco@658: /**
faluco@658:  * Returns the client's origin vector.
faluco@658:  *
faluco@658:  * @param client		Player's index.
faluco@658:  * @param vec			Destination vector to store the client's origin vector.
faluco@658:  * @noreturn
faluco@658:  * @error				Invalid client index, client not in game, or no mod support.
faluco@658:  */
faluco@658: native GetClientAbsOrigin(client, Float:vec[3]);
faluco@658: 
faluco@658: /**
faluco@658:  * Returns the client's armor.
faluco@658:  *
faluco@658:  * @param client		Player's index.
faluco@658:  * @return				Armor value.
faluco@658:  * @error				Invalid client index, client not in game, or no mod support.
faluco@658:  */
faluco@658: native GetClientArmor(client);
faluco@658: 
faluco@658: /**
faluco@658:  * Returns the client's death count.
faluco@658:  *
faluco@658:  * @param client		Player's index.
faluco@658:  * @return				Death count.
faluco@658:  * @error				Invalid client index, client not in game, or no mod support.
faluco@658:  */
faluco@658: native GetClientDeaths(client);
faluco@658: 
faluco@658: /**
faluco@658:  * Returns the client's frag count.
faluco@658:  *
faluco@658:  * @param client		Player's index.
faluco@658:  * @return				Frag count.
faluco@658:  * @error				Invalid client index, client not in game, or no mod support.
faluco@658:  */
faluco@658: native GetClientFrags(client);
faluco@682: 
faluco@682: /**
faluco@682:  * Returns the client's send data rate in bytes/sec.
faluco@682:  *
faluco@682:  * @param client		Player's index.
faluco@682:  * @return				Data rate.
faluco@682:  * @error				Invalid client index, client not in game, or fake client.
faluco@682:  */
dvander@691: native GetClientDataRate(client);
faluco@682: 
faluco@682: /**
faluco@682:  * Returns if a client is timing out
faluco@682:  *
faluco@682:  * @param client		Player's index.
faluco@682:  * @return				True if client is timing out, false otherwise.
faluco@682:  * @error				Invalid client index, client not in game, or fake client.
faluco@682:  */
dvander@691: native bool:IsClientTimingOut(client);
faluco@682: 
faluco@682: /**
faluco@682:  * Returns the client's connection time in seconds.
faluco@682:  *
faluco@682:  * @param client		Player's index.
faluco@682:  * @return				Connection time.
faluco@682:  * @error				Invalid client index, client not in game, or fake client.
faluco@682:  */
dvander@691: native Float:GetClientTime(client);
faluco@682: 
faluco@682: /**
faluco@682:  * Returns the client's current latency (RTT), more accurate than GetAvgLatency but jittering.
faluco@682:  *
faluco@682:  * @param client		Player's index.
faluco@682:  * @param flow			Traffic flowing direction.
faluco@682:  * @return				Latency.
faluco@682:  * @error				Invalid client index, client not in game, or fake client.
faluco@682:  */
dvander@691: native Float:GetClientLatency(client, NetFlow:flow);
faluco@682: 
faluco@682: /**
faluco@682:  * Returns the client's average packet latency in seconds.
faluco@682:  *
faluco@682:  * @param client		Player's index.
faluco@682:  * @param flow			Traffic flowing direction.
faluco@682:  * @return				Average latency.
faluco@682:  * @error				Invalid client index, client not in game, or fake client.
faluco@682:  */
dvander@691: native Float:GetClientAvgLatency(client, NetFlow:flow);
faluco@682: 
faluco@682: /**
faluco@682:  * Returns the client's average packet loss, values go from 0 to 1 (for percentages).
faluco@682:  *
faluco@682:  * @param client		Player's index.
faluco@682:  * @param flow			Traffic flowing direction.
faluco@682:  * @return				Average packet loss.
faluco@682:  * @error				Invalid client index, client not in game, or fake client.
faluco@682:  */
dvander@691: native Float:GetClientAvgLoss(client, NetFlow:flow);
faluco@682: 
faluco@682: /**
faluco@682:  * Returns the client's average packet choke, values go from 0 to 1 (for percentages).
faluco@682:  *
faluco@682:  * @param client		Player's index.
faluco@682:  * @param flow			Traffic flowing direction.
faluco@682:  * @return				Average packet choke.
faluco@682:  * @error				Invalid client index, client not in game, or fake client.
faluco@682:  */
dvander@691: native Float:GetClientAvgChoke(client, NetFlow:flow);
faluco@682: 
faluco@682: /**
faluco@682:  * Returns the client's data flow in bytes/sec.
faluco@682:  *
faluco@682:  * @param client		Player's index.
faluco@682:  * @param flow			Traffic flowing direction.
faluco@682:  * @return				Data flow.
faluco@682:  * @error				Invalid client index, client not in game, or fake client.
faluco@682:  */
dvander@691: native Float:GetClientAvgData(client, NetFlow:flow);
faluco@682: 
faluco@682: /**
faluco@682:  * Returns the client's average packet frequency in packets/sec.
faluco@682:  *
faluco@682:  * @param client		Player's index.
faluco@682:  * @param flow			Traffic flowing direction.
faluco@682:  * @return				Packet frequency.
faluco@682:  * @error				Invalid client index, client not in game, or fake client.
faluco@682:  */
dvander@691: native Float:GetClientAvgPackets(client, NetFlow:flow);
faluco@682: 
faluco@682: /**
faluco@682:  * Translates an userid index to the real player index.
faluco@682:  *
faluco@682:  * @param userid		Userid value.
faluco@682:  * @return				Client value.
faluco@682:  * @error				Returns 0 if invalid userid.
faluco@682:  */
faluco@682: native GetClientOfUserId(userid);
ds@992: 
ds@992: /**
ds@992:  * Disconnects a client from the server.
ds@992:  *
ds@992:  * @param client		Client index.
ds@992:  * @param format		Optional formatting rules for disconnect reason.
ds@992:  *                      Note that a period is automatically appended to the string by the engine.
ds@992:  * @param ...			Variable number of format parameters.
ds@992:  * @noreturn
ds@992:  * @error				Invalid client index, or client not connected.
ds@992:  */
ds@996: native KickClient(client, const String:format[]="", any:...);