00001 /** 00002 * vim: set ts=4 : 00003 * ============================================================================= 00004 * SourceMod 00005 * Copyright (C) 2004-2008 AlliedModders LLC. All rights reserved. 00006 * ============================================================================= 00007 * 00008 * This program is free software; you can redistribute it and/or modify it under 00009 * the terms of the GNU General Public License, version 3.0, as published by the 00010 * Free Software Foundation. 00011 * 00012 * This program is distributed in the hope that it will be useful, but WITHOUT 00013 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 00014 * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more 00015 * details. 00016 * 00017 * You should have received a copy of the GNU General Public License along with 00018 * this program. If not, see <http://www.gnu.org/licenses/>. 00019 * 00020 * As a special exception, AlliedModders LLC gives you permission to link the 00021 * code of this program (as well as its derivative works) to "Half-Life 2," the 00022 * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software 00023 * by the Valve Corporation. You must obey the GNU General Public License in 00024 * all respects for all other code used. Additionally, AlliedModders LLC grants 00025 * this exception to all derivative works. AlliedModders LLC defines further 00026 * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007), 00027 * or <http://www.sourcemod.net/license.php>. 00028 * 00029 * Version: $Id$ 00030 */ 00031 00032 #ifndef _INCLUDE_SOURCEMOD_INTERFACE_IPLAYERHELPERS_H_ 00033 #define _INCLUDE_SOURCEMOD_INTERFACE_IPLAYERHELPERS_H_ 00034 00035 /** 00036 * @file IPlayerHelpers.h 00037 * @brief Defines basic helper functions for Half-Life 2 clients 00038 */ 00039 00040 #include <IShareSys.h> 00041 #include <IAdminSystem.h> 00042 00043 #define SMINTERFACE_PLAYERMANAGER_NAME "IPlayerManager" 00044 #define SMINTERFACE_PLAYERMANAGER_VERSION 15 00045 00046 struct edict_t; 00047 class IPlayerInfo; 00048 00049 #define SM_REPLY_CONSOLE 0 /**< Reply to console. */ 00050 #define SM_REPLY_CHAT 1 /**< Reply to chat. */ 00051 00052 namespace SourceMod 00053 { 00054 /** 00055 * @brief Abstracts some Half-Life 2 and SourceMod properties about clients. 00056 */ 00057 class IGamePlayer 00058 { 00059 public: 00060 /** 00061 * @brief Returns the player's name. 00062 * 00063 * @return String containing the player's name, 00064 * or NULL if unavailable. 00065 */ 00066 virtual const char *GetName() =0; 00067 00068 /** 00069 * @brief Returns the player's IP address. 00070 * 00071 * @return String containing the player's IP address, 00072 * or NULL if unavailable. 00073 */ 00074 virtual const char *GetIPAddress() =0; 00075 00076 /** 00077 * @brief Returns the player's authentication string. 00078 * 00079 * @return String containing the player's auth string. 00080 * May be NULL if unavailable. 00081 */ 00082 virtual const char *GetAuthString() =0; 00083 00084 /** 00085 * @brief Returns the player's edict_t structure. 00086 * 00087 * @return edict_t pointer, or NULL if unavailable. 00088 */ 00089 virtual edict_t *GetEdict() =0; 00090 00091 /** 00092 * @brief Returns whether the player is in game (putinserver). 00093 * 00094 * @return True if in game, false otherwise. 00095 */ 00096 virtual bool IsInGame() =0; 00097 00098 /** 00099 * @brief Returns whether the player is connected. 00100 * 00101 * Note: If this returns true, all above functions except for 00102 * GetAuthString() should return non-NULL results. 00103 * 00104 * @return True if connected, false otherwise. 00105 */ 00106 virtual bool IsConnected() =0; 00107 00108 /** 00109 * @brief Returns whether the player is a fake client. 00110 * 00111 * @return True if a fake client, false otherwise. 00112 */ 00113 virtual bool IsFakeClient() =0; 00114 00115 /** 00116 * @brief Returns the client's AdminId, if any. 00117 * 00118 * @return AdminId, or INVALID_ADMIN_ID if none. 00119 */ 00120 virtual AdminId GetAdminId() =0; 00121 00122 /** 00123 * @brief Sets the client's AdminId. 00124 * 00125 * @param id AdminId to set. 00126 * @param temp If true, the id will be invalidated on disconnect. 00127 */ 00128 virtual void SetAdminId(AdminId id, bool temp) =0; 00129 00130 /** 00131 * @brief Returns the client's userid. 00132 * 00133 * @return Userid. 00134 */ 00135 virtual int GetUserId() =0; 00136 00137 /** 00138 * @brief Returns the client's language id. 00139 * 00140 * @return Language id. 00141 */ 00142 virtual unsigned int GetLanguageId() =0; 00143 00144 /** 00145 * @brief Returns a player's IPlayerInfo object, if any. 00146 * 00147 * @return IPlayerInfo pointer, or NULL if none. 00148 */ 00149 virtual IPlayerInfo *GetPlayerInfo() =0; 00150 00151 /** 00152 * @brief Runs through Core's admin authorization checks. If the 00153 * client is already an admin, no checks are performed. 00154 * 00155 * Note that this function operates solely against the in-memory admin 00156 * cache. It will check steamids, IPs, names, and verify a password 00157 * if one exists. To implement other authentication schemes, simply 00158 * don't call this function and use IGamePlayer::SetAdminId() instead. 00159 * 00160 * @return True if access changed, false otherwise. 00161 */ 00162 virtual bool RunAdminCacheChecks() =0; 00163 00164 /** 00165 * @brief Notifies all listeners that the client has completed 00166 * all of your post-connection (in-game, auth, admin) checks. 00167 * 00168 * If you returned "false" from OnClientPreAdminCheck(), you must 00169 * ALWAYS manually invoke this function, even if RunAdminCacheChecks() 00170 * failed or you did not assign an AdminId. Failure to call this 00171 * function could result in plugins (such as reservedslots) not 00172 * working properly. 00173 * 00174 * If you are implementing asynchronous fetches, and the client 00175 * disconnects during your fetching process, you should make sure to 00176 * recognize that case and not call this function. That is, do not 00177 * call this function on mismatched PreCheck calls, or on disconnected 00178 * clients. A good way to check this is to pass userids around, which 00179 * are unique per client connection. 00180 * 00181 * Calling this has no effect if it has already been called on the 00182 * given client (thus it is safe for multiple asynchronous plugins to 00183 * call it at various times). 00184 */ 00185 virtual void NotifyPostAdminChecks() =0; 00186 00187 /** 00188 * @brief Returns the clients unique serial identifier. 00189 * 00190 * @return Serial number. 00191 */ 00192 virtual unsigned int GetSerial() =0; 00193 00194 /** 00195 * @brief Return whether the client is authorized. 00196 * 00197 * @return True if authorized, false otherwise. 00198 */ 00199 virtual bool IsAuthorized() =0; 00200 00201 /** 00202 * @brief Kicks the client with a message 00203 * 00204 * @param message The message shown to the client when kicked 00205 */ 00206 virtual void Kick(const char *message) =0; 00207 00208 /** 00209 * @brief Returns whether the client is marked as being in the kick 00210 * queue. The client doesn't necessarily have to be in the actual kick 00211 * queue for this function to return true. 00212 * 00213 * @return True if in the kick queue, false otherwise. 00214 */ 00215 virtual bool IsInKickQueue() =0; 00216 00217 /** 00218 * @brief Marks the client as being in the kick queue. They are not 00219 * actually added to the kick queue. Use IGameHelpers::AddDelayedKick() 00220 * to actually add them to the queue. 00221 */ 00222 virtual void MarkAsBeingKicked() =0; 00223 00224 virtual void SetLanguageId(unsigned int id) =0; 00225 00226 /** 00227 * @brief Returns whether the player is the SourceTV bot. 00228 * 00229 * @return True if the SourceTV bot, false otherwise. 00230 */ 00231 virtual bool IsSourceTV() const =0; 00232 00233 /** 00234 * @brief Returns whether the player is the Replay bot. 00235 * 00236 * @return True if the Replay bot, false otherwise. 00237 */ 00238 virtual bool IsReplay() const =0; 00239 }; 00240 00241 /** 00242 * @brief Provides callbacks for important client events. 00243 */ 00244 class IClientListener 00245 { 00246 public: 00247 /** 00248 * @brief Returns the current client listener version. 00249 * 00250 * @return Client listener version. 00251 */ 00252 virtual unsigned int GetClientListenerVersion() 00253 { 00254 return SMINTERFACE_PLAYERMANAGER_VERSION; 00255 } 00256 public: 00257 /** 00258 * @brief Called when a client requests connection. 00259 * 00260 * @param client Index of the client. 00261 * @param error Error buffer for a disconnect reason. 00262 * @param maxlength Maximum length of error buffer. 00263 * @return True to allow client, false to reject. 00264 */ 00265 virtual bool InterceptClientConnect(int client, char *error, size_t maxlength) 00266 { 00267 return true; 00268 } 00269 00270 /** 00271 * @brief Called when a client has connected. 00272 * 00273 * @param client Index of the client. 00274 */ 00275 virtual void OnClientConnected(int client) 00276 { 00277 } 00278 00279 /** 00280 * @brief Called when a client is put in server. 00281 * 00282 * @param client Index of the client. 00283 */ 00284 virtual void OnClientPutInServer(int client) 00285 { 00286 } 00287 00288 /** 00289 * @brief Called when a client is disconnecting (not fully disconnected yet). 00290 * 00291 * @param client Index of the client. 00292 */ 00293 virtual void OnClientDisconnecting(int client) 00294 { 00295 } 00296 00297 /** 00298 * @brief Called when a client has fully disconnected. 00299 * 00300 * @param client Index of the client. 00301 */ 00302 virtual void OnClientDisconnected(int client) 00303 { 00304 } 00305 00306 /** 00307 * @brief Called when a client has received authorization. 00308 * 00309 * @param client Index of the client. 00310 * @param authstring Authorization string. 00311 */ 00312 virtual void OnClientAuthorized(int client, const char *authstring) 00313 { 00314 } 00315 00316 /** 00317 * @brief Called when the server is activated. 00318 */ 00319 virtual void OnServerActivated(int max_clients) 00320 { 00321 } 00322 00323 /** 00324 * @brief Called once a client is authorized and fully in-game, but 00325 * before admin checks are done. This can be used to override the 00326 * default admin checks for a client. 00327 * 00328 * By default, this function allows the authentication process to 00329 * continue as normal. If you need to delay the cache searching 00330 * process in order to get asynchronous data, then return false here. 00331 * 00332 * If you return false, you must call IPlayerManager::NotifyPostAdminCheck 00333 * for the same client, or else the OnClientPostAdminCheck callback will 00334 * never be called. 00335 * 00336 * @param client Client index. 00337 * @return True to continue normally, false to override 00338 * the authentication process. 00339 */ 00340 virtual bool OnClientPreAdminCheck(int client) 00341 { 00342 return true; 00343 } 00344 00345 /** 00346 * @brief Called once a client is authorized and fully in-game, and 00347 * after all post-connection authorizations have been passed. If the 00348 * client does not have an AdminId by this stage, it means that no 00349 * admin entry was in the cache that matched, and the user could not 00350 * be authenticated as an admin. 00351 * 00352 * @param client Client index. 00353 */ 00354 virtual void OnClientPostAdminCheck(int client) 00355 { 00356 } 00357 00358 /** 00359 * @brief Notifies the extension that the maxplayers value has changed 00360 * 00361 * @param newvalue New maxplayers value. 00362 */ 00363 virtual void OnMaxPlayersChanged(int newvalue) 00364 { 00365 } 00366 00367 /** 00368 * @brief Notifies the extension that a clients settings changed 00369 * 00370 * @param client Client index. 00371 */ 00372 virtual void OnClientSettingsChanged(int client) 00373 { 00374 } 00375 }; 00376 00377 #define COMMAND_FILTER_ALIVE (1<<0) /**< Only allow alive players */ 00378 #define COMMAND_FILTER_DEAD (1<<1) /**< Only filter dead players */ 00379 #define COMMAND_FILTER_CONNECTED (1<<2) /**< Allow players not fully in-game */ 00380 #define COMMAND_FILTER_NO_IMMUNITY (1<<3) /**< Ignore immunity rules */ 00381 #define COMMAND_FILTER_NO_MULTI (1<<4) /**< Do not allow multiple target patterns */ 00382 #define COMMAND_FILTER_NO_BOTS (1<<5) /**< Do not allow bots to be targetted */ 00383 00384 #define COMMAND_TARGET_VALID 1 /**< Client passed the filter */ 00385 #define COMMAND_TARGET_NONE 0 /**< No target was found */ 00386 #define COMMAND_TARGET_NOT_ALIVE -1 /**< Single client is not alive */ 00387 #define COMMAND_TARGET_NOT_DEAD -2 /**< Single client is not dead */ 00388 #define COMMAND_TARGET_NOT_IN_GAME -3 /**< Single client is not in game */ 00389 #define COMMAND_TARGET_IMMUNE -4 /**< Single client is immune */ 00390 #define COMMAND_TARGET_EMPTY_FILTER -5 /**< A multi-filter (such as @all) had no targets */ 00391 #define COMMAND_TARGET_NOT_HUMAN -6 /**< Target was not human */ 00392 #define COMMAND_TARGET_AMBIGUOUS -7 /**< Partial name had too many targets */ 00393 00394 #define COMMAND_TARGETNAME_RAW 0 /**< Target name is a raw string */ 00395 #define COMMAND_TARGETNAME_ML 1 /**< Target name is a multi-lingual phrase */ 00396 00397 /** 00398 * @brief Holds the many command target info parameters. 00399 */ 00400 struct cmd_target_info_t 00401 { 00402 const char *pattern; /**< IN: Target pattern string. */ 00403 int admin; /**< IN: Client admin index, or 0 if server .*/ 00404 cell_t *targets; /**< IN: Array to store targets. */ 00405 cell_t max_targets; /**< IN: Max targets (always >= 1) */ 00406 int flags; /**< IN: COMMAND_FILTER flags. */ 00407 char *target_name; /**< OUT: Buffer to store target name. */ 00408 size_t target_name_maxlength; /**< IN: Maximum length of the target name buffer. */ 00409 int target_name_style; /**< OUT: Target name style (COMMAND_TARGETNAME) */ 00410 int reason; /**< OUT: COMMAND_TARGET reason. */ 00411 unsigned int num_targets; /**< OUT: Number of targets. */ 00412 }; 00413 00414 /** 00415 * @brief Intercepts a command target operation. 00416 */ 00417 class ICommandTargetProcessor 00418 { 00419 public: 00420 /** 00421 * @brief Must process the command target and return a COMMAND_TARGET value. 00422 * 00423 * @param info Struct containing command target information. 00424 * Any members labelled OUT must be filled if processing 00425 * is to be completed (i.e. true returned). 00426 * @return True to end processing, false to let Core continue. 00427 */ 00428 virtual bool ProcessCommandTarget(cmd_target_info_t *info) =0; 00429 }; 00430 00431 class IPlayerManager : public SMInterface 00432 { 00433 public: 00434 const char *GetInterfaceName() 00435 { 00436 return SMINTERFACE_PLAYERMANAGER_NAME; 00437 } 00438 unsigned int GetInterfaceVersion() 00439 { 00440 return SMINTERFACE_PLAYERMANAGER_VERSION; 00441 } 00442 public: 00443 /** 00444 * @brief Adds a client listener. 00445 * 00446 * @param listener Pointer to an IClientListener. 00447 */ 00448 virtual void AddClientListener(IClientListener *listener) =0; 00449 00450 /** 00451 * @brief Removes a client listener. 00452 * 00453 * @param listener Pointer to an IClientListener. 00454 */ 00455 virtual void RemoveClientListener(IClientListener *listener) =0; 00456 00457 /** 00458 * @brief Retrieves an IGamePlayer object by its client index. 00459 * 00460 * Note: This will return a valid object for any player, connected or not. 00461 * Note: Client indexes start at 1, not 0. 00462 * 00463 * @param client Index of the client. 00464 * @return An IGamePlayer pointer, or NULL if out of range. 00465 */ 00466 virtual IGamePlayer *GetGamePlayer(int client) =0; 00467 00468 /** 00469 * @brief Retrieves an IGamePlayer object by its edict_t pointer. 00470 * 00471 * @param pEdict Index of the client 00472 * @return An IGamePlayer pointer, or NULL if out of range. 00473 */ 00474 virtual IGamePlayer *GetGamePlayer(edict_t *pEdict) =0; 00475 00476 /** 00477 * @brief Returns the maximum number of clients. 00478 * 00479 * Note: this will not work until the server is activated. 00480 * 00481 * @return Maximum number of clients. 00482 */ 00483 virtual int GetMaxClients() =0; 00484 00485 /** 00486 * @brief Returns the number of players currently connected. 00487 * 00488 * @return Current number of connected clients. 00489 */ 00490 virtual int GetNumPlayers() =0; 00491 00492 /** 00493 * @brief Returns the client index by its userid. 00494 * 00495 * @param userid Userid of the client. 00496 * @return Client index, or 0 if invalid userid passed. 00497 */ 00498 virtual int GetClientOfUserId(int userid) =0; 00499 00500 /** 00501 * @brief Returns whether or not the server is activated. 00502 * 00503 * @return True if ServerActivate() has been called 00504 * at least once, false otherwise. 00505 */ 00506 virtual bool IsServerActivated() =0; 00507 00508 /** 00509 * @brief Gets SourceMod's reply source. 00510 * 00511 * @return ReplyTo source. 00512 */ 00513 virtual unsigned int GetReplyTo() =0; 00514 00515 /** 00516 * @brief Sets SourceMod's reply source. 00517 * 00518 * @param reply Reply source. 00519 * @return Old reply source. 00520 */ 00521 virtual unsigned int SetReplyTo(unsigned int reply) =0; 00522 00523 /** 00524 * @brief Tests if a player meets command filtering rules. 00525 * 00526 * @param pAdmin IGamePlayer of the admin, or NULL if the server. 00527 * @param pTarget IGamePlayer of the player being targeted. 00528 * @param flags COMMAND_FILTER flags. 00529 * @return COMMAND_TARGET value. 00530 */ 00531 virtual int FilterCommandTarget(IGamePlayer *pAdmin, IGamePlayer *pTarget, int flags) =0; 00532 00533 /** 00534 * @brief Registers a command target processor. 00535 * 00536 * @param pHandler Pointer to an ICommandTargetProcessor instance. 00537 */ 00538 virtual void RegisterCommandTargetProcessor(ICommandTargetProcessor *pHandler) =0; 00539 00540 /** 00541 * @brief Removes a command target processor. 00542 * 00543 * @param pHandler Pointer to an ICommandTargetProcessor instance. 00544 */ 00545 virtual void UnregisterCommandTargetProcessor(ICommandTargetProcessor *pHandler) =0; 00546 00547 /** 00548 * @brief Returns the client index by its serial number. 00549 * 00550 * @return Client index, or 0 for invalid serial. 00551 */ 00552 virtual int GetClientFromSerial(unsigned int serial) =0; 00553 00554 /** 00555 * @brief Processes the pattern inside a cmd_target_info_t structure 00556 * and outputs the clients that match it. 00557 * 00558 * @param info Pointer to the cmd_target_info_t structure to process. 00559 */ 00560 virtual void ProcessCommandTarget(cmd_target_info_t *info) =0; 00561 }; 00562 } 00563 00564 #endif //_INCLUDE_SOURCEMOD_INTERFACE_IPLAYERHELPERS_H_
1.7.1