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: IPlayerHelpers.h 1964 2008-03-27 04:54:56Z damagedsoul $ 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 7 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 /** 00189 * @brief Provides callbacks for important client events. 00190 */ 00191 class IClientListener 00192 { 00193 public: 00194 /** 00195 * @brief Returns the current client listener version. 00196 * 00197 * @return Client listener version. 00198 */ 00199 virtual unsigned int GetClientListenerVersion() 00200 { 00201 return SMINTERFACE_PLAYERMANAGER_VERSION; 00202 } 00203 public: 00204 /** 00205 * @brief Called when a client requests connection. 00206 * 00207 * @param client Index of the client. 00208 * @param error Error buffer for a disconnect reason. 00209 * @param maxlength Maximum length of error buffer. 00210 * @return True to allow client, false to reject. 00211 */ 00212 virtual bool InterceptClientConnect(int client, char *error, size_t maxlength) 00213 { 00214 return true; 00215 } 00216 00217 /** 00218 * @brief Called when a client has connected. 00219 * 00220 * @param client Index of the client. 00221 */ 00222 virtual void OnClientConnected(int client) 00223 { 00224 } 00225 00226 /** 00227 * @brief Called when a client is put in server. 00228 * 00229 * @param client Index of the client. 00230 */ 00231 virtual void OnClientPutInServer(int client) 00232 { 00233 } 00234 00235 /** 00236 * @brief Called when a client is disconnecting (not fully disconnected yet). 00237 * 00238 * @param client Index of the client. 00239 */ 00240 virtual void OnClientDisconnecting(int client) 00241 { 00242 } 00243 00244 /** 00245 * @brief Called when a client has fully disconnected. 00246 * 00247 * @param client Index of the client. 00248 */ 00249 virtual void OnClientDisconnected(int client) 00250 { 00251 } 00252 00253 /** 00254 * @brief Called when a client has received authorization. 00255 * 00256 * @param client Index of the client. 00257 * @param authstring Authorization string. 00258 */ 00259 virtual void OnClientAuthorized(int client, const char *authstring) 00260 { 00261 } 00262 00263 /** 00264 * @brief Called when the server is activated. 00265 */ 00266 virtual void OnServerActivated(int max_clients) 00267 { 00268 } 00269 00270 /** 00271 * @brief Called once a client is authorized and fully in-game, but 00272 * before admin checks are done. This can be used to override the 00273 * default admin checks for a client. 00274 * 00275 * By default, this function allows the authentication process to 00276 * continue as normal. If you need to delay the cache searching 00277 * process in order to get asynchronous data, then return false here. 00278 * 00279 * If you return false, you must call IPlayerManager::NotifyPostAdminCheck 00280 * for the same client, or else the OnClientPostAdminCheck callback will 00281 * never be called. 00282 * 00283 * @param client Client index. 00284 * @return True to continue normally, false to override 00285 * the authentication process. 00286 */ 00287 virtual bool OnClientPreAdminCheck(int client) 00288 { 00289 return true; 00290 } 00291 00292 /** 00293 * @brief Called once a client is authorized and fully in-game, and 00294 * after all post-connection authorizations have been passed. If the 00295 * client does not have an AdminId by this stage, it means that no 00296 * admin entry was in the cache that matched, and the user could not 00297 * be authenticated as an admin. 00298 * 00299 * @param client Client index. 00300 */ 00301 virtual void OnClientPostAdminCheck(int client) 00302 { 00303 } 00304 }; 00305 00306 #define COMMAND_FILTER_ALIVE (1<<0) /**< Only allow alive players */ 00307 #define COMMAND_FILTER_DEAD (1<<1) /**< Only filter dead players */ 00308 #define COMMAND_FILTER_CONNECTED (1<<2) /**< Allow players not fully in-game */ 00309 #define COMMAND_FILTER_NO_IMMUNITY (1<<3) /**< Ignore immunity rules */ 00310 #define COMMAND_FILTER_NO_MULTI (1<<4) /**< Do not allow multiple target patterns */ 00311 #define COMMAND_FILTER_NO_BOTS (1<<5) /**< Do not allow bots to be targetted */ 00312 00313 #define COMMAND_TARGET_VALID 1 /**< Client passed the filter */ 00314 #define COMMAND_TARGET_NONE 0 /**< No target was found */ 00315 #define COMMAND_TARGET_NOT_ALIVE -1 /**< Single client is not alive */ 00316 #define COMMAND_TARGET_NOT_DEAD -2 /**< Single client is not dead */ 00317 #define COMMAND_TARGET_NOT_IN_GAME -3 /**< Single client is not in game */ 00318 #define COMMAND_TARGET_IMMUNE -4 /**< Single client is immune */ 00319 #define COMMAND_TARGET_EMPTY_FILTER -5 /**< A multi-filter (such as @all) had no targets */ 00320 #define COMMAND_TARGET_NOT_HUMAN -6 /**< Target was not human */ 00321 #define COMMAND_TARGET_AMBIGUOUS -7 /**< Partial name had too many targets */ 00322 00323 #define COMMAND_TARGETNAME_RAW 0 /**< Target name is a raw string */ 00324 #define COMMAND_TARGETNAME_ML 1 /**< Target name is a multi-lingual phrase */ 00325 00326 /** 00327 * @brief Holds the many command target info parameters. 00328 */ 00329 struct cmd_target_info_t 00330 { 00331 const char *pattern; /**< IN: Target pattern string. */ 00332 int admin; /**< IN: Client admin index, or 0 if server .*/ 00333 cell_t *targets; /**< IN: Array to store targets. */ 00334 cell_t max_targets; /**< IN: Max targets (always >= 1) */ 00335 int flags; /**< IN: COMMAND_FILTER flags. */ 00336 char *target_name; /**< OUT: Buffer to store target name. */ 00337 size_t target_name_maxlength; /**< IN: Maximum length of the target name buffer. */ 00338 int target_name_style; /**< OUT: Target name style (COMMAND_TARGETNAME) */ 00339 int reason; /**< OUT: COMMAND_TARGET reason. */ 00340 unsigned int num_targets; /**< OUT: Number of targets. */ 00341 }; 00342 00343 /** 00344 * @brief Intercepts a command target operation. 00345 */ 00346 class ICommandTargetProcessor 00347 { 00348 public: 00349 /** 00350 * @brief Must process the command target and return a COMMAND_TARGET value. 00351 * 00352 * @param info Struct containing command target information. 00353 * Any members labelled OUT must be filled if processing 00354 * is to be completed (i.e. true returned). 00355 * @return True to end processing, false to let Core continue. 00356 */ 00357 virtual bool ProcessCommandTarget(cmd_target_info_t *info) =0; 00358 }; 00359 00360 class IPlayerManager : public SMInterface 00361 { 00362 public: 00363 const char *GetInterfaceName() 00364 { 00365 return SMINTERFACE_PLAYERMANAGER_NAME; 00366 } 00367 unsigned int GetInterfaceVersion() 00368 { 00369 return SMINTERFACE_PLAYERMANAGER_VERSION; 00370 } 00371 public: 00372 /** 00373 * @brief Adds a client listener. 00374 * 00375 * @param listener Pointer to an IClientListener. 00376 */ 00377 virtual void AddClientListener(IClientListener *listener) =0; 00378 00379 /** 00380 * @brief Removes a client listener. 00381 * 00382 * @param listener Pointer to an IClientListener. 00383 */ 00384 virtual void RemoveClientListener(IClientListener *listener) =0; 00385 00386 /** 00387 * @brief Retrieves an IGamePlayer object by its client index. 00388 * 00389 * Note: This will return a valid object for any player, connected or not. 00390 * Note: Client indexes start at 1, not 0. 00391 * 00392 * @param client Index of the client. 00393 * @return An IGamePlayer pointer, or NULL if out of range. 00394 */ 00395 virtual IGamePlayer *GetGamePlayer(int client) =0; 00396 00397 /** 00398 * @brief Retrieves an IGamePlayer object by its edict_t pointer. 00399 * 00400 * @param pEdict Index of the client 00401 * @return An IGamePlayer pointer, or NULL if out of range. 00402 */ 00403 virtual IGamePlayer *GetGamePlayer(edict_t *pEdict) =0; 00404 00405 /** 00406 * @brief Returns the maximum number of clients. 00407 * 00408 * Note: this will not work until the server is activated. 00409 * 00410 * @return Maximum number of clients. 00411 */ 00412 virtual int GetMaxClients() =0; 00413 00414 /** 00415 * @brief Returns the number of players currently connected. 00416 * 00417 * @return Current number of connected clients. 00418 */ 00419 virtual int GetNumPlayers() =0; 00420 00421 /** 00422 * @brief Returns the client index by its userid. 00423 * 00424 * @param userid Userid of the client. 00425 * @return Client index, or 0 if invalid userid passed. 00426 */ 00427 virtual int GetClientOfUserId(int userid) =0; 00428 00429 /** 00430 * @brief Returns whether or not the server is activated. 00431 * 00432 * @return True if ServerActivate() has been called 00433 * at least once, false otherwise. 00434 */ 00435 virtual bool IsServerActivated() =0; 00436 00437 /** 00438 * @brief Gets SourceMod's reply source. 00439 * 00440 * @return ReplyTo source. 00441 */ 00442 virtual unsigned int GetReplyTo() =0; 00443 00444 /** 00445 * @brief Sets SourceMod's reply source. 00446 * 00447 * @param reply Reply source. 00448 * @return Old reply source. 00449 */ 00450 virtual unsigned int SetReplyTo(unsigned int reply) =0; 00451 00452 /** 00453 * @brief Tests if a player meets command filtering rules. 00454 * 00455 * @param pAdmin IGamePlayer of the admin, or NULL if the server. 00456 * @param pTarget IGamePlayer of the player being targeted. 00457 * @param flags COMMAND_FILTER flags. 00458 * @return COMMAND_TARGET value. 00459 */ 00460 virtual int FilterCommandTarget(IGamePlayer *pAdmin, IGamePlayer *pTarget, int flags) =0; 00461 00462 /** 00463 * @brief Registers a command target processor. 00464 * 00465 * @param pHandler Pointer to an ICommandTargetProcessor instance. 00466 */ 00467 virtual void RegisterCommandTargetProcessor(ICommandTargetProcessor *pHandler) =0; 00468 00469 /** 00470 * @brief Removes a command target processor. 00471 * 00472 * @param pHandler Pointer to an ICommandTargetProcessor instance. 00473 */ 00474 virtual void UnregisterCommandTargetProcessor(ICommandTargetProcessor *pHandler) =0; 00475 }; 00476 } 00477 00478 #endif //_INCLUDE_SOURCEMOD_INTERFACE_IPLAYERHELPERS_H_
1.5.1