Home - sourcemod-central - file revision - plugins/include/clients.inc@53ec063c462d Mercurial
summary | shortlog | changelog | graph | tags | branches | files | changeset | file | latest | revisions | annotate | diff | raw | help
plugins/include/clients.inc
author David Anderson <dvander@alliedmods.net>
Fri Apr 13 07:17:52 2007 +0000 (2007-04-13)
changeset 691 53ec063c462d
parent 682 a70055d6d3b3
child 784 0ff19a8bd981
permissions -rw-r--r--
function names now follow convention 
     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:IsPlayerInGame(client);
   162 
   163 /**
   164  * Returns if a certain player has been authenticated.
   165  *
   166  * @param client		Player index.
   167  * @return				True if player has been authenticated, false otherwise.
   168  */
   169 native bool:IsClientAuthorized(client);
   170 
   171 /**
   172  * Returns if a certain player is a fake client.
   173  *
   174  * @param client		Player index.
   175  * @return				True if player is a fake client, false otherwise.
   176  */
   177 native bool:IsFakeClient(client);
   178 
   179 /**
   180  * Retrieves values from client replicated keys.
   181  *
   182  * @param client		Player's index.
   183  * @param key			Key string.
   184  * @param value			Buffer to store value.
   185  * @param maxlen		Maximum length of valve (UTF-8 safe).
   186  * @return 				True on success, false otherwise.
   187  * @error				Invalid client index, or client not connected.
   188  */
   189 native bool:GetClientInfo(client, const String:key[], String:value[], maxlen);
   190 
   191 /**
   192  * Retrieves a client's team index.
   193  *
   194  * @param client		Player's index.
   195  * @return				Team index the client is on (mod specific).
   196  * @error				Invalid client index, client not in game, or no mod support.
   197  */
   198 native GetClientTeam(client);
   199  
   200 /**
   201  * Sets a client's AdminId.  
   202  *
   203  * @param client		Player's index.
   204  * @param id			AdminId to set.  INVALID_ADMIN_ID removes admin permissions.
   205  * @param temp			True if the id should be freed on disconnect.
   206  * @noreturn
   207  * @error				Invalid client index, client not connected, or bogus AdminId.
   208  */
   209 native SetUserAdmin(client, AdminId:id, bool:temp=false);
   210 
   211 /**
   212  * Retrieves a client's AdminId.
   213  *
   214  * @param client		Player's index.
   215  * @return				AdminId of the client, or INVALID_ADMIN_ID if none.
   216  * @error				Invalid client index, or client not connected.
   217  */
   218 native AdminId:GetUserAdmin(client);
   219 
   220 /**
   221  * Sets access flags on a client.  If the client is not an admin,
   222  * a temporary, anonymous AdminId is given.
   223  *
   224  * @param client		Player's index.
   225  * @param ...			Flags to set on the client.
   226  * @noreturn
   227  * @error				Invalid client index, or client not connected.
   228  */
   229 native AddUserFlags(client, AdminFlag:...);
   230 
   231 /**
   232  * Removes flags from a client.  If the client is not an admin,
   233  * this has no effect.
   234  *
   235  * @param client		Player's index.
   236  * @param ...			Flags to remove from the client.
   237  * @noreturn
   238  * @error				Invalid client index, or client not connected.
   239  */
   240 native RemoveUserFlags(client, AdminFlag:...);
   241 
   242 /** 
   243  * Sets access flags on a client using bits instead of flags.  If the
   244  * client is not an admin, and flags not 0, a temporary, anonymous AdminId is given.
   245  *
   246  * @param client		Player's index.
   247  * @param flags			Bitstring of flags to set on client.
   248  * @noreturn
   249  */
   250 native SetUserFlagBits(client, flags);
   251 
   252 /**
   253  * Returns client access flags.  If the client is not an admin,
   254  * the result is always 0.
   255  * 
   256  * @param client		Player's index.
   257  * @return				Flags
   258  * @error				Invalid client index, or client not connected.
   259  */
   260 native GetUserFlagBits(client);
   261 
   262 /**
   263  * Returns whether a user can target another user.
   264  * This is a helper function for CanAdminTarget.
   265  *
   266  * @param client		Player's index.
   267  * @param target		Target player's index.
   268  * @return				True if target is targettable by the player, false otherwise.
   269  * @error				Invalid or unconnected player indexers.
   270  */
   271 native bool:CanUserTarget(client, target);
   272 
   273 /** 
   274  * Creates a fake client.
   275  *
   276  * @param name			Name to use.
   277  * @return				Client index on success, 0 otherwise.
   278  */
   279 native CreateFakeClient(const String:name[]);
   280 
   281 /**
   282  * Sets a convar value on a fake client.
   283  *
   284  * @param client		Client index.
   285  * @param cvar			ConVar name.
   286  * @param value			ConVar value.
   287  * @noreturn
   288  * @error				Invalid client index, client not connected,
   289  *						or client not a fake client.
   290  */
   291 native SetFakeClientConVar(client, const String:cvar[], const String:value[]);
   292 
   293 /**
   294  * Returns the client's health.
   295  *
   296  * @param client		Player's index.
   297  * @return				Health value.
   298  * @error				Invalid client index, client not in game, or no mod support.
   299  */
   300 native GetClientHealth(client);
   301 
   302 /**
   303  * Returns the client's model name.
   304  *
   305  * @param client		Player's index.
   306  * @param model			Buffer to store the client's model name.
   307  * @param maxlen		Maximum length of string buffer (includes NULL terminator).
   308  * @noreturn
   309  * @error				Invalid client index, client not in game, or no mod support.
   310  */
   311 native GetClientModel(client, String:model[], maxlen);
   312 
   313 /**
   314  * Returns the client's weapon name.
   315  *
   316  * @param client		Player's index.
   317  * @param weapon		Buffer to store the client's weapon name.
   318  * @param maxlen		Maximum length of string buffer (includes NULL terminator).
   319  * @noreturn
   320  * @error				Invalid client index, client not in game, or no mod support.
   321  */
   322 native GetClientWeapon(client, String:weapon[], maxlen);
   323 
   324 /**
   325  * Returns the client's max size vector.
   326  *
   327  * @param client		Player's index.
   328  * @param vec			Destination vector to store the client's max size.
   329  * @noreturn
   330  * @error				Invalid client index, client not in game, or no mod support.
   331  */
   332 native GetClientMaxs(client, Float:vec[3]);
   333 
   334 /**
   335  * Returns the client's min size vector.
   336  *
   337  * @param client		Player's index.
   338  * @param vec			Destination vector to store the client's min size.
   339  * @noreturn
   340  * @error				Invalid client index, client not in game, or no mod support.
   341  */
   342 native GetClientMins(client, Float:vec[3]);
   343 
   344 /**
   345  * Returns the client's position angle.
   346  *
   347  * @param client		Player's index.
   348  * @param ang			Destination vector to store the client's position angle.
   349  * @noreturn
   350  * @error				Invalid client index, client not in game, or no mod support.
   351  */
   352 native GetClientAbsAngles(client, Float:ang[3]);
   353 
   354 /**
   355  * Returns the client's origin vector.
   356  *
   357  * @param client		Player's index.
   358  * @param vec			Destination vector to store the client's origin vector.
   359  * @noreturn
   360  * @error				Invalid client index, client not in game, or no mod support.
   361  */
   362 native GetClientAbsOrigin(client, Float:vec[3]);
   363 
   364 /**
   365  * Returns the client's armor.
   366  *
   367  * @param client		Player's index.
   368  * @return				Armor value.
   369  * @error				Invalid client index, client not in game, or no mod support.
   370  */
   371 native GetClientArmor(client);
   372 
   373 /**
   374  * Returns the client's death count.
   375  *
   376  * @param client		Player's index.
   377  * @return				Death count.
   378  * @error				Invalid client index, client not in game, or no mod support.
   379  */
   380 native GetClientDeaths(client);
   381 
   382 /**
   383  * Returns the client's frag count.
   384  *
   385  * @param client		Player's index.
   386  * @return				Frag count.
   387  * @error				Invalid client index, client not in game, or no mod support.
   388  */
   389 native GetClientFrags(client);
   390 
   391 /**
   392  * Returns the client's send data rate in bytes/sec.
   393  *
   394  * @param client		Player's index.
   395  * @return				Data rate.
   396  * @error				Invalid client index, client not in game, or fake client.
   397  */
   398 native GetClientDataRate(client);
   399 
   400 /**
   401  * Returns if a client is timing out
   402  *
   403  * @param client		Player's index.
   404  * @return				True if client is timing out, false otherwise.
   405  * @error				Invalid client index, client not in game, or fake client.
   406  */
   407 native bool:IsClientTimingOut(client);
   408 
   409 /**
   410  * Returns the client's connection time in seconds.
   411  *
   412  * @param client		Player's index.
   413  * @return				Connection time.
   414  * @error				Invalid client index, client not in game, or fake client.
   415  */
   416 native Float:GetClientTime(client);
   417 
   418 /**
   419  * Returns the client's current latency (RTT), more accurate than GetAvgLatency but jittering.
   420  *
   421  * @param client		Player's index.
   422  * @param flow			Traffic flowing direction.
   423  * @return				Latency.
   424  * @error				Invalid client index, client not in game, or fake client.
   425  */
   426 native Float:GetClientLatency(client, NetFlow:flow);
   427 
   428 /**
   429  * Returns the client's average packet latency in seconds.
   430  *
   431  * @param client		Player's index.
   432  * @param flow			Traffic flowing direction.
   433  * @return				Average latency.
   434  * @error				Invalid client index, client not in game, or fake client.
   435  */
   436 native Float:GetClientAvgLatency(client, NetFlow:flow);
   437 
   438 /**
   439  * Returns the client's average packet loss, values go from 0 to 1 (for percentages).
   440  *
   441  * @param client		Player's index.
   442  * @param flow			Traffic flowing direction.
   443  * @return				Average packet loss.
   444  * @error				Invalid client index, client not in game, or fake client.
   445  */
   446 native Float:GetClientAvgLoss(client, NetFlow:flow);
   447 
   448 /**
   449  * Returns the client's average packet choke, values go from 0 to 1 (for percentages).
   450  *
   451  * @param client		Player's index.
   452  * @param flow			Traffic flowing direction.
   453  * @return				Average packet choke.
   454  * @error				Invalid client index, client not in game, or fake client.
   455  */
   456 native Float:GetClientAvgChoke(client, NetFlow:flow);
   457 
   458 /**
   459  * Returns the client's data flow in bytes/sec.
   460  *
   461  * @param client		Player's index.
   462  * @param flow			Traffic flowing direction.
   463  * @return				Data flow.
   464  * @error				Invalid client index, client not in game, or fake client.
   465  */
   466 native Float:GetClientAvgData(client, NetFlow:flow);
   467 
   468 /**
   469  * Returns the client's average packet frequency in packets/sec.
   470  *
   471  * @param client		Player's index.
   472  * @param flow			Traffic flowing direction.
   473  * @return				Packet frequency.
   474  * @error				Invalid client index, client not in game, or fake client.
   475  */
   476 native Float:GetClientAvgPackets(client, NetFlow:flow);
   477 
   478 /**
   479  * Translates an userid index to the real player index.
   480  *
   481  * @param userid		Userid value.
   482  * @return				Client value.
   483  * @error				Returns 0 if invalid userid.
   484  */
   485 native GetClientOfUserId(userid);
   486 
   487 /**
   488  * Executes a client command on the server without being networked.
   489  *
   490  * @param client		Index of the client.
   491  * @param fmt			Format of the client command.
   492  * @param ...			Format parameters
   493  * @noreturn
   494  * @error				Invalid client index, or client not connected.
   495  */
   496 native FakeClientCommand(client, const String:fmt[], any:...);
sourcemod-central
Feed