1.1 --- a/plugins/include/clients.inc Fri Mar 28 06:21:34 2008 +0000
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,628 +0,0 @@
1.4 -/**
1.5 - * vim: set ts=4 :
1.6 - * =============================================================================
1.7 - * SourceMod (C)2004-2007 AlliedModders LLC. All rights reserved.
1.8 - * =============================================================================
1.9 - *
1.10 - * This file is part of the SourceMod/SourcePawn SDK.
1.11 - *
1.12 - * This program is free software; you can redistribute it and/or modify it under
1.13 - * the terms of the GNU General Public License, version 3.0, as published by the
1.14 - * Free Software Foundation.
1.15 - *
1.16 - * This program is distributed in the hope that it will be useful, but WITHOUT
1.17 - * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
1.18 - * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
1.19 - * details.
1.20 - *
1.21 - * You should have received a copy of the GNU General Public License along with
1.22 - * this program. If not, see <http://www.gnu.org/licenses/>.
1.23 - *
1.24 - * As a special exception, AlliedModders LLC gives you permission to link the
1.25 - * code of this program (as well as its derivative works) to "Half-Life 2," the
1.26 - * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software
1.27 - * by the Valve Corporation. You must obey the GNU General Public License in
1.28 - * all respects for all other code used. Additionally, AlliedModders LLC grants
1.29 - * this exception to all derivative works. AlliedModders LLC defines further
1.30 - * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),
1.31 - * or <http://www.sourcemod.net/license.php>.
1.32 - *
1.33 - * Version: $Id$
1.34 - */
1.35 -
1.36 -#if defined _clients_included
1.37 - #endinput
1.38 -#endif
1.39 -#define _clients_included
1.40 -
1.41 -enum NetFlow
1.42 -{
1.43 - NetFlow_Outgoing = 0, /**< Outgoing traffic */
1.44 - NetFlow_Incoming, /**< Incoming traffic */
1.45 - NetFlow_Both /**< Incoming and outgoing traffic */
1.46 -};
1.47 -
1.48 -#define MAXPLAYERS 64 /**< Maximum number of players that can be in server */
1.49 -#define MAX_NAME_LENGTH 32 /**< Maximum buffer required to store a client name */
1.50 -
1.51 -/**
1.52 - * Called on client connection.
1.53 - *
1.54 - * @param client Client index.
1.55 - * @param rejectmsg Buffer to store the rejection message when the connection is refused.
1.56 - * @param maxlen Maximum number of characters for rejection buffer.
1.57 - * @return True to validate client's connection, false to refuse it.
1.58 - */
1.59 -forward bool:OnClientConnect(client, String:rejectmsg[], maxlen);
1.60 -
1.61 -/**
1.62 - * Called when a client is entering to the game.
1.63 - *
1.64 - * @note Whether a client has a steamid is undefined until OnClientAuthorized
1.65 - * is called, which may occur either before or after OnClientPutInServer.
1.66 - *
1.67 - * @param client Client index.
1.68 - * @noreturn
1.69 - */
1.70 -forward OnClientPutInServer(client);
1.71 -
1.72 -/**
1.73 - * Called when a client is disconnecting from the server.
1.74 - *
1.75 - * @param client Client index.
1.76 - * @noreturn
1.77 - */
1.78 -forward OnClientDisconnect(client);
1.79 -
1.80 -/**
1.81 - * Called when a client is disconnected from the server.
1.82 - *
1.83 - * @param client Client index.
1.84 - * @noreturn
1.85 - */
1.86 -forward OnClientDisconnect_Post(client);
1.87 -
1.88 -/**
1.89 - * Called when a client is sending a command.
1.90 - *
1.91 - * @param client Client index.
1.92 - * @param args Number of arguments.
1.93 - * @noreturn
1.94 - */
1.95 -forward Action:OnClientCommand(client, args);
1.96 -
1.97 -/**
1.98 - * Called whenever the client's settings are changed.
1.99 - *
1.100 - * @param client Client index.
1.101 - * @noreturn
1.102 - */
1.103 -forward OnClientSettingsChanged(client);
1.104 -
1.105 -/**
1.106 - * Called when a client receives a Steam ID.
1.107 -
1.108 - * Admin properties are not assigned here, but on OnClientPostAdminCheck().
1.109 - * This is called by bots, but the ID will be "BOT".
1.110 - *
1.111 - * @param client Client index.
1.112 - * @param auth Client auth string.
1.113 - * @noreturn
1.114 - */
1.115 -forward OnClientAuthorized(client, const String:auth[]);
1.116 -
1.117 -/**
1.118 - * Called once a client is authorized and fully in-game, but
1.119 - * before admin checks are done. This can be used to override
1.120 - * the default admin checks for a client.
1.121 - *
1.122 - * Note: If handled/blocked, PostAdminCheck must be signalled
1.123 - * manually via NotifyPostAdminCheck().
1.124 - *
1.125 - * @param client Client index.
1.126 - * @return Plugin_Handled to block admin checks.
1.127 - */
1.128 -forward Action:OnClientPreAdminCheck(client);
1.129 -
1.130 -/**
1.131 - * Called once a client is authorized and fully in-game, and
1.132 - * after all post-connection authorizations have been performed.
1.133 - *
1.134 - * @param client Client index.
1.135 - * @noreturn
1.136 - */
1.137 -forward OnClientPostAdminCheck(client);
1.138 -
1.139 -/**
1.140 - * Returns the maximum number of clients allowed on the server. This may
1.141 - * return 0 if called before OnMapStart(), and thus should not be called
1.142 - * in OnPluginStart().
1.143 - *
1.144 - * @return Maximum number of clients allowed.
1.145 - */
1.146 -native GetMaxClients();
1.147 -
1.148 -/**
1.149 - * Returns the client count put in the server.
1.150 - *
1.151 - * @param inGameOnly If false connecting players are also counted.
1.152 - * @return Client count in the server.
1.153 - */
1.154 -native GetClientCount(bool:inGameOnly=true);
1.155 -
1.156 -/**
1.157 - * Returns the client's name.
1.158 - *
1.159 - * @param client Player index.
1.160 - * @param name Buffer to store the client's name.
1.161 - * @param maxlen Maximum length of string buffer (includes NULL terminator).
1.162 - * @return True on success, false otherwise.
1.163 - * @error If the client is not connected an error will be thrown.
1.164 - */
1.165 -native bool:GetClientName(client, String:name[], maxlen);
1.166 -
1.167 -/**
1.168 - * Retrieves a client's IP address.
1.169 - *
1.170 - * @param client Player index.
1.171 - * @param name Buffer to store the client's ip address.
1.172 - * @param maxlen Maximum length of string buffer (includes NULL terminator).
1.173 - * @param remport Remove client's port from the ip string (true by default).
1.174 - * @return True on success, false otherwise.
1.175 - * @error If the client is not connected or the index is invalid.
1.176 - */
1.177 -native bool:GetClientIP(client, String:ip[], maxlen, bool:remport=true);
1.178 -
1.179 -/**
1.180 - * Retrieves a client's authentication string (SteamID).
1.181 - *
1.182 - * @param client Player index.
1.183 - * @param auth Buffer to store the client's auth string.
1.184 - * @param maxlen Maximum length of string buffer (includes NULL terminator).
1.185 - * @return True on success, false otherwise.
1.186 - * @error If the client is not connected or the index is invalid.
1.187 - */
1.188 -native bool:GetClientAuthString(client, String:auth[], maxlen);
1.189 -
1.190 -/**
1.191 - * Retrieves a client's user id, which is an index incremented for every client
1.192 - * that joins the server.
1.193 - *
1.194 - * @param client Player index.
1.195 - * @return User id of the client.
1.196 - * @error If the client is not connected or the index is invalid.
1.197 - */
1.198 -native GetClientUserId(client);
1.199 -
1.200 -/**
1.201 - * Returns if a certain player is connected.
1.202 - *
1.203 - * @param client Player index.
1.204 - * @return True if player is connected to the server, false otherwise.
1.205 - */
1.206 -native bool:IsClientConnected(client);
1.207 -
1.208 -/**
1.209 - * Returns if a certain player has entered the game.
1.210 - *
1.211 - * @param client Player index (index does not have to be connected).
1.212 - * @return True if player has entered the game, false otherwise.
1.213 - * @error Invalid client index.
1.214 - */
1.215 -native bool:IsClientInGame(client);
1.216 -
1.217 -/**
1.218 - * Returns if a client is in the "kick queue" (i.e. the client will be kicked
1.219 - * shortly and thus they should not appear as valid).
1.220 - *
1.221 - * @param client Player index (must be connected).
1.222 - * @return True if in the kick queue, false otherwise.
1.223 - * @error Invalid client index.
1.224 - */
1.225 -native bool:IsClientInKickQueue(client);
1.226 -
1.227 -/**
1.228 - * Backwards compatibility stock - use IsClientInGame
1.229 - * @deprecated Renamed to IsClientInGame
1.230 - */
1.231 -#pragma deprecated Use IsClientInGame() instead
1.232 -stock bool:IsPlayerInGame(client)
1.233 -{
1.234 - return IsClientInGame(client);
1.235 -}
1.236 -
1.237 -/**
1.238 - * Returns if a certain player has been authenticated.
1.239 - *
1.240 - * @param client Player index.
1.241 - * @return True if player has been authenticated, false otherwise.
1.242 - */
1.243 -native bool:IsClientAuthorized(client);
1.244 -
1.245 -/**
1.246 - * Returns if a certain player is a fake client.
1.247 - *
1.248 - * @param client Player index.
1.249 - * @return True if player is a fake client, false otherwise.
1.250 - */
1.251 -native bool:IsFakeClient(client);
1.252 -
1.253 -/**
1.254 - * Returns if a certain player is an observer/spectator.
1.255 - *
1.256 - * @param client Player index.
1.257 - * @return True if player is an obverser, false otherwise.
1.258 - */
1.259 -native bool:IsClientObserver(client);
1.260 -
1.261 -/**
1.262 - * Returns if the client is alive or dead.
1.263 - *
1.264 - * Note: This function was originally in SDKTools and was moved to core.
1.265 - *
1.266 - * @param client Player's index.
1.267 - * @return True if the client is alive, false otherwise.
1.268 - * @error Invalid client index, client not in game, or no mod support.
1.269 - */
1.270 -native bool:IsPlayerAlive(client);
1.271 -
1.272 -/**
1.273 - * Retrieves values from client replicated keys.
1.274 - *
1.275 - * @param client Player's index.
1.276 - * @param key Key string.
1.277 - * @param value Buffer to store value.
1.278 - * @param maxlen Maximum length of valve (UTF-8 safe).
1.279 - * @return True on success, false otherwise.
1.280 - * @error Invalid client index, or client not connected.
1.281 - */
1.282 -native bool:GetClientInfo(client, const String:key[], String:value[], maxlen);
1.283 -
1.284 -/**
1.285 - * Retrieves a client's team index.
1.286 - *
1.287 - * @param client Player's index.
1.288 - * @return Team index the client is on (mod specific).
1.289 - * @error Invalid client index, client not in game, or no mod support.
1.290 - */
1.291 -native GetClientTeam(client);
1.292 -
1.293 -/**
1.294 - * Sets a client's AdminId.
1.295 - *
1.296 - * @param client Player's index.
1.297 - * @param id AdminId to set. INVALID_ADMIN_ID removes admin permissions.
1.298 - * @param temp True if the id should be freed on disconnect.
1.299 - * @noreturn
1.300 - * @error Invalid client index, client not connected, or bogus AdminId.
1.301 - */
1.302 -native SetUserAdmin(client, AdminId:id, bool:temp=false);
1.303 -
1.304 -/**
1.305 - * Retrieves a client's AdminId.
1.306 - *
1.307 - * @param client Player's index.
1.308 - * @return AdminId of the client, or INVALID_ADMIN_ID if none.
1.309 - * @error Invalid client index, or client not connected.
1.310 - */
1.311 -native AdminId:GetUserAdmin(client);
1.312 -
1.313 -/**
1.314 - * Sets access flags on a client. If the client is not an admin,
1.315 - * a temporary, anonymous AdminId is given.
1.316 - *
1.317 - * @param client Player's index.
1.318 - * @param ... Flags to set on the client.
1.319 - * @noreturn
1.320 - * @error Invalid client index, or client not connected.
1.321 - */
1.322 -native AddUserFlags(client, AdminFlag:...);
1.323 -
1.324 -/**
1.325 - * Removes flags from a client. If the client is not an admin,
1.326 - * this has no effect.
1.327 - *
1.328 - * @param client Player's index.
1.329 - * @param ... Flags to remove from the client.
1.330 - * @noreturn
1.331 - * @error Invalid client index, or client not connected.
1.332 - */
1.333 -native RemoveUserFlags(client, AdminFlag:...);
1.334 -
1.335 -/**
1.336 - * Sets access flags on a client using bits instead of flags. If the
1.337 - * client is not an admin, and flags not 0, a temporary, anonymous AdminId is given.
1.338 - *
1.339 - * @param client Player's index.
1.340 - * @param flags Bitstring of flags to set on client.
1.341 - * @noreturn
1.342 - */
1.343 -native SetUserFlagBits(client, flags);
1.344 -
1.345 -/**
1.346 - * Returns client access flags. If the client is not an admin,
1.347 - * the result is always 0.
1.348 - *
1.349 - * @param client Player's index.
1.350 - * @return Flags
1.351 - * @error Invalid client index, or client not connected.
1.352 - */
1.353 -native GetUserFlagBits(client);
1.354 -
1.355 -/**
1.356 - * Returns whether a user can target another user.
1.357 - * This is a helper function for CanAdminTarget.
1.358 - *
1.359 - * @param client Player's index.
1.360 - * @param target Target player's index.
1.361 - * @return True if target is targettable by the player, false otherwise.
1.362 - * @error Invalid or unconnected player indexers.
1.363 - */
1.364 -native bool:CanUserTarget(client, target);
1.365 -
1.366 -/**
1.367 - * Runs through the Core-defined admin authorization checks on a player.
1.368 - * Has no effect if the player is already an admin.
1.369 - *
1.370 - * Note: This function is based on the internal cache only.
1.371 - *
1.372 - * @param client Client index.
1.373 - * @return True if access was changed, false if it did not.
1.374 - * @error Invalid client index or client not in-game AND authorized.
1.375 - */
1.376 -native bool:RunAdminCacheChecks(client);
1.377 -
1.378 -/**
1.379 - * Signals that a player has completed post-connection admin checks.
1.380 - * Has no effect if the player has already had this event signalled.
1.381 - *
1.382 - * Note: This must be sent even if no admin id was assigned.
1.383 - *
1.384 - * @param client Client index.
1.385 - * @noreturn
1.386 - * @error Invalid client index or client not in-game AND authorized.
1.387 - */
1.388 -native NotifyPostAdminCheck(client);
1.389 -
1.390 -/**
1.391 - * Creates a fake client.
1.392 - *
1.393 - * @param name Name to use.
1.394 - * @return Client index on success, 0 otherwise.
1.395 - */
1.396 -native CreateFakeClient(const String:name[]);
1.397 -
1.398 -/**
1.399 - * Sets a convar value on a fake client.
1.400 - *
1.401 - * @param client Client index.
1.402 - * @param cvar ConVar name.
1.403 - * @param value ConVar value.
1.404 - * @noreturn
1.405 - * @error Invalid client index, client not connected,
1.406 - * or client not a fake client.
1.407 - */
1.408 -native SetFakeClientConVar(client, const String:cvar[], const String:value[]);
1.409 -
1.410 -/**
1.411 - * Returns the client's health.
1.412 - *
1.413 - * @param client Player's index.
1.414 - * @return Health value.
1.415 - * @error Invalid client index, client not in game, or no mod support.
1.416 - */
1.417 -native GetClientHealth(client);
1.418 -
1.419 -/**
1.420 - * Returns the client's model name.
1.421 - *
1.422 - * @param client Player's index.
1.423 - * @param model Buffer to store the client's model name.
1.424 - * @param maxlen Maximum length of string buffer (includes NULL terminator).
1.425 - * @noreturn
1.426 - * @error Invalid client index, client not in game, or no mod support.
1.427 - */
1.428 -native GetClientModel(client, String:model[], maxlen);
1.429 -
1.430 -/**
1.431 - * Returns the client's weapon name.
1.432 - *
1.433 - * @param client Player's index.
1.434 - * @param weapon Buffer to store the client's weapon name.
1.435 - * @param maxlen Maximum length of string buffer (includes NULL terminator).
1.436 - * @noreturn
1.437 - * @error Invalid client index, client not in game, or no mod support.
1.438 - */
1.439 -native GetClientWeapon(client, String:weapon[], maxlen);
1.440 -
1.441 -/**
1.442 - * Returns the client's max size vector.
1.443 - *
1.444 - * @param client Player's index.
1.445 - * @param vec Destination vector to store the client's max size.
1.446 - * @noreturn
1.447 - * @error Invalid client index, client not in game, or no mod support.
1.448 - */
1.449 -native GetClientMaxs(client, Float:vec[3]);
1.450 -
1.451 -/**
1.452 - * Returns the client's min size vector.
1.453 - *
1.454 - * @param client Player's index.
1.455 - * @param vec Destination vector to store the client's min size.
1.456 - * @noreturn
1.457 - * @error Invalid client index, client not in game, or no mod support.
1.458 - */
1.459 -native GetClientMins(client, Float:vec[3]);
1.460 -
1.461 -/**
1.462 - * Returns the client's position angle.
1.463 - *
1.464 - * @param client Player's index.
1.465 - * @param ang Destination vector to store the client's position angle.
1.466 - * @noreturn
1.467 - * @error Invalid client index, client not in game, or no mod support.
1.468 - */
1.469 -native GetClientAbsAngles(client, Float:ang[3]);
1.470 -
1.471 -/**
1.472 - * Returns the client's origin vector.
1.473 - *
1.474 - * @param client Player's index.
1.475 - * @param vec Destination vector to store the client's origin vector.
1.476 - * @noreturn
1.477 - * @error Invalid client index, client not in game, or no mod support.
1.478 - */
1.479 -native GetClientAbsOrigin(client, Float:vec[3]);
1.480 -
1.481 -/**
1.482 - * Returns the client's armor.
1.483 - *
1.484 - * @param client Player's index.
1.485 - * @return Armor value.
1.486 - * @error Invalid client index, client not in game, or no mod support.
1.487 - */
1.488 -native GetClientArmor(client);
1.489 -
1.490 -/**
1.491 - * Returns the client's death count.
1.492 - *
1.493 - * @param client Player's index.
1.494 - * @return Death count.
1.495 - * @error Invalid client index, client not in game, or no mod support.
1.496 - */
1.497 -native GetClientDeaths(client);
1.498 -
1.499 -/**
1.500 - * Returns the client's frag count.
1.501 - *
1.502 - * @param client Player's index.
1.503 - * @return Frag count.
1.504 - * @error Invalid client index, client not in game, or no mod support.
1.505 - */
1.506 -native GetClientFrags(client);
1.507 -
1.508 -/**
1.509 - * Returns the client's send data rate in bytes/sec.
1.510 - *
1.511 - * @param client Player's index.
1.512 - * @return Data rate.
1.513 - * @error Invalid client index, client not in game, or fake client.
1.514 - */
1.515 -native GetClientDataRate(client);
1.516 -
1.517 -/**
1.518 - * Returns if a client is timing out
1.519 - *
1.520 - * @param client Player's index.
1.521 - * @return True if client is timing out, false otherwise.
1.522 - * @error Invalid client index, client not in game, or fake client.
1.523 - */
1.524 -native bool:IsClientTimingOut(client);
1.525 -
1.526 -/**
1.527 - * Returns the client's connection time in seconds.
1.528 - *
1.529 - * @param client Player's index.
1.530 - * @return Connection time.
1.531 - * @error Invalid client index, client not in game, or fake client.
1.532 - */
1.533 -native Float:GetClientTime(client);
1.534 -
1.535 -/**
1.536 - * Returns the client's current latency (RTT), more accurate than GetAvgLatency but jittering.
1.537 - *
1.538 - * @param client Player's index.
1.539 - * @param flow Traffic flowing direction.
1.540 - * @return Latency.
1.541 - * @error Invalid client index, client not in game, or fake client.
1.542 - */
1.543 -native Float:GetClientLatency(client, NetFlow:flow);
1.544 -
1.545 -/**
1.546 - * Returns the client's average packet latency in seconds.
1.547 - *
1.548 - * @param client Player's index.
1.549 - * @param flow Traffic flowing direction.
1.550 - * @return Average latency.
1.551 - * @error Invalid client index, client not in game, or fake client.
1.552 - */
1.553 -native Float:GetClientAvgLatency(client, NetFlow:flow);
1.554 -
1.555 -/**
1.556 - * Returns the client's average packet loss, values go from 0 to 1 (for percentages).
1.557 - *
1.558 - * @param client Player's index.
1.559 - * @param flow Traffic flowing direction.
1.560 - * @return Average packet loss.
1.561 - * @error Invalid client index, client not in game, or fake client.
1.562 - */
1.563 -native Float:GetClientAvgLoss(client, NetFlow:flow);
1.564 -
1.565 -/**
1.566 - * Returns the client's average packet choke, values go from 0 to 1 (for percentages).
1.567 - *
1.568 - * @param client Player's index.
1.569 - * @param flow Traffic flowing direction.
1.570 - * @return Average packet choke.
1.571 - * @error Invalid client index, client not in game, or fake client.
1.572 - */
1.573 -native Float:GetClientAvgChoke(client, NetFlow:flow);
1.574 -
1.575 -/**
1.576 - * Returns the client's data flow in bytes/sec.
1.577 - *
1.578 - * @param client Player's index.
1.579 - * @param flow Traffic flowing direction.
1.580 - * @return Data flow.
1.581 - * @error Invalid client index, client not in game, or fake client.
1.582 - */
1.583 -native Float:GetClientAvgData(client, NetFlow:flow);
1.584 -
1.585 -/**
1.586 - * Returns the client's average packet frequency in packets/sec.
1.587 - *
1.588 - * @param client Player's index.
1.589 - * @param flow Traffic flowing direction.
1.590 - * @return Packet frequency.
1.591 - * @error Invalid client index, client not in game, or fake client.
1.592 - */
1.593 -native Float:GetClientAvgPackets(client, NetFlow:flow);
1.594 -
1.595 -/**
1.596 - * Translates an userid index to the real player index.
1.597 - *
1.598 - * @param userid Userid value.
1.599 - * @return Client value.
1.600 - * @error Returns 0 if invalid userid.
1.601 - */
1.602 -native GetClientOfUserId(userid);
1.603 -
1.604 -/**
1.605 - * Disconnects a client from the server.
1.606 - *
1.607 - * Kicking clients from certain events or callbacks may cause crashes. If in
1.608 - * doubt, create a short (0.1 second) timer to kick the client in the next
1.609 - * available frame.
1.610 - *
1.611 - * @param client Client index.
1.612 - * @param format Optional formatting rules for disconnect reason.
1.613 - * Note that a period is automatically appended to the string by the engine.
1.614 - * @param ... Variable number of format parameters.
1.615 - * @noreturn
1.616 - * @error Invalid client index, or client not connected.
1.617 - */
1.618 -native KickClient(client, const String:format[]="", any:...);
1.619 -
1.620 -/**
1.621 - * Changes a client's team through the mod's generic team changing function.
1.622 - * On CS:S, this will kill the player.
1.623 - *
1.624 - * @param client Client index.
1.625 - * @param team Mod-specific team index.
1.626 - * @noreturn
1.627 - * @error Invalid client index, client not connected, or lack of
1.628 - * mod support.
1.629 - */
1.630 -native ChangeClientTeam(client, team);
1.631 -
