/**

  * vim: set ts=4 :

  * =============================================================================

  * SourceMod

  * Copyright (C) 2004-2008 AlliedModders LLC.  All rights reserved.

  * =============================================================================

  *

  * This program is free software; you can redistribute it and/or modify it under

  * the terms of the GNU General Public License, version 3.0, as published by the

  * Free Software Foundation.

  * 

  * This program is distributed in the hope that it will be useful, but WITHOUT

  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS

  * FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more

  * details.

  *

  * You should have received a copy of the GNU General Public License along with

  * this program.  If not, see <http://www.gnu.org/licenses/>.

  *

  * As a special exception, AlliedModders LLC gives you permission to link the

  * code of this program (as well as its derivative works) to "Half-Life 2," the

  * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software

  * by the Valve Corporation.  You must obey the GNU General Public License in

  * all respects for all other code used.  Additionally, AlliedModders LLC grants

  * this exception to all derivative works.  AlliedModders LLC defines further

  * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),

  * or <http://www.sourcemod.net/license.php>.

  *

  * Version: $Id$

  */

 #ifndef _INCLUDE_SOURCEMOD_INTERFACE_IPLAYERHELPERS_H_

 #define _INCLUDE_SOURCEMOD_INTERFACE_IPLAYERHELPERS_H_

 /**

  * @file IPlayerHelpers.h

  * @brief Defines basic helper functions for Half-Life 2 clients

  */

 #include <IShareSys.h>

 #include <IAdminSystem.h>

 #define SMINTERFACE_PLAYERMANAGER_NAME		"IPlayerManager"

 #define SMINTERFACE_PLAYERMANAGER_VERSION	9

 struct edict_t;

 class IPlayerInfo;

 #define SM_REPLY_CONSOLE	0			/**< Reply to console. */

 #define SM_REPLY_CHAT		1			/**< Reply to chat. */

 namespace SourceMod

 {

 	/**

 	 * @brief Abstracts some Half-Life 2 and SourceMod properties about clients.

 	 */

 	class IGamePlayer

 	{

 	public:

 		/**

 		 * @brief Returns the player's name.

 		 *

 		 * @return		String containing the player's name,

 		 *				or NULL if unavailable.

 		 */

 		virtual const char *GetName() =0;

 		/**

 		 * @brief Returns the player's IP address.

 		 *

 		 * @return		String containing the player's IP address,

 		 *				or NULL if unavailable.

 		 */

 		virtual const char *GetIPAddress() =0;

 		/**

 		 * @brief Returns the player's authentication string.

 		 *

 		 * @return		String containing the player's auth string.

 		 *				May be NULL if unavailable.

 		 */

 		virtual const char *GetAuthString() =0;

 		/**

 		 * @brief Returns the player's edict_t structure.

 		 *

 		 * @return		edict_t pointer, or NULL if unavailable.

 		 */

 		virtual edict_t *GetEdict() =0;

 		/**

 		 * @brief Returns whether the player is in game (putinserver).

 		 *

 		 * @return		True if in game, false otherwise.

 		 */

 		virtual bool IsInGame() =0;

 		/**

 		 * @brief Returns whether the player is connected.

 		 *

 		 * Note: If this returns true, all above functions except for

 		 * GetAuthString() should return non-NULL results.

 		 *

 		 * @return		True if connected, false otherwise.

 		 */

 		virtual bool IsConnected() =0;

 		/**

 		 * @brief Returns whether the player is a fake client.

 		 *

 		 * @return		True if a fake client, false otherwise.

 		 */

 		virtual bool IsFakeClient() =0;

 		/**

 		 * @brief Returns the client's AdminId, if any.

 		 *

 		 * @return		AdminId, or INVALID_ADMIN_ID if none.

 		 */

 		virtual AdminId GetAdminId() =0;

 		/**

 		 * @brief Sets the client's AdminId.

 		 *

 		 * @param id	AdminId to set.

 		 * @param temp	If true, the id will be invalidated on disconnect.

 		 */

 		virtual void SetAdminId(AdminId id, bool temp) =0;

 		/**

 		 * @brief Returns the client's userid.

 		 *

 		 * @return		Userid.

 		 */

 		virtual int GetUserId() =0;

 		/**

 		 * @brief Returns the client's language id.

 		 *

 		 * @return		Language id.

 		 */

 		virtual unsigned int GetLanguageId() =0;

 		/**

 		 * @brief Returns a player's IPlayerInfo object, if any.

 		 *

 		 * @return		IPlayerInfo pointer, or NULL if none.

 		 */

 		virtual IPlayerInfo *GetPlayerInfo() =0;

 		/**

 		 * @brief Runs through Core's admin authorization checks.  If the 

 		 * client is already an admin, no checks are performed.  

 		 *

 		 * Note that this function operates solely against the in-memory admin 

 		 * cache.  It will check steamids, IPs, names, and verify a password 

 		 * if one exists.  To implement other authentication schemes, simply 

 		 * don't call this function and use IGamePlayer::SetAdminId() instead.

 		 *

 		 * @return				True if access changed, false otherwise.

 		 */

 		virtual bool RunAdminCacheChecks() =0;

 		/**

 		 * @brief Notifies all listeners that the client has completed 

 		 * all of your post-connection (in-game, auth, admin) checks.  

 		 *

 		 * If you returned "false" from OnClientPreAdminCheck(), you must 

 		 * ALWAYS manually invoke this function, even if RunAdminCacheChecks() 

 		 * failed or you did not assign an AdminId.  Failure to call this 

 		 * function could result in plugins (such as reservedslots) not 

 		 * working properly.

 		 *

 		 * If you are implementing asynchronous fetches, and the client 

 		 * disconnects during your fetching process, you should make sure to 

 		 * recognize that case and not call this function.  That is, do not 

 		 * call this function on mismatched PreCheck calls, or on disconnected 

 		 * clients.  A good way to check this is to pass userids around, which 

 		 * are unique per client connection.

 		 *

 		 * Calling this has no effect if it has already been called on the 

 		 * given client (thus it is safe for multiple asynchronous plugins to 

 		 * call it at various times).

 		 */

 		virtual void NotifyPostAdminChecks() =0;

 		/**

 		 * @brief Returns the clients unique serial identifier.

 		 *

 		 * @return	Serial number.

 		 */

 		virtual unsigned int GetSerial() =0;

 	};

 	/**

 	 * @brief Provides callbacks for important client events.

 	 */

 	class IClientListener

 	{

 	public:

 	   /**

 		* @brief Returns the current client listener version.

 		*

 		* @return		Client listener version.

 		*/

 		virtual unsigned int GetClientListenerVersion()

 		{

 			return SMINTERFACE_PLAYERMANAGER_VERSION;

 		}

 	public:

 		/**

 		 * @brief Called when a client requests connection.

 		 *

 		 * @param client		Index of the client.

 		 * @param error			Error buffer for a disconnect reason.

 		 * @param maxlength		Maximum length of error buffer.

 		 * @return				True to allow client, false to reject.

 		 */

 		virtual bool InterceptClientConnect(int client, char *error, size_t maxlength)

 		{

 			return true;

 		}

 		/**

 		 * @brief Called when a client has connected.

 		 *

 		 * @param client		Index of the client.

 		 */

 		virtual void OnClientConnected(int client)

 		{

 		}

 		/**

 		 * @brief Called when a client is put in server.

 		 *

 		 * @param client		Index of the client.

 		 */

 		virtual void OnClientPutInServer(int client)

 		{

 		}

 		/**

 		 * @brief Called when a client is disconnecting (not fully disconnected yet).

 		 *

 		 * @param client		Index of the client.

 		 */

 		virtual void OnClientDisconnecting(int client)

 		{

 		}

 		/**

 		 * @brief Called when a client has fully disconnected.

 		 *

 		 * @param client		Index of the client.

 		 */

 		virtual void OnClientDisconnected(int client)

 		{

 		}

 		/**

 		 * @brief Called when a client has received authorization.

 		 *

 		 * @param client		Index of the client.

 		 * @param authstring	Authorization string.

 		 */

 		virtual void OnClientAuthorized(int client, const char *authstring)

 		{

 		}

 		/**

 		 * @brief Called when the server is activated.

 		 */

 		virtual void OnServerActivated(int max_clients)

 		{

 		}

 		/**

 		 * @brief Called once a client is authorized and fully in-game, but 

 		 * before admin checks are done.  This can be used to override the 

 		 * default admin checks for a client.

 		 *

 		 * By default, this function allows the authentication process to 

 		 * continue as normal.  If you need to delay the cache searching 

 		 * process in order to get asynchronous data, then return false here. 

 		 *

 		 * If you return false, you must call IPlayerManager::NotifyPostAdminCheck 

 		 * for the same client, or else the OnClientPostAdminCheck callback will 

 		 * never be called.

 		 *

 		 * @param client		Client index.

 		 * @return				True to continue normally, false to override 

 		 *						the authentication process.

 		 */

 		virtual bool OnClientPreAdminCheck(int client)

 		{

 			return true;

 		}

 		/**

 		 * @brief Called once a client is authorized and fully in-game, and 

 		 * after all post-connection authorizations have been passed.  If the 

 		 * client does not have an AdminId by this stage, it means that no 

 		 * admin entry was in the cache that matched, and the user could not 

 		 * be authenticated as an admin.

 		 *

 		 * @param client		Client index.

 		 */

 		virtual void OnClientPostAdminCheck(int client)

 		{

 		}

 		/**

 		* @brief Notifies the extension that the maxplayers value has changed

 		*

 		* @param newvalue			New maxplayers value.

 		*/

 		virtual void OnMaxPlayersChanged(int newvalue)

 		{

 		}

 	};

 	#define COMMAND_FILTER_ALIVE		(1<<0)		/**< Only allow alive players */

 	#define COMMAND_FILTER_DEAD			(1<<1)		/**< Only filter dead players */

 	#define COMMAND_FILTER_CONNECTED	(1<<2)		/**< Allow players not fully in-game */

 	#define COMMAND_FILTER_NO_IMMUNITY	(1<<3)		/**< Ignore immunity rules */

 	#define COMMAND_FILTER_NO_MULTI		(1<<4)		/**< Do not allow multiple target patterns */

 	#define COMMAND_FILTER_NO_BOTS		(1<<5)		/**< Do not allow bots to be targetted */

 	#define COMMAND_TARGET_VALID		1			/**< Client passed the filter */

 	#define COMMAND_TARGET_NONE			0			/**< No target was found */

 	#define COMMAND_TARGET_NOT_ALIVE	-1			/**< Single client is not alive */

 	#define COMMAND_TARGET_NOT_DEAD		-2			/**< Single client is not dead */

 	#define COMMAND_TARGET_NOT_IN_GAME	-3			/**< Single client is not in game */

 	#define COMMAND_TARGET_IMMUNE		-4			/**< Single client is immune */

 	#define COMMAND_TARGET_EMPTY_FILTER	-5			/**< A multi-filter (such as @all) had no targets */

 	#define COMMAND_TARGET_NOT_HUMAN	-6			/**< Target was not human */

 	#define COMMAND_TARGET_AMBIGUOUS	-7			/**< Partial name had too many targets */

 	#define COMMAND_TARGETNAME_RAW		0			/**< Target name is a raw string */

 	#define COMMAND_TARGETNAME_ML		1			/**< Target name is a multi-lingual phrase */

 	/**

 	 * @brief Holds the many command target info parameters.

 	 */

 	struct cmd_target_info_t

 	{

 		const char *pattern;			/**< IN: Target pattern string. */

 		int admin;						/**< IN: Client admin index, or 0 if server .*/

 		cell_t *targets;				/**< IN: Array to store targets. */

 		cell_t max_targets;				/**< IN: Max targets (always >= 1) */

 		int flags;						/**< IN: COMMAND_FILTER flags. */

 		char *target_name;				/**< OUT: Buffer to store target name. */

 		size_t target_name_maxlength;	/**< IN: Maximum length of the target name buffer. */

 		int target_name_style;			/**< OUT: Target name style (COMMAND_TARGETNAME) */

 		int reason;						/**< OUT: COMMAND_TARGET reason. */

 		unsigned int num_targets;		/**< OUT: Number of targets. */

 	};

 	/**

 	 * @brief Intercepts a command target operation.

 	 */

 	class ICommandTargetProcessor

 	{

 	public:

 		/**

 		 * @brief Must process the command target and return a COMMAND_TARGET value.

 		 *

 		 * @param info			Struct containing command target information.

 		 *						Any members labelled OUT must be filled if processing 

 		 *						is to be completed (i.e. true returned).

 		 * @return				True to end processing, false to let Core continue.

 		 */

 		virtual bool ProcessCommandTarget(cmd_target_info_t *info) =0;

 	};

 	class IPlayerManager : public SMInterface

 	{

 	public:

 		const char *GetInterfaceName()

 		{

 			return SMINTERFACE_PLAYERMANAGER_NAME;

 		}

 		unsigned int GetInterfaceVersion()

 		{

 			return SMINTERFACE_PLAYERMANAGER_VERSION;

 		}

 	public:

 		/**

 		 * @brief Adds a client listener.

 		 *

 		 * @param listener		Pointer to an IClientListener.

 		 */

 		virtual void AddClientListener(IClientListener *listener) =0;

 		/**

 		 * @brief Removes a client listener.

 		 *

 		 * @param listener		Pointer to an IClientListener.

 		 */

 		virtual void RemoveClientListener(IClientListener *listener) =0;

 		/**

 		 * @brief Retrieves an IGamePlayer object by its client index.

 		 *

 		 * Note: This will return a valid object for any player, connected or not.

 		 * Note: Client indexes start at 1, not 0.

 		 *

 		 * @param client		Index of the client.

 		 * @return				An IGamePlayer pointer, or NULL if out of range.

 		 */

 		virtual IGamePlayer *GetGamePlayer(int client) =0;

 		/**

 		 * @brief Retrieves an IGamePlayer object by its edict_t pointer.

 		 *

 		 * @param pEdict		Index of the client

 		 * @return				An IGamePlayer pointer, or NULL if out of range.

 		 */

 		virtual IGamePlayer *GetGamePlayer(edict_t *pEdict) =0;

 		/**

 		 * @brief Returns the maximum number of clients.

 		 *

 		 * Note: this will not work until the server is activated.

 		 *

 		 * @return				Maximum number of clients.

 		 */

 		virtual int GetMaxClients() =0;

 		/**

 		 * @brief Returns the number of players currently connected.

 		 *

 		 * @return				Current number of connected clients.

 		 */

 		virtual int GetNumPlayers() =0;

 		/**

 		 * @brief Returns the client index by its userid.

 		 *

 		 * @param userid		Userid of the client.

 		 * @return				Client index, or 0 if invalid userid passed.

 		 */

 		virtual int GetClientOfUserId(int userid) =0;

 		/**

 		 * @brief Returns whether or not the server is activated.

 		 *

 		 * @return				True if ServerActivate() has been called

 		 *						at least once, false otherwise.

 		 */

 		virtual bool IsServerActivated() =0;

 		/**

 		 * @brief Gets SourceMod's reply source.

 		 *

 		 * @return				ReplyTo source.

 		 */

 		virtual unsigned int GetReplyTo() =0;

 		/**

 		 * @brief Sets SourceMod's reply source.

 		 *

 		 * @param reply			Reply source.

 		 * @return				Old reply source.

 		 */

 		virtual unsigned int SetReplyTo(unsigned int reply) =0;

 		/**

 		 * @brief Tests if a player meets command filtering rules.

 		 *

 		 * @param pAdmin		IGamePlayer of the admin, or NULL if the server. 

 		 * @param pTarget		IGamePlayer of the player being targeted.

 		 * @param flags			COMMAND_FILTER flags.

 		 * @return				COMMAND_TARGET value.

 		 */

 		virtual int FilterCommandTarget(IGamePlayer *pAdmin, IGamePlayer *pTarget, int flags) =0;

 		/**

 		 * @brief Registers a command target processor.

 		 *

 		 * @param pHandler		Pointer to an ICommandTargetProcessor instance.

 		 */

 		virtual void RegisterCommandTargetProcessor(ICommandTargetProcessor *pHandler) =0;

 		/**

 		 * @brief Removes a command target processor.

 		 *

 		 * @param pHandler		Pointer to an ICommandTargetProcessor instance.

 		 */

 		virtual void UnregisterCommandTargetProcessor(ICommandTargetProcessor *pHandler) =0;

 		/**

 		 * @brief Returns the client index by its serial number.

 		 *

 		 * @return				Client index, or 0 for invalid serial.

 		 */

 		virtual int GetClientFromSerial(unsigned int serial) =0;

 	};

 }

 #endif //_INCLUDE_SOURCEMOD_INTERFACE_IPLAYERHELPERS_H_