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