Home - sourcemod-central - file revision - plugins/include/clients.inc@0ff19a8bd981 Mercurial
summary | shortlog | changelog | graph | tags | branches | files | changeset | file | latest | revisions | annotate | diff | raw | help
plugins/include/clients.inc
author Scott Ehlert <ds@alliedmods.net>
Sun May 13 07:48:36 2007 +0000 (2007-05-13)
changeset 784 0ff19a8bd981
parent 691 53ec063c462d
child 873 a2136b3be10d
permissions -rw-r--r--
amb283 - Renamed IsPlayerInGame() to IsClientInGame() 
     1 /**
     2  * vim: set ts=4 :
     3  * ===============================================================
     4  * SourceMod (C)2004-2007 AlliedModders LLC.  All rights reserved.
     5  * ===============================================================
     6  *
     7  *  This file is part of the SourceMod/SourcePawn SDK.  This file may only be used 
     8  * or modified under the Terms and Conditions of its License Agreement, which is found 
     9  * in LICENSE.txt.  The Terms and Conditions for making SourceMod extensions/plugins 
    10  * may change at any time.  To view the latest information, see:
    11  *   http://www.sourcemod.net/license.php
    12  *
    13  * Version: $Id$
    14  */
    15 
    16 #if defined _clients_included
    17  #endinput
    18 #endif
    19 #define _clients_included
    20 
    21 enum NetFlow
    22 {
    23 	NetFlow_Outgoing = 0,		/**< Outgoing traffic */
    24 	NetFlow_Incoming,		/**< Incoming traffic */
    25 	NetFlow_Both			/**< Incoming and outgoing traffic */
    26 };
    27 
    28 /**
    29  * Called on client connection.
    30  *
    31  * @param client		Player index.
    32  * @param rejectmsg		Buffer to store the rejection message when the connection is refused.
    33  * @param maxlen		Maximum number of characters for rejection buffer.
    34  * @return				True to validate client's connection, false to refuse it.
    35  */
    36 forward bool:OnClientConnect(client, String:rejectmsg[], maxlen);
    37 
    38 /**
    39  * Called when a client is entering to the game.
    40  *
    41  * @param client		Player index.
    42  * @noreturn
    43  */
    44 forward OnClientPutInServer(client);
    45 
    46 /**
    47  * Called when a client is disconnecting from the server.
    48  *
    49  * @param client		Player index.
    50  * @noreturn
    51  */
    52 forward OnClientDisconnect(client);
    53 
    54 /**
    55  * Called when a client is disconnected from the server.
    56  *
    57  * @param client		Player index.
    58  * @noreturn
    59  */
    60 forward OnClientDisconnect_Post(client);
    61 
    62 /**
    63  * Called when a client is sending a command.
    64  *
    65  * @param client		Player index.
    66  * @param args			Number of arguments.
    67  * @noreturn
    68  */
    69 forward Action:OnClientCommand(client, args);
    70 
    71 /**
    72  * Called whenever the client's settings are changed.
    73  *
    74  * @param client		Player index.
    75  * @noreturn
    76  */
    77 forward OnClientSettingsChanged(client);
    78 
    79 /**
    80  * Called when a client receives a Steam ID.
    81  * @note This is called by bots, but the ID will be "BOT"
    82  *
    83  * @param client		Player index.
    84  * @param auth			Player auth string.
    85  */
    86 forward OnClientAuthorized(client, const String:auth[]);
    87 
    88 /**
    89  * Returns the maximum number of clients allowed on the server.
    90  *
    91  * @return				Maximum number of clients allowed.
    92  */
    93 native GetMaxClients();
    94 
    95 /**
    96  * Returns the client count put in the server.
    97  *
    98  * @param inGameOnly	If false connecting players are also counted.
    99  * @return				Client count in the server.
   100  */
   101 native GetClientCount(bool:inGameOnly=true);
   102 
   103 /**
   104  * Returns the client's name.
   105  *
   106  * @param client		Player index.
   107  * @param name			Buffer to store the client's name.
   108  * @param maxlen		Maximum length of string buffer (includes NULL terminator).
   109  * @return				True on success, false otherwise.
   110  * @error				If the client is not connected an error will be thrown.
   111  */
   112 native bool:GetClientName(client, String:name[], maxlen);
   113 
   114 /**
   115  * Retrieves a client's IP address.
   116  *
   117  * @param client		Player index.
   118  * @param name			Buffer to store the client's ip address.
   119  * @param maxlen		Maximum length of string buffer (includes NULL terminator).
   120  * @param remport		Remove client's port from the ip string (true by default).
   121  * @return				True on success, false otherwise.
   122  * @error				If the client is not connected or the index is invalid.
   123  */
   124 native bool:GetClientIP(client, String:ip[], maxlen, bool:remport=true);
   125 
   126 /**
   127  * Retrieves a client's authentication string (SteamID).
   128  *
   129  * @param client		Player index.
   130  * @param auth			Buffer to store the client's auth string.
   131  * @param maxlen		Maximum length of string buffer (includes NULL terminator).
   132  * @return				True on success, false otherwise.
   133  * @error				If the client is not connected or the index is invalid.
   134  */
   135 native bool:GetClientAuthString(client, String:auth[], maxlen);
   136 
   137 /**
   138  * Retrieves a client's user id, which is an index incremented for every client
   139  * that joins the server.
   140  *
   141  * @param client		Player index.
   142  * @return				User id of the client.
   143  * @error 				If the client is not connected or the index is invalid.
   144  */
   145 native GetClientUserId(client);
   146 
   147 /**
   148  * Returns if a certain player is connected.
   149  *
   150  * @param client		Player index.
   151  * @return				True if player is connected to the server, false otherwise.
   152  */
   153 native bool:IsClientConnected(client);
   154 
   155 /**
   156  * Returns if a certain player has entered the game.
   157  *
   158  * @param client		Player index.
   159  * @return				True if player has entered the game, false otherwise.
   160  */
   161 native bool:IsClientInGame(client);
   162 
   163 /**
   164  * Backwards compatibility stock - use IsClientInGame
   165  * @deprecated			Renamed to IsClientInGame
   166  */
   167 stock bool:IsPlayerInGame(client)
   168 {
   169 	return IsClientInGame(client);
   170 }
   171 
   172 /**
   173  * Returns if a certain player has been authenticated.
   174  *
   175  * @param client		Player index.
   176  * @return				True if player has been authenticated, false otherwise.
   177  */
   178 native bool:IsClientAuthorized(client);
   179 
   180 /**
   181  * Returns if a certain player is a fake client.
   182  *
   183  * @param client		Player index.
   184  * @return				True if player is a fake client, false otherwise.
   185  */
   186 native bool:IsFakeClient(client);
   187 
   188 /**
   189  * Retrieves values from client replicated keys.
   190  *
   191  * @param client		Player's index.
   192  * @param key			Key string.
   193  * @param value			Buffer to store value.
   194  * @param maxlen		Maximum length of valve (UTF-8 safe).
   195  * @return 				True on success, false otherwise.
   196  * @error				Invalid client index, or client not connected.
   197  */
   198 native bool:GetClientInfo(client, const String:key[], String:value[], maxlen);
   199 
   200 /**
   201  * Retrieves a client's team index.
   202  *
   203  * @param client		Player's index.
   204  * @return				Team index the client is on (mod specific).
   205  * @error				Invalid client index, client not in game, or no mod support.
   206  */
   207 native GetClientTeam(client);
   208  
   209 /**
   210  * Sets a client's AdminId.  
   211  *
   212  * @param client		Player's index.
   213  * @param id			AdminId to set.  INVALID_ADMIN_ID removes admin permissions.
   214  * @param temp			True if the id should be freed on disconnect.
   215  * @noreturn
   216  * @error				Invalid client index, client not connected, or bogus AdminId.
   217  */
   218 native SetUserAdmin(client, AdminId:id, bool:temp=false);
   219 
   220 /**
   221  * Retrieves a client's AdminId.
   222  *
   223  * @param client		Player's index.
   224  * @return				AdminId of the client, or INVALID_ADMIN_ID if none.
   225  * @error				Invalid client index, or client not connected.
   226  */
   227 native AdminId:GetUserAdmin(client);
   228 
   229 /**
   230  * Sets access flags on a client.  If the client is not an admin,
   231  * a temporary, anonymous AdminId is given.
   232  *
   233  * @param client		Player's index.
   234  * @param ...			Flags to set on the client.
   235  * @noreturn
   236  * @error				Invalid client index, or client not connected.
   237  */
   238 native AddUserFlags(client, AdminFlag:...);
   239 
   240 /**
   241  * Removes flags from a client.  If the client is not an admin,
   242  * this has no effect.
   243  *
   244  * @param client		Player's index.
   245  * @param ...			Flags to remove from the client.
   246  * @noreturn
   247  * @error				Invalid client index, or client not connected.
   248  */
   249 native RemoveUserFlags(client, AdminFlag:...);
   250 
   251 /** 
   252  * Sets access flags on a client using bits instead of flags.  If the
   253  * client is not an admin, and flags not 0, a temporary, anonymous AdminId is given.
   254  *
   255  * @param client		Player's index.
   256  * @param flags			Bitstring of flags to set on client.
   257  * @noreturn
   258  */
   259 native SetUserFlagBits(client, flags);
   260 
   261 /**
   262  * Returns client access flags.  If the client is not an admin,
   263  * the result is always 0.
   264  * 
   265  * @param client		Player's index.
   266  * @return				Flags
   267  * @error				Invalid client index, or client not connected.
   268  */
   269 native GetUserFlagBits(client);
   270 
   271 /**
   272  * Returns whether a user can target another user.
   273  * This is a helper function for CanAdminTarget.
   274  *
   275  * @param client		Player's index.
   276  * @param target		Target player's index.
   277  * @return				True if target is targettable by the player, false otherwise.
   278  * @error				Invalid or unconnected player indexers.
   279  */
   280 native bool:CanUserTarget(client, target);
   281 
   282 /** 
   283  * Creates a fake client.
   284  *
   285  * @param name			Name to use.
   286  * @return				Client index on success, 0 otherwise.
   287  */
   288 native CreateFakeClient(const String:name[]);
   289 
   290 /**
   291  * Sets a convar value on a fake client.
   292  *
   293  * @param client		Client index.
   294  * @param cvar			ConVar name.
   295  * @param value			ConVar value.
   296  * @noreturn
   297  * @error				Invalid client index, client not connected,
   298  *						or client not a fake client.
   299  */
   300 native SetFakeClientConVar(client, const String:cvar[], const String:value[]);
   301 
   302 /**
   303  * Returns the client's health.
   304  *
   305  * @param client		Player's index.
   306  * @return				Health value.
   307  * @error				Invalid client index, client not in game, or no mod support.
   308  */
   309 native GetClientHealth(client);
   310 
   311 /**
   312  * Returns the client's model name.
   313  *
   314  * @param client		Player's index.
   315  * @param model			Buffer to store the client's model name.
   316  * @param maxlen		Maximum length of string buffer (includes NULL terminator).
   317  * @noreturn
   318  * @error				Invalid client index, client not in game, or no mod support.
   319  */
   320 native GetClientModel(client, String:model[], maxlen);
   321 
   322 /**
   323  * Returns the client's weapon name.
   324  *
   325  * @param client		Player's index.
   326  * @param weapon		Buffer to store the client's weapon name.
   327  * @param maxlen		Maximum length of string buffer (includes NULL terminator).
   328  * @noreturn
   329  * @error				Invalid client index, client not in game, or no mod support.
   330  */
   331 native GetClientWeapon(client, String:weapon[], maxlen);
   332 
   333 /**
   334  * Returns the client's max size vector.
   335  *
   336  * @param client		Player's index.
   337  * @param vec			Destination vector to store the client's max size.
   338  * @noreturn
   339  * @error				Invalid client index, client not in game, or no mod support.
   340  */
   341 native GetClientMaxs(client, Float:vec[3]);
   342 
   343 /**
   344  * Returns the client's min size vector.
   345  *
   346  * @param client		Player's index.
   347  * @param vec			Destination vector to store the client's min size.
   348  * @noreturn
   349  * @error				Invalid client index, client not in game, or no mod support.
   350  */
   351 native GetClientMins(client, Float:vec[3]);
   352 
   353 /**
   354  * Returns the client's position angle.
   355  *
   356  * @param client		Player's index.
   357  * @param ang			Destination vector to store the client's position angle.
   358  * @noreturn
   359  * @error				Invalid client index, client not in game, or no mod support.
   360  */
   361 native GetClientAbsAngles(client, Float:ang[3]);
   362 
   363 /**
   364  * Returns the client's origin vector.
   365  *
   366  * @param client		Player's index.
   367  * @param vec			Destination vector to store the client's origin vector.
   368  * @noreturn
   369  * @error				Invalid client index, client not in game, or no mod support.
   370  */
   371 native GetClientAbsOrigin(client, Float:vec[3]);
   372 
   373 /**
   374  * Returns the client's armor.
   375  *
   376  * @param client		Player's index.
   377  * @return				Armor value.
   378  * @error				Invalid client index, client not in game, or no mod support.
   379  */
   380 native GetClientArmor(client);
   381 
   382 /**
   383  * Returns the client's death count.
   384  *
   385  * @param client		Player's index.
   386  * @return				Death count.
   387  * @error				Invalid client index, client not in game, or no mod support.
   388  */
   389 native GetClientDeaths(client);
   390 
   391 /**
   392  * Returns the client's frag count.
   393  *
   394  * @param client		Player's index.
   395  * @return				Frag count.
   396  * @error				Invalid client index, client not in game, or no mod support.
   397  */
   398 native GetClientFrags(client);
   399 
   400 /**
   401  * Returns the client's send data rate in bytes/sec.
   402  *
   403  * @param client		Player's index.
   404  * @return				Data rate.
   405  * @error				Invalid client index, client not in game, or fake client.
   406  */
   407 native GetClientDataRate(client);
   408 
   409 /**
   410  * Returns if a client is timing out
   411  *
   412  * @param client		Player's index.
   413  * @return				True if client is timing out, false otherwise.
   414  * @error				Invalid client index, client not in game, or fake client.
   415  */
   416 native bool:IsClientTimingOut(client);
   417 
   418 /**
   419  * Returns the client's connection time in seconds.
   420  *
   421  * @param client		Player's index.
   422  * @return				Connection time.
   423  * @error				Invalid client index, client not in game, or fake client.
   424  */
   425 native Float:GetClientTime(client);
   426 
   427 /**
   428  * Returns the client's current latency (RTT), more accurate than GetAvgLatency but jittering.
   429  *
   430  * @param client		Player's index.
   431  * @param flow			Traffic flowing direction.
   432  * @return				Latency.
   433  * @error				Invalid client index, client not in game, or fake client.
   434  */
   435 native Float:GetClientLatency(client, NetFlow:flow);
   436 
   437 /**
   438  * Returns the client's average packet latency in seconds.
   439  *
   440  * @param client		Player's index.
   441  * @param flow			Traffic flowing direction.
   442  * @return				Average latency.
   443  * @error				Invalid client index, client not in game, or fake client.
   444  */
   445 native Float:GetClientAvgLatency(client, NetFlow:flow);
   446 
   447 /**
   448  * Returns the client's average packet loss, values go from 0 to 1 (for percentages).
   449  *
   450  * @param client		Player's index.
   451  * @param flow			Traffic flowing direction.
   452  * @return				Average packet loss.
   453  * @error				Invalid client index, client not in game, or fake client.
   454  */
   455 native Float:GetClientAvgLoss(client, NetFlow:flow);
   456 
   457 /**
   458  * Returns the client's average packet choke, values go from 0 to 1 (for percentages).
   459  *
   460  * @param client		Player's index.
   461  * @param flow			Traffic flowing direction.
   462  * @return				Average packet choke.
   463  * @error				Invalid client index, client not in game, or fake client.
   464  */
   465 native Float:GetClientAvgChoke(client, NetFlow:flow);
   466 
   467 /**
   468  * Returns the client's data flow in bytes/sec.
   469  *
   470  * @param client		Player's index.
   471  * @param flow			Traffic flowing direction.
   472  * @return				Data flow.
   473  * @error				Invalid client index, client not in game, or fake client.
   474  */
   475 native Float:GetClientAvgData(client, NetFlow:flow);
   476 
   477 /**
   478  * Returns the client's average packet frequency in packets/sec.
   479  *
   480  * @param client		Player's index.
   481  * @param flow			Traffic flowing direction.
   482  * @return				Packet frequency.
   483  * @error				Invalid client index, client not in game, or fake client.
   484  */
   485 native Float:GetClientAvgPackets(client, NetFlow:flow);
   486 
   487 /**
   488  * Translates an userid index to the real player index.
   489  *
   490  * @param userid		Userid value.
   491  * @return				Client value.
   492  * @error				Returns 0 if invalid userid.
   493  */
   494 native GetClientOfUserId(userid);
   495 
   496 /**
   497  * Executes a client command on the server without being networked.
   498  *
   499  * @param client		Index of the client.
   500  * @param fmt			Format of the client command.
   501  * @param ...			Format parameters
   502  * @noreturn
   503  * @error				Invalid client index, or client not connected.
   504  */
   505 native FakeClientCommand(client, const String:fmt[], any:...);
sourcemod-central
Feed