sourcemm/ISmmPlugin.h
branchhookman_autogen
changeset 531 0180319136ba
parent 479 b43ebc944319
child 532 9729de2d7551
     1.1 --- a/sourcemm/ISmmPlugin.h	Sun Nov 25 01:22:41 2007 +0000
     1.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.3 @@ -1,505 +0,0 @@
     1.4 -/**
     1.5 - * vim: set ts=4 :
     1.6 - * ======================================================
     1.7 - * Metamod:Source
     1.8 - * Copyright (C) 2004-2007 AlliedModders LLC and authors.
     1.9 - * All rights reserved.
    1.10 - * ======================================================
    1.11 - *
    1.12 - * This software is provided 'as-is', without any express or implied warranty.
    1.13 - * In no event will the authors be held liable for any damages arising from 
    1.14 - * the use of this software.
    1.15 - * 
    1.16 - * Permission is granted to anyone to use this software for any purpose, 
    1.17 - * including commercial applications, and to alter it and redistribute it 
    1.18 - * freely, subject to the following restrictions:
    1.19 - *
    1.20 - * 1. The origin of this software must not be misrepresented; you must not 
    1.21 - * claim that you wrote the original software. If you use this software in a 
    1.22 - * product, an acknowledgment in the product documentation would be 
    1.23 - * appreciated but is not required.
    1.24 - * 2. Altered source versions must be plainly marked as such, and must not be
    1.25 - * misrepresented as being the original software.
    1.26 - * 3. This notice may not be removed or altered from any source distribution.
    1.27 - *
    1.28 - * Version: $Id$
    1.29 - */
    1.30 -
    1.31 -#ifndef _INCLUDE_ISMM_PLUGIN_H
    1.32 -#define _INCLUDE_ISMM_PLUGIN_H
    1.33 -
    1.34 -/**
    1.35 - * @brief Plugin API interface
    1.36 - * @file ISmmPlugin.h
    1.37 - */
    1.38 -
    1.39 -#include <interface.h>
    1.40 -#include <sourcehook.h>
    1.41 -#include <IPluginManager.h>
    1.42 -#include <ISmmAPI.h>
    1.43 -#include <ISmmPluginExt.h>
    1.44 -
    1.45 -namespace SourceMM
    1.46 -{
    1.47 -	class ISmmAPI;
    1.48 -
    1.49 -	/**
    1.50 -	 * @brief Callbacks that a plugin must expose.
    1.51 -	 */
    1.52 -	class ISmmPlugin
    1.53 -	{
    1.54 -	public:
    1.55 -		/**
    1.56 -		 * @brief Called to request the plugin's API version.
    1.57 -		 *
    1.58 -		 * This is the first callback invoked, and always remains at the top 
    1.59 -		 * of the virtual table.  
    1.60 -		 *
    1.61 -		 * @return			Plugin API version.
    1.62 -		 */
    1.63 -		virtual int GetApiVersion() 
    1.64 -		{ 
    1.65 -			return METAMOD_PLAPI_VERSION; 
    1.66 -		}
    1.67 -
    1.68 -		/**
    1.69 -		 * @brief Virtual destructor so GCC doesn't complain.
    1.70 -		 */
    1.71 -		virtual ~ISmmPlugin()
    1.72 -		{
    1.73 -		}
    1.74 -
    1.75 -	public:
    1.76 -		/**
    1.77 -		 * @brief Called on plugin load.
    1.78 -		 *
    1.79 -		 * This is called as DLLInit() executes - after the parameters are 
    1.80 -		 * known, but before the original GameDLL function is called.  
    1.81 -		 * Therefore, you cannot hook it, but you don't need to - Load() is 
    1.82 -		 * basically your hook.  You can override factories before the engine 
    1.83 -		 * and gamedll exchange them.  However, take care to note that if your 
    1.84 -		 * plugin is unloaded, and the gamedll/engine have cached an interface 
    1.85 -		 * you've passed, something will definitely crash.  Be careful.
    1.86 -		 *
    1.87 -		 * @param id		Internal id of plugin.  Saved globally by PLUGIN_SAVEVARS()
    1.88 -		 * @param ismm		External API for SourceMM.  Saved globally by PLUGIN_SAVEVARS()
    1.89 -		 * @param error		Error message buffer
    1.90 -		 * @param maxlength	Size of error message buffer
    1.91 -		 * @param late		Set to true if your plugin was loaded late (not at server load).
    1.92 -		 * @return			True if successful, return false to reject the load.
    1.93 -		 */
    1.94 -		virtual bool Load(PluginId id, ISmmAPI *ismm, char *error, size_t maxlength, bool late) =0;
    1.95 -
    1.96 -		/**
    1.97 -		 * @brief Called when all plugins have been loaded.  
    1.98 -		 *
    1.99 -		 * This is called after DLLInit(), and thus the mod has been mostly initialized. 
   1.100 -		 * It is also safe to assume that all other (automatically loaded) plugins are now 
   1.101 -		 * ready to start interacting, because they are all loaded.
   1.102 -		 */
   1.103 -		virtual void AllPluginsLoaded()
   1.104 -		{
   1.105 -		}
   1.106 -
   1.107 -		/**
   1.108 -		 * @brief Called when your plugin is "queried".  
   1.109 -		 * 
   1.110 -		 * This is useful for rejecting a loaded state.  For example, if your 
   1.111 -		 * plugin wants to stop operating, it can simply return false and copy 
   1.112 -		 * an error message.  This will notify other plugins or MM:S of 
   1.113 -		 * something bad that happened.  MM:S will not cache the return state, 
   1.114 -		 * so if you return false,  your plugin will not actually be paused or 
   1.115 -		 * unloaded.  This callback will be called when:
   1.116 -		 *  - Another plugin requests it
   1.117 -		 *  - Someone types "meta list", it will show up as "REFUSED"
   1.118 -		 *  - When Metamod need to re-check the plugin's status
   1.119 -		 *  - If the plugin does something like overload a factory, Metamod 
   1.120 -		 *    will make sure the Query() returns true before calling it.
   1.121 -		 *  Also note that this query will only override Metamod when the 
   1.122 -		 *  plugin is running and not paused.
   1.123 -		 *
   1.124 -		 * @param error		Buffer for error message, or NULL if none.
   1.125 -		 * @param maxlen	Maximum length of error buffer.
   1.126 -		 * @return			Status code - true for okay, false for badness.
   1.127 -		 */
   1.128 -		virtual bool QueryRunning(char *error, size_t maxlen)
   1.129 -		{
   1.130 -			return true;
   1.131 -		}
   1.132 -
   1.133 -		/** 
   1.134 -		 * @brief Called on plugin unload.  You can return false if you know 
   1.135 -		 * your plugin is not capable of restoring critical states it modifies.
   1.136 -		 *
   1.137 -		 * @param error		Error message buffer
   1.138 -		 * @param maxlen	Size of error message buffer
   1.139 -		 * @return			True on success, return false to request no unload.
   1.140 -		 */
   1.141 -		virtual bool Unload(char *error, size_t maxlen)
   1.142 -		{
   1.143 -			return true;
   1.144 -		}
   1.145 -
   1.146 -		/** 
   1.147 -		 * @brief Called on plugin pause.
   1.148 -		 *
   1.149 -		 * @param	error Error message buffer
   1.150 -		 * @param	maxlen Size of error message buffer
   1.151 -		 * @return	True on success, return false to request no pause.
   1.152 -		 */
   1.153 -		virtual bool Pause(char *error, size_t maxlen)
   1.154 -		{
   1.155 -			return true;
   1.156 -		}
   1.157 -
   1.158 -		/** 
   1.159 -		 * @brief Called on plugin unpause.
   1.160 -		 *
   1.161 -		 * @param	error Error message buffer
   1.162 -		 * @param	maxlen Size of error message buffer
   1.163 -		 * @return	True on success, return false to request no unpause.
   1.164 -		 */
   1.165 -		virtual bool Unpause(char *error, size_t maxlen)
   1.166 -		{
   1.167 -			return true;
   1.168 -		}
   1.169 -	public:
   1.170 -		/** @brief Return author as string */
   1.171 -		virtual const char *GetAuthor() =0;
   1.172 -	
   1.173 -		/** @brief Return plugin name as string */
   1.174 -		virtual const char *GetName() =0;
   1.175 -	
   1.176 -		/** @brief Return a description as string */
   1.177 -		virtual const char *GetDescription() =0;
   1.178 -	
   1.179 -		/** @brief Return a URL as string */
   1.180 -		virtual const char *GetURL() =0;
   1.181 -	
   1.182 -		/** @brief Return quick license code as string */
   1.183 -		virtual const char *GetLicense() =0;
   1.184 -	
   1.185 -		/** @brief Return version as string */
   1.186 -		virtual const char *GetVersion() =0;
   1.187 -	
   1.188 -		/** @brief Return author as string */
   1.189 -		virtual const char *GetDate() =0;
   1.190 -	
   1.191 -		/** @brief Return author as string */
   1.192 -		virtual const char *GetLogTag() =0;
   1.193 -	};
   1.194 -
   1.195 -	/**
   1.196 -	 * @brief Various events that Metamod can fire.
   1.197 -	 */
   1.198 -	class IMetamodListener
   1.199 -	{
   1.200 -	public:
   1.201 -		/**
   1.202 -		 * @brief Called when a plugin is loaded.
   1.203 -		 *
   1.204 -		 * @param id		Id of the plugin.
   1.205 -		 */
   1.206 -		virtual void OnPluginLoad(PluginId id)
   1.207 -		{
   1.208 -		}
   1.209 -
   1.210 -		/**
   1.211 -		 * @brief Called when a plugin is unloaded.
   1.212 -		 *
   1.213 -		 * @param id		Id of the plugin.
   1.214 -		 */
   1.215 -		virtual void OnPluginUnload(PluginId id)
   1.216 -		{
   1.217 -		}
   1.218 -	
   1.219 -		/**
   1.220 -		 * @brief Called when a plugin is paused.
   1.221 -		 *
   1.222 -		 * @param id		Id of the plugin.
   1.223 -		 */
   1.224 -		virtual void OnPluginPause(PluginId id)
   1.225 -		{
   1.226 -		}
   1.227 -	
   1.228 -		/**
   1.229 -		 * @brief Called when a plugin is unpaused.
   1.230 -		 *
   1.231 -		 * @param id		Id of the plugin.
   1.232 -		 */
   1.233 -		virtual void OnPluginUnpause(PluginId id)
   1.234 -		{
   1.235 -		}
   1.236 -	
   1.237 -		/**
   1.238 -		 * @brief Called when the level is loaded (after GameInit, before 
   1.239 -		 * ServerActivate).
   1.240 -		 *
   1.241 -		 * To override this, hook IServerGameDLL::LevelInit().
   1.242 -		 *
   1.243 -		 * @param pMapName		Name of the map.
   1.244 -		 * @param pMapEntities	Lump string of the map entities, in KeyValues
   1.245 -		 * 						format.
   1.246 -		 * @param pOldLevel		Unknown.
   1.247 -		 * @param pLandmarkName	Unknown.
   1.248 -		 * @param loadGame		Unknown.
   1.249 -		 * @param background	Unknown.
   1.250 -		 */
   1.251 -		virtual void OnLevelInit(char const *pMapName, 
   1.252 -								 char const *pMapEntities, 
   1.253 -								 char const *pOldLevel, 
   1.254 -								 char const *pLandmarkName, 
   1.255 -								 bool loadGame, 
   1.256 -								 bool background) 
   1.257 -		{ 
   1.258 -		}
   1.259 -
   1.260 -		/**
   1.261 -		 * @brief Called when the level is shut down.  May be called more than 
   1.262 -		 * once.
   1.263 -		 */
   1.264 -		virtual void OnLevelShutdown()
   1.265 -		{
   1.266 -		}
   1.267 -
   1.268 -		/**
   1.269 -		 * @brief Called when engineFactory() is used through Metamod:Source's 
   1.270 -		 * wrapper.  This can be used to provide interfaces to other plugins or
   1.271 -		 * the GameDLL.
   1.272 -		 *
   1.273 -		 * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED.
   1.274 -		 *
   1.275 -		 * @param iface			Interface string.
   1.276 -		 * @param ret			Optional pointer to store return code.
   1.277 -		 * @return				Generic pointer to the interface, or NULL if 
   1.278 -		 * 						not found.
   1.279 -		 */
   1.280 -		virtual void *OnEngineQuery(const char *iface, int *ret)
   1.281 -		{
   1.282 -			if (ret)
   1.283 -			{
   1.284 -				*ret = IFACE_FAILED;
   1.285 -			}
   1.286 -
   1.287 -			return NULL; 
   1.288 -		}
   1.289 -
   1.290 -		/**
   1.291 -		 * @brief Called when the physics factory is used through 
   1.292 -		 * Metamod:Source's wrapper. This can be used to provide interfaces to 
   1.293 -		 * other plugins.
   1.294 -		 *
   1.295 -		 * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED.
   1.296 -		 *
   1.297 -		 * @param iface			Interface string.
   1.298 -		 * @param ret			Optional pointer to store return code.
   1.299 -		 * @return				Generic pointer to the interface, or NULL if 
   1.300 -		 * 						not found.
   1.301 -		 */
   1.302 -		virtual void *OnPhysicsQuery(const char *iface, int *ret)
   1.303 -		{
   1.304 -			if (ret)
   1.305 -			{
   1.306 -				*ret = IFACE_FAILED;
   1.307 -			}
   1.308 -	
   1.309 -			return NULL; 
   1.310 -		}
   1.311 -
   1.312 -		/**
   1.313 -		 * @brief Called when the filesystem factory is used through 
   1.314 -		 * Metamod:Source's wrapper.  This can be used to provide interfaces to 
   1.315 -		 * other plugins.
   1.316 -		 *
   1.317 -		 * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED.
   1.318 -		 *
   1.319 -		 * @param iface			Interface string.
   1.320 -		 * @param ret			Optional pointer to store return code.
   1.321 -		 * @return				Generic pointer to the interface, or NULL if not 
   1.322 -		 * 						found.
   1.323 -		 */
   1.324 -		virtual void *OnFileSystemQuery(const char *iface, int *ret)
   1.325 -		{
   1.326 -			if (ret)
   1.327 -			{
   1.328 -				*ret = IFACE_FAILED;
   1.329 -			}
   1.330 -			
   1.331 -			return NULL; 
   1.332 -		}
   1.333 -
   1.334 -		/**
   1.335 -		 * @brief Called when the server DLL's factory is used through 
   1.336 -		 * Metamod:Source's wrapper.  This can be used to provide interfaces to 
   1.337 -		 * other plugins.
   1.338 -		 *
   1.339 -		 * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED.
   1.340 -		 *
   1.341 -		 * @param iface			Interface string.
   1.342 -		 * @param ret			Optional pointer to store return code.
   1.343 -		 * @return				Generic pointer to the interface, or NULL if not 
   1.344 -		 * 						found.
   1.345 -		 */
   1.346 -		virtual void *OnGameDLLQuery(const char *iface, int *ret)
   1.347 -		{
   1.348 -			if (ret)
   1.349 -			{
   1.350 -				*ret = IFACE_FAILED;
   1.351 -			}
   1.352 -	
   1.353 -			return NULL; 
   1.354 -		}
   1.355 -
   1.356 -		/**
   1.357 -		 * @brief Called when Metamod's own factory is invoked.  
   1.358 -		 * This can be used to provide interfaces to other plugins.
   1.359 -		 *
   1.360 -		 * If ret is passed, you should fill it with IFACE_OK or IFACE_FAILED.
   1.361 -		 *
   1.362 -		 * @param iface			Interface string.
   1.363 -		 * @param ret			Optional pointer to store return code.
   1.364 -		 * @return				Generic pointer to the interface, or NULL if not 
   1.365 -		 * 						found.
   1.366 -		 */
   1.367 -		virtual void *OnMetamodQuery(const char *iface, int *ret)
   1.368 -		{
   1.369 -			if (ret)
   1.370 -			{
   1.371 -				*ret = IFACE_FAILED;
   1.372 -			}
   1.373 -	
   1.374 -			return NULL; 	
   1.375 -		}
   1.376 -
   1.377 -		/**
   1.378 -		 * @brief Called when Metamod:Source acquires a valid 
   1.379 -		 * IServerPluginCallbacks pointer to be used for hooking by plugins.
   1.380 -		 *
   1.381 -		 * This will only be called after a call to ISmmAPI::EnableVSPListener().
   1.382 -		 * If called before GameInit, this callback will occur before LevelInit.
   1.383 -		 * Otherwise, it will be called on the first call after that.
   1.384 -		 *
   1.385 -		 * This callback is provided to all plugins regardless of which (or how 
   1.386 -		 * many) called EnableVSPListener(), but only if at least one did in 
   1.387 -		 * fact enable it, and only once for all plugins.  That is, a late 
   1.388 -		 * loading plugin should use ISmmAPI::GetVSPInfo() before relying on 
   1.389 -		 * this callback.
   1.390 -		 *
   1.391 -		 * @param iface			Interface pointer.  If NULL, then the VSP 
   1.392 -		 * 						listening construct failed to initialize and 
   1.393 -		 * 						is not available.
   1.394 -		 */
   1.395 -		virtual void OnVSPListening(IServerPluginCallbacks *iface) 
   1.396 -		{ 
   1.397 -		}
   1.398 -
   1.399 -		/**
   1.400 -		 * @brief Called when Metamod:Source is about to remove a concommand or 
   1.401 -		 * convar.  This can also be called if ISmmAPI::UnregisterConCmdBase is 
   1.402 -		 * used by a plugin.
   1.403 -		 *
   1.404 -		 * @param id			Id of the plugin that created the concommand or 
   1.405 -		 * 						convar.
   1.406 -		 * @param pCommand		Pointer to concommand or convar that is being 
   1.407 -		 * 						removed.
   1.408 -		 */
   1.409 -		virtual void OnUnlinkConCommandBase(PluginId id, ConCommandBase *pCommand)
   1.410 -		{
   1.411 -		}
   1.412 -	};
   1.413 -}
   1.414 -
   1.415 -#if !defined METAMOD_NO_AUTO_NAMESPACE
   1.416 -using namespace SourceMM;
   1.417 -#endif
   1.418 -
   1.419 -#define PL_EXPOSURE		CreateInterface
   1.420 -#define PL_EXPOSURE_C	"CreateInterface"
   1.421 -
   1.422 -#define PLUGIN_EXPOSE(name, var) \
   1.423 -	ISmmAPI *g_SMAPI = NULL; \
   1.424 -	ISmmPlugin *g_PLAPI = NULL; \
   1.425 -	PluginId g_PLID = (PluginId)0; \
   1.426 -	SourceHook::ISourceHook *g_SHPtr = NULL; \
   1.427 -	SMM_API void *PL_EXPOSURE(const char *name, int *code) { \
   1.428 -		if (name && !strcmp(name, METAMOD_PLAPI_NAME)) { \
   1.429 -			return static_cast<void *>(&var); \
   1.430 -		} \
   1.431 -		return NULL; \
   1.432 -	}
   1.433 -
   1.434 -#define PLUGIN_GLOBALVARS()	\
   1.435 -	extern SourceHook::ISourceHook *g_SHPtr; \
   1.436 -	extern ISmmAPI *g_SMAPI; \
   1.437 -	extern ISmmPlugin *g_PLAPI; \
   1.438 -	extern PluginId g_PLID; 
   1.439 -
   1.440 -#define PLUGIN_SAVEVARS() \
   1.441 -	g_SMAPI = ismm; \
   1.442 -	g_SHPtr = static_cast<SourceHook::ISourceHook *>(ismm->MetaFactory(MMIFACE_SOURCEHOOK, NULL, NULL)); \
   1.443 -	g_PLAPI = static_cast<ISmmPlugin *>(this); \
   1.444 -	g_PLID = id;
   1.445 -
   1.446 -#define META_LOG				g_SMAPI->LogMsg
   1.447 -#define META_REGCMD(name)		g_SMAPI->RegisterConCommandBase(g_PLAPI, name##_command)
   1.448 -#define META_REGCVAR(var)		g_SMAPI->RegisterConCommandBase(g_PLAPI, var)
   1.449 -#define META_UNREGCMD(name)		g_SMAPI->UnregisterConCommandBase(g_PLAPI, name##_command)
   1.450 -#define META_UNREGCVAR(var)		g_SMAPI->UnregisterConCommandBase(g_PLAPI, var)
   1.451 -#define	META_CONPRINT			g_SMAPI->ConPrint
   1.452 -#define META_CONPRINTF			g_SMAPI->ConPrintf
   1.453 -
   1.454 -/* Probably should use this up above someday */
   1.455 -#define CONCMD_VARNAME(name) name##_command
   1.456 -
   1.457 -#if !defined SMM_API
   1.458 -#if defined __WIN32__ || defined _WIN32 || defined WIN32
   1.459 -	#define SMM_API extern "C" __declspec(dllexport)
   1.460 -#elif defined __GNUC__
   1.461 -	#if (__GNUC__ == 4) && (__GNUC_MINOR__ >= 1)
   1.462 -		#define SMM_API extern "C" __attribute__ ((visibility("default")))	
   1.463 -	#else
   1.464 -		#define SMM_API	extern "C" 
   1.465 -	#endif	
   1.466 -#endif
   1.467 -#endif //!defined SMM_API
   1.468 -
   1.469 -/**
   1.470 - * @brief Macro for automatically getting a current or newer Valve interface.
   1.471 - *
   1.472 - * @param v_factory		Factory method to use from ISmmAPI (such as engineFactory).
   1.473 - * @param v_var			Variable name to store into.
   1.474 - * @param v_type		Interface type (do not include the pointer/asterisk).
   1.475 - * @param v_name		Interface name.
   1.476 - */
   1.477 -#define GET_V_IFACE_CURRENT(v_factory, v_var, v_type, v_name) \
   1.478 -	v_var = (v_type *)ismm->VInterfaceMatch(ismm->v_factory(), v_name); \
   1.479 -	if (!v_var) \
   1.480 -	{ \
   1.481 -		if (error && maxlen) \
   1.482 -		{ \
   1.483 -			ismm->Format(error, maxlen, "Could not find interface: %s", v_name); \
   1.484 -		} \
   1.485 -		return false; \
   1.486 -	}
   1.487 -
   1.488 - /**
   1.489 -  * @brief Same as GET_V_IFACE, except searches for any.
   1.490 -  *
   1.491 -  * @param v_factory	Factory method to use from ISmmAPI (such as engineFactory).
   1.492 -  * @param v_var		Variable name to store into.
   1.493 -  * @param v_type		Interface type (do not include the pointer/asterisk).
   1.494 -  * @param v_name		Interface name.
   1.495 -  */
   1.496 -#define GET_V_IFACE_ANY(v_factory, v_var, v_type, v_name) \
   1.497 -	v_var = (v_type *)ismm->VInterfaceMatch(ismm->v_factory(), v_name, 0); \
   1.498 -	if (!v_var) \
   1.499 -	{ \
   1.500 -		if (error && maxlen) \
   1.501 -		{ \
   1.502 -			ismm->Format(error, maxlen, "Could not find interface: %s", v_name); \
   1.503 -		} \
   1.504 -		return false; \
   1.505 -	}
   1.506 -
   1.507 -#endif //_INCLUDE_ISMM_PLUGIN_H
   1.508 -