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